# 知识库管理系统 - 环境变量配置

## 新增环境变量

在 `chat-ai-api/.env` 文件中添加以下配置：

```env
# ========== 阿里云 OSS 配置 ==========
ALIYUN_OSS_ACCESS_KEY_ID=your_access_key_id
ALIYUN_OSS_ACCESS_KEY_SECRET=your_access_key_secret
ALIYUN_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
ALIYUN_OSS_BUCKET=chat-ai-knowledge

# ========== Qdrant 向量数据库配置 ==========
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=kb_vectors

# ========== 向量模型配置 ==========
# 使用豆包的 doubao-embedding-vision-251215 向量模型
# 无需额外配置，使用现有的 ARK_API_KEY 和 ARK_BASE_URL
```

## MongoDB 集合说明

系统会自动创建以下集合（在 `arklogs` 数据库中）：

1. **kb_documents** - 文档元数据
   - tenant_id: 租户ID（appName）
   - filename: 文件名
   - file_type: 文件类型（.xlsx, .docx, .pdf）
   - file_size: 文件大小
   - oss_path: 阿里云OSS路径
   - status: 处理状态（pending, processing, completed, failed）
   - chunk_count: 切片数量
   - created_at, updated_at, deleted

2. **kb_chunks** - 文档切片
   - doc_id: 所属文档ID
   - tenant_id: 租户ID
   - chunk_index: 切片索引
   - content: 切片内容
   - vector_id: Qdrant中的向量ID
   - metadata: 元数据
   - created_at, deleted

3. **kb_tenants** - 租户配置
   - tenant_id: 租户ID（appName）
   - agent_enabled: 智能客服是否开启
   - agent_name: 客服名称
   - agent_greeting: 欢迎语
   - created_at, updated_at, deleted

## Qdrant 安装和启动

### Docker 方式（推荐）
```bash
docker run -d -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  --name qdrant \
  qdrant/qdrant
```

### 验证 Qdrant 运行
```bash
curl http://localhost:6333/collections
```

## 阿里云 OSS Bucket 配置

1. 登录阿里云控制台
2. 创建 Bucket：`chat-ai-knowledge`
3. 设置权限：私有读写
4. 创建 RAM 用户并获取 AccessKey
5. 为 RAM 用户授予 OSS 读写权限

## API 接口说明

### 知识库管理接口（/main/kb）

#### 文档管理
- `POST /main/kb/documents/upload` - 上传文档
- `GET /main/kb/documents` - 获取文档列表
- `GET /main/kb/documents/{doc_id}` - 获取文档详情（含切片）
- `DELETE /main/kb/documents/{doc_id}` - 删除文档

#### 智能客服配置
- `GET /main/kb/agent/config` - 获取智能客服配置
- `POST /main/kb/agent/config` - 更新智能客服配置

#### 统计
- `GET /main/kb/stats` - 获取知识库统计数据

## 嵌入地址格式

新的嵌入地址携带租户信息：

```
https://aichat.zhongsou.com/?token=<用户token>&source=app&tenant=<租户ID>
```

例如：
```
https://aichat.zhongsou.com/?token=237ea8d7-a042-4f1c-b084-281f3fd4eab1&source=app&tenant=com.xiaoyouhui
```

参数说明：
- `token`: 用户登录令牌
- `source`: 来源标识（app表示来自App）
- `tenant`: 租户ID（等同于appName，如 com.xiaoyouhui）

## 工作流程

### 文档上传流程
1. 用户上传文档（Excel/Word/PDF）
2. 文件上传到阿里云 OSS（路径：`{tenant_id}/documents/{timestamp}_{filename}`）
3. 后台任务开始处理：
   - 提取文本内容
   - 智能切片（800字符/片，100字符重叠）
   - 调用豆包 embedding API 生成向量
   - 向量存储到 Qdrant
   - 切片元数据存储到 MongoDB
4. 文档状态更新为 completed

### 聊天检索流程
1. 用户发送消息
2. 系统根据租户ID检索自建知识库：
   - 用户消息向量化
   - Qdrant 相似度搜索（Top 5）
   - 获取完整切片内容
3. 将检索结果注入到 system prompt
4. 模型基于知识库内容生成回答
5. 知识库不足时才触发联网搜索

## 多租户隔离

- **文件存储隔离**: OSS 使用租户前缀（`{tenant_id}/`）
- **向量检索隔离**: Qdrant 搜索时过滤 `tenant_id`
- **数据库隔离**: MongoDB 所有文档和切片都带 `tenant_id` 字段

## AI 配置新增字段

在 `ai_config` 集合中新增字段：
- `use_custom_kb`: 是否使用自建知识库（默认 true）
- 保留 `knowledgeId` 用于兼容豆包原生知识库