chat-ai-api/KB_README.md

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

新增环境变量

在 chat-ai-api/.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 方式（推荐）

docker run -d -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  --name qdrant \
  qdrant/qdrant

验证 Qdrant 运行

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 用于兼容豆包原生知识库