大家好，这里是 AI开源提效指南！
传统 RAG 系统有个致命缺陷：它会把网页渲染成纯文本格式，表格、图表、信息图——所有视觉结构全丢了。
伯克利 SkyLab 团队开源的 PixelRAG 彻底颠覆了这一范式——直接对页面截图，在像素级别进行检索。
上线不到一个月狂揽 3000+ Star，已经预索引了近 800 多万篇文章！
一句话推荐：检索的未来，是看而不是读。
适合场景：
✅ 需要理解表格/图表内容的 RAG 系统 ✅ AI Agent 的网页视觉理解能力 ✅ 大规模 Wikipedia 视觉搜索
推荐理由：
像素级检索：直接对截图做向量检索，表格/图表/排版信息完整保留 即开即用：预索引 828 万 Wikipedia 文章，一行 curl 即可搜索 伯克利血统：来自 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
代码解读：
通过 Chrome DevTools Protocol（CDP）原生 WebSocket 控制浏览器，无需 Playwright 依赖 使用 _readiness_expr()注入 JavaScript 等待页面完全加载（load 事件 + 字体就绪 + 两帧 RAF），确保 SPA 页面也正确渲染将长页面按 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, ...)
关键设计：
8192px 瓦片预切分为 1024px 的块（chunk），减少视觉 token 数量约 8 倍 支持 vLLM（ runner="pooling"）和 SGLang 两种推理后端使用 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 服务端）
数据流向图
技术栈选型
📈 项目总结
范式创新：首次将 RAG 从「文本解析」提升到「像素级检索」，完整保留文档视觉结构 性能卓越：LoRA 微调 Qwen3-VL-Embedding，QA Score 从 0.715 提升至 0.785 工程完备：从渲染→嵌入→索引→搜索→前端，完整端到端流水线 即开即用：800 多万文章预索引，一行 curl 即可搜索 完全开源：训练数据、LoRA 适配器、完整源码全部 Apache-2.0 开源 生态整合：Claude Code 插件、Colab 笔记本、REST API 多入口 学术严谨：附带完整论文，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
