PixelRAG:把网页/PDF 渲染成截图再检索,这个 Berkeley 8.28M 索引的开源项目重新定义了 RAG

做 RAG 这两年，我观察到一个挺扎心的现象：

99% 的 RAG 失败案例，发生在"文本解析"这一步。

你想想——

你把一篇写满表格、图表、信息图的 Wikipedia 文章喂给 LangChain / LlamaIndex，HTML 解析器会把<table>拆成稀碎、把 SVG 图直接扔掉、把带坐标的图说成"一张图"。

等你做检索时，模型拿着"图、图、图"这三块文本去回答"这家公司去年营收增长多少"——它只能瞎编。

更尴尬的是 PDF：双栏论文、横向 A4 报告、扫描件——传统 PDF parser 拆出来的文本顺序完全是乱的，引用错位、表格错位、图说错位。

你费了大力气搭的 RAG，最后被"文本解析"这一步坑到怀疑人生。

直到 Berkeley SkyLab + BAIR + Berkeley NLP 联合放出一个叫StarTrail-org/PixelRAG的开源项目——

Apache-2.0 协议、24 个子包、像素级页面渲染 + Qwen3-VL-Embedding 微调 + 8.28M 维基百科预建索引 + 一个 Live API 不用 API Key 就能查——

把 RAG 从"文本检索"推进到"视觉检索"。

核心思路说人话就一句：

别拆 HTML 了，直接把页面/PDF 渲染成截图；别解图表了，直接让 VLM 看图。

项目地址：https://github.com/StarTrail-org/PixelRAG
论文地址：https://github.com/StarTrail-org/PixelRAG/blob/main/assets/pixelrag-paper.pdf
Live API：https://api.pixelrag.ai
在线体验：https://pixelrag.ai

它到底是个什么东西

PixelRAG 不是一个"更聪明的文本切片器"——它是一个"以图搜图"的 RAG 框架：把任何文档（网页、PDF、图片）渲染成一张张"页面截图块"（screenshot tiles），用专门为截图训练的多模态 Embedding 模型把图片变成向量，建一个 FAISS 索引，检索时直接返回"看起来最像问题"的那张截图，让 Reader 模型"看图回答"。

但更准确地说，它解决的核心问题是：

为什么我的 RAG 回答不出"图里那个数字是多少"？

你想想：

• HTML parser 会把<table>拆成"行 1：xxx；行 2：xxx"，但表格的"列对齐"信息全丢
• 图表被读成"图 1：一柱状图"，但"哪个柱子代表什么"丢了
• PDF 双栏论文的左右栏文本被串成一团，引用 [3] 错位到第 5 段
• 信息图里的视觉叙事（流程、对比、并列）变成"一堆小图标 + 几行文字"
• 传统 Embedding 算的是"文本相似度"——再像也救不回"信息已经丢了"

PixelRAG 想做的，就是把"信息保留"这件事从源头解决：

• 不解析 HTML，直接截图 → 视觉结构 100% 保留
• 不解析 PDF，按页/按 tile 切 → 引用对位、双栏不串
• 不靠文本 Embedding，用 Qwen3-VL-Embedding 微调模型 → "图"和"问题"在同一个向量空间

这套链路的关键洞察是：HTML 解析是"减法"（拆掉结构留文本），截图渲染是"加法"（完整保留再加标注）——RAG 想要的是"保真"，不是"精简"。

它要解决的五个具体痛点

1. 表格 / 图表 / 信息图在 RAG 里是"信息黑洞"。

你用 LangChain 的UnstructuredPDFLoader拆一份 10 页财报——所有图表都被读成"图 1：一柱状图"。你问"Q3 营收增长多少"，模型答不出来，因为数字在"柱子"里，不在文本里。

2. 双栏论文 / 横向 PDF 的文本顺序全乱。

学术论文 90% 是双栏、报告 50% 有横向 A4、扫描件更别提。pypdf/pdfplumber拆出来的文本是"左栏上 → 右栏上 → 左栏下 → 右栏下"还是"左栏上 → 左栏下 → 右栏上 → 右栏下"——取决于实现。引用 [3] 可能跑到第 5 段。

3. 网页的"视觉信息"完全丢失。

HTML 的视觉层级（h1 / h2 / 字号 / 颜色 / 位置）是设计语言，HTML parser 全扔了。一篇写得"标题清晰、图表居中、对比靠色块"的博客，parse 出来是平铺的文本。

4. 文本 Embedding 看不到"图"。

CLIP / BGE / OpenAI text-embedding-3 算的都是"文本 ↔ 文本"相似度。你问"那个饼图里最大的一块是什么"，模型怎么都查不到——因为图根本没进索引。

