知识管理接口 | 微信开放文档

# 知识管理接口

# POST /api/v1/knowledge-bases/:id/knowledge/file

功能: 从文件创建知识

请求参数:

id: 知识库ID (路径参数)
file: 上传的文件 (表单参数，multipart/form-data)
title: 知识标题 (可选，表单参数)
description: 知识描述 (可选，表单参数)
metadata: 元数据信息 (可选，表单参数，string类型，可解析为map[string]string的JSON字符串，例如：{"source":"web"})

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "title": "上传的文件知识",
    "type": "file",
    "file_name": "document.pdf",
    "file_size": 102400,
    "parse_status": "pending",
    "created_at": "2026-03-02T12:00:00+08:00"
  }
}

参数说明:

参数名	类型	必填	说明
id	string	是	知识库ID
file	file	是	上传的文件
title	string	否	知识标题
description	string	否	知识描述
metadata	string	否	元数据信息，JSON字符串格式，可解析为map[string]string，例如：{"source":"web"}

# POST /api/v1/knowledge-bases/:id/knowledge/url

功能: 从URL创建知识

请求参数:

id: 知识库ID (路径参数)
url: 目标URL地址 (JSON body)
title: 知识标题 (可选，JSON body)
description: 知识描述 (可选，JSON body)

请求示例:

{
  "url": "https://example.com/ai-tutorial.html",
  "title": "AI教程",
  "description": "人工智能相关教程内容"
}

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "title": "AI教程",
    "type": "url",
    "source": "https://example.com/ai-tutorial.html",
    "parse_status": "pending",
    "created_at": "2026-03-02T12:00:00+08:00"
  }
}

参数说明:

参数名	类型	必填	说明
id	string	是	知识库ID
url	string	是	目标URL地址
title	string	否	知识标题
description	string	否	知识描述

# POST /api/v1/knowledge-bases/:id/knowledge/manual

功能: 手工Markdown录入

请求参数:

id: 知识库ID (路径参数)
content: Markdown内容 (JSON body)
title: 知识标题 (可选，JSON body)
description: 知识描述 (可选，JSON body)
status: 知识状态（draft（草稿）：知识保存为草稿状态，不会立即进行索引处理进行解析、分块以及模型总结，草稿状态的知识不会在对话时被使用， publish（发布）：知识立即发布，会触发后续的索引处理流程)

请求示例:

{
  "content": "# 人工智能基础概念\n\n人工智能是计算机科学的一个分支...",
  "title": "AI基础概念",
  "description": "人工智能的基础概念介绍",
  "status": "publish"
}

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "title": "AI基础概念",
    "type": "manual",
    "parse_status": "completed",
    "created_at": "2026-03-02T12:00:00+08:00"
  }
}

参数说明:

参数名	类型	必填	说明
id	string	是	知识库ID
content	string	是	Markdown内容
title	string	否	知识标题
description	string	否	知识描述

# GET /api/v1/knowledge-bases/:id/knowledge

功能: 获取知识库下的知识列表

请求参数:

id: 知识库ID (路径参数)
page: 页码，默认为1 (查询参数)
page_size: 每页数量，默认为50 (查询参数)

响应示例:

{
  "data": [
    {
      "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
      "tenant_id": 10001,
      "knowledge_base_id": "d648307d-ca53-4fb0-9761-5526c26f8dc3",
      "tag_id": "",
      "type": "url",
      "title": "AI教程",
      "description": "---\\ntitle: Example Domain\\n---\\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\\n\\nLearn more",
      "source": "https://example.com/ai-tutorial.html",
      "parse_status": "completed",
      "summary_status": "completed",
      "enable_status": "enabled",
      "embedding_model_id": "model_id",
      "file_name": "",
      "file_type": "",
      "file_size": 0,
      "file_hash": "26415d28c86547df65d4b23bdb61e79e",
      "file_path": "",
      "storage_size": 464,
      "metadata": null,
      "last_faq_import_result": null,
      "created_at": "2026-03-02T11:51:40+08:00",
      "updated_at": "2026-03-02T11:51:44+08:00",
      "processed_at": "2026-03-02T11:51:43+08:00",
      "error_message": "",
      "deleted_at": null,
      "knowledge_base_name": ""
    }
  ],
  "page": 1,
  "page_size": 50,
  "success": true,
  "total": 11
}

参数说明:

参数名	类型	必填	说明
id	string	是	知识库ID
page	integer	否	页码，从1开始
page_size	integer	否	每页数量，最大50

响应格式说明:

