X-Agents/teams/api/knowledge-api.md

知识库 API

基础信息

项目	说明
基础URL	http://localhost:8082

接口列表

1. 创建知识库

请求

POST /api/knowledge/create
Content-Type: application/json

参数	类型	必填	说明
name	String	是	知识库名称
description	String	否	知识库描述
llm_model_id	String	是	LLM 模型 ID
embedding_model_id	String	是	Embedding 模型 ID
parsing_config	Object	是	解析配置
- engine	String	是	解析引擎：markitdown / docling
- docling_url	String	条件	Docling URL（engine=docling 时必填）
- enable_pdf	Boolean	否	是否启用 PDF 解析
- pandoc	Boolean	否	是否启用 Pandoc
storage_config	Object	否	存储配置，不传则使用全局配置
- type	String	否	存储模式：local / minio
- endpoint	String	否	MinIO endpoint
- bucket	String	否	MinIO bucket
- access_key	String	否	MinIO access key
- secret_key	String	否	MinIO secret key
- use_ssl	Boolean	否	MinIO 是否使用 SSL

响应

{
  "success": true,
  "id": "kb_xxx",
  "message": "Knowledge base created successfully"
}

---

2. 获取知识库列表

请求

GET /api/knowledge/list

响应

{
  "success": true,
  "data": [
    {
      "id": "kb_001",
      "name": "产品文档知识库",
      "description": "用于存储产品手册",
      "llm_model_id": "model_001",
      "embedding_model_id": "model_002",
      "status": "active",
      "document_count": 15,
      "chunk_count": 156,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

3. 获取知识库详情

请求

GET /api/knowledge/:id

响应

{
  "success": true,
  "data": {
    "id": "kb_001",
    "name": "产品文档知识库",
    "description": "用于存储产品手册",
    "llm_model_id": "model_001",
    "embedding_model_id": "model_002",
    "parsing_config": {
      "engine": "markitdown",
      "enable_pdf": true,
      "pandoc": true
    },
    "status": "active",
    "document_count": 15,
    "chunk_count": 156,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

---

4. 删除知识库

请求

DELETE /api/knowledge/:id

响应

{
  "success": true,
  "message": "Knowledge base deleted"
}

---

5. 获取知识库下的文档列表

请求

GET /api/knowledge/:id/documents

参数	类型	必填	说明
status	String	否	过滤状态：all / parsed / parsing / failed

响应

{
  "success": true,
  "data": [
    {
      "id": "doc_001",
      "knowledge_base_id": "kb_001",
      "name": "产品手册_v2.0.pdf",
      "file_key": "abc123.pdf",
      "file_url": "http://localhost:8082/files/abc123.pdf",
      "file_size": 2516582,
      "status": "parsed",
      "chunk_count": 156,
      "uploaded_at": "2024-01-15T10:30:00Z"
    }
  ]
}

---

6. 上传文档到知识库

请求

POST /api/knowledge/:id/documents
Content-Type: multipart/form-data

参数	类型	必填	说明
file	File	是	要上传的文件

响应

{
  "success": true,
  "id": "doc_001",
  "url": "http://localhost:8082/files/abc123.pdf",
  "document": {
    "id": "doc_001",
    "knowledge_base_id": "kb_001",
    "name": "产品手册_v2.0.pdf",
    "file_size": 2516582,
    "status": "parsing",
    "chunk_count": 0,
    "uploaded_at": "2024-01-15T10:30:00Z"
  },
  "message": "Document uploaded"
}

---

7. 删除知识库文档

请求

DELETE /api/knowledge/:id/documents/:doc_id

响应

{
  "success": true,
  "message": "Document deleted"
}

---

8. 重新解析文档

请求

POST /api/knowledge/:id/documents/:doc_id/reparse

响应

{
  "success": true,
  "message": "Document reparse started"
}

---

9. 获取文档预览内容

请求

GET /api/knowledge/:id/documents/:doc_id/preview

参数	类型	必填	说明
page	Number	否	页码（默认 1）

响应

{
  "success": true,
  "data": {
    "total_pages": 3,
    "current_page": 1,
    "content": "第一章 产品介绍..."
  }
}