5. 重建一个完整 RAG 索引的工程量太大。

要自己写 HTML 渲染、写 PDF 切分、写 Embedding 服务、写 FAISS 索引、写 FastAPI、写 MCP 集成——一个开源项目把这些全包了。

PixelRAG 的解法是"页面 → 截图 tile → VLM Embedding → FAISS"——五个痛点一次打包。

核心能力一览

完整架构：渲染 → 切片 → Embedding → 索引 → 检索 五步流水线

按pixelragumbrella 的 CLI 编排，PixelRAG 的设计精髓就三个字："保真"。

整条流水线可以这么画：

[网页 / PDF / 图片]
   ↓ pixelshot（Playwright/CDP + Poppler，原生分辨率）
[截图 tile 集合：每页一张或切成 N 张]
   ↓ pixelrag chunk（按页/按区域切片）
[分片元数据：page_id / bbox / source_url]
   ↓ pixelrag embed（Qwen3-VL-Embedding + LoRA）
[向量集合：每张 tile 一个 embedding]
   ↓ pixelrag build-index（FAISS 归一化 + 内积索引）
[可服务的 FAISS 索引文件]
   ↓ pixelrag serve（FastAPI /search 接口）
[Reader 模型（Claude / GPT-4o / Qwen-VL）看图回答]

这套架构的精妙之处在于：每一步都可以独立替换 / 单独执行。

这意味着：

• 你只想截图？pip install pixelrag+pixelshot <url> -o ./tiles，其他一概不装
• 你已经手动截图了？跳过渲染，直接pixelrag chunk+embed
• 你想换 Embedding 模型？只改pixelrag.yaml的embed.model字段
• 你想跑 CPU 推理？device: cpu（macOS Apple Silicon 自动 MPS）
• 你想让 Claude 看图？装pixelbrowseSkill，一句screenshot <url>

这种"管线化"的设计，让 PixelRAG 在 Qwen3-VL 快速迭代的今天保持了相当灵活的扩展性——换 Embedding 不用改其他代码。

5 个让我眼前一亮的设计

1. 用"截图"代替"解析"——保真度从源头解决

传统 RAG 的链路是"HTML → DOM → 文本 → chunk → embedding"。每一步都是"减法"——拆掉结构、扔掉视觉、压平层级。

PixelRAG 反过来：HTML → 截图（不解析）。截图本身就是"完整页面 + 完整视觉 + 完整布局"的快照——表格的列对齐、图表的柱子、信息图的视觉叙事，100% 保留。

这是它最被低估的设计——它不试图"让模型理解拆开的文本"，而是让模型直接看完整的图：

• 表格的"列对齐"在图里天然成立，模型直接看
• 图表的"哪个柱子代表什么"在图里天然成立，模型直接看
• 双栏论文的"左右栏"在图里天然成立，模型直接看
• 信息图的"流程、对比、并列"在图里天然成立，模型直接看

这一句话看起来简单，但实际把"RAG 回答图表问题"的天花板拔高了一大截。

2. Qwen3-VL-Embedding + LoRA 微调——专门为截图训练的 Embedding

CLIP / BGE 算的都是"通用文本/图像"相似度。它们没在"网页截图"上训练过——所以"那个饼图"和"哪个部门占比最大"算出来的相似度很低。

PixelRAG 的解法是：用Qwen/Qwen3-VL-Embedding-2B作为底座，LoRA 微调在"网页截图 + 真实查询对上"的数据集上。

微调数据集（screenshot-training-natural-filtered-v2）已经开源到 HuggingFace——包含 100K+ 真实网页截图 + 真实 query + 真实点击 tile 的三元组。

训练好的 LoRA 适配器也开源了——你不用自己训练也能用。

这一句话看起来简单，但实际把"多模态 Embedding 的领域适配"门槛拉低了一大截——中小团队也能用上"为截图定制"的 Embedding。

3. 8.28M 维基百科预建索引 + 免 API Key 的 Live API

做 RAG demo 最痛苦的不是搭框架，是"我连数据都没有"。要爬 Wikipedia、要切、要 embedding、要建索引——一个 demo 折腾一周。

PixelRAG 直接在 HuggingFace 上放了预建的 8.28M Wikipedia 索引（base 版本约 217GB），并且在https://api.pixelrag.ai跑了一个免 API Key 的 Live 服务：

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）。你可以上传一张截图，问"这页讲了什么"，API 直接返回相似页面。

这一句话看起来简单，但实际把"多模态 RAG 的复现成本"压到了零——一个 curl 就能跑通 8.28M 维基百科的视觉检索。

4.pixelbrowseSkill——把"截图 → 看图"变成 Claude 的本能