字段名	类型	说明
data	array	知识列表
data[].id	string	知识ID
data[].tenant_id	integer	租户ID
data[].knowledge_base_id	string	知识库ID
data[].type	string	知识类型 (url/manual/file)
data[].title	string	知识标题
data[].source	string	知识来源
data[].parse_status	string	解析状态（详见知识状态说明章节）
data[].summary_status	string	摘要状态（详见知识状态说明章节）
data[].enable_status	string	启用状态（详见知识状态说明章节）
data[].created_at	string	创建时间
data[].updated_at	string	更新时间
page	integer	当前页码
page_size	integer	每页数量
success	boolean	请求是否成功
total	integer	总知识数量

# GET /api/v1/knowledge/batch

功能: 批量获取知识

请求参数:

ids: 知识ID列表，用逗号分隔 (查询参数)

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
      "tenant_id": 10001,
      "knowledge_base_id": "d648307d-ca53-4fb0-9761-5526c26f8dc3",
      "type": "url",
      "title": "AI教程",
      "source": "https://example.com/ai-tutorial.html",
      "parse_status": "completed",
      "enable_status": "enabled",
      "created_at": "2026-03-02T11:51:40+08:00",
      "updated_at": "2026-03-02T11:51:44+08:00"
    }
  ]
}

# GET /api/v1/knowledge/:id

功能: 获取知识详情

请求参数:

id: 知识ID (路径参数)

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "tenant_id": 10001,
    "knowledge_base_id": "d648307d-ca53-4fb0-9761-5526c26f8dc3",
    "type": "url",
    "title": "AI教程",
    "description": "AI相关教程内容",
    "source": "https://example.com/ai-tutorial.html",
    "parse_status": "completed",
    "summary_status": "completed",
    "enable_status": "enabled",
    "file_name": "",
    "file_type": "",
    "file_size": 0,
    "created_at": "2026-03-02T11:51:40+08:00",
    "updated_at": "2026-03-02T11:51:44+08:00"
  }
}

**响应格式说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| success | boolean | 请求是否成功 |
| data | object | 知识详情数据 |
| data.id | string | 知识ID |
| data.tenant_id | integer | 租户ID |
| data.knowledge_base_id | string | 知识库ID |
| data.type | string | 知识类型 (url/manual/file) |
| data.title | string | 知识标题 |
| data.description | string | 知识描述 |
| data.source | string | 知识来源 |
| data.parse_status | string | 解析状态（详见知识状态说明章节） |
| data.summary_status | string | 摘要状态（详见知识状态说明章节） |
| data.enable_status | string | 启用状态（详见知识状态说明章节） |
| data.file_name | string | 文件名 |
| data.file_type | string | 文件类型 |
| data.file_size | integer | 文件大小（字节） |
| data.created_at | string | 创建时间 |
| data.updated_at | string | 更新时间 |

##### DELETE /api/v1/knowledge/:id
**功能**: 删除知识

**请求参数**:
- `id`: 知识ID (路径参数)

**响应示例**:
```json
{
  "success": true,
  "message": "知识删除成功"
}

# PUT /api/v1/knowledge/:id

功能: 更新知识

请求参数:

id: 知识ID (路径参数)
title: 知识标题 (可选)
description: 知识描述 (可选)
enable_status: 启用状态 (可选)

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "title": "更新后的AI教程",
    "description": "更新后的描述",
    "enable_status": "enabled",
    "updated_at": "2026-03-02T12:00:00+08:00"
  }
}

# PUT /api/v1/knowledge/manual/:id

功能: 更新手工Markdown知识

请求参数:

id: 知识ID (路径参数)
content: Markdown内容 (必填)
title: 知识标题 (可选)

响应示例:

{
  "success": true,
  "data": {
    "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
    "title": "手工知识标题",
    "type": "manual",
    "updated_at": "2026-03-02T12:00:00+08:00"
  }
}

# GET /api/v1/knowledge/:id/download

功能: 获取知识文件

请求参数:

id: 知识ID (路径参数)

响应: 返回文件流

# GET /api/v1/knowledge/:id/preview

功能: 预览知识文件（内联显示，返回正确Content-Type）

描述: 返回知识条目关联的原始文件，Content-Type根据文件类型自动设置，用于浏览器内嵌预览。与下载接口的区别在于预览接口设置Content-Disposition为"inline"，适合内联显示而非强制下载。

特殊处理: 如果请求的知识是URL类型（网页抓取内容），则返回JSON格式的分块内容，包含网页抓取内容的前10块数据。

请求参数:

id: 知识ID (路径参数)

响应:

文件类型: 返回文件流，包含以下响应头：
- Content-Type: 根据文件扩展名自动设置正确的MIME类型
- Content-Disposition: "inline"，支持浏览器内联显示
- `Cache-Control": "private, max-age=3600"
URL类型: 返回JSON格式的分块内容，包含以下字段：
- data: 分块数据数组，包含网页抓取内容的前10块，每个分块包含以下字段：
  - id: 分块唯一标识
  - seq_id: 序列ID
  - tenant_id: 租户ID
  - knowledge_id: 知识ID
  - knowledge_base_id: 知识库ID
  - tag_id: 标签ID
  - content: 分块内容（包含网页元数据和正文内容）
  - chunk_index: 分块索引
  - is_enabled: 是否启用
  - flags: 标志位
  - status: 状态
  - start_at: 内容起始位置
  - end_at: 内容结束位置
  - chunk_type: 分块类型（如"text"）
  - parent_chunk_id: 父分块ID
  - relation_chunks: 相关分块
  - metadata: 元数据（包含生成的问题等）
  - content_hash: 内容哈希
  - image_info: 图片信息
  - created_at: 创建时间
  - updated_at: 更新时间
  - deleted_at: 删除时间
