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.

By default PixelRAG stores vectors in a local FAISS index — a flat binary file that is fast to load and requires no extra infrastructure. Qdrant is the right choice when you need features that FAISS cannot provide: configurable quantization to reduce memory use, disk-backed vectors that survive server restarts, payload filtering at query time, or a single collection shared by multiple PixelRAG server instances. Both backends produce identical search results for the same index, so you can start with FAISS and migrate to Qdrant later without retraining.

​
Install

Install the qdrant extra alongside the stage you are using. You need it for whichever of index or serve you are running — install both if you are doing both on the same machine: 
pip install 'pixelrag[serve,qdrant]'   # or 'pixelrag[index,qdrant]'

​
Start a local Qdrant server

The quickest way to get a Qdrant server running locally is with Docker: 
docker run -p 6333:6333 qdrant/qdrant
The server listens on http://localhost:6333 and is ready to accept collections immediately.

​
Build an index against Qdrant

Run pixelrag build-index with --backend qdrant to write vectors into a Qdrant collection instead of a local FAISS file: 
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index \
    --backend qdrant --qdrant-url http://localhost:6333 --collection pixelrag
Flags:
FlagDescription
--backend qdrantSelect the Qdrant backend
--qdrant-urlQdrant server URL
--collectionCollection name (default: pixelrag)
--qdrant-quantization-configPath to a JSON file with a Qdrant quantization config
--appendAdd vectors to an existing collection without recreating it
--recreateDelete and recreate the collection before indexing

​
Quantization

Qdrant supports scalar and product quantization to compress stored vectors, which reduces memory consumption and can speed up search at a configurable recall tradeoff. Create a JSON file with your quantization_config object: 
{
  "scalar": {
    "type": "int8",
    "quantile": 0.99,
    "always_ram": true
  }
}
Pass it to build-index: 
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index \
    --backend qdrant --qdrant-url http://localhost:6333 --collection pixelrag \
    --qdrant-quantization-config ./quantization.json
The int8 scalar method compresses each 32-bit float to 8 bits (4× compression), with always_ram: true keeping the quantized vectors in RAM for low-latency search while leaving the full-precision originals on disk. See Qdrant’s quantization guide for all supported methods and parameters.

​
Serve from Qdrant

Start pixelrag serve with --qdrant-url to connect to your collection. The server reads the backend type (qdrant) from summary.json automatically — you do not need to pass --backend qdrant at serve time: 
pixelrag serve --index-dir ./index --qdrant-url http://localhost:6333 \
    --qdrant-client-config ./qdrant-client.json --port 30001
--qdrant-client-config is a path to a JSON file containing any QdrantClient constructor arguments (for example, TLS settings or timeout overrides). At serve time, summary.json supplies the collection name, so you only need --collection if you want to override it.

​
pixelrag.yaml configuration

To use Qdrant through the orchestrated pixelrag index build pipeline, add an index: section to your pixelrag.yaml: 
index:
  backend: qdrant
  qdrant_url: http://localhost:6333
  collection: pixelrag
  client_config: ./qdrant-client.json
  quantization_config: ./quantization.json
  # append: true
  # recreate: true
Uncomment append: true to add documents to an existing collection, or recreate: true to replace it. Both flags are mutually exclusive; recreate takes precedence if both are set.
Qdrant Cloud — replace qdrant_url with your Qdrant Cloud cluster URL and pass --qdrant-api-key (or set the QDRANT_API_KEY environment variable) to authenticate. The qdrant-client.json approach also works: add an "api_key" field to the JSON object alongside the "url" so credentials stay out of the command line.

Build docs developers (and LLMs) love

Get started for freeTalk to us