hyf-backend/scripts/setup_vector_db.md

本地向量数据库配置指南

当前配置

项目使用 ChromaDB 作为本地向量数据库，数据存储在 ./data/chroma/ 目录下。

配置说明

1. 环境变量配置 (.env)

在 .env 文件中配置以下参数：

# 向量数据库类型（虽然代码中已使用 Chroma，但建议设置为 chroma）
VECTOR_DB_TYPE=chroma

# 向量数据库存储路径（本地文件系统）
# 相对路径会基于项目根目录
VECTOR_DB_PERSIST_DIRECTORY=./data/chroma

# 集合名称（默认）
VECTOR_DB_COLLECTION_NAME=documents

2. 目录结构

向量数据库按知识库 ID 组织，每个知识库有独立的目录：

data/chroma/
├── kb_1/          # 知识库 1 的向量数据
├── kb_2/          # 知识库 2 的向量数据
├── kb_13/         # 知识库 13 的向量数据
└── ...

3. 使用方式

向量数据库会在以下场景自动创建：

1. 上传文档时：如果上传时选择立即处理，会自动创建向量数据库
2. 处理文档时：调用 POST /api/knowledge-bases/{kb_id}/documents/{doc_id}/process 接口

4. 验证安装

运行以下命令验证向量数据库是否正常工作：

python3 -c "
import chromadb
from pathlib import Path

# 测试创建本地 Chroma 数据库
test_path = './data/chroma/test_kb'
client = chromadb.PersistentClient(path=test_path)
collection = client.get_or_create_collection(name='test')
print('✅ ChromaDB 本地数据库创建成功')
"

5. 依赖包

已安装的依赖：

• chromadb>=1.0.20 - ChromaDB 核心库
• langchain-chroma>=0.1.0 - LangChain Chroma 集成

6. 注意事项

• 向量数据库数据存储在本地文件系统，无需额外服务
• 每个知识库的向量数据独立存储
• 删除知识库时，对应的向量数据目录也会被清理
• 确保 data/chroma/ 目录有写入权限

故障排查

问题：向量数据库不存在

原因：文档尚未被处理和向量化

解决：

1. 先调用处理文档接口：POST /api/knowledge-bases/{kb_id}/documents/{doc_id}/process
2. 处理完成后，向量数据库会自动创建

问题：权限错误

解决：

chmod -R 755 data/chroma/

问题：磁盘空间不足

解决：清理不需要的知识库向量数据，或扩展存储空间