PixelRAG：把表格和版式重新放回 RAG 的证据链

PixelRAG 更像一条可拆分的视觉数据管线，而不是一个“安装后自动变聪明”的 RAG 黑盒。它把网页/PDF 渲染、切瓦片、嵌入、建索引和提供搜索 API 分成独立阶段，工程上最值得借鉴的不是一句“截图比文本好”，而是每个阶段都能单独验收、替换和回滚。

从渲染开始建立可追踪输入

网页渲染必须处理字体加载、懒加载、动态请求、滚动触发和宽页面。PixelRAG 的 pixelshot 通过 CDP 捕获页面，并在新版本中记录源文档、article_id 与 manifest，避免增量重跑时把一个文档的图像错配到另一个文档。对生产系统来说，这类元数据和原子写入比演示效果更重要。

轻量安装与重量级阶段分离

根包只承担截图和 CLI，embed/index/serve 通过 extras 引入 PyTorch、Transformers、FAISS、FastAPI 等依赖；训练目录又是单独的 uv 项目。这样可以先把渲染作为独立服务部署，再根据规模增加嵌入和检索资源，也避免每个开发环境都下载完整训练栈。

pip install pixelrag
pip install "pixelrag[embed]"
pip install "pixelrag[serve,qdrant]"
# 训练环境必须在 train/ 中单独 uv sync

FAISS 适合本地，Qdrant 适合共享服务

FAISS 是低复杂度的默认选择，适合单机索引和实验；Qdrant 提供磁盘向量、payload 过滤、量化和多服务共享 collection 的能力。量化能降低内存和搜索成本，但会带来召回权衡。选择后端时要同时压测召回率、更新方式、并发、磁盘占用和故障恢复，不要只看首次查询延迟。

评测不能只报一个总分

项目 eval 目录把 reader、pixel/text serve、索引和 grader 分开，并提醒 NQ/NQ-Tables 的论文数字使用 LLM judge，严格 exact-match 会低很多。复现实验时应记录 reader 模型、top-k、查询指令、judge、数据版本和硬件；否则“提升了多少”无法与论文或自己的旧管线比较。

生产拓扑需要可回滚

官方 deploy 文档采用两个搜索 API slot，通过 nginx upstream 切换，先启动空闲槽、健康检查和 smoke 后再切流；大 FAISS 索引原地重启会造成分钟级中断，因此蓝绿切换比简单 restart 更合适。索引和模型变更也要有版本指纹、样本查询和回滚槽。

一份可执行的上线清单

先锁定浏览器和模型版本，再保存渲染 manifest；用一小组表格、图表和普通文本做金丝雀；检查搜索返回的瓦片能否被 reader 读取；压测冷启动、并发和内存；最后才扩展到大索引。若任何阶段不能解释输入、输出和失败处方，就还不适合交给无人值守的 Agent。