Use Ollama locally

ParseHawk can use Ollama through the existing openai_compatible_api provider. No separate provider adapter is required. Extraction sends chat-completions requests with JSON Schema response constraints. Parsing sends one image page at a time and requests Markdown.

Verified compatibility

This path was verified on Apple Silicon with Ollama 0.32.0 on 14 July 2026. qwen3:0.6b produced schema-valid text extraction, and qwen3-vl:2b-instruct matched every field in ParseHawk’s receipt image ground truth. That check covered extraction, not Markdown parsing. Treat these small models as compatibility checks, not production accuracy recommendations.

1. Start Ollama and pull a small model

Install Ollama, then start its local server. The desktop app normally starts it for you; from a terminal you can run:

ollama serve

For a lightweight text test:

ollama pull qwen3:0.6b

For image and rendered-PDF extraction:

ollama pull qwen3-vl:2b-instruct

Confirm Ollama’s OpenAI-compatible endpoint:

curl --fail http://127.0.0.1:11434/v1/models

2. Start ParseHawk without its bundled runtime

parsehawk start -x runtime

The API and worker still run in Docker. Point them at the Mac host, not at their own container loopback:

parsehawk providers configure openai_compatible_api \
  --base-url http://host.docker.internal:11434/v1

If you run parsehawk dev with API and worker processes directly on the host, use http://127.0.0.1:11434/v1 instead.

3. Test structured text extraction

From a ParseHawk repository checkout, create a saved extractor with the bundled receipt schema and assign the text model:

parsehawk extractors create \
  --name ollama-receipt \
  --display-name "Ollama receipt" \
  --instructions "Extract receipt fields and preserve written values." \
  --schema tests/fixtures/receipt/receipt_schema.json \
  --provider openai_compatible_api \
  --model qwen3:0.6b

parsehawk extract \
  --text "Merchant: Sparrow Books. Receipt ID: A-204. Date: 2026-07-14. Total: EUR 128.40." \
  --extractor ollama-receipt \
  --wait

The command should print schema-valid JSON. If you are not working from a repository checkout, replace the fixture path with your own schema; the reusable extractor tutorial builds one from scratch.

4. Test a multimodal model

Switch the same user-created extractor to the vision-language model, then run the bundled image:

parsehawk extractors update ollama-receipt \
  --provider openai_compatible_api \
  --model qwen3-vl:2b-instruct

parsehawk extract tests/fixtures/receipt/receipt.jpg \
  --extractor ollama-receipt \
  --wait

PDFs use the same multimodal path: ParseHawk renders pages to images before calling the model. The default limit is 25 pages at 170 DPI.

5. Test Markdown parsing

Create a custom parser with the same vision-language model:

parsehawk parsers put ollama-markdown \
  --display-name "Ollama Markdown" \
  --instructions "Preserve section numbers and table structure." \
  --provider openai_compatible_api \
  --model qwen3-vl:2b-instruct

parsehawk parse tests/fixtures/receipt/receipt.pdf \
  --parser ollama-markdown \
  --wait \
  --output receipt.md

Inspect receipt.md and the parse job before using the model in production. Parsing compatibility and transcription quality depend on the selected Ollama model and version.

Troubleshoot the connection

• If /v1/models fails on the host, Ollama is not listening yet. Open the app or run ollama serve and retry.
• If the host request works but ParseHawk cannot connect, verify that the stored base URL uses host.docker.internal for the Docker stack.
• If a model returns free-form prose instead of JSON, try its instruction-tuned variant and inspect the model trace in Phoenix. This response-format check applies to extraction.
• If a vision job fails immediately, confirm that the selected model supports images; a text-only model cannot process image or PDF inputs.
• Small models are useful for compatibility checks, not an accuracy baseline. Evaluate a representative document set before choosing a production model.