startrail-org--pixelrag/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation 的官方代码库

Yichuan Wang*, Zhifei Li*, Zirui Wang, Paul Teiletche, Lesheng Jin
Matei Zaharia†, Joseph E. Gonzalez†, Sewon Min†

_{* 同等贡献   † 同等指导
工作完成于 Berkeley SkyLab & BAIR & Berkeley NLP}

按文档的外观搜索，而不仅仅看它包含的文字。

它是什么 · 给 Claude 一双「眼睛」 · 工作原理 · 流水线

---

pip install pixelrag

两大核心操作——将页面渲染（render）为截图，并在视觉索引中搜索（search）：

# Render any page or document to screenshot tiles
pixelshot https://en.wikipedia.org/wiki/Python --output ./tiles

# Search a hosted index of 8.28M Wikipedia pages — no setup, runs against the live API
curl -X POST https://api.pixelrag.ai/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'

在线托管端点 — https://api.pixelrag.ai 提供由 8.28M 篇 Wikipedia 页面构成的预构建索引。无需配置，无需 API 密钥。查询甚至可以是图片（视觉搜索（visual search）) — 详见 API 参考 →.

或在浏览器中访问 pixelrag.ai,，或在 Colab 中运行演示 notebook — 它会渲染页面并搜索托管索引，图像内联显示。

它是什么

PixelRAG 将文档——网页、PDF、图像——渲染为截图，并直接在图像上进行检索。HTML 解析会丢弃的视觉结构——表格、图表、版式、信息图——得以保留，因此阅读模型能够真正回答相关问题。Wikipedia 的 8.28M 篇文章以预构建索引形式提供；流水线本身则是通用型的。

给 Claude 一双「眼睛」

渲染器还以 Claude Code 插件形式提供——pixelbrowse 技能。Claude 不再抓取原始 HTML，而是用 pixelshot 对页面截图并阅读图像，从而像人一样看到图表、示意图、表格和版式。

安装即可——无需克隆仓库。安装 pixelshot CLI，使其位于你的 PATH 上（使用 uv tool 或 pipx，既可隔离环境，又随时可供 Claude 使用——仅向项目 venv 执行普通 pip install 可能会使 pixelshot 不在 PATH 中）：

uv tool install pixelrag                            # pixelshot on PATH (or: pipx install pixelrag)
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

然后直接让 Claude 查看某个页面即可：

claude -p "screenshot https://news.ycombinator.com and summarize the top stories"
claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findings"

或在交互式会话中使用斜杠命令：/screenshot https://example.com。 无需 MCP 服务器，也无需后端：该技能只在你本机调用 pixelshot（Playwright/CDP）。

工作原理

基于文本的 RAG 将页面解析为文本块并丢失表格——阅读器找不到答案。PixelRAG 将页面渲染为截图分块（screenshot tiles），检索到正确的分块后，阅读器可直接从图像中读取数字。

实现这一点需要两个组件：(1) 将文档渲染为图像，而非解析为文本；(2) 一个在截图数据上经 LoRA 微调的 Qwen3-VL-Embedding 模型，将页面图像嵌入到可视内容可检索的空间中。

流水线

Capture 是独立的 pixelshot 命令；流水线的其余部分通过 pixelrag 总入口运行——pixelrag <stage>。只需安装你需要的阶段：

命令	功能	安装
pixelshot	文档 → 图像分块（Playwright CDP、PDF）	pip install pixelrag
pixelrag chunk · embed · build-index	分块 → 向量 → FAISS 索引	pip install 'pixelrag[embed]'
pixelrag index	编排完整流水线：源 → 摄取 → 嵌入 → 索引	pip install 'pixelrag[index]'
pixelrag serve	FAISS 搜索 API（FastAPI，CPU 或 GPU）	pip install 'pixelrag[serve]'

render ←── index ──→ embed       serve (independent)       train → serve (HTTP)

train 是一个独立的 uv 项目，拥有各自锁定的环境（torch==2.9.1+cu129、 transformers==4.57.1、cuDNN 9.20）——请在 train/ 内部安装，而非在仓库根目录。

搜索预构建索引

pip install 'pixelrag[serve]'

# Download a pre-built index from Hugging Face. The dataset repo holds four FAISS indexes
# (base/LoRA Wikipedia pixel, Wikipedia text, news pixel); grab just the base one (~217G) here.
huggingface-cli download StarTrail-org/pixelrag-faiss-indexes \
  --repo-type dataset --include "search_index_normed_v2/*" --local-dir ./index

