PixelRAG：伯克利团队颠覆传统 RAG，用截图代替文本检索! 28 天狂揽 3000+ Star！

大家好，这里是 AI开源提效指南！

传统 RAG 系统有个致命缺陷：它会把网页渲染成纯文本格式，表格、图表、信息图——所有视觉结构全丢了。

伯克利 SkyLab 团队开源的 PixelRAG 彻底颠覆了这一范式——直接对页面截图，在像素级别进行检索。

上线不到一个月狂揽 3000+ Star，已经预索引了近  800 多万篇文章！

一句话推荐：检索的未来，是看而不是读。

适合场景：

• ✅ 需要理解表格/图表内容的 RAG 系统
• ✅ AI Agent 的网页视觉理解能力
• ✅ 大规模 Wikipedia 视觉搜索

推荐理由：

1. 像素级检索：直接对截图做向量检索，表格/图表/排版信息完整保留
2. 即开即用：预索引 828 万 Wikipedia 文章，一行 curl 即可搜索
3. 伯克利血统：来自 SkyLab/BAIR/Berkeley NLP，附带完整学术论文

✨ 核心功能

功能 1：像素级截图渲染（pixelshot）

将任意网页、PDF、本地 HTML 渲染为 8192px 高的 JPEG 截图瓦片（tile），再切分为 1024px 的块（chunk）。支持 CDP 协议直接控制 Chrome，无需 Playwright 依赖。

关键优势：

• ✅ 无 Playwright 依赖，通过原生 WebSocket 协议控制 Chrome
• ✅ 支持 Turbo 加速路径（定制版 Chrome + 共享内存 + 并行 JPEG 压缩），批量吞吐翻倍
• ✅ 支持 URL、PDF、本地图片、HTML 文件多种输入

功能 2：视觉语义嵌入（Qwen3-VL-Embedding）

使用 LoRA 微调的 Qwen3-VL-Embedding-2B 模型，将截图块编码为向量。支持 ViT 视觉编码器 LoRA + 文本预热 + 难负样本挖掘。

关键优势：

• ✅ 在 SimpleQA 测试集上达到 QA Score ≈ 0.785（基础模型仅 0.715~0.730）
• ✅ 支持 vLLM / SGLang / 原生 transformers 多种推理后端
• ✅ 训练数据、LoRA 适配器全部开源

功能 3：FAISS 向量搜索引擎

基于 FAISS IVF 索引的视觉搜索引擎，支持文本查询、图片查询、文本+图片联合查询。

关键优势：

• ✅ 预索引 828 万 Wikipedia 文章，约 2810 万个截图块
• ✅ 支持 articles_only 过滤（排除 Wikipedia 元页面）
• ✅ 单次搜索延迟约 42ms（GPU 编码）+ FAISS 毫秒级检索

功能 4：Claude Code 插件（pixelbrowse）

pixelshot 还作为 Claude Code 的插件发布，让 Claude 能「看」网页——截图后直接读取图片内容。

关键优势：

• ✅ 无需 MCP 服务器，一行命令安装
• ✅ 支持 /screenshot 斜杠命令
• ✅ 图表、表格、排版信息完整保留

📦 安装步骤

环境要求

• Python >= 3.12
• 操作系统：Linux / macOS / Windows
• 渲染需要 Chrome/Chromium（pixelshot install-chrome 自动下载）

安装命令

# 核心渲染工具（无 ML 依赖，轻量）
pip install pixelrag

# 完整索引构建（含 torch、transformers）
pip install 'pixelrag[index]'

# 搜索服务（FastAPI + FAISS）
pip install 'pixelrag[serve]'

# 全部安装
pip install 'pixelrag[all]'

快速上手

请参考：官方 API 文档

🔧 工作原理

核心模块 1：CDP 渲染引擎

文件路径：render/src/pixelrag_render/backends/cdp.py

async def capture_url(ws, msg_id_ref, url, tile_dir, *, tile_h=8192, quality=85, ...):
    # 1. 导航到目标 URL
    await _cdp_send(ws, msg_id_ref, "Page.navigate", {"url": url})
    
    # 2. 等待页面加载 + 字体就绪 + 布局稳定
    result = await _cdp_send(ws, msg_id_ref, "Runtime.evaluate", {
        "expression": _readiness_expr(wait_network_idle),
        "awaitPromise": True,
    })
    
    # 3. 从顶部开始，按 tile_h 高度切片截图
    while y < page_height:
        clip_h = min(tile_h, page_height - y)
        result = await _cdp_send(ws, msg_id_ref, "Page.captureScreenshot", {
            "clip": {"x": 0, "y": y, "width": viewport_w, "height": clip_h, "scale": 1},
        })
        # 保存为 JPEG 瓦片
        tile_path.write_bytes(base64.b64decode(result["data"]))
        y += tile_h

