智能工作流

Prerequisites

• Python 3.12.10+ (use pyenv for version management)
• macOS (for MLX backend) or Linux/Windows (for other backends)
• GPU (make sure GPU have enough memory to run selected Vision LLM)

30-Second Setup

```bash

1. Install pyenv and Python 3.12.10

pyenv install 3.12.10 pyenv global 3.12.10

3. Install Sparrow Parse pipeline

git clone https://github.com/katanaml/sparrow.git cd sparrow/sparrow-ml/llm pip install -r requirements_sparrow_parse.txt

4. For macOS: Install poppler for PDF processing

brew install poppler

🛠️ Installation

Quick Setup

```bash

Test installation

python api.py --port 8002

If MLX fails to install

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

If pip install command throws AttributeError: 'NoneType' object has no attribute 'get'

Verify installation

pdftoppm -h

</details>

<details>
<summary>🔧 Runtime Issues</summary>

**Memory Errors:**
- Use smaller or MoE models to reduce VRAM footprint
- Enable image cropping: `--crop-size 100`
- Process single pages instead of entire PDFs

**Model Loading Fails:**

🚀 Quickstart

📚 Examples

Function calling example

./sparrow.sh assistant --pipeline "stocks" --query "Oracle"

**JSON Output:**

**Additional Output:**

💻 CLI Usage

Advanced Examples

```bash

🌐 API Usage

Usage

```bash

2. Create virtual environment

python -m venv .env_sparrow_parse source .env_sparrow_parse/bin/activate # Linux/Mac

or .env_sparrow_parse\Scripts\activate # Windows

Pipeline Options

#### Sparrow Parse (Vision LLM) ```bash

Fix with pyenv

pyenv install 3.12.10 pyenv global 3.12.10

**MLX Installation (Apple Silicon):**

5. Start the API server

python api.py ```

Before running pip install -r requirements_sparrow_parse.txt, check your platform. If you are on macOS and want to run MLX backend, go to requirements_sparrow_parse.txt and make sure sparrow-parse[mlx] libary reference is defined. If you are running Sparrow on Linux/Windows, make sure to use sparrow-parse library reference, this will skip MLX related libraries.

Visit http://localhost:8002/api/v1/sparrow-llm/docs

```

API Endpoints

Document Extraction (/inference)

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/inference' \
  -H 'Content-Type: multipart/form-data' \
  -F 'query=[{"field_name":"str", "amount":0}]' \
  -F 'pipeline=sparrow-parse' \
  -F 'options=mlx,mlx-community/Qwen2.5-VL-72B-Instruct-4bit' \
  -F 'file=@document.pdf'

Text Instructions (/instruction-inference)

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/instruction-inference' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'query=instruction: analyze data, payload: {...}' \
  -d 'pipeline=sparrow-instructor' \
  -d 'options=mlx,mlx-community/Qwen3.6-35B-A3B-8bit'

API Documentation

Visit http://localhost:8002/api/v1/sparrow-llm/docs for interactive Swagger documentation.

Core Components

🔧 Pipeline Comparison

🔍 Troubleshooting