Claude Code 装了pixelbrowseSkill 之后，可以直接对 Claude 说：

screenshot https://news.ycombinator.com and summarize the top stories
screenshot https://arxiv.org/abs/2404.12387 and explain the key findings

Claude 会自动调pixelshot截图，然后自己看图回答——不用 MCP server、不用 backend、不用自建 RAG 索引。

这意味着：你打开 Chrome 看到一张图、看到一张表格、看到一段写满 LaTeX 的论文——直接让 Claude 截图看，不用复制粘贴 HTML，不用写 PDF 解析器。

这一句话看起来简单，但实际把"AI 看网页"这件事的体验天花板拔高了一大截——从此"网页 → AI 知识"零摩擦。

5. 端到端管线 + uv 隔离环境——每个 stage 独立可选

PixelRAG 的 CLI 设计是"按需装"：

pip install pixelrag              # 核心（只有 pixelshot）
pip install 'pixelrag[embed]'     # 加上 chunk/embed/build-index
pip install 'pixelrag[index]'     # 加上完整 index 编排
pip install 'pixelrag[serve]'     # 加上 FastAPI 服务
pip install 'pixelrag[pdf]'       # 加上 Poppler PDF 支持

每个 stage 用单独的 Python 包（pixelrag_embed/pixelrag_index/pixelrag_serve/pixelrag_render），独立的 pyproject.toml + uv 锁。

train/目录更是完全独立的 uv 项目——torch==2.9.1+cu129+transformers==4.57.1+ cuDNN 9.20 全锁死，和主项目 0 冲突。

这一句话看起来简单，但实际把"AI 工程的依赖管理"做到了工业级——你装serve不会把torch拉下来污染环境，训练时也不会被其他依赖打架。

5 分钟上手

Step 1：环境

python --version

Step 2：装包

pip install pixelrag

pip install 'pixelrag[index]'

Step 3：（可选）准备一个 PDF 做本地索引

curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf

Step 4：写配置

source:
  type: local
  path: ./paper.pdf

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto   # mps on Mac, cuda on Linux, cpu fallback

output: ./paper_index

Step 5：建索引 + 起服务

pixelrag index build

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

Step 6：检索

curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "Overview of PixelRAG and the diagram"}], "n_docs": 1}'

Step 7：（可选）让 Claude 看图

uv tool install pixelrag

claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findings"

Step 8：（可选）免 API Key 的 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}'

这套上手流程跑完，你就有了一个能"看图回答"的本地 RAG + 一个免 Key 的 Live API + 一个"装好就能用"的 Claude 插件。

它真正牛在哪

我看到很多人说："把网页截图给 VLM 不就行了，为什么还要单独搞个 RAG 框架？"

这话只对了一半。

它确实不是第一个"用截图做 RAG"的项目——Google 的 ScreenAI、Adobe 的 PDF AI、Mistral 的 Pixtral 早就在做视觉理解了。

它牛在：把"视觉 RAG"从"研究 prototype"推进到"生产可用的开源基础设施"。

具体来说，它做了五件别人没认真做的事：

1. 完整管线开源——从渲染到 Embedding 到 FAISS 到 FastAPI，全套代码可改可商用
2. 领域微调的 Embedding——Qwen3-VL + LoRA 专门为截图训练，模型权重 + 训练数据全开源
3. Live API + 预建索引——8.28M 维基百科免 API Key 就能查，把"复现门槛"压到零
4. Claude Code 原生集成——pixelbrowseSkill 让 Agent 拥有"看网页"的能力
5. 依赖隔离 + 按需安装——pip install pixelrag[xxx]细粒度可选，训练/服务完全解耦

这才是它真正值得被关注的地方。

小结

• Apache-2.0、Berkeley 三实验室背书、v0.3.0 已发
• "截图 → Embedding → FAISS → 检索"全链路开源
• Qwen3-VL-Embedding + LoRA 微调，模型/适配器/数据集全开源
• 8.28M 维基百科预建索引 + 免 API Key 的 Live API
• pixelbrowseSkill 让 Claude 直接"看网页"
• uv 隔离环境、按需安装、训练/服务完全解耦
• Linux CUDA / macOS MPS / CPU 自动 fallback
• 支持文本和图片双模态查询
• 54 commits、24 个子包、Jun 23 2026 仍在活跃迭代
• Web UI、Live API、Claude Plugin、Colab notebook 四种入口

说到底，"RAG"这件事，过去三年的关键词是"文本切片 + 向量检索"——

PixelRAG 用"页面截图 + 视觉 Embedding"打开了一个新方向。

这是工程化思维对"信息保真"的回答。

仓库地址：

https://github.com/StarTrail-org/PixelRAG