PixelRAG 新手教程

01这是什么

一句话：搜索任何文档时按「它长什么样」来找，而不是只按它包含的文字。

PixelRAG（arXiv 2606.28344，Berkeley SkyLab / BAIR / Berkeley NLP）是一个视觉检索增强生成框架：它把网页、PDF、图片渲染成截图瓦片，用专门微调的视觉嵌入模型直接在图像空间做检索。传统 RAG 要把页面解析成文本块——这一步会把表格、图表、信息图的视觉结构拍平丢掉；PixelRAG 跳过这一步，让阅读模型直接从图上读数。

02为什么需要它

想想那个经典翻车现场：答案明明在页面表格里，RAG 就是答不出来。

原因是结构性的：HTML 解析成文本块时，<table> 的行列关系、单元格合并、图表坐标轴都会被拍平。数字还在，但它依赖的视觉上下文没了。此前社区的三种 workaround，各有各的疼：

效果有论文背书：Natural Questions 上 PixelRAG 取得 57.9（LLM judge 口径）的成绩；注意严格 exact-match 口径约 29%——论文用的是语义判分，看数字时先对齐口径。

03核心流程

五个阶段组成建索引管道，三步完成一次查询。每个阶段都可以独立安装、独立运行。

两大件让这条路走得通：（1）渲染器 pixelshot，用 headless Chrome（Playwright / CDP）把页面和 PDF 切成纵向瓦片；（2）嵌入模型 Qwen3-VL-Embedding-2B 的 LoRA 微调版，把页面图像嵌进一个「视觉内容可检索」的向量空间。模型权重和训练集都已开源，不想微调可以直接用。

04安装

一条命令装基础版；按需加装 extras，管道每个阶段独立分发。

pip install pixelrag

05环境自检

装完先跑 30 秒冒烟，把浏览器和依赖问题拦在实战之前。

