daren/apps/knowledge_base/knowledge_base_readme.md

# 知识库模块使用文档

## 概述

知识库模块提供了创建、管理和查询知识库的功能，支持文档的上传、分割和检索。本模块与外部API服务交互，实现知识库的高级功能。

## 模型结构

### KnowledgeBase 模型
- 核心知识库模型，包含知识库的基本信息和文档引用
- 支持多种知识库类型：管理级、部门级、成员级、私有、保密级
- 与外部知识库API进行同步

### KnowledgeBaseDocument 模型
- 知识库文档关联模型
- 保存文档基本信息和外部文档ID
- 提供文档状态管理（有效/已删除）

## API接口使用方法

### 1. 知识库创建
```
POST /api/knowledge-base/
```

**请求参数:**
```json
{
  "name": "知识库名称",
  "desc": "知识库描述",
  "type": "private", // admin/leader/member/private/secret
  "department": "部门名称", // 当type为leader或member时必填
  "group": "组名称" // 当type为member时必填
}
```

**注意事项:**
- 名称必须唯一
- 权限等级与用户角色匹配：
  - 管理员可创建所有类型知识库
  - 部门领导可创建成员级和私有知识库
  - 普通成员只能创建私有知识库

### 2. 知识库查询
```
GET /api/knowledge-base/
GET /api/knowledge-base/{id}/
```

**查询参数:**
- `page`: 页码
- `page_size`: 每页数量
- `keyword`: 搜索关键词

**搜索接口:**
```
GET /api/knowledge-base/search/?keyword=关键词
```

### 3. 知识库更新
```
PUT/PATCH /api/knowledge-base/{id}/
```

**请求参数:**
与创建接口相同，支持部分字段更新

### 4. 知识库删除
```
DELETE /api/knowledge-base/{id}/
```

**注意事项:**
- 删除知识库会同时删除本地数据和外部知识库数据
- 如果外部删除失败，本地数据仍会被删除

### 5. 知识库类型修改
```
POST /api/knowledge-base/{id}/change_type/
```

**请求参数:**
```json
{
  "type": "private",
  "department": "部门名称",
  "group": "组名称"
}
```

### 6. 文档上传
```
POST /api/knowledge-base/{id}/upload_document/
```

**请求参数:**
- 使用multipart/form-data格式
- 字段名使用`files`或`file`
- 支持多文件批量上传

**接口响应:**
```json
{
  "code": 200,
  "message": "文档上传完成，成功: X，失败: Y",
  "data": {
    "uploaded_count": X,
    "failed_count": Y,
    "total_files": Z,
    "documents": [文档列表],
    "failed_documents": [失败文档列表]
  }
}
```

### 7. 获取文档列表
```
GET /api/knowledge-base/{id}/documents/
```

### 8. 获取文档内容
```
GET /api/knowledge-base/{id}/document_content/?document_id=xxx
```

### 9. 删除文档
```
DELETE /api/knowledge-base/{id}/delete_document/?document_id=xxx
```

## 操作流程

### 知识库创建流程
1. 验证用户权限与知识库类型匹配
2. 创建本地知识库记录
3. 调用外部API创建知识库
4. 更新本地记录的external_id
5. 创建相应的权限记录

### 文档上传流程
1. 验证用户对知识库的编辑权限
2. 验证知识库external_id存在且有效
3. 调用分割API处理文件（支持批量处理）
4. 获取分割结果，处理每个文档
5. 调用上传API将文档发送到外部知识库
6. 创建本地文档记录，关联外部文档ID

## 注意事项

1. **外部API依赖**
   - 知识库功能强依赖外部API服务
   - 如果外部API不可用，部分功能将无法正常工作
   - 外部服务响应超时可能导致操作失败

2. **权限管理**
   - 知识库访问基于用户角色和显式权限控制
   - 默认权限基于知识库类型和用户所属部门/组
   - 可通过权限表提供额外访问权限

3. **文件处理**
   - 支持多种文件格式，但实际处理能力依赖外部API
   - 大文件上传可能需要较长时间，请确保请求超时设置合理
   - 批量上传文件时注意总大小限制

4. **数据一致性**
   - 本地数据与外部API数据同步依赖于操作成功
   - 操作失败可能导致数据不一致

## 需要优化的地方

1. **错误处理**
   - 完善外部API调用的错误处理机制
   - 对特定异常类型进行更精确的处理
   - 减少使用通用异常捕获，改为针对特定异常处理

2. **事务管理**
   - 增强本地数据库操作与外部API调用的事务一致性
   - 在外部API调用失败时，回滚本地数据库事务
   - 提供数据修复工具，处理不一致状态

3. **模型定义优化**
   - 修复to_response_dict方法中对不存在字段的引用
   - 移除或添加缺失的字段：meta、embedding_mode_id等
   - 优化from_external_format方法的参数使用

4. **批量处理能力**
   - 进一步优化文件批量处理的效率
   - 提供异步处理大量文件的能力
   - 增加处理进度反馈机制

5. **日志与监控**
   - 增强日志记录的详细程度和结构化
   - 添加关键操作的审计日志
   - 实现对外部API调用的监控和告警

6. **响应格式统一**
   - 标准化API响应格式
   - 统一错误码和错误信息的表达方式
   - 提供结构化的错误详情

## 开发指南

### 架构说明
- 本地模型与外部知识库API保持同步
- 本地存储基本元数据，内容存储在外部API
- KnowledgeBaseDocument作为文档映射和状态管理工具

### 外部API交互
- 所有外部API调用封装在external_api_service.py中
- 使用requests库进行API请求
- 提供统一的错误处理和日志记录

### 示例代码

**创建知识库:**
```python
from apps.knowledge_base.models import KnowledgeBase
from apps.common.services.external_api_service import create_external_dataset

# 创建本地知识库
knowledge_base = KnowledgeBase.objects.create(
    name="测试知识库",
    desc="这是一个测试知识库",
    type="private",
    user_id=request.user.id
)

# 创建外部知识库
try:
    external_id = create_external_dataset(knowledge_base)
    knowledge_base.external_id = external_id
    knowledge_base.save()
except ExternalAPIError as e:
    # 处理错误
    logger.error(f"创建外部知识库失败: {str(e)}")
```

**上传文档:**
```python
from apps.common.services.external_api_service import call_split_api_multiple, call_upload_api

# 分割文件
split_response = call_split_api_multiple(files)

# 处理分割结果
if split_response and split_response.get('code') == 200:
    documents_data = split_response.get('data', [])
    for doc in documents_data:
        # 上传到外部知识库
        doc_data = {
            "name": doc.get('name'),
            "paragraphs": [...]  # 组装段落数据
        }
        upload_response = call_upload_api(external_id, doc_data)
        
        # 处理上传结果
        if upload_response and upload_response.get('code') == 200:
            # 创建本地文档记录
            document_id = upload_response['data']['id']
            KnowledgeBaseDocument.objects.create(...)
```

## 故障排除

1. **创建知识库失败**
   - 检查API_BASE_URL配置是否正确
   - 验证外部API服务是否可用
   - 检查用户权限是否满足要求

2. **文档上传失败**
   - 检查文件格式是否支持
   - 查看日志了解具体错误原因
   - 验证知识库external_id是否正确

3. **查询文档内容失败**
   - 确认文档ID是否存在
   - 检查用户是否有查看权限
   - 验证外部API连接状态

## 未来计划

- 添加文档版本控制功能
- 增强文档搜索和过滤能力
- 提供文档内容编辑功能
- 优化多文件批处理性能
- 添加知识库统计和分析功能