Quivr 怎么用：从 Docker 部署到知识库上传的完整流程

Quivr 是一个开源的文档问答工具，上传资料后可以基于这些内容向大模型提问。
很多新手卡在第一步：不知道它需要哪些外部依赖，也不清楚装好之后从哪里开始用。
本文按实际使用顺序，从环境准备讲到知识库上传和问答验证，适合已经有一台 Linux 服务器、想快速跑通 Quivr 的用户。

装之前先确认这三样东西

Quivr 本身不包含大模型，需要调用外部 API 或自建模型服务。
以最常见的 OpenAI 接口为例，你需要：

• 一台安装了 Docker 和 Docker Compose 的 Linux 服务器，建议内存不低于 4GB。
• 一个可用的 OpenAI API Key，并且账户有余额。Quivr 的向量化和问答都依赖它，没有 Key 或余额不足时，上传文档和提问都会失败。
• 服务器能正常访问 api.openai.com。如果服务器在国内，需要提前配置网络代理，否则容器内请求会超时。

可以用下面两条命令快速检查 Docker 环境：

docker --version
docker compose version

两条命令都能输出版本号，再继续下一步。

用 compose 启动 Quivr 服务

Quivr 官方提供了 docker-compose 部署方式。
先拉取代码：

git clone https://github.com/QuivrHQ/quivr.git
cd quivr

进入项目目录后，复制环境变量模板并编辑：

cp .env.example .env
nano .env

在 .env 中至少确认这两项：

OPENAI_API_KEY=sk-你的实际Key
SUPABASE_URL=你的Supabase地址

Quivr 使用 Supabase 存储向量数据。
如果你没有现成的 Supabase 实例，需要先按项目文档启动自带的 Supabase 服务，或者使用 Supabase 云服务并填入对应的 URL 和 Key。
这一步是新手最容易漏掉的，没有配置 Supabase，容器能启动但无法保存知识库。

配置完成后启动：

docker compose up -d

启动后检查容器状态：

docker compose ps

确认 backend、frontend 和 supabase 相关容器都是 Up 状态。
如果某个容器反复重启，用 docker compose logs 容器名 查看报错，常见原因是环境变量缺失或端口冲突。

在网页端创建知识库并上传文档

浏览器访问 http://服务器IP:3000，首次打开会进入 Quivr 的界面。
按下面顺序操作：

1. 点击左侧的 Add Knowledge Base，输入一个名称，例如“产品手册”，点击创建。
2. 进入刚创建的知识库，点击 Upload 按钮，选择本地 PDF、TXT 或 Markdown 文件。
3. 上传后页面会显示处理状态。等状态变为可用，说明文档已经完成解析和向量化。
4. 回到对话输入框，输入一个文档中明确写有的问题，例如文档里写了“退货期限是 7 天”，就问“退货期限是多久”。

如果回答内容与文档一致，说明整个流程已经跑通。

上传成功但答非所问怎么排查

文档显示上传成功，提问却得不到相关内容，按以下顺序检查：

• API Key 是否有效：进入服务器项目目录，执行 docker compose logs backend | grep -i openai，如果出现 401 或 insufficient_quota，说明 Key 错误或余额不足。
• 文档是否解析完成：在知识库页面查看文件状态，如果一直停留在处理中，可能是文件过大或格式不支持。先换一个小的 TXT 文件测试。
• 问题是否超出文档范围：Quivr 只基于已上传内容回答，问文档里没有的信息，模型可能编造或拒答。换一个文档中明确写有的问题再试。
• Supabase 连接是否正常：执行 docker compose logs backend | grep -i supabase，如果出现连接超时，检查 .env 中的 SUPABASE_URL 和 SUPABASE_KEY 是否与 Supabase 实例匹配。

日常使用要注意的两个点

第一，Quivr 的问答质量取决于文档切分和向量化效果。
上传结构清晰的 Markdown 或纯文本，比扫描版 PDF 效果更好。
扫描件需要先做 OCR，否则解析出来是空内容。

第二，修改 .env 后必须重启服务才生效：

docker compose down
docker compose up -d

不要只重启前端容器，后端读取的是启动时的环境变量。

如果部署过程中遇到端口占用，可以修改 docker-compose.yml 中 frontend 的端口映射，例如把 3000:3000 改成 8080:3000，然后重新启动。

整体来看，Quivr 的使用门槛主要在前期依赖配置，只要 API Key 和 Supabase 两项填对，后续上传文档和提问都是界面操作。
建议第一次部署时先用一个小文本文件验证流程，再批量上传正式资料。