---

name: pixelrag description: "Use PixelRAG for visual document RAG: screenshot capture, visual index building, FAISS/Qdrant serving, evaluation reproduction, and LoRA training/data workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

PixelRAG

Use this skill when a task names PixelRAG, pixelshot, pixelrag, visual RAG over screenshots, document screenshot tiles, Qwen3-VL visual embeddings, FAISS/Qdrant visual indexes, PixelRAG search APIs, paper reproduction, or the PixelRAG LoRA training data pipeline.

First Checks

• Check staleness: Read repo-provenance.md before using this skill with a checkout; refresh if the commit, package version, or evidence paths changed.
• Install minimally: Base capture is pip install pixelrag. Add only the needed extra: pixelrag[index], pixelrag[serve], pixelrag[qdrant], pixelrag[pdf], or pixelrag[dev].
• Verify commands:

  python -c "import pixelrag, pixelrag_render; print('ok')"
  pixelshot --help
  pixelrag --help
  

• Run diagnostics: Use pixelrag_doctor.py before deeper debugging.
• Read troubleshooting: Use troubleshooting.md for install, optional dependency, CUDA, Chrome, model-download, data/config, and stale-skill failures.

Route by Task

User request	Use this route
Capture URLs, authenticated browser pages, PDFs, HTML, text, or images into screenshot tiles	render-capture
Build a local visual index from documents, debug pixelrag.yaml, chunk/embed/build FAISS or Qdrant indexes	index-build
Start or query pixelrag serve, call /search, use FAISS/Qdrant backends, fetch tile images, debug departments	serve-search
Reproduce paper benchmark cells, configure reader/search serves, run eval graders, debug low scores	evaluation-reproduction
Use the released LoRA adapter, prepare synthetic data, run or debug the separate training project	training-and-data

Minimal Patterns

Render a page or local file:

pixelshot https://example.org --output ./tiles
pixelshot paper.pdf --output ./tiles --dpi 200

Build an index from local documents:

source:
  type: local
  path: ./my_docs
embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto
output: ./my_index

pixelrag index build --config pixelrag.yaml --limit 10

Serve and search:

pixelrag serve --index-dir ./my_index --articles-json ./my_index/articles.json --tiles-dir ./my_index/tiles --port 30001
curl -s -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries":[{"text":"overview diagram"}],"n_docs":5}'

References

• install-and-routing.md covers package extras, CLI dispatch, and workflow selection.
• agent-integration.md covers hosted API use, pixelbrowse, and agent/tool integration boundaries.
• deployment-and-operations.md covers production topology and safe blue-green deployment concepts.
• repo-routing-metadata.json is structured router metadata for managed repo-skill import.

Important Boundaries

• Do not treat full embedding, benchmark reproduction, or training as cheap: they may download large Qwen/HF assets, load huge FAISS indexes, start long-running services, require GPUs, and consume paid API keys.
• The train/ workflow is a separate uv project. Do not install it into the root PixelRAG package environment unless the task explicitly asks for training.
• Do not run deploy scripts, systemd units, or nginx switch scripts unless the user confirms they are on the deploy host and wants operational changes.
• Do not depend on original repo examples, docs, or tests at runtime; this skill bundles distilled references and safe helper scripts.