operations_project/apps/knowledge_base/knowledge_base_readme.md

知识库模块使用文档

概述

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

模型结构

KnowledgeBase 模型

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

KnowledgeBaseDocument 模型

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

API接口使用方法

1. 知识库创建

POST /api/knowledge-base/

请求参数:

{
  "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/

请求参数:

{
  "type": "private",
  "department": "部门名称",
  "group": "组名称"
}

6. 文档上传

POST /api/knowledge-base/{id}/upload_document/

请求参数:

• 使用multipart/form-data格式
• 字段名使用files或file
• 支持多文件批量上传

接口响应:

{
  "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请求
• 提供统一的错误处理和日志记录

示例代码

创建知识库:

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)}")

上传文档:

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连接状态

未来计划

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