pixelrag

这是什么？适合谁？

PixelRAG 是 UC Berkeley SkyLab/BAIR/NLP 团队的开源研究项目（论文《PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation》）：把文档—网页、PDF、图片—渲染成截图瓦片（screenshot tiles），直接在图像上做检索，而不是解析成文本再切块。HTML 解析会丢掉的表格、图表、版式、信息图在截图里完整保留，阅读模型可以直接”看着图”回答问题。官方在 api.pixelrag.ai 托管了 828 万篇 Wikipedia 页面的预建索引，无需安装、无需 API key 即可检索。

适合人群：构建 RAG 应用的工程师（尤其是文档里表格/图表多的场景）、做检索增强研究的科研人员、想让 Claude Code”看网页”而不是读 HTML 的开发者。 使用前提：Python 环境（pip install pixelrag）；想自建索引需要 pixelrag[embed]（LoRA 微调的 Qwen3-VL-Embedding 模型）与 FAISS；仅用托管 API 则零依赖。

快速上手（3 步）

第一步：安装 CLI

pip install pixelrag

这会装上 pixelshot（文档 -> 截图瓦片，Playwright/CDP 渲染）与 pixelrag 命令伞。

第二步：渲染一个页面

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

页面被渲染为截图瓦片目录，视觉结构（表格、图表、布局）原样保留。

第三步：检索托管索引（无需任何配置）

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

这是 828 万页 Wikipedia 的在线检索端点，甚至支持用图片作为查询（视觉检索）。也可以直接在 pixelrag.ai 浏览器试用，或跑 Colab 快速笔记本。

初级用法

• 两步心智模型：render（页面 -> 截图瓦片）+ search（视觉索引检索），核心操作只有这两个。
• 按需安装流水线阶段：pixelrag[embed] 装嵌入与索引构建，pixelrag[index] 装完整编排（source -> ingest -> embed -> index），pixelrag[serve] 装 FAISS 检索 API（FastAPI，CPU/GPU）。
• Claude 插件：renderer 同时以 Claude Code 插件发布（pixelbrowse skill），见下文高级玩法。

高级玩法

1. 给 Claude 一双眼睛：uv tool install pixelrag 后 claude plugin marketplace add StarTrail-org/PixelRAG && claude plugin install pixelbrowse@pixelrag-plugins，然后 claude -p "screenshot https://news.ycombinator.com and summarize the top stories"—Claude 用 pixelshot 截图并直接读图，看图表/表格的方式和人一样，无需 MCP server 或后端。
2. 自建领域视觉索引：对内部文档（含大量表格/扫描件的 PDF）跑 pixelrag index 全管线，用 pixelrag serve 起 FAISS 检索服务，得到一个”按长相检索”的私有知识库。
3. 视觉查询检索：用一张截图作为 query 检索相似版式的页面—适合”找到和这张图表长得像的那篇文档”类需求。

常见踩坑（5 条）

踩坑 1：把 pixelshot 装进项目 venv 后 Claude 找不到命令

• 现象：插件调用报 pixelshot 不在 PATH
• 原因：plain pip install 进项目 venv 不会全局暴露命令
• 解决：官方建议 uv tool install pixelrag 或 pipx install pixelrag 保持隔离又全局可用

踩坑 2：纯文本问题也期待视觉检索更强

• 现象：普通事实型文本问题效果与文本 RAG 差别不明显
• 原因：PixelRAG 的增益集中在视觉结构内容（表格数值、图表趋势、版式信息）
• 解决：识别场景—视觉密集型文档用它，纯文本流水线用常规 RAG 即可

踩坑 3：自建索引 GPU 不可用

• 现象：pixelrag[embed] 嵌入阶段极慢
• 原因：LoRA 微调的 Qwen3-VL-Embedding 模型在 CPU 上吞吐有限
• 解决：用 GPU 跑嵌入；或直接用托管索引，别自建

踩坑 4：Playwright 渲染失败

• 现象：pixelshot 对某些页面报渲染错误
• 原因：Playwright/CDP 依赖浏览器内核，首次运行需安装
• 解决：按 Playwright 官方指引安装浏览器；动态页面等待加载完成

踩坑 5：把托管 API 当生产依赖

• 现象：服务限流或不可用影响业务
• 原因：api.pixelrag.ai 是研究性质的免费托管端点（无 key）
• 解决：生产场景用 pixelrag[serve] 自托管 FAISS 检索服务

FAQ（5 个常见问题）

Q1：PixelRAG 免费吗？ A：代码 Apache-2.0 开源免费；托管检索端点当前免费无 key，但属研究性质，生产依赖请自托管。

Q2：和常规文本 RAG（LangChain/LlamaIndex）有什么本质区别？ A：常规 RAG 解析页面为文本块，表格/图表信息在解析时丢失；PixelRAG 检索的是截图瓦片本身，阅读模型直接从图像读答案。论文标题即立场：“Web Screenshots Beat Text for RAG”。

Q3：检索质量有基准吗？ A：有—arXiv 论文（2606.28344）给出了与文本 RAG 的对比实验；8.28M Wikipedia 页索引与 Colab demo 可复现。

Q4：支持中文文档吗？ A：渲染（截图）天然与语言无关；检索嵌入模型为 Qwen3-VL 系（多语言视觉模型），中文页面渲染检索原则上可行，具体效果未实测。

Q5：数据隐私如何？ A：托管 API 会把查询发到官方服务器；隐私敏感场景用 pixelrag[serve] 全自托管，渲染、嵌入、索引、检索全部本地完成。

小技巧（5 条）

1. 先用托管索引验证场景：零成本跑几组真实查询，确认视觉检索对你的文档类型有增益，再决定是否自建索引。
2. pixelshot 输出目录当资产管：截图瓦片可复用于嵌入与索引多个阶段，重跑流水线前先检查已有瓦片。
3. Colab 笔记本当教学材料：quickstart.ipynb 内联展示渲染+检索全流程，是给团队介绍视觉 RAG 的最快方式。
4. 查询带图：遇到”按版式找文档”的需求，直接把参考截图作为 query 发给视觉检索端点。
5. 关注论文与仓库联动：仓库是论文官方代码库，方法迭代会先落在 README 与 demos，跟进比读二次资料快。

进阶学习建议

• 精读 arXiv 论文的实验设计：视觉检索相对文本 RAG 在哪些查询类型上增益最大、为什么
• 拆解 pixelrag index 的四阶段编排（source -> ingest -> embed -> index），学习”渲染即解析”的流水线设计
• 对比 Qwen3-VL-Embedding 的 LoRA 微调方案与你现有嵌入模型在表格类文档上的召回差异
• 研究 pixelbrowse Claude 插件的”截图即阅读”模式，把同样的思路（工具输出图像而非文本）迁移到自己的 Agent 工具设计

参考链接

• PixelRAG GitHub 仓库
• PixelRAG 论文 (arXiv)
• 在线 Demo

本文基于公开资料于 2026-08-18 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。