Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

pixelrag index build orchestrates the four-stage visual indexing pipeline: it renders your documents to screenshot tiles, splits the tiles into 1024-pixel strips, embeds each strip with Qwen3-VL-Embedding-2B, and writes a FAISS index that the pixelrag serve API can query. The whole pipeline is driven by a single pixelrag.yaml file so you never have to run the stages manually.

​
Prerequisites

Install the index extra, which pulls in the render, embed, and index stages together: 
pip install 'pixelrag[index]'
The pipeline runs on Linux (CUDA) and macOS (Apple Silicon / MPS). Setting device: auto in your config file lets PixelRAG pick the fastest available backend automatically — CUDA on Linux, MPS on macOS, and CPU as the universal fallback.

​
Quick start with pixelrag.yaml

Create a pixelrag.yaml in your working directory: 
source:
  type: local
  path: ./my_docs

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto

output: ./my_index
Then run the build command: 
pixelrag index build
PixelRAG reads pixelrag.yaml automatically from the current directory (or pixelrag.yml). When the build finishes, the index is ready to serve from ./my_index.

​
Source types

Scans a directory tree and ingests every supported file it finds. Supported extensions:
ExtensionHandled as
.pdfPDF — rendered page by page
.html, .htmWeb page — rendered via CDP
.png, .jpg, .jpegImage — copied directly into the tile structure
.md, .txtText — converted to styled HTML, then rendered
source:
  type: local
  path: ./my_docs

​
Full config reference

All top-level keys with their defaults: 
source:
  type: local          # local | web | pdf | kiwix
  path: ./docs

ingest:
  backend: cdp         # cdp (default) | playwright
  quality: 85          # JPEG quality
  tile_height: 8192    # max tile height in pixels
  wait_network_idle: false

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: cuda         # cuda (default) | auto | mps | cpu

index:
  backend: faiss       # faiss (default) | qdrant
  # qdrant options (if backend: qdrant):
  # qdrant_url: http://localhost:6333
  # collection: pixelrag

output: ./my_index
The built-in default for embed.device is "cuda". Set device: auto to let PixelRAG detect the best available device automatically — CUDA on Linux, MPS on Apple Silicon, CPU as the universal fallback. You can also pin mps or cpu explicitly for reproducible builds in CI.

​
Department-based filtering

When you organise documents into subdirectories under your source path, PixelRAG reads the first subdirectory name as a department label and stores it in articles.json: 
my_docs/
├── engineering/
│   ├── api-spec.pdf
│   └── runbook.md
└── legal/
    ├── terms.html
    └── privacy.html
Files directly in engineering/ get department: "engineering" and files in legal/ get department: "legal". Files placed directly under my_docs/ (not inside any subdirectory) have no department. At query time you can pass "department": "engineering" to the search API to pre-filter results to that subdirectory — the filter runs inside FAISS as an IDSelector, not as post-filtering, so you always get the full n_docs results when the department has enough tiles.

​
Incremental builds

Re-running pixelrag index build is safe — already-rendered documents are skipped. The pipeline compares each document’s current source identity (URL or file path recorded in tiles.json) against what was last rendered; only new or changed documents are re-rendered. 
# Re-run; only new/changed documents are processed
pixelrag index build

# Force a complete clean rebuild from scratch
pixelrag index build --force
For Qdrant indexes, two additional flags control collection lifecycle:
  • --append — add documents to an existing Qdrant collection
  • --recreate — delete and recreate the collection before indexing

​
Downloading a pre-built Wikipedia index

If you want to search Wikipedia without building an index yourself, download the pre-built FAISS index from Hugging Face (~217 GB for the base model): 
pip install 'pixelrag[serve]'
huggingface-cli download StarTrail-org/pixelrag-faiss-indexes \
  --repo-type dataset --include "search_index_normed_v2/*" --local-dir ./index
Then serve it directly: 
pixelrag serve --index-dir ./index/search_index_normed_v2 --port 30001
The dataset repository holds four FAISS indexes (base/LoRA Wikipedia visual, Wikipedia text, and news visual). The command above downloads only the base Wikipedia visual index.

Build docs developers (and LLMs) love

Get started for freeTalk to us