pixelshot --version                              # CLI 在不在 PATH
pixelshot https://example.com -o ./smoke         # 渲染一页试试
ls ./smoke/*/ | head                             # 有瓦片 + tiles.json 就绪

06第一次实战：5 分钟跑通

不求全：先把「渲染任意页面」和「搜 828 万维基页面」两个能力跑起来，全程不需要自建索引。

第一步：渲染任意网页为瓦片

pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

跑完在 ./tiles/ 下能看到按纵向切好的截图瓦片和一个 tiles.json 清单（下一节细看）。

第二步：免搭建，直接搜官方托管索引

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}'

返回 JSON，hits 里是按相关度排序的命中瓦片（带 score、来源 URL 等）：

{
  "results": [{
    "hits": [
      { "score": 0.73, "url": "https://en.wikipedia.org/wiki/...", "article_id": 123 }
    ]
  }]
}

07产物长什么样

渲染产物就两样：一组纵向瓦片 + 一份清单。理解它们，就理解了 PixelRAG 的检索粒度。

./tiles/
└── Python.png.tiles/
    ├── tile_0000.jpg     # 页面第 1 屏
    ├── tile_0001.jpg     # 页面第 2 屏
    ├── ...
    └── tiles.json        # 清单：瓦片顺序、来源 URL、页码等

08在 Cursor CLI 里用

官方插件目前只覆盖 Claude Code（pixelbrowse）和 opencode（@startrail/pixelbrowse）。Cursor CLI 没有插件市场，但没关系——插件的本质只是「教 agent 何时调 pixelshot、然后读返回的图」，这两件事 Cursor CLI 原生都做得到。

原理一句话：pixelshot 是个普通 CLI，Cursor CLI 的 agent 既能执行 shell 命令，又能把生成的瓦片图片读进上下文（多模态读图）——这正是 pixelbrowse 在 Claude Code 里做的事，机制完全一致。缺的只是「教它」，而这恰好是 Cursor 项目规则 .cursor/rules/*.mdc 的本职。三条路径按投入从低到高：

第 0 步（一次性）：让 Cursor 能摸到 pixelshot

uv tool install pixelrag      # 或 pipx install pixelrag，pixelshot 常驻 PATH
pixelshot --version           # 确认装好了

路径 A：零配置，自然语言直接指挥

cursor-agent "用 pixelshot 把 https://arxiv.org/abs/2606.28344 渲染到 ./tiles，然后读图总结这篇论文的架构图"

agent 会执行 pixelshot <url> -o ./tiles，再把瓦片读进来作答。不想敲命令行，直接在 cursor-agent 交互会话里说同样的话也行。适合偶尔用一次；用得频繁就升级到路径 B。

路径 B：写一份项目规则（一次配置，长期生效）

在项目里新建 .cursor/rules/pixelshot.mdc，内容直接抄（改写自官方 skill 提示词 skill/pixelrag.md，去掉了内部路径、并入 pixelbrowse 的默认参数）：

---
description: 用 pixelshot 截图网页/PDF 并读图回答，而不是抓原始 HTML
globs:
alwaysApply: true
---

# pixelshot — 给你装上"眼睛"

回答以下问题时，优先用 pixelshot 渲染后读图，而不是获取原始 HTML：
- 表格里的数字、合并单元格、行列关系
- 图表、架构图、流程图、信息图的内容
- PDF（论文、财报、文档）的版面与插图
- 页面的实际渲染效果（HTML 源码看不出布局时）

## 常用命令
- 网页:  pixelshot <url> -o ./tiles --tile-height 1568 --wait-network-idle
- PDF:   pixelshot paper.pdf -o ./tiles --dpi 200
- 混合:  URL 和本地文件可以混在一条命令里

## 渲染之后必须做
1. 读 ./tiles/ 下的 tiles.json，弄清瓦片顺序和来源
2. 按顺序读取 tile_*.jpg 图片，不要只看第一张
3. 引用答案时注明来自哪张瓦片

## 视觉检索（可选）
- 托管索引: curl -X POST https://api.pixelrag.ai/search \
    -H "Content-Type: application/json" \
    -d '{"queries":[{"text":"..."}],"n_docs":5}'
- 本地索引: 先 pixelrag serve --index-dir ./my_index --port 30001，
  再 curl http://localhost:30001/search（格式同上）

为什么这么写：alwaysApply: true 让所有会话都带上这条规则（放项目 .cursor/rules/ 即项目级生效；想全局生效可把同款文字填进 Cursor 设置的 User Rules）；--tile-height 1568 是官方 pixelbrowse 插件的默认值；而「渲染之后必须做」三步是最容易漏的——不写明，agent 可能 ls 一下就凭文件名猜答案。

配置完的会话体验：

你   : 帮我看看 arxiv.org/abs/2606.28344 这篇论文的 Figure 2 画的是什么
agent: ① pixelshot https://arxiv.org/abs/2606.28344 -o ./tiles \
         --tile-height 1568 --wait-network-idle
       ② 读 ./tiles/<页面名>.png.tiles/tiles.json → 共 N 张瓦片
       ③ 逐张读图，在 tile_0003.jpg 找到 Figure 2 ……
       答 : Figure 2 是文本 RAG 与 PixelRAG 的管道对比图：文本 RAG
            把表格拍平丢失结构，PixelRAG 保留截图瓦片……

路径 C：自建知识库 + 本地检索

把私有文档建成索引并本地起服务（建索引的完整步骤见下一节），之后在 Cursor 会话里让 agent 查询本地端口即可——命中瓦片由 agent 读图作答，私有知识全程不出本机（渲染公网页面除外）。

09进阶用法

PDF 渲染、自建索引、编程调用、大规模后端——按需取用。

渲染 PDF（论文、财报）——需要 pdf extra 和系统 poppler，URL 与本地文件可混着传：

pip install 'pixelrag[pdf]' && brew install poppler   # Debian/Ubuntu: apt-get install poppler-utils
curl -sL -o paper.pdf https://arxiv.org/pdf/2503.09516
pixelshot paper.pdf -o ./tiles --dpi 200
pixelshot https://github.com/StarTrail-org/PixelRAG paper.pdf -o ./tiles

给自己的文档建索引——写一份 pixelrag.yaml，一条命令建完，Linux 走 CUDA、macOS 走 MPS（device: auto 自动选）：

pip install 'pixelrag[index]'

cat > pixelrag.yaml << 'EOF'
source:
  type: local          # 支持 local / web / pdf 等来源
  path: ./my_docs

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto         # Linux→cuda · macOS→mps · 兜底 cpu

output: ./my_index
EOF

pixelrag index build                                          # M 系列芯片约 3 分钟（35 页论文量级）
pixelrag serve --index-dir ./my_index --port 30001            # 起本地搜索服务

编程式渲染——在 Python 里直接调，适合自己写 agent 循环：

from pixelrag_render import render_url

tiles = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")

大规模与省内存——FAISS 是默认后端；索引大了换 Qdrant（支持 int8 量化、磁盘向量、多服务共享一个 collection），加载大索引用 mmap 模式近即时启动：

PIXELRAG_INDEX_MMAP=1 pixelrag serve --index-dir ./big_index --port 30001

视觉搜索——托管 API 还接受图像作为查询（以图搜页）：把截图丢给它，返回视觉上最相关的维基页面。具体图像字段格式见官方 API 文档。

10不止于此

名字叫 PixelRAG，但它首先是一个「把文档变成 agent 可读图像」的渲染器——用途比 RAG 宽得多。

11性能与规模

官方给了从单机到全维基的真实数字——注意每一行的条件，脱离条件比数字没意义。

批量渲染那 109–130 瓦片/秒不是白来的：官方从 Playwright 基线的 20 瓦片/秒一路优化（直连 CDP、fonts.ready 事件驱动、Chromium 补丁绕过编码互斥锁、48 worker 工作窃取队列），累计 5.5 倍，而且每一步都做过 100% 像素级正确性校验——细节在 docs/screenshot-throughput-optimization.md。

12FAQ / 踩坑

每条都给可执行的解法，不做无用的道歉。

13合规与引用

代码 Apache-2.0，商用友好；模型权重与训练数据同样开源。

• 许可证：Apache-2.0，可自由使用、修改、商用（保留许可声明即可）。
• 渲染第三方网页的注意：个人研究、给自己或 agent 阅读一般没问题；但把截图公开再分发、或对外提供检索服务时，注意目标站点的服务条款与版权。
• 全开源全家桶：LoRA 权重（Chrisyichuan/wiki-screenshot-embedding-lora）与完整训练集（Chrisyichuan/screenshot-training-natural-filtered-v2）都在 Hugging Face，可换骨干模型自行微调。

论文引用：

@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}
}

14参考链接

官方资源清单 + 仓库地图，收藏这一页就够了。

仓库地图（看懂这个，找代码不迷路）：

render/   pixelshot 截图渲染（Playwright / CDP · PDF）
embed/    瓦片 → 向量（chunk · embed）
index/    向量 → FAISS / Qdrant 索引
serve/    FastAPI 搜索服务（/search）
skill/    官方 agent skill 提示词（本教程 Cursor 规则的蓝本）
train/    LoRA 微调（独立 uv 项目，从 train/ 目录内安装）
web/      pixelrag.ai 前端 + 聊天 agent 后端
deploy/   systemd、蓝绿部署等生产运维