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.yaml is the single configuration file for the PixelRAG pipeline orchestrator. It drives pixelrag index build and controls every stage from source selection through embedding and index building. All keys are optional — PixelRAG applies sensible defaults for any missing fields so you only need to declare what differs from the defaults.

​
File discovery

PixelRAG searches for a config file in the current working directory, in this order:
  1. pixelrag.yaml
  2. pixelrag.yml
Override the search path with the --config flag: 
pixelrag index build --config path/to/my-config.yaml
Default values are applied for any key not present in the file. See Default values for the full list.

​
Complete reference

The annotated example below shows every supported key. Comment out or omit any section you don’t need — the pipeline fills in defaults automatically. 
# Source of documents to index
source:
  type: local          # local | web | pdf | kiwix
  path: ./my_docs      # (local/pdf) directory or file path
  # urls_file: ./urls.txt   # (web) one URL per line
  # zim_file: ./wikipedia.zim  # (kiwix) path to .zim file

# Rendering / ingest settings
ingest:
  backend: cdp         # cdp (default, fastest) | playwright
  quality: 85          # JPEG quality 1-100
  tile_height: 8192    # max tile height in pixels
  wait_network_idle: false  # true for JS-heavy pages (disables turbo path)

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

# Index backend settings
index:
  backend: faiss       # faiss (default) | qdrant
  # Qdrant-only options (when backend: qdrant):
  # qdrant_url: http://localhost:6333
  # collection: pixelrag
  # client_config: ./qdrant-client.json
  # quantization_config: ./quantization.json
  # append: false      # add to existing collection
  # recreate: false    # replace existing collection

# Output directory for all pipeline artifacts
output: ./my_index

​
Source types

The source.type field selects which document provider the pipeline uses. Each type has its own required and optional fields.
TypeDescriptionRequired fieldsOptional fields
localIndexes files from a directory. Supports PDF, HTML, Markdown, and images.path—
webIndexes URLs read from a plain-text file (one URL per line).urls_file or preset—
pdfIndexes a single PDF file or a directory of PDFs.path—
kiwixIndexes articles from a Kiwix ZIM archive served locally via kiwix-serve.zim_filekiwix_serve_url, book_name, num_kiwix_instances
The web source type automatically sets wait_network_idle: true unless you explicitly override it in the ingest section. This is because web URLs frequently serve JavaScript-rendered content that loads after the initial page load event. For all other source types (local, pdf, kiwix) the default is false, since their content is ready before load fires — and enabling it would cost ≥500 ms per page and disable the turbo capture path.

​
Default values

These are the values PixelRAG applies when a key is absent from pixelrag.yaml. They come from DEFAULT_CONFIG in config.py:
KeyDefaultNotes
ingest.backend"cdp"Fastest rendering backend.
ingest.quality85JPEG quality for tile images.
ingest.tile_height8192Maximum tile height in pixels.
embed.model"Qwen/Qwen3-VL-Embedding-2B"HuggingFace model used for visual embeddings.
embed.device"cuda"Override with auto, mps, or cpu as needed.
output"./index"Directory for tiles, embeddings, and index files.

​
Department-based filtering

When your source is a local directory, PixelRAG automatically assigns a department to each document based on its location in the directory tree. The department is the first subdirectory under the source path that contains the file. Example directory layout: 
docs/
├── engineering/
│   └── report.pdf          → department = "engineering"
├── marketing/
│   └── campaign-brief.pdf  → department = "marketing"
└── overview.pdf            → department = "" (no department)
With a config like: 
source:
  type: local
  path: ./docs
A file at ./docs/engineering/report.pdf is indexed with department="engineering". A file directly under ./docs/ has no department (empty string). At search time, pass the department field to restrict results to a single department: 
{
  "queries": [{ "text": "system architecture" }],
  "department": "engineering"
}
The department filter is a true pre-filter inside the vector backend — not post-filtering — so n_docs results are always returned when the department has enough indexed content.

Build docs developers (and LLMs) love

Get started for freeTalk to us