Running PixelRAG as a Production Pipeline

The operational value of PixelRAG is its stage boundaries. Rendering a page, embedding tiles, building an index, and serving queries are separate concerns with different failure modes. Treating them as one clever demo makes the system hard to operate; treating them as inspectable stages makes it possible to run a controlled visual-retrieval service.

Rendering is a data-quality operation

A screenshot is not automatically faithful evidence. Pages may depend on fonts, JavaScript, lazy loading, cookie state, viewport width, and network readiness. PixelRAG’s newer releases address practical issues such as network-idle readiness, source-aware manifests, incremental reruns, local image inputs, Markdown rendering, wide-page tiling, and browser attachment. These are not cosmetic improvements: a wrong render produces a plausible but invalid index.

Keep the base install small

The root package supports the light `pixelshot` and umbrella CLI. Heavy retrieval stages are opt-in extras, while training lives in its own pinned environment. A sensible deployment starts with capture-only validation, then adds embedding and serving once the input corpus and query set are stable.

pip install pixelrag
pip install "pixelrag[index]"
pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001

Choose the index backend for the operating model

FAISS is a good local baseline. Qdrant becomes attractive when teams need disk-backed vectors, payload filters, quantization, append/recreate workflows, or one collection shared by multiple servers. The choice should be tested against incremental updates and recovery, not only top-k latency.

The resource boundary is real

The official documentation uses a roughly 217G base FAISS index as a concrete download example. The evaluation notes describe substantially larger combined requirements for indexes, models, and tiles. Hosted search is useful for a proof of concept; self-hosting needs a storage budget, GPU or CPU plan, tile delivery strategy, and a retention policy for rendered documents.

A production rollout pattern

The project’s deployment notes use two search API slots behind nginx. The idle slot is started and checked before traffic is switched, because reloading a large FAISS index in place can cause minutes of downtime. The same principle applies to model or index upgrades: version the artifact, run known queries, verify returned images, switch traffic, and keep the previous slot available for rollback.

Operational acceptance criteria

Before expanding the corpus, require reproducible manifests, stable source identifiers, health checks, representative queries, resource ceilings, and an explicit rollback command. A visual RAG service should be observable as a pipeline: when an answer is wrong, the operator must be able to tell whether capture, retrieval, image delivery, or reading failed.