# 本地向量数据库配置指南

## 当前配置

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

## 配置说明

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

在 `.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. 验证安装

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

```bash
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. 处理完成后，向量数据库会自动创建

### 问题：权限错误

**解决**：
```bash
chmod -R 755 data/chroma/
```

### 问题：磁盘空间不足

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