大家好，这里是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 captureurl(ws, msgidref, url, tiledir, *, tileh=8192, quality=85, …): # 1. 导航到目标 URL await cdpsend(ws, msgidref, "Page.navigate", {"url": url}) # 2. 等待页面加载 + 字体就绪 + 布局稳定 result = await cdpsend(ws, msgidref, "Runtime.evaluate", { "expression": readinessexpr(waitnetworkidle), "awaitPromise": True, }) # 3. 从顶部开始，按 tileh 高度切片截图 while y < pageheight: cliph = min(tileh, pageheight – y) result = await cdpsend(ws, msgidref, "Page.captureScreenshot", { "clip": {"x": 0, "y": y, "width": viewportw, "height": cliph, "scale": 1}, }) # 保存为 JPEG 瓦片 tilepath.writebytes(base64.b64decode(result["data"])) y += tile_h
代码解读：
通过 Chrome DevTools Protocol（CDP）原生 WebSocket 控制浏览器，无需 Playwright 依赖
使用readinessexpr()注入 JavaScript 等待页面完全加载（load 事件 + 字体就绪 + 两帧 RAF），确保 SPA 页面也正确渲染
将长页面按 8192px 高度切片为多个 JPEG 瓦片，每个瓦片附带tiles.json清单文件
核心模块 2：视觉嵌入流水线
文件路径：embed/src/pixelrag_embed/embed.py
def buildchatprompt(tokenizer, instruction=None): # 使用 Qwen3-VL-Embedding 官方 prompt 格式 conversation = [ {"role": "system", "content": [{"type": "text", "text": instruction}]}, {"role": "user", "content": [{"type": "image"}]}, ] return tokenizer.applychat_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. 编码查询（文本/图片/联合） queryvectors = encodequeries(req.queries, req.instruction) # 2. FAISS IVF 搜索（支持 nprobe 调节精度） distances, indices = index.search(queryvectors, fetchk) # 3. 构建结果（含文章过滤、tile 路径解析） for j in range(fetchk): vid = int(indices[qi, j]) hit = Hit(score=float(distances[qi, j]), article_id=aid, …)
关键算法流程
🏗️ 技术架构
整体架构图
PixelRAG├── render/（截图渲染引擎）│ ├── backends/cdp.py（标准 CDP 路径）│ ├── backends/fastcdp.py（Turbo 加速路径）│ ├── backends/pdf.py（PDF 渲染）│ └── chrome.py（Chrome 二进制管理）├── embed/（向量嵌入流水线）│ ├── embed.py（GPU 嵌入，vLLM/SGLang）│ ├── embedcpu.py（CPU/MPS 嵌入）│ ├── chunk.py（瓦片切块）│ └── index.py（FAISS 索引构建）├── index/（端到端索引构建）│ ├── pipelines.py（编排流水线）│ ├── config.py（YAML 配置解析）│ └── sources/（数据源：本地/Kiwix/Web/PDF）├── serve/（搜索 API 服务）│ ├── api.py（FastAPI 搜索端点）│ └── renderondemand.py（按需渲染）├── train/（LoRA 微调，独立 uv 项目）│ ├── traincontrastors.py（对比学习训练器）│ └── model.py（模型定义）└── web/（Next.js 前端 + Agent 后端） ├── app/（搜索页面 + 聊天页面 + API 文档） └── agent-server.mjs（Claude Agent SDK 服务端）
数据流向图
技术栈选型
| 层级 | 技术 | 选型理由 |
| — | — | — |
| 渲染引擎 | Chrome CDP（原生 WebSocket） | 无 Playwright 依赖，性能更高 |
| 视觉模型 | Qwen3-VL-Embedding-2B（LoRA） | 开源最强视觉嵌入模型 |
| 向量索引 | FAISS IVF | 十亿级检索，毫秒级延迟 |
| 搜索服务 | FastAPI + Uvicorn | 高性能异步 Python Web 框架 |
| 前端 | Next.js + Tailwind CSS | 现代 React 框架，SSR 支持 |
| 训练框架 | PyTorch + GradCache | 梯度缓存，显存与 batch size 解耦 |
📈 项目总结
范式创新：首次将 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
* *
免责声明：本文内容仅供学习交流，所述工具/方法请遵守相关平台服务条款及法律法规。如涉及第三方服务，请以官方最新政策为准。
