7.9 KiB
7.9 KiB
知识库 (Knowledge Base) API
知识库 API 用于管理知识库和文档的创建、索引和搜索。
基础信息
| 项目 | 值 |
|---|---|
| Base URL | /api/v1/knowledge |
| 认证方式 | Bearer Token (预留) |
数据模型
KnowledgeBase
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
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. 获取知识库列表
GET /api/v1/knowledge/bases
Query Parameters:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| user_id | int | 否 | 1 | 用户ID |
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 50 | 每页数量 |
Response:
{
"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. 获取单个知识库详情
GET /api/v1/knowledge/bases/{kb_id}
Response:
{
"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. 创建知识库
POST /api/v1/knowledge/bases
Request Body:
{
"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. 更新知识库
PUT /api/v1/knowledge/bases/{kb_id}
Request Body: (部分更新)
{
"name": "更新后的知识库名称",
"description": "新的描述",
"chunkSize": 800
}
注意: 如果知识库中已有索引的文档，则不能修改 embeddingModel。如需修改，请先删除所有文档。
5. 删除知识库
DELETE /api/v1/knowledge/bases/{kb_id}
Response:
{
"message": "Deleted successfully"
}
注意: 删除知识库会同时删除向量数据库中的相关数据。
6. 上传文档
POST /api/v1/knowledge/bases/{kb_id}/documents
支持两种上传方式：
方式一：文件上传 (multipart/form-data)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | 是 | 要上传的文档文件 |
支持的文件类型：.txt, .md, .csv, .json, .pdf, .docx
方式二：仅创建文档记录 (application/json)
{
"name": "document.pdf",
"size": "1.2 MB",
"fileType": "application/pdf",
"storageUrl": "https://storage.example.com/doc.pdf"
}
Response (文件上传):
{
"id": "doc_001",
"name": "产品手册.pdf",
"size": "1.2 MB",
"fileType": "application/pdf",
"storageUrl": "",
"status": "completed",
"chunkCount": 45,
"message": "Document uploaded and indexed"
}
7. 索引文档内容
POST /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}/index
直接向向量数据库索引文本内容，无需上传文件。
Request Body:
{
"content": "要索引的文本内容..."
}
Response:
{
"message": "Document indexed",
"chunkCount": 10
}
8. 删除文档
DELETE /api/v1/knowledge/bases/{kb_id}/documents/{doc_id}
Response:
{
"message": "Deleted successfully"
}
9. 搜索知识库
POST /api/v1/knowledge/search
Request Body:
{
"kb_id": "kb_001",
"query": "产品退货政策",
"nResults": 5
}
Fields 说明:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kb_id | string | 是 | 知识库ID |
| query | string | 是 | 搜索查询文本 |
| nResults | int | 否 | 返回结果数量，默认 5 |
Response:
{
"results": [
{
"id": "doc_001",
"text": "我们的退货政策是...",
"score": 0.85,
"metadata": {
"document_name": "退货政策.pdf",
"chunk_index": 3
}
}
]
}
10. 获取知识库统计
GET /api/v1/knowledge/bases/{kb_id}/stats
Response:
{
"kb_id": "kb_001",
"docCount": 10,
"chunkCount": 150
}
支持的文件类型
| 文件类型 | 扩展名 | 说明 |
|---|---|---|
| 纯文本 | .txt | 纯文本文件 |
| Markdown | .md | Markdown 格式文档 |
| CSV | .csv | CSV 表格数据 |
| JSON | .json | JSON 格式数据 |
| PDF 文档 (需要 pypdf) | ||
| Word | .docx | Word 文档 (需要 python-docx) |
注意: 不支持旧的 .doc 格式，请转换为 .docx 或其他格式。
Schema 定义
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。
运行测试
# 运行知识库相关测试
pytest api/tests/test_knowledge.py -v
# 运行所有测试
pytest api/tests/ -v