sparrow

环境要求

• Python 3.12.10（README 指定版本）
• pyenv（用于安装和切换 Python 版本）
• pip（安装 Python 依赖）
• macOS 处理 PDF 需安装 poppler

安装与启动步骤

1. 1安装 Python 3.12.10

   用 pyenv 安装 3.12.10 并设为全局版本，保证后续依赖兼容。

   pyenv install 3.12.10
   pyenv global 3.12.10

   复制

2. 2克隆并进入目录

   拉取 sparrow 源码，进入 sparrow-ml/llm 目录，后续命令都在此执行。

   git clone https://github.com/katanaml/sparrow.git
   cd sparrow/sparrow-ml/llm

   复制

3. 3安装解析依赖

   在该目录下根据 requirements_sparrow_parse.txt 安装 Sparrow Parse 所需依赖。

   pip install -r requirements_sparrow_parse.txt

   复制

4. 4安装 poppler

   macOS 处理 PDF 需要 poppler，用 Homebrew 安装；非 macOS 用户可跳过此步。

   brew install poppler

   复制

5. 5启动 API 服务

   在 sparrow-ml/llm 目录运行 api.py，指定 8002 端口启动服务。

   python api.py --port 8002

   复制

6. 6修复 mlx 安装失败

   若 mlx-vlm 安装失败，先升级 pip，再禁用缓存重新安装该包。

   pip install --upgrade pip
   pip install mlx-vlm --no-cache-dir

   复制

关键配置

如何确认成功

执行 pdftoppm -h 能看到帮助信息；再用 curl http://localhost:8002/health 检查服务是否正常响应。

常见问题

注意事项

• 服务在本机自行运行，README 强调不依赖外部云 API 调用。
• Python 版本必须按 README 使用 3.12.10，通过 pyenv 管理。
• 处理 PDF 依赖 poppler，macOS 用 Homebrew 安装。
• 大文件或多页 PDF 建议逐页处理或开启裁剪，降低显存压力。