- page: 当前页码（默认为1）
- page_size: 每页数据量（默认为10）
- success: 请求是否成功（true/false）
- total: 总数据量

URL类型响应示例:

{
  "data": [
    {
      "id": "8288dc4f-2a38-44db-a28d-238b253009bf",
      "seq_id": 203165286,
      "tenant_id": 16374,
      "knowledge_id": "a73628fa-6c10-4787-9996-82e0e0280937",
      "knowledge_base_id": "ed33bc3d-1faf-447f-bdc0-049a5aa913b8",
      "tag_id": "",
      "content": "---\\ntitle: 云服务器概述\\nurl: https://cloud.tencent.com/document/product/213/495\\nhostname: tencent.com\\ndescription: 本文介绍了腾讯云云服务器（CVM）的基本概念、使用方法、配置选项、定价模式以及相关产品。CVM是一种可扩展的计算服务，支持自定义资源（CPU、内存、硬盘等）并灵\\nsitename: cloud.tencent.com\\ndate: 2025-07-15\\ntags: [&amp;#39;CVM介绍,服务器介绍,CVM操作指引,服务器操作指引,服务器使用,什么是腾讯云 CVM？&amp;#39;]\\n---\\n# 云服务器概述\\n\\n最近更新时间：2025-07-15 14:47:42\\n\\n## 什么是腾讯云云服务器？\\n\\n",
      "chunk_index": 0,
      "is_enabled": true,
      "flags": 0,
      "status": 0,
      "start_at": 0,
      "end_at": 349,
      "pre_chunk_id": "",
      "next_chunk_id": "",
      "chunk_type": "text",
      "parent_chunk_id": "6c123394-5a54-400e-956b-299c445cc1b4",
      "relation_chunks": null,
      "indirect_relation_chunks": null,
      "metadata": {
        "generated_questions": [
          {
            "id": "q1775094672936011076",
            "question": "什么是腾讯云云服务器（CVM）？"
          },
          {
            "id": "q1775094672936011967",
            "question": "腾讯云服务器CVM与传统服务器相比有什么优势？"
          },
          {
            "id": "q1775094672936012257",
            "question": "如何理解腾讯云CVM是一种可扩展的计算服务？"
          }
        ]
      },
      "content_hash": "",
      "image_info": "",
      "created_at": "2026-04-02T09:51:10+08:00",
      "updated_at": "2026-04-02T09:51:13+08:00",
      "deleted_at": null
    }
  ],
  "page": 1,
  "page_size": 10,
  "success": true,
  "total": 7
}

支持的Content-Type类型:

PDF文件: application/pdf
图片文件: image/jpeg, image/png, image/gif, image/bmp, image/webp, image/svg+xml, image/tiff
Office文档: application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/msword, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel
文本文件: text/plain; charset=utf-8, text/markdown; charset=utf-8, text/html; charset=utf-8, text/css; charset=utf-8, text/javascript; charset=utf-8, text/typescript; charset=utf-8, text/x-python; charset=utf-8, text/x-go; charset=utf-8, text/x-java; charset=utf-8, text/yaml; charset=utf-8, text/x-shellscript; charset=utf-8
其他格式: text/csv, application/json; charset=utf-8, application/xml; charset=utf-8
默认: application/octet-stream（未知文件类型）

实现逻辑:

通过mimeTypeByExt函数根据文件扩展名映射到对应的MIME类型
使用流式传输文件内容，支持大文件预览
设置正确的Content-Disposition头为"inline"，确保浏览器内联显示而非下载
支持缓存控制，提高重复访问性能

与下载接口的区别:

预览接口: Content-Disposition为"inline"，适合内联显示
下载接口: Content-Disposition为"attachment"，强制下载
两者都返回文件流，但响应头设置不同，适应不同的使用场景

# PUT /api/v1/knowledge/tags

功能: 批量更新知识标签

请求参数:

knowledge_ids: 知识ID列表 (必填)
tag_id: 标签ID (必填)

响应示例:

{
  "success": true,
  "message": "批量更新标签成功",
  "data": {
    "updated_count": 5
  }
}

