PixelRAG 中文教程：网页截图检索、PixelShot 与视觉 RAG
PixelRAG 的关键做法是先把网页、PDF 或图片渲染成截图，再在图像上检索。这样表格、图表、信息图和页面布局仍然存在，视觉模型可以像读屏一样读取它们。
1. 安装命令
uv tool install pixelrag
也可以用 pipx install pixelrag。README 不建议只在项目虚拟环境里运行普通 pip install，因为 pixelshot 可能不在 PATH 中。
2. 渲染网页
pixelshot https://en.wikipedia.org/wiki/Python --output ./tiles
先打开 ./tiles 检查截图是否完整，尤其看长页面、表格和需要登录的页面。PixelRAG 的渲染器是通用管线，预构建索引只是官方提供的一种现成数据。
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}'官方示例称该 endpoint 不需要本地建索引和 API key，并提供浏览器演示。生产场景应确认数据是否适合发送到在线服务。
4. 给 Claude Code 安装视觉浏览
claude plugin marketplace add StarTrail-org/PixelRAG && claude plugin install pixelbrowse@pixelrag-plugins
安装后可用 /screenshot URL，或让 Claude 执行 screenshot 请求。插件只是调用本机的 pixelshot，不等于把整套 RAG 服务装进 Claude。
5. 和文本 RAG 的区别
文本 RAG 对正文和结构化字段更省资源；PixelRAG 适合视觉信息是答案一部分的页面，例如图表、表格和复杂排版。截图会增加渲染和视觉模型成本，也可能把小字体、动态内容和权限墙带来的问题放大。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合图表、表格和复杂排版是答案一部分的页面；普通正文检索或敏感资料不应默认使用在线 API。
采用建议
适合图表、表格和复杂排版是答案一部分的页面；普通正文检索或敏感资料不应默认使用在线 API。采用前需要核对：截图增加渲染和视觉模型成本。
原教程未展开的系统信息
架构与数据流
renderer 先用浏览器截图保留视觉结构，检索层在图像内容上进行匹配；预构建 Wikipedia 索引和本地自定义渲染是两条路径。
技术栈和运行条件
语言
Python/Node.js tooling
框架
pixelshot renderer + visual index API + Claude Code plugin
关键依赖
- uv 或 pipx
- Playwright/CDP 运行环境
- 可选在线 API
运行环境
本地渲染；官方提供 api.pixelrag.ai 预构建索引
核验与使用边界
优势与限制
优势
- 保留纯文本解析容易丢失的视觉结构
- 提供无需本地建索引的 Wikipedia demo
- 可作为 Claude Code 的截图工具
限制
- 截图增加渲染和视觉模型成本
- 动态页面、登录墙和小字体可能影响结果
- 在线 API 的数据边界需要单独确认
排错时先核对版本、运行环境和未覆盖范围。这里没有执行过的步骤不会写成实测结论。
版本与同类选择
版本与迁移信息
本轮按官方仓库 README 核对，没有锁定一个单独 release 版本。
常见问题
PixelRAG 会解析 HTML 吗？
它的核心路径是把页面渲染成截图后检索，目的是保留纯文本解析容易丢失的视觉结构。
必须自己建索引吗？
官方 API 有预构建 Wikipedia 索引；使用自己的资料则需要按仓库管线处理。
为什么不用普通 pip？
README 推荐 uv tool 或 pipx，主要是确保 pixelshot 命令稳定在 PATH。
在线 API 适合敏感文档吗？
不要默认适合。先确认数据传输、保存和服务条款，再决定是否上传。