> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/StarTrail-org/PixelRAG) · [上游 README](https://github.com/StarTrail-org/PixelRAG/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 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 一双「眼睛」 ·
工作原理 ·
流水线
---
```bash
pip install pixelrag
```
两大核心操作——将页面**渲染（render）**为截图，并在视觉索引中**搜索（search）**：
```bash
# 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`](https://api.pixelrag.ai/status) 提供由 **8.28M** 篇 Wikipedia 页面构成的预构建索引。无需配置，无需 API 密钥。查询甚至可以是图片（[视觉搜索（visual search）](https://pixelrag.ai/docs#search)) — 详见 **[API 参考 →](https://pixelrag.ai/docs)**.
或在浏览器中访问 **[pixelrag.ai](https://pixelrag.ai)**,，或在 Colab 中运行演示 notebook [](https://colab.research.google.com/github/StarTrail-org/PixelRAG/blob/main/demos/quickstart.ipynb) — 它会渲染页面并搜索托管索引，图像内联显示。
## 它是什么
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` 中）：
```bash
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 查看某个页面即可：
```bash
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 `。只需安装你需要的阶段：
| 命令 | 功能 | 安装 |
| ------------------------------------------ | --------------------------------------------------------------- | ------------------------------- |
| `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/` 内部安装，而非在仓库根目录。
### 搜索预构建索引
```bash
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` 会自动选择最佳后端。
```bash
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+ 的机器上运行。
```bash
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}'
```
### 以编程方式渲染页面
```python
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` 一起提供：
```bash
# 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）：
```bash
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`](train/README.md)。
使用模型无需自行重新训练 — 训练好的适配器已发布在 [`Chrisyichuan/wiki-screenshot-embedding-lora`](https://huggingface.co/Chrisyichuan/wiki-screenshot-embedding-lora/tree/main/lora_vit/ckpt200).
我们还发布了完整训练集（[`Chrisyichuan/screenshot-training-natural-filtered-v2`](https://huggingface.co/datasets/Chrisyichuan/screenshot-training-natural-filtered-v2)),），方便你自行适配其他骨干模型 — 例如更大的 Qwen，或任意其他嵌入模型。数据整理流水线（LLM 增强的查询生成、过滤、困难负样本挖掘）详见 [`train/docs/synthetic_data_pipeline.md`](train/docs/synthetic_data_pipeline.md)。
## 引用
如果你觉得 PixelRAG 有用，请引用我们的论文：
```bibtex
@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](https://rulinshao.github.io/) 的支持。
同时感谢 [Claude Code](https://github.com/anthropics/claude-code) 和
[OpenAI Codex](https://github.com/openai/codex) 为开源贡献者提供积分与方案支持，
这些支持是我们在参与 [LEANN](https://github.com/StarTrail-org/LEANN). 工作期间获得的。
本工作由 [Berkeley Sky Computing Lab](https://sky.cs.berkeley.edu/),
[BAIR](https://bair.berkeley.edu/), 与 [Berkeley NLP Group](https://nlp.cs.berkeley.edu/). 完成。
## 许可证
Apache-2.0