# GET /api/v1/knowledge/search

功能: 搜索知识，只能关键字搜索

请求参数:

keyword: 搜索关键词 (查询参数)
knowledge_base_id: 知识库ID (查询参数)
page: 页码 (查询参数)
page_size: 每页数量 (查询参数)

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "feabfd7a-16b1-477d-9569-22b9befc0436",
      "title": "AI教程",
      "description": "AI相关教程内容",
      "type": "url",
      "knowledge_base_id": "d648307d-ca53-4fb0-9761-5526c26f8dc3",
      "created_at": "2026-03-02T11:51:40+08:00"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

# POST /api/v1/knowledge/move

功能: 移动知识到其他知识库

请求参数:

knowledge_ids: 要移动的知识ID列表 (JSON body)
source_kb_id: 源知识库ID (JSON body)
target_kb_id: 目标知识库ID (JSON body)
mode: 移动模式，可选值："reuse_vectors"（复用向量）或"reparse"（重新解析） (JSON body)

请求示例:

{
  "knowledge_ids": ["feabfd7a-16b1-477d-9569-22b9befc0436", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "source_kb_id": "source-knowledge-base-id",
  "target_kb_id": "target-knowledge-base-id",
  "mode": "reuse_vectors"
}

响应示例:

{
  "success": true,
  "data": {
    "task_id": "move-task-00000001",
    "source_kb_id": "source-knowledge-base-id",
    "target_kb_id": "target-knowledge-base-id",
    "knowledge_count": 2,
    "message": "移动任务已创建"
  }
}

参数说明:

参数名	类型	必填	说明
knowledge_ids	array	是	要移动的知识ID列表
source_kb_id	string	是	源知识库ID
target_kb_id	string	是	目标知识库ID
mode	string	是	移动模式：reuse_vectors（复用向量）或reparse（重新解析）

# GET /api/v1/knowledge/move/progress/:task_id

功能: 获取知识移动进度

请求参数:

task_id: 移动任务ID (路径参数)

响应示例:

{
  "success": true,
  "data": {
    "task_id": "move-task-00000001",
    "status": "processing",
    "progress": 50,
    "total": 2,
    "processed": 1,
    "message": "正在处理中...",
    "error": ""
  }
}

参数说明:

参数名	类型	必填	说明
task_id	string	是	移动任务ID

响应格式说明:

字段名	类型	说明
task_id	string	移动任务ID
status	string	任务状态：pending/processing/completed/failed
progress	number	进度百分比
total	number	总知识数量
processed	number	已处理知识数量
message	string	进度消息
error	string	错误信息（如果任务失败）

# 知识库标签接口

# POST /api/v1/knowledge-bases/:id/tags

功能: 创建知识库标签

请求参数:

id: 知识库ID (路径参数)

请求体参数:

{
    "name": "标签名称",
    "color": "#FF0000",
    "sort_order": 1
}

参数说明:

参数名	类型	必填	说明
name	string	是	标签名称
color	string	否	显示颜色（十六进制格式）
sort_order	integer	否	排序顺序

响应示例:

{
    "success": true,
    "data": {
        "id": "tag-001",
        "seq_id": 1,
        "tenant_id": 10001,
        "knowledge_base_id": "kb-00000001",
        "name": "标签名称",
        "color": "#FF0000",
        "sort_order": 1,
        "created_at": "2026-03-02T12:00:00+08:00",
        "updated_at": "2026-03-02T12:00:00+08:00"
    }
}

# PUT /api/v1/knowledge-bases/:id/tags/:tag_id

功能: 更新知识库标签

请求参数:

id: 知识库ID (路径参数)
tag_id: 标签ID (路径参数，支持UUID或seq_id)

请求体参数:

{
    "name": "新标签名称",
    "color": "#00FF00",
    "sort_order": 2
}

参数说明:

参数名	类型	必填	说明
name	string	否	标签名称（可选更新）
color	string	否	显示颜色（可选更新）
sort_order	integer	否	排序顺序（可选更新）

响应示例:

{
    "success": true,
    "data": {
        "id": "tag-001",
        "seq_id": 1,
        "tenant_id": 10001,
        "knowledge_base_id": "kb-00000001",
        "name": "新标签名称",
        "color": "#00FF00",
        "sort_order": 2,
        "created_at": "2026-03-02T12:00:00+08:00",
        "updated_at": "2026-03-02T12:30:00+08:00"
    }
}

响应格式说明:

字段名	类型	说明
id	string	标签唯一标识符（UUID）
seq_id	integer	序列ID（知识库内唯一）
tenant_id	integer	租户ID
knowledge_base_id	string	知识库ID
name	string	标签名称
color	string	显示颜色
sort_order	integer	排序顺序
created_at	string	创建时间
updated_at	string	更新时间