Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
94 lines (66 loc) · 2.44 KB

GETTING_STARTED.md

File metadata and controls

94 lines (66 loc) · 2.44 KB

Getting Started

This guide is for a fresh clone of VisoRAG.

Dev-only checks do not need a .env file. Real serving should always set VISORAG_API_TOKEN; placeholder values such as change-me or test_bearer_123 are not deployment values.

What You Can Verify Without a GPU

The default development install is lightweight. It verifies packaging, import safety, API contracts, notebook structure, and mocked tests. It does not download or run ColQwen2 or Qwen2.5-VL.

python -m pip install -e ".[dev]"
python scripts/check_notebook_contract.py
python scripts/smoke_import.py
python -m pytest

This proves the package and public contracts, not real model inference.

Real Inference Requirements

Real document question answering requires:

  • Python 3.10 or newer.
  • A CUDA-capable GPU runtime.
  • The .[gpu] optional dependency set.
  • Model downloads for vidore/colqwen2-v1.0 and Qwen/Qwen2.5-VL-3B-Instruct.
  • Enough GPU memory for the selected image pixel bounds and document size.

Install the GPU dependencies only in a CUDA environment:

python -m pip install -e ".[gpu]"

The notebook-origin workflow was designed around a Google Colab T4-style runtime. CPU execution is not a supported path for real Qwen2.5-VL generation.

DOCX Support

DOCX files are converted through LibreOffice. Verify soffice is available before testing DOCX input:

soffice --version

If that command fails, install LibreOffice and add its program directory to PATH. PDF and image inputs do not require LibreOffice.

Run the API

macOS/Linux:

export VISORAG_API_TOKEN="change-me"
python -m visorag serve --host 127.0.0.1 --port 8000

Windows PowerShell:

$env:VISORAG_API_TOKEN = "change-me"
python -m visorag serve --host 127.0.0.1 --port 8000

Then open http://127.0.0.1:8000/docs or check health:

python -m visorag health --url http://127.0.0.1:8000

Submit a Query

python -m visorag query \
  --url http://127.0.0.1:8000 \
  --token "$VISORAG_API_TOKEN" \
  --file /path/to/document.pdf \
  --query "What is the invoice total?" \
  --query-type factual \
  --top-k 5

PowerShell:

python -m visorag query `
  --url http://127.0.0.1:8000 `
  --token $env:VISORAG_API_TOKEN `
  --file C:\path\to\document.pdf `
  --query "What is the invoice total?" `
  --query-type factual `
  --top-k 5

Do not use private or customer documents in public demos, issues, logs, or screenshots.