Quivr 知识库怎么配置：从创建到上传文档的完整流程
Quivr 知识库配置主要围绕三件事展开：先准备好可运行的环境，再创建 Brain（Quivr 中用于存放知识库的容器），然后上传文档并检查检索是否正常。
整个过程不复杂，但向量存储和嵌入模型的选型会直接影响后续使用体验，建议按本文顺序操作。
开始前需要确认的条件
Quivr 支持云端托管和自托管两种方式。
云端注册后即可使用，适合快速验证；
自托管适合对数据隐私有要求或需要深度定制的场景。
无论哪种方式，动手前先确认以下条件：
- 账号与权限：云端版需要注册 Quivr 账号；自托管需要能操作 Docker 和服务器命令行。
- 文档格式：Quivr 支持常见文本类文件，上传前把扫描版 PDF、图片型文档先转成可提取文字的格式，否则后续检索可能为空。
- 网络环境：自托管部署时，拉取镜像和调用嵌入模型接口都可能需要稳定的外网连接。
- 密钥准备：如果使用 OpenAI 等外部嵌入模型，需要提前准备好 API Key，并确认账户有可用额度。
创建 Brain 并选择存储与模型
Brain 是 Quivr 管理知识库的基本单位，一个账号可以创建多个 Brain，分别对应不同主题或团队。
登录后进入 Brain 管理页面，点击新建，填写名称和描述。
描述建议写清楚这个知识库的用途，例如“产品售后问答库”，方便后续区分。
创建过程中会涉及两个关键选项：
- 向量存储（Vector Store）：用于存放文档切片的向量表示。云端版通常提供默认选项；自托管常见选择包括 Supabase、PGVector 等。选型时优先考虑你已有运维能力的数据库，避免额外维护负担。
- 嵌入模型（Embedding Model）：决定文档如何转成向量。使用外部模型时注意 API Key 的配置位置，通常在环境变量或设置页的模型配置区域。
配置完成后保存，回到 Brain 列表确认新知识库已出现。
上传文档与检查解析结果
进入刚创建的 Brain，找到上传入口，选择本地文件或拖拽上传。
上传后 Quivr 会自动进行文本提取、切片和向量化，这一步需要等待处理完成。
上传完成后重点检查两件事：
- 文档状态：确认文件显示为已处理，而不是停留在处理中或失败状态。
- 切片数量：如果切片数为 0 或明显偏少，通常说明文本提取失败，需要检查文件是否为扫描件或加密 PDF。
对于自托管环境，如果上传后长时间无响应，先查看后端服务日志，确认嵌入模型接口是否可达、向量数据库连接是否正常。
验证检索效果与常见问题
配置是否成功，最终要看提问时能否召回正确内容。
在 Brain 的对话或检索入口输入一个文档中明确存在答案的问题，观察返回结果是否引用了对应文档片段。
如果检索结果不理想，按以下顺序排查：
- 回答为空或无关：确认文档已成功向量化，切片数量不为零。
- 上传报错：检查文件大小是否超限、格式是否在支持列表内。
- 自托管连接失败：核对环境变量中的数据库连接串和 API Key 是否填写正确，重启服务后重试。
- 检索速度慢：向量数据库资源不足或嵌入模型响应慢都可能导致延迟，可先单独测试模型接口的响应时间。
配置完成后建议先用少量文档跑通全流程，再批量导入，这样出问题时更容易定位。
常见疑问
Quivr 知识库配置必须用 OpenAI 吗？
不一定。Quivr 支持多种嵌入模型，具体可选范围取决于你使用的版本和部署方式。自托管时可在模型配置中替换为其他兼容服务，但需要确认向量维度与存储端匹配。
一个 Brain 放多少文档合适？
没有固定上限，但文档越多，检索时的候选范围越大。建议按主题拆分 Brain，而不是把所有资料堆在一个库里，这样召回结果更集中。
上传后能修改或删除文档吗？
通常可以在 Brain 的文档管理界面操作。删除文档后对应的向量数据一般会同步清理，但不同版本行为可能有差异，操作前建议先确认当前版本的文档管理功能。
自托管部署时数据库连不上怎么办？
先检查容器网络是否互通，再核对连接串中的主机名、端口、用户名和密码。用 docker logs 查看后端服务日志，通常能看到具体的连接错误信息。
