StarTrail-org/PixelRAG · 上手攻略

仓库：StarTrail-org/PixelRAG
链接：https://github.com/StarTrail-org/PixelRAG
分类：engineering · agent · rag · multimodal
作者：Tom
更新：2026-07-08

一、是什么

PixelRAG 是一个基于视觉渲染的 RAG（检索增强生成）系统，核心思想：把文档（网页、PDF）渲染成截图切片（screenshot tiles），再对图片做向量检索，而不是解析 HTML 提取文本。传统 RAG 丢掉的表格、图表、排版信息，在 PixelRAG 里完整保留，读者模型可以直接"看"到原始视觉布局。

源自 Berkeley SkyLab、BAIR 和 Berkeley NLP 的论文 PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation（arXiv 2606.28344），生产级项目，Apache-2.0 许可。

二、解决什么问题

传统 RAG 的盲区： HTML 解析会丢失表格结构、图表信息、排版层次。多栏布局、嵌入图表、PDF 里非文字内容，用文本 chunk 检索效果很差。

典型失败场景： - Wikipedia 页面里一张表格中藏着答案，文本检索无法捕获 → PixelRAG 渲染截图后直接命中该页面 - PDF 里的流程图、架构图，文字提取后变成乱码 token → PixelRAG 保留完整视觉

核心改进： 1. 用 Playwright/CDP 将文档渲染为图片切片，而非解析 HTML 2. 用 LoRA 微调后的 Qwen3-VL-Embedding-2B 对截图做视觉向量编码 3. FAISS 向量检索返回最相关的截图，再由读者模型从图像中提取答案

三、快速安装

# 基础安装（包含 pixelshot CLI 和核心 pipeline）
pip install pixelrag

# 本地索引构建（embed + build-index）
pip install 'pixelrag[index]'

# 本地 FastAPI 搜索服务
pip install 'pixelrag[serve]'

# PDF 支持（需要 poppler-utils）
pip install 'pixelrag[pdf]'

⚠️ Python 3.10+。CUDA/Linux 自动用 GPU，macOS Apple Silicon 自动 MPS，均可 fallback CPU。

Claude Code 插件方式（无需 clone）：

# 安装 pixelshot CLI（推荐用 uv tool 或 pipx 隔离安装）
uv tool install pixelrag   # pipx install pixelrag 也可以

# 添加 Claude Code 插件
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

# 直接用自然语言让 Claude 截图读网页
claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findings"

四、核心用法

4.1 最简体验：搜索 8.28M Wikipedia（零建索引）

# 调用官方托管 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}'

支持图片作为查询（visual search）：把一张截图 POST 上去，在视觉空间里找相似页面。API 状态页：https://api.pixelrag.ai/status

4.2 本地文档构建索引并搜索

pip install 'pixelrag[index]'

# 1. 创建配置文件
cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./my_docs

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto   # cuda / mps / cpu 自动选择

output: ./my_index
EOF

# 2. 构建索引
pixelrag index build

# 3. 启动本地搜索服务
pixelrag serve --index-dir ./my_index --port 30001

# 4. 查询
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "关键信息是什么"}], "n_docs": 5}'

4.3 PDF 索引示例

pip install 'pixelrag[index]'

# 下载示例 PDF
curl -sL -o paper.pdf \
  https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf

cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./paper.pdf
embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto
output: ./paper_index
EOF

pixelrag index build
pixelrag serve --index-dir ./paper_index --port 30001

⚠️ PDF 渲染需要系统安装 poppler：sudo apt install poppler-utils（Linux）或 brew install poppler（macOS）。

4.4 分步 Pipeline（跳过 orchestrator）

pip install 'pixelrag[embed]'

# 1. 截图
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

# 2. 切分 tiles
pixelrag chunk --tiles-dir ./tiles

# 3. 向量编码（可多 GPU）
pixelrag embed --shard-dir ./tiles --output-dir ./embeddings --gpu-ids 0,1

# 4. 构建 FAISS 索引
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index

4.5 下载预训练 LoRA 适配器（HuggingFace）

无需重新训练，直接使用论文提供的微调权重：

# 模型权重在 HuggingFace：Chrisyichuan/wiki-screenshot-embedding-lora
# 配合 Qwen/Qwen3-VL-Embedding-2B 使用，详见 HuggingFace 仓库

五、典型适用场景

场景	为什么选 PixelRAG
视觉密集型文档（PDF 报告、财报、论文图表）	HTML 解析丢失排版和图表，截图完整保留
Agent 读网页（研究助手、新闻摘要）	渲染截图比 HTML 更忠实于人类看到的内容
Wikipedia / 知识库问答	已有 8.28M 页面预建索引，零成本启动
需要跨模态检索的 RAG	文字 + 图表混合内容，一套索引搞定
对比实验：文本 RAG vs 视觉 RAG	同一数据集，两种检索方式直接对照

六、坑与注意

Chrome 依赖（Linux）： Linux x86_64 需要系统安装 Chrome/Chromium。其他平台从标准路径自动检测，找不到时设置 CHROME_PATH=/path/to/chrome。
PDF 需要 poppler： Linux sudo apt install poppler-utils，macOS brew install poppler，否则 PDF 转截图可能失败或质量差。
Apple Silicon MPS 后端： 首次运行会触发 MPS 编译，较慢（约 3-5 分钟），之后有缓存提速明显。
大索引磁盘占用： Wikipedia 预建索引约 217 GB（base + LoRA 版本），个人使用建议从小规模本地文档集开始。
预训练 LoRA 使用方式： LoRA 适配器需配合基座模型 Qwen/Qwen3-VL-Embedding-2B 加载，详细用法参考 HuggingFace 仓库说明（非开箱即用）。
训练需要独立环境： train/ 是单独的 uv 项目（torch==2.9.1+cu129, transformers==4.57.1），需 cd train && uv sync 后运行，不是 pip install pixelrag 能覆盖的。
Windows Chrome： 支持，与 macOS/Linux 相同，独立临时 profile 机制。

七、与同类对比

方案	检索方式	视觉保真度	搭建成本	适用内容类型
传统文本 RAG（LlamaIndex/LangChain）	文本向量	❌ 无	低	结构化文本为主
RAGFlow	PDF 解析 + 文本 chunk	⚠️ 中（依赖解析质量）	中	文档理解型
PixelRAG	截图视觉向量	✅ 高（像素级）	中（建索引需 GPU）	视觉密集型
Unstructured.io	多模态解析	⚠️ 中	中	混合文档

选择建议： - 文档以文字为主、无复杂排版 → 传统 RAG 够用，成本低 - 需要从图表、表格中提取答案 → PixelRAG 显著优于文本方案 - 需要快速启动 Wikipedia 问答 → 直接调 PixelRAG 托管 API，零运维

八、一句话推荐结论

PixelRAG 用"截图替代文字"打开了视觉 RAG 的大门——对于表格密集的财报、图表密集的论文、版式复杂的 PDF，它比任何 HTML 解析方案都更接近人类阅读体验；Claude Code 插件形式更是让 AI 直接"看"网页变成了零配置操作。