ColiVara
tjmlabs/ColiVara加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一个场景： 你上传了一份 200 页的 PDF 年度报告，里面混杂着文字段落、数据表格、流程图和截图。用传统的 RAG（检索增强生成）系统，你得先做 OCR 识别文本，再用规则切片（chunking），结果表格乱了套、截图的上下文丢了、页眉页脚的干扰词反而排在了前面。检索结果差，问答自然也不准。
ColiVara 换了一条完全不同的思路——不做文字提取，直接把文档当图片处理，用视觉语言模型（VLM）做语义索引。它不需要 OCR，不需要文本解析，不需要规则切片，文档是什么样子就原封不动地编码成向量。表格、截图、流程图、字体变化，一切视觉线索都被纳入检索。这不是简单的增强，而是对 RAG 范式的根本性挑战。
ColiVara 架构图
ColiVara 的技术根基是 2024 年 7 月发表的 ColPali 论文（arXiv:2407.01449）。ColPali 的核心创新在于将 Vision-Language Model（VLM）的 late-interaction 多向量嵌入机制引入文档检索领域。传统 RAG 用文本 embedding 模型产生一个池化向量（pooled embedding），而 ColPali/VLM 方案为文档页面的每个 patch（图像块）生成独立向量，查询时 Query 和 Document 之间做多向量 late interaction——这种机制在文本检索领域（如 ColBERT）已被验证能大幅提升召回精度。
tjmlabs 团队将 ColPali 从论文转化为可用的生产级服务，构建了完整的文档上传到视觉编码到向量存储到语义检索的全链路。2025 年 6 月发布 1.5.0 版本（Benchmark 平均得分已达 86.8，Vidore 数据集），部分子项高达 98.7。
ColiVara 的检索管线分为三个阶段：
1. 文档上传与格式转换
用户上传 PDF、DOCX、PPTX 等 100+ 种格式的文件，系统通过 Gotenberg 服务将所有文件统一转换为图像（PNG/JPG）。这一步完全规避了格式解析的歧义——无论文档内部结构多复杂，最终都变成像素矩阵。
2. 视觉语义编码（ColiVarE）
转换后的图像被送入 ColiVarE 嵌入服务，由 VLM（如 PaliGemma）进行编码。每个文档页面被划分为多个 patch，模型为每个 patch 生成独立的多维向量。这些向量存储在 PostgreSQL + pgvector（使用 HalfVecs 压缩格式）中，支持高速向量相似度搜索。
关键点：没有 OCR，没有文本提取，没有任何 chunking 规则。文档的视觉布局本身就是检索维度。
3. 查询与 Late-Interaction 匹配
用户输入自然语言查询后，Query 同样被 VLM 编码为多向量序列。系统通过 MaxSim（最大相似度）算法在向量空间中寻找与 Query 最匹配的文档页面（top-k）。与传统单向量 cosine 相似度不同，late-interaction 能捕捉查询词与文档局部区域之间的细粒度语义对齐。
对于包含大量表格、图表、截图的文档，ColiVara 的优势是压倒性的。传统 RAG 的文本提取在遇到合并单元格表格时就崩溃了，而 ColiVara 直接看到的是表格的像素图像。Benchmark 显示 InfoVQA（信息图表问答）得分高达 90.1，TabFQuad（表格问答）86.6，证明了其对结构化视觉内容的理解能力。
即使文档是纯文本的，ColiVara 仍然可能优于传统方案。原因在于 late-interaction 机制本身的检索精度优势，以及 VLM 强大的语义理解能力。README 中明确提到：即使是 text-only 数据集，ColiVara 依然超越了现有系统。
图1：ColiVara 在 Vidore Benchmark 上的评测结果对比
ColiVara 替用户托管了 PostgreSQL/pgvector、嵌入服务和文件存储（S3 兼容）。用户不需要自己搭向量数据库，不需要管理 GPU 资源，也不需要生成或保存嵌入向量——API 调用即完成一切。如果你想自托管，也可以通过嵌入端点自行处理。
项目主仓库（ColiVara）是 Django + FastAPI（Uvicorn）的 Python 后端，分为两个核心部分：
web/ — 主 API 服务（端口 8000）
ColiVarE（独立仓库）— 嵌入服务
依赖技术栈：Python 3.12、Django、FastAPI/Uvicorn、PostgreSQL 16 + pgvector、Docker Compose、Redis（生产环境缓存）、Gotenberg（文档转换）、uv 包管理。
本地开发（docker-compose.yml）
git clone https://github.com/tjmlabs/ColiVara
cd ColiVara
# 配置 .env.dev（ColiVarE URL、S3 凭证）
docker-compose up -d --build
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py createsuperuser
# 获取 Token 后访问 http://localhost:8001/v1/docs
pytest # 运行测试（100% 覆盖率）
生产环境（docker-compose-prod.yml）
生产配置增加了 Redis 缓存（LRU 驱逐，2GB 限制）和内存限制（web 6GB、gotenberg 3GB、redis 3GB），同时使用 release.sh 作为启动脚本。
SDK 快速接入
无需部署后端，直接使用官方 SDK：
pip install colivara-py
from colivara_py import ColiVara
client = ColiVara(api_key=os.environ.get("COLIVARA_API_KEY"))
doc = client.upsert_document(
name="report.pdf",
document_url="https://example.com/report.pdf",
wait=True
)
results = client.search("公司去年营收增长了多少？", collection_name="user_1_collection")
print(results)
Python SDK 和 TypeScript SDK 均已开源。
图2：ColiVara Release 1.5.0 分层聚类版本评测数据
| 维度 | 得分 | 备注 |
|---|---|---|
| Benchmark 平均 | 86.8 | Vidore Leaderboard |
| Artificial Intelligence | 98.7 | 最高分子项 |
| ArxivQA | 87.6 | 科研问答 |
| InfoVQA | 90.1 | 信息图表 |
| Healthcare Industry | 98.5 | 医疗文档 |
| Energy | 96.4 | 能源报告 |
| TabFQuad | 86.6 | 表格问答 |
| TatDQA | 70.9 | 最低子项，复杂表格仍有挑战 |
平均延迟 3-5 秒（1000 文档规模），整体性能已接近生产可用水平。
1. 必须 GPU — 嵌入服务需要 8GB+ VRAM 的 NVIDIA GPU，这是部署的硬性门槛。无 GPU 环境的用户只能使用官方托管 API（colivara.com 的云服务），自托管受限。
2. 延迟较高 — 相比纯文本 embedding（毫秒级），VLM 视觉编码单次推理在 3-8 秒，对实时性要求极高的场景不够友好。
3. TatDQA 短板 — 复杂多表文档问答（70.9 分）仍是明显短板，说明在跨页、多步推理场景下仍有提升空间。
4. 生态成熟度 — 作为一个新兴项目，LangChain/LlamaIndex 等主流 LLM 框架的原生集成尚在推进中，生态工具链不如传统 RAG 完善。
ColiVara 代表了文档 AI 领域的一个重要趋势：从文本优先到视觉优先的范式转换。ColPali/ColiVara 这条技术路线证明，视觉语言模型不只是能看图，它的多向量 late-interaction 机制在语义检索精度上天然优于传统文本 embedding。
随着 VLM 推理成本持续下降（GPT-4V → Gemini 1.5 Flash → 开源 PaliGemma），ColiVara 这类视觉优先检索方案的成本边界会进一步打开。它不仅仅是一个 RAG 增强工具，更可能成为未来文档智能基础设施的标准组件。
如果你在构建企业知识库、法律文档检索、财务报告分析、学术论文问答等应用，ColiVara 是目前最值得关注的新一代文档检索引擎之一。