# 知识库 (Knowledge Base) API 知识库 API 用于管理知识库和文档的创建、索引和搜索。 ## 基础信息 | 项目 | 值 | |------|-----| | Base URL | `/api/v1/knowledge` | | 认证方式 | Bearer Token (预留) | --- ## 数据模型 ### KnowledgeBase ```typescript interface KnowledgeBase { id: string; // 知识库唯一标识 (8位UUID) user_id: number; // 所属用户ID name: string; // 知识库名称 description: string; // 知识库描述 embeddingModel: string; // Embedding 模型名称 chunkSize: number; // 文档分块大小 chunkOverlap: number; // 分块重叠大小 docCount: number; // 文档数量 chunkCount: number; // 切分后的文本块数量 status: string; // 状态: "active" | "inactive" createdAt: string; // 创建时间 updatedAt: string; // 更新时间 documents: KnowledgeDocument[]; // 关联的文档列表 } ``` ### KnowledgeDocument ```typescript interface KnowledgeDocument { id: string; // 文档唯一标识 kb_id: string; // 所属知识库ID name: string; // 文档名称 size: string; // 文件大小 fileType: string; // 文件类型 storageUrl: string; // 存储地址 status: string; // 状态: "pending" | "processing" | "completed" | "failed" chunkCount: number; // 切分后的文本块数量 errorMessage: string; // 错误信息 uploadDate: string; // 上传时间 createdAt: string; // 创建时间 processedAt: string; // 处理完成时间 } ``` --- ## API 端点 ### 1. 获取知识库列表 ```http GET /api/v1/knowledge/bases ``` **Query Parameters:** | 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | user_id | int | 否 | 1 | 用户ID | | page | int | 否 | 1 | 页码 | | limit | int | 否 | 50 | 每页数量 | **Response:** ```json { "total": 2, "page": 1, "limit": 50, "list": [ { "id": "kb_001", "user_id": 1, "name": "产品知识库", "description": "产品文档和FAQ", "embeddingModel": "text-embedding-3-small", "chunkSize": 500, "chunkOverlap": 50, "docCount": 10, "chunkCount": 150, "status": "active", "createdAt": "2024-01-15T10:30:00", "updatedAt": "2024-01-15T10:30:00", "documents": [...] } ] } ``` --- ### 2. 获取单个知识库详情 ```http GET /api/v1/knowledge/bases/{kb_id} ``` **Response:** ```json { "id": "kb_001", "user_id": 1, "name": "产品知识库", "description": "产品文档和FAQ", "embeddingModel": "text-embedding-3-small", "chunkSize": 500, "chunkOverlap": 50, "docCount": 10, "chunkCount": 150, "status": "active", "createdAt": "2024-01-15T10:30:00", "updatedAt": "2024-01-15T10:30:00", "documents": [ { "id": "doc_001", "kb_id": "kb_001", "name": "产品手册.pdf", "size": "1.2 MB", "fileType": "application/pdf", "storageUrl": "", "status": "completed", "chunkCount": 45, "errorMessage": null, "uploadDate": "2024-01-15T10:30:00", "createdAt": "2024-01-15T10:30:00", "processedAt": "2024-01-15T10:30:05" } ] } ``` --- ### 3. 创建知识库 ```http POST /api/v1/knowledge/bases ``` **Request Body:** ```json { "name": "产品知识库", "description": "产品文档和FAQ", "embeddingModel": "text-embedding-3-small", "chunkSize": 500, "chunkOverlap": 50 } ``` **Fields 说明:** | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 知识库名称 | | description | string | 否 | 知识库描述 | | embeddingModel | string | 否 | Embedding 模型名称，默认 "text-embedding-3-small" | | chunkSize | int | 否 | 文档分块大小，默认 500 | | chunkOverlap | int | 否 | 分块重叠大小，默认 50 | --- ### 4. 更新知识库 ```http PUT /api/v1/knowledge/bases/{kb_id} ``` **Request Body:** (部分更新) ```json { "name": "更新后的知识库名称", "description": "新的描述", "chunkSize": 800 } ``` **注意:** 如果知识库中已有索引的文档，则不能修改 embeddingModel。如需修改，请先删除所有文档。 --- ### 5. 删除知识库 ```http DELETE /api/v1/knowledge/bases/{kb_id} ``` **Response:** ```json { "message": "Deleted successfully" } ``` **注意:** 删除知识库会同时删除向量数据库中的相关数据。 --- ### 6. 上传文档 ```http POST /api/v1/knowledge/bases/{kb_id}/documents ``` 支持两种上传方式： **方式一：文件上传 (multipart/form-data)** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | file | file | 是 | 要上传的文档文件 | 支持的文件类型：`.txt`, `.md`, `.csv`, `.json`, `.pdf`, `.docx` **方式二：仅创建文档记录 (application/json)** ```json { "name": "document.pdf", "size": "1.2 MB", "fileType": "application/pdf", "storageUrl": "https://storage.example.com/doc.pdf" } ``` **Response (文件上传):** ```json { "id": "doc_001", "name": "产品手册.pdf", "size": "1.2 MB", "fileType": "application/pdf", "storageUrl": "", "status": "completed", "chunkCount": 45, "message": "Document uploaded and indexed" } ``` --- ### 7. 索引文档内容 ```http POST /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}/index ``` 直接向向量数据库索引文本内容，无需上传文件。 **Request Body:** ```json { "content": "要索引的文本内容..." } ``` **Response:** ```json { "message": "Document indexed", "chunkCount": 10 } ``` --- ### 8. 删除文档 ```http DELETE /api/v1/knowledge/bases/{kb_id}/documents/{doc_id} ``` **Response:** ```json { "message": "Deleted successfully" } ``` --- ### 9. 搜索知识库 ```http POST /api/v1/knowledge/search ``` **Request Body:** ```json { "kb_id": "kb_001", "query": "产品退货政策", "nResults": 5 } ``` **Fields 说明:** | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | kb_id | string | 是 | 知识库ID | | query | string | 是 | 搜索查询文本 | | nResults | int | 否 | 返回结果数量，默认 5 | **Response:** ```json { "results": [ { "id": "doc_001", "text": "我们的退货政策是...", "score": 0.85, "metadata": { "document_name": "退货政策.pdf", "chunk_index": 3 } } ] } ``` --- ### 10. 获取知识库统计 ```http GET /api/v1/knowledge/bases/{kb_id}/stats ``` **Response:** ```json { "kb_id": "kb_001", "docCount": 10, "chunkCount": 150 } ``` --- ## 支持的文件类型 | 文件类型 | 扩展名 | 说明 | |----------|--------|------| | 纯文本 | .txt | 纯文本文件 | | Markdown | .md | Markdown 格式文档 | | CSV | .csv | CSV 表格数据 | | JSON | .json | JSON 格式数据 | | PDF | .pdf | PDF 文档 (需要 pypdf) | | Word | .docx | Word 文档 (需要 python-docx) | **注意:** 不支持旧的 .doc 格式，请转换为 .docx 或其他格式。 --- ## Schema 定义 ```python from pydantic import BaseModel from typing import Optional, List class KnowledgeBaseCreate(BaseModel): name: str description: Optional[str] = None embeddingModel: Optional[str] = "text-embedding-3-small" chunkSize: Optional[int] = 500 chunkOverlap: Optional[int] = 50 class KnowledgeBaseUpdate(BaseModel): name: Optional[str] = None description: Optional[str] = None embeddingModel: Optional[str] = None chunkSize: Optional[int] = None chunkOverlap: Optional[int] = None class KnowledgeSearchQuery(BaseModel): kb_id: str query: str nResults: Optional[int] = 5 class DocumentIndexRequest(BaseModel): content: str ``` --- ## 单元测试 项目包含完整的单元测试，位于 `api/tests/test_knowledge.py`。 ### 运行测试 ```bash # 运行知识库相关测试 pytest api/tests/test_knowledge.py -v # 运行所有测试 pytest api/tests/ -v ```