# Serve, then query
pixelrag serve --index-dir ./index/search_index_normed_v2 --port 30001

curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'

用自己的文档构建索引

适用于 Linux（CUDA） 和 macOS（Apple Silicon / MPS）——device: auto 会自动选择最佳后端。

pip install 'pixelrag[index]'

# Create pixelrag.yaml
cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./my_docs

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto          # cuda on Linux, mps on macOS, cpu as fallback

output: ./my_index
EOF

# Build, then serve
pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001

试试看：索引 PDF 并在本地搜索

无需 GPU — 可在 macOS（Apple Silicon）或任何装有 Python 3.10+ 的机器上运行。

pip install 'pixelrag[index]'

# 1. Grab a sample PDF (or use your own)
curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf

# 2. Create config (device: auto picks MPS on Mac, CUDA on Linux)
cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./paper.pdf

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

output: ./paper_index
EOF

# 3. Build the index (~3 min on Apple M-series, ~1 min on GPU)
pixelrag index build

# 4. Serve it
pixelrag serve --index-dir ./paper_index --port 30001

# 5. Search — should return page 2 (the overview diagram)
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "Overview of PixelRAG and the diagram"}], "n_docs": 1}'

以编程方式渲染页面

from pixelrag_render import render_url

# render a single page to tiles — e.g. for an agent to read
tiles = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")

同样的渲染能力也可通过 CLI 使用 — pixelshot 随 pip install pixelrag 一起提供：

# Web page → tiles (headless Chromium via CDP)
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

# PDF → tiles (requires poppler; install the pdf extra: pip install 'pixelrag[pdf]')
curl -sL -o paper.pdf https://arxiv.org/pdf/2503.09516
pixelshot paper.pdf -o ./tiles --dpi 200

# URLs and local files can be mixed freely
pixelshot https://github.com/StarTrail-org/PixelRAG paper.pdf -o ./tiles

Windows/macOS 上的 Chrome — 捆绑的 turbo headless_shell 仅在 linux-x64 上自动安装。在其他平台上，pixelshot 会使用你系统中的 Chrome/Chromium（或 Playwright 的 Chromium），从标准安装位置自动检测。若无法自动找到，可通过 CHROME_PATH=/path/to/chrome 指定具体可执行文件路径。每次渲染都在隔离的临时 Chrome 配置文件中运行，因此即使你正在使用 Chrome 也能正常工作。

嵌入工具（独立运行）

各阶段可独立运行，无需编排器（orchestrator）：

pip install 'pixelrag[embed]'

pixelrag chunk --tiles-dir ./tiles
pixelrag embed --shard-dir ./tiles --output-dir ./embeddings --gpu-ids 0,1
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index

训练

微调代码位于 train/ — 这是一个 独立的 uv 项目（wiki-screenshot-training），拥有自己固定版本的环境。它对 Qwen/Qwen3-VL-Embedding-2B 进行 LoRA 微调，用于网页检索；请在 train/（cd train && uv sync）内运行。完整流程请参阅 train/README.md。

使用模型无需自行重新训练 — 训练好的适配器已发布在 Chrisyichuan/wiki-screenshot-embedding-lora.

我们还发布了完整训练集（Chrisyichuan/screenshot-training-natural-filtered-v2),），方便你自行适配其他骨干模型 — 例如更大的 Qwen，或任意其他嵌入模型。数据整理流水线（LLM 增强的查询生成、过滤、困难负样本挖掘）详见 train/docs/synthetic_data_pipeline.md。

引用

如果你觉得 PixelRAG 有用，请引用我们的论文：

@misc{wang2026pixelragwebscreenshotsbeat,
      title={PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation}, 
      author={Yichuan Wang and Zhifei Li and Zirui Wang and Paul Teiletche and Lesheng Jin and Matei Zaharia and Joseph E. Gonzalez and Sewon Min},
      year={2026},
      eprint={2606.28344},
      archivePrefix={arXiv},
      primaryClass={cs.IR},
      url={https://arxiv.org/abs/2606.28344}, 
}

致谢

感谢 Rulin Shao 的支持。

同时感谢 Claude Code 和 OpenAI Codex 为开源贡献者提供积分与方案支持， 这些支持是我们在参与 LEANN. 工作期间获得的。

本工作由 Berkeley Sky Computing Lab, BAIR, 与 Berkeley NLP Group. 完成。

许可证

Apache-2.0