代码解读：

1. 通过 Chrome DevTools Protocol（CDP）原生 WebSocket 控制浏览器，无需 Playwright 依赖
2. 使用 _readiness_expr() 注入 JavaScript 等待页面完全加载（load 事件 + 字体就绪 + 两帧 RAF），确保 SPA 页面也正确渲染
3. 将长页面按 8192px 高度切片为多个 JPEG 瓦片，每个瓦片附带 tiles.json 清单文件

核心模块 2：视觉嵌入流水线

文件路径：embed/src/pixelrag_embed/embed.py

def _build_chat_prompt(tokenizer, instruction=None):
    # 使用 Qwen3-VL-Embedding 官方 prompt 格式
    conversation = [
        {"role": "system", "content": [{"type": "text", "text": instruction}]},
        {"role": "user", "content": [{"type": "image"}]},
    ]
    return tokenizer.apply_chat_template(conversation, tokenize=False, ...)

关键设计：

1. 8192px 瓦片预切分为 1024px 的块（chunk），减少视觉 token 数量约 8 倍
2. 支持 vLLM（runner="pooling"）和 SGLang 两种推理后端
3. 使用 Last-token pooling + L2 归一化生成最终向量

核心模块 3：搜索 API

文件路径：serve/src/pixelrag_serve/api.py

@app.post("/search")
async def search(req: SearchRequest):
    # 1. 编码查询（文本/图片/联合）
    query_vectors = _encode_queries(req.queries, req.instruction)
    
    # 2. FAISS IVF 搜索（支持 nprobe 调节精度）
    distances, indices = index.search(query_vectors, fetch_k)
    
    # 3. 构建结果（含文章过滤、tile 路径解析）
    for j in range(fetch_k):
        vid = int(indices[qi, j])
        hit = Hit(score=float(distances[qi, j]), article_id=aid, ...)

关键算法流程

🏗️ 技术架构

整体架构图

PixelRAG
├── render/（截图渲染引擎）
│   ├── backends/cdp.py（标准 CDP 路径）
│   ├── backends/fast_cdp.py（Turbo 加速路径）
│   ├── backends/pdf.py（PDF 渲染）
│   └── chrome.py（Chrome 二进制管理）
├── embed/（向量嵌入流水线）
│   ├── embed.py（GPU 嵌入，vLLM/SGLang）
│   ├── embed_cpu.py（CPU/MPS 嵌入）
│   ├── chunk.py（瓦片切块）
│   └── index.py（FAISS 索引构建）
├── index/（端到端索引构建）
│   ├── pipelines.py（编排流水线）
│   ├── config.py（YAML 配置解析）
│   └── sources/（数据源：本地/Kiwix/Web/PDF）
├── serve/（搜索 API 服务）
│   ├── api.py（FastAPI 搜索端点）
│   └── render_ondemand.py（按需渲染）
├── train/（LoRA 微调，独立 uv 项目）
│   ├── train_contrastors.py（对比学习训练器）
│   └── model.py（模型定义）
└── web/（Next.js 前端 + Agent 后端）
    ├── app/（搜索页面 + 聊天页面 + API 文档）
    └── agent-server.mjs（Claude Agent SDK 服务端）

数据流向图

技术栈选型

📈 项目总结

1. 范式创新：首次将 RAG 从「文本解析」提升到「像素级检索」，完整保留文档视觉结构
2. 性能卓越：LoRA 微调 Qwen3-VL-Embedding，QA Score 从 0.715 提升至 0.785
3. 工程完备：从渲染→嵌入→索引→搜索→前端，完整端到端流水线
4. 即开即用：800 多万文章预索引，一行 curl 即可搜索
5. 完全开源：训练数据、LoRA 适配器、完整源码全部 Apache-2.0 开源
6. 生态整合：Claude Code 插件、Colab 笔记本、REST API 多入口
7. 学术严谨：附带完整论文，W&B 训练曲线公开

🔗 参考资源

项目仓库：https://github.com/StarTrail-org/PixelRAG

官方资源：
- 在线演示：https://pixelrag.ai
- API 文档：https://pixelrag.ai/docs
- 搜索 API：https://api.pixelrag.ai
- 状态监控：https://status.pixelrag.ai

模型与数据：
- LoRA 适配器：https://huggingface.co/Chrisyichuan/wiki-screenshot-embedding-lora
- 训练数据集：https://huggingface.co/datasets/Chrisyichuan/screenshot-training-natural-filtered-v2
- FAISS 索引：https://huggingface.co/StarTrail-org/pixelrag-faiss-indexes

- 训练复现文档：train/README.md
- 论文：assets/pixelrag-paper.pdf