StarTrail-org/PixelRAG

pip install pixelrag

两个核心操作——将页面渲染为截图，在视觉索引中搜索：

# 将任何页面或文档渲染为截图瓦片
pixelshot https://en.wikipedia.org/wiki/Python --output ./tiles

# 搜索托管了828万维基百科页面的索引——无需设置，直接调用实时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 提供了 828万维基百科页面的预构建索引。无需设置，无需API密钥。它甚至支持以图像作为查询 （视觉搜索）——请参阅 API参考 →。

或者直接在浏览器中尝试 pixelrag.ai，或在Colab中运行演示笔记本 —— 它 会渲染一个页面并搜索托管索引，图像内联显示。

它是什么

PixelRAG将文档——网页、PDF、图像——渲染为截图，并直接在图像上进行检索。HTML解析会丢弃的视觉结构——表格、图表、布局、信息图——得以完整保留，因此阅读器模型能够真正回答关于它们的问题。维基百科的828万篇文章以预构建索引的形式提供；流水线本身是通用的。

给Claude装上眼睛

渲染器还作为Claude Code插件提供——即pixelbrowse技能。Claude不再获取原始HTML，而是使用pixelshot截取页面截图并_读取图像_，从而像人类一样看到图表、图示、表格和布局。

安装它——无需克隆（pixelshot来自pip install pixelrag）：

pip install pixelrag                                # 提供pixelshot命令
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将页面渲染为截图瓦片，检索正确的瓦片，阅读器直接从图像上读取数字。

两个部分使其工作：(1) 将文档渲染为图像而非解析为文本，以及(2) 一个Qwen3-VL-Embedding模型，经过截图数据的LoRA微调，将页面图像嵌入到一个视觉内容可检索的空间中。

流水线

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

render ←── index ──→ embed       serve (独立)       train → serve (HTTP)

train是一个独立的uv项目，拥有自己固定的环境（torch==2.9.1+cu129，transformers==4.57.1，cuDNN 9.20）——从train/内部安装，而不是从根目录。

搜索预构建索引

pip install 'pixelrag[serve]'

# 从Hugging Face下载预构建索引。数据集仓库包含四个FAISS索引
# (base/LoRA维基百科像素、维基百科文本、新闻像素)；此处仅获取base索引（约217G）。
huggingface-cli download StarTrail-org/pixelrag-faiss-indexes \
  --repo-type dataset --include "search_index_normed_v2/*" --local-dir ./index

# 启动服务，然后查询
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]'

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

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto          # Linux上为cuda，macOS上为mps，CPU作为后备

output: ./my_index
EOF

# 构建，然后启动服务
pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001

无需GPU——可在macOS (Apple Silicon) 或任何安装了Python 3.10+的机器上运行。

pip install 'pixelrag[index]'

# 1. 获取一个示例PDF（或使用你自己的）
curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf

# 2. 创建配置（device: auto 在Mac上选择MPS，在Linux上选择CUDA）
cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./paper.pdf

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

output: ./paper_index
EOF

# 3. 构建索引（Apple M系列上约3分钟，GPU上约1分钟）
pixelrag index build

# 4. 启动服务
pixelrag serve --index-dir ./paper_index --port 30001

# 5. 搜索——应返回第2页（概览图）
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

# 将单个页面渲染为瓦片——例如供agent读取
tiles = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")

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

# 网页 → 瓦片（通过CDP的无头Chromium）
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

# PDF → 瓦片（需要poppler；安装pdf扩展：pip install 'pixelrag[pdf]'）
curl -sL -o paper.pdf https://arxiv.org/pdf/2503.09516
pixelshot paper.pdf -o ./tiles --dpi 200

# URL和本地文件可以自由混合
pixelshot https://github.com/StarTrail-org/PixelRAG paper.pdf -o ./tiles

嵌入工具（独立使用）

每个阶段独立运行，无需编排器：

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，或任何其他embedding模型。 数据整理流水线（LLM增强的查询生成、过滤、难负样本挖掘）在 train/docs/synthetic_data_pipeline.md中有文档说明。

致谢

感谢 Rulin Shao 的支持。

同时感谢 Claude Code 和 OpenAI Codex 为开源贡献者提供积分和计划支持， 我们通过参与 LEANN 项目获得了这些支持。

本工作由 Berkeley Sky Computing Lab、 BAIR 和 Berkeley NLP Group 完成。

许可证

Apache-2.0