把公司内部的合同、技术手册、会议纪要统一丢进一个系统，然后像聊天一样随时问它“去年 Q3 的服务器采购条款是什么”，这大概是很多团队对知识库的终极想象。但一旦涉及敏感数据，把文档传到云端 SaaS 服务里往往意味着合规风险。Quivr 正是为解决这个矛盾而生的开源项目——它把检索增强生成（RAG）能力打包成一个完整平台，让你可以在自己的服务器上跑起一个“第二大脑”，文档不出内网，答案照样精准。
Quivr 的核心定位是“开源的 GenAI 第二大脑”，本质上是一个全栈 RAG 应用。它不是一个简单的 Python 库，而是包含了前端界面、后端 API、向量数据库和文档解析管道的完整系统。你可以通过浏览器上传 PDF、Markdown、Word 文件，系统会自动完成切片、向量化并存入知识库，之后就能以对话方式检索提问。相比从零搭建 LangChain 管道，Quivr 最大的价值在于把“能跑通的 RAG 系统”这件复杂事，压缩成了几条 Docker 命令。
部署前的硬件与架构认知
在动手敲命令之前，先想清楚一个关键问题：你的文档要存在哪里，模型要跑在哪里。Quivr 本身支持多种部署形态，但私有化部署的核心诉求通常是“数据不出内网”，这意味着你需要本地运行大模型，而不是调用 OpenAI 等云端 API。
这里有个容易被忽略的点：Quivr 的架构里，向量化（Embedding）和生成回答（LLM）是两个独立环节。你可以用本地模型做 Embedding，同时用云端模型做生成，也可以全部本地化。如果追求完全离线，两者都需要本地跑。硬件门槛主要取决于你选的模型大小——7B 参数的量化模型通常需要至少 8GB 显存，13B 模型建议 16GB 以上，如果跑 70B 级别模型，单卡 24GB 是起步线。CPU 推理不是不行，但长文档检索的响应延迟会明显拉高，体验会打折扣。
用 Docker 拉起 Quivr 全家桶
Quivr 官方提供了完整的 Docker Compose 配置，这是目前最省心的部署路径。整个栈包含前端（Next.js）、后端（FastAPI）、PostgreSQL（元数据存储）、Supabase（认证与存储）以及向量数据库。默认情况下，Quivr 使用 Supabase 作为其后端服务，但私有化部署时你需要用自托管的 Supabase 容器替代云服务。
部署的第一步是克隆仓库并准备环境变量文件：
git clone https://github.com/QuivrHQ/quivr.git
cd quivr
cp .env.example .env在 .env 文件中，你需要修改几个核心配置项。首先是 POSTGRES_USER、POSTGRES_PASSWORD 和 POSTGRES_DB，这些是数据库的访问凭证。其次是 JWT_SECRET_KEY，用于生成认证令牌，务必改成足够随机的长字符串。接着是 SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY，在自托管模式下，它们指向本地运行的 Supabase 容器地址，默认通常是 http://supabase:8000。
配置完成后，执行：
docker compose up -d首次启动会拉取多个镜像，耗时取决于网络状况。全部容器进入运行状态后，访问 http://localhost:3000 即可看到 Quivr 的登录界面。首次访问需要注册账号，这个账号会保存在本地 Supabase 实例中，不会外传。
配置 Megaparse 解析管道：长文档切片的关键
文档解析质量直接决定检索效果。Quivr 默认使用内部的解析逻辑，但对长文档（比如几十页的 PDF）经常出现切片不理想、上下文断裂的问题。Quivr 集成了 Megaparse 作为增强解析方案，专门优化了 PDF、DOCX 等格式的版面分析和语义切分。
Megaparse 的核心优势在于智能切片。普通 RAG 管道按固定字符数硬切，很容易把一句话或一个表格从中间切断，导致向量化后语义失真。Megaparse 会先做版面分析，识别标题、段落、表格、页眉页脚，然后基于语义边界切片，每个 chunk 尽量保持完整语义单元。
在 Quivr 中启用 Megaparse，需要在 .env 中设置：
MEGAPARSE_API_KEY=your_key不过要注意，Megaparse 本身有云端 API 和本地开源版本之分。完全离线部署时，你需要运行自托管的 Megaparse 服务，并在 Quivr 的后端配置中把解析端点指向本地地址。具体做法是在 quivr-backend 容器的环境变量中设置：
MEGAPARSE_URL=http://megaparse:8080这样上传的文档会先经过本地 Megaparse 完成解析和切片，再进入向量化环节。对于动辄上百页的技术手册，这一步能显著减少后续检索时的“答非所问”。
连接本地大模型：Ollama 与 API 调优
Quivr 通过 LLM_SUPPLIER 环境变量决定使用哪家模型服务。选择 ollama 时，配置如下：
LLM_SUPPLIER=ollama
OLLAMA_API_BASE_URL=http://ollama:11434
OLLAMA_MODEL=llama3.1:8b同时还需要指定 Embedding 模型。Quivr 支持通过 Ollama 加载 Embedding 模型，比如 nomic-embed-text 或 bge-m3：
EMBEDDING_SUPPLIER=ollama
EMBEDDING_MODEL=nomic-embed-text这里有一个实践建议：生成模型和 Embedding 模型不要共用同一个模型。生成模型追求对话质量和推理能力，Embedding 模型追求语义表征的维度与区分度，混用会导致检索质量下降。
连接完成后，在 Quivr 的“设置”页面里把模型供应商切换为 Ollama，并选择已经拉取到本地的模型。第一次提问时会明显感觉到响应速度比云端 API 慢，这是本地推理的正常现象。如果延迟过高，可以调整 CHUNK_SIZE 和 CHUNK_OVERLAP 参数——默认切片大小是 1200 字符，重叠 200 字符，对中文文档建议把 CHUNK_SIZE 降到 800 左右，减少单次送入模型的 token 数，能有效降低首 token 延迟。
长文档切片失真与检索延迟的排错思路
部署完成后，最常见的两个问题是“检索结果不相关”和“回答太慢”，两者往往相互关联。
切片失真的典型表现是：文档明明包含答案，但模型答非所问。排查时先确认 Megaparse 是否真正生效——上传一个带复杂表格的 PDF，在 Quivr 后台查看解析后的文本块，如果表格被拆得七零八落，说明解析管道没走对。另一种可能是 Embedding 模型对中文支持不佳，nomic-embed-text 的中文效果只能说够用，换成 bge-m3 或 bge-large-zh 会有明显改善。
检索延迟的瓶颈通常在向量检索环节。Quivr 默认使用 PostgreSQL 的 pgvector 扩展做相似度检索，当文档数量超过几万条 chunk 时，暴力扫描的耗时就会凸显。解决思路有两个：一是调低 RETRIEVAL_K 值（默认返回 10 条），减少后续重排和生成的负载；二是为向量字段建立 HNSW 索引：
CREATE INDEX ON vectors USING hnsw (embedding vector_cosine_ops);这个索引能把检索时间从线性扫描降到对数级别，对知识库体量增长后的体验提升非常明显。
Quivr 的私有化部署并不复杂，但也不是开箱即用的零配置工具。它适合那些对数据主权有明确要求、并且愿意花半天时间折腾环境的团队。如果你只是想快速验证 RAG 效果，用云端 API 跑通再迁移到本地是更平滑的路径。而一旦完成本地化落地，文档留在内网、模型跑在自己的显卡上，这种“完全可控”的安全感，是任何 SaaS 知识库都给不了的。
评论列表 (1条)：
加载更多评论 Loading...