PixelRAG 部署教程：基于网页截图的视觉检索增强生成

本教程将指导你部署 PixelRAG，一个通过将文档渲染为截图并进行视觉检索的开源系统。它基于论文《PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation》，能保留文本解析丢失的视觉结构（如表格、图表、布局），实现更准确的检索与生成。

📋 准备工作

1. 环境要求

  • Python 版本：3.10 或更高版本。
  • 操作系统：Linux (支持 CUDA)、macOS (Apple Silicon 支持 MPS) 或 Windows (通过 WSL2)。
  • 包管理器：推荐 uv 或 pipx 来安装 CLI 工具，确保 pixelshot 命令在 PATH 中可用。
  • 可选依赖：
    • 处理 PDF：需要 poppler (macOS: brew install poppler；Ubuntu/Debian: apt-get install poppler-utils)。
    • GPU 加速：如需在 Linux 上使用 CUDA，需安装 NVIDIA 驱动和 CUDA 工具包。

2. 安装 PixelRAG

PixelRAG 提供了多种功能组件，可按需安装：

1
2
3
4
5
6
7
8
9
10
11
12
# 基础安装：包含渲染功能 (pixelshot)
pip install pixelrag

# 安装嵌入和索引功能
pip install 'pixelrag[embed]'
pip install 'pixelrag[index]'

# 安装服务端 (用于搜索 API)
pip install 'pixelrag[serve]'

# 同时安装全部功能 (推荐)
pip install 'pixelrag[index,serve,pdf]'

注意：train (训练) 是一个独立的 uv 项目，位于 train/ 目录下，有自己独立的环境，通常不需要部署。

🚀 快速开始：搜索预构建的维基百科索引

PixelRAG 提供了一个托管在 https://api.pixelrag.ai 的实时 API，索引了 828 万篇维基百科文章，无需 API 密钥即可使用。

1
2
3
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}'

你也可以在浏览器中访问 pixelrag.ai 进行交互式体验，或在 Colab 中运行演示笔记本。

🔧 核心功能：构建和使用本地索引

1. 渲染页面为截图 (pixelshot)

pixelshot 命令将网页或 PDF 渲染为图片分块 (tiles)。

1
2
3
4
5
# 渲染网页
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

# 渲染 PDF (需安装 PDF 支持和 poppler)
pixelshot paper.pdf -o ./tiles --dpi 200

程序化使用:

1
2
from pixelrag_render import render_url
tiles = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")

2. 从本地文档构建索引

  1. 创建配置文件 pixelrag.yaml:
1
2
3
4
5
6
7
source:
  type: local
  path: ./my_docs/          # 可以是目录或单个 PDF 文件
embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto              # Linux 上使用 cuda, macOS 使用 mps, 否则为 cpu
output: ./my_index
  1. 构建索引:
1
2
3
4
5
# 安装索引功能
pip install 'pixelrag[index]'

# 执行构建
pixelrag index build
  1. 启动搜索服务:
1
2
3
4
5
# 安装服务端
pip install 'pixelrag[serve]'

# 启动服务
pixelrag serve --index-dir ./my_index --port 30001
  1. 执行查询:
1
2
3
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "你的查询问题"}], "n_docs": 5}'

3. 端到端示例：索引并搜索一篇 PDF 论文

这个示例展示了在没有 GPU 的情况下 (使用 macOS MPS 或 CPU)，从零开始索引一篇 PDF 并进行查询。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 1. 安装所有必要的功能
pip install 'pixelrag[index,serve,pdf]'

# 2. 下载示例 PDF
curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf

# 3. 创建配置文件 (设备 auto 会自动选择 MPS/CUDA/CPU)
cat > pixelrag.yaml << 'EOF'
source:
  type: local
  path: ./paper.pdf
embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto
output: ./paper_index
EOF

# 4. 构建索引 (在 Apple M 系列上约需 3 分钟)
pixelrag index build

# 5. 启动服务
pixelrag serve --index-dir ./paper_index --port 30001

# 6. 搜索 (查询会返回包含示意图的页面，如第 2 页)
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "PixelRAG 概览和示意图"}], "n_docs": 1}'

⚙️ 高级配置与集成

1. 使用 Qdrant 作为向量后端 (大规模生产)

对于大规模或生产级部署，推荐使用 Qdrant 替代本地的 FAISS 索引。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 安装 Qdrant 支持
pip install 'pixelrag[serve,qdrant]'  # 或 'pixelrag[index,qdrant]'

# 启动本地 Qdrant 服务器 (Docker)
docker run -p 6333:6333 qdrant/qdrant

# 构建索引时指定 Qdrant 后端 (首次)
pixelrag build-index --embeddings-dir ./embeddings --output-dir ./index \
    --backend qdrant --qdrant-url http://localhost:6333 --collection pixelrag

# 后续构建可使用 --append 或 --recreate
pixelrag build-index --embeddings-dir ./more --output-dir ./index \
    --backend qdrant --qdrant-url http://localhost:6333 --collection pixelrag --append

在 pixelrag.yaml 中配置 Qdrant 参数，并支持设置量化配置以优化内存和速度。

2. 作为 Claude Code 插件使用 (pixelbrowse skill)

PixelRAG 提供了一个 Claude Code 插件，让 Claude 能够“看到”网页。

1
2
3
4
5
6
# 确保 pixelshot 在 PATH 中
uv tool install pixelrag  # 或 pipx install pixelrag

# 安装插件
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

安装后，在 Claude 会话中使用 /screenshot https://example.com 命令，或让 Claude 自动调用“截图并总结”等任务。

❓ 常见问题排查

  • pixelshot 命令未找到：确保使用了 uv tool install 或 pipx install 进行全局安装。如果使用 pip install 在虚拟环境中安装，需先激活虚拟环境。
  • 渲染 PDF 失败：确认已安装 poppler 系统库 (macOS: brew install poppler；Ubuntu: apt-get install poppler-utils) 并安装了 pixelrag[pdf] 扩展。
  • Chrome 未自动发现：pixelshot 依赖 Chromium 浏览器。在 Linux 上，它尝试使用自带的 headless_shell。在其他系统上，会尝试从标准路径查找。可通过环境变量 CHROME_PATH=/path/to/chrome 手动指定浏览器路径。
  • 索引构建时内存不足 (OOM)：对于大型文档集，可以降低 embed 阶段的批处理大小（通过修改配置或命令行参数），或使用 Qdrant 作为后端以支持磁盘存储。对于超大索引（如维基百科），建议直接下载并使用预构建的 FAISS 索引。

通过以上步骤，你可以成功部署 PixelRAG，无论是快速使用其托管服务，还是为自己文档构建专用的视觉检索系统。其核心创新在于将文档“截图”作为检索单元，为需要理解复杂视觉布局的 RAG 应用提供了新的可能性。