知识中枢API文档

约 3176 字大约 11 分钟

2026-03-27

本文档为知识工具集调用指南，向您全面介绍平台可调用的七大核心智能处理工具，涵盖文件解析、多模态大模型文档解析、网页解析、文本切片、实体关系提取、内容结构化抽取及向量化处理能力。文档内容从常规文档提取、多模态信息解析，到网页数据爬取、长文本分块、知识实体挖掘与语义向量化，都提供了明确的能力说明与调用指向。您可依托本文档快速理解各工具功能边界与技术特性，高效完成工具调用、功能集成与业务适配，为数据处理、知识挖掘、语义检索等研发工作提供标准化、可落地的技术支撑。

轻量化接入无需复杂部署，仅凭专属 APIKey 即可快速启用全栈接口能力，低门槛完成技术融合，加速业务创新迭代。请联系 李亚楠18072748728 申请。

接口名称	HTTP 方法	路径	功能描述
知识检索	POST	/retrieve	根据用户输入和检索策略，返回匹配的知识片段
创建知识库	POST	/kb/create	创建新的知识库
删除知识库	POST	/kb/remove	删除知识库
上传文档	POST	/doc/upload	上传文档到指定知识库
添加文档	POST	/doc/add	添加外部来源的文档到知识库
删除文档	POST	/doc/remove	删除文档
解析文档	POST	/doc/parse	解析上传的文档内容，生成知识库片段
查询文档解析状态	GET	/doc/id	根据文档ID查询文档状态
知识问答	POST	/chat/stream	基于知识库内容与大模型进行对话，流式返回

3. 详细接口说明

3.1 知识检索

接口路径：POST /v1/open/retrieve

功能描述：根据用户输入和检索策略，返回匹配的知识片段

请求体：

{
  "query": "查询语句",
  "kbIds": [123, 456],
  "docIds": [123, 456],
  "retrieveOptions": {
    "type": "hybrid",
    "threshold": 0.8,
    "top": 10,
    "customQuery": {},
    "rankerType": "rrf",
    "denseWeight": 0.5,
    "sparseWeight": 0.5,
    "rrfK": 60
  }
}

请求参数说明：

参数名	类型	必填	描述
query	String	是	查询语句
kbIds	`List<Long>`	否	知识库id列表
docIds	`List<Long>`	否	文档id列表
retrieveOptions	Object	否	检索选项

retrieveOptions参数说明：

参数名	类型	必填	描述
type	String	否	查询类型，fulltext：全文检索；semantic：语义检索；hybrid：混合检索，默认值：hybrid
threshold	Double	否	相似度阈值
top	Integer	否	返回Top N结果，默认值：10
customQuery	`Map<String, Object>`	否	自定义查询参数，ES场景可以传入ES查询语句
rankerType	String	否	排序类型，rrf或weighted，默认rrf
denseWeight	Float	否	向量检索权重，weighted模式下使用，默认0.5
sparseWeight	Float	否	BM25检索权重，weighted模式下使用，默认0.5
rrfK	Integer	否	RRF的k参数，默认60

响应：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "kbId": 123,
      "docId": 456,
      "docOuterId": "doc_outer_123",
      "docPath": "/path/to/document.pdf",
      "docTitle": "文档标题.pdf",
      "chunkId": "chunk_1",
      "chunkType": "text",
      "content": "知识片段内容",
      "retrievalScore": 0.95,
      "rerankScore": 0.92,
      "extra": {}
    }
  ]
}

3.2 创建知识库

接口路径：POST /v1/open/kb/create

功能描述：创建新的知识库

请求体：

{
  "name": "知识库名称",
  "description": "知识库描述",
  "type": 30,
  "embeddingModelId": 1,
  "dimension": 384,
  "customFields": {}
}

请求参数说明：

参数名	类型	必填	描述
id	Long	否	知识库ID
name	String	是	知识库名称
description	String	否	知识库描述
type	Integer	否	知识库类型，默认1：自建知识库
embeddingModelId	Long	是	嵌入模型ID
dimension	Integer	否	嵌入维度，默认1024
customFields	`Map<String, Object>`	否	自定义字段，适用于自定义ES存储

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "知识库名称",
    "description": "知识库描述",
    "type": 30,
    "embeddingModelId": 1,
    "customFields": {}
  }
}

3.3 删除知识库

接口路径：POST /v1/open/kb/remove

功能描述：删除指定的知识库

请求参数：

参数名	类型	必填	描述
id	Long	是	知识库ID

响应：

{
  "code": 200,
  "message": "success",
  "data": null
}

3.4 上传文档

接口路径：POST /v1/open/doc/upload

功能描述：上传文档到指定知识库

请求方式：multipart/form-data

请求参数：

参数名	类型	必填	描述
file	MultipartFile	是	文档文件
kbId	Long	是	知识库ID

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "kbId": 456,
    "fileName": "example.pdf",
    "status": "UPLOADED"
  }
}

3.5 添加文档（外部来源）

接口路径：POST /v1/open/doc/add

功能描述：添加外部来源的文档到知识库

请求参数：

参数名	类型	必填	描述
kbId	Long	是	知识库ID

请求体：

{
  "docType": 1,
  "outerId": "外部文档ID",
  "fileName": "文档名称",
  "fileExtension": ".pdf",
  "fileSize": 1024000,
  "fileHash": "abc123",
  "url": "文件预览URL",
  "bucketName": "oss-bucket",
  "ossPath": "path/to/file.pdf",
  "docSourceId": 123
}

请求体参数说明：

参数名	类型	必填	描述
docType	Integer	是	文档类型: 1:本地文档, 2:问之OSS文档, 3:外部OSS文档, 4：网址URL
outerId	String	是	外部文档ID
fileName	String	是	文件名
fileExtension	String	否	文件扩展名
fileSize	Long	否	文件大小
fileHash	String	否	文件哈希值
url	String	否	文件预览URL
bucketName	String	否	OSS桶名，docType为OSS时必填
ossPath	String	否	OSS文件路径，docType为OSS时必填
docSourceId	Long	否	文档来源ID，外部OSS时必填

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "kbId": 456,
    "fileName": "example.pdf",
    "status": "UPLOADED"
  }
}

3.6 删除文档

接口路径：POST /v1/open/doc/remove

功能描述：删除指定的文档

请求参数：

参数名	类型	必填	描述
id	Long	是	文档ID

响应：

{
  "code": 200,
  "message": "success",
  "data": null
}

3.7 解析文档

接口路径：POST /v1/open/doc/parse

功能描述：解析上传的文档内容，生成知识库片段

请求体：

{
  "docId": 123,
  "parseStrategy": "default",
  "splitOptions": {
    "splitType": "regex",
    "regex": "\\n\\n",
    "separatorList": ["\\n\\n", "\\n"],
    "maxChunkLength": 500,
    "overlapRate": 0.1
  },
  "enableSummary": false,
  "async": true
}

请求参数说明：

参数名	类型	必填	描述
docId	Long	是	文档id
parseStrategy	String	否	解析策略，默认自动识别策略
splitOptions	SplitOptions	否	分块选项
async	Boolean	否	是否异步，默认异步

SplitOptions参数说明：

参数名	类型	必填	描述
splitStrategy	String	否	分块策略，默认自动识别策略
regex	String	否	正则表达式
separatorList	`List<String>`	否	分隔符列表
maxChunkLength	Integer	否	最大分块长度
overlapRate	Double	否	重叠率

响应：

{
  "code": 200,
  "message": "success",
  "data": null
}

3.8 查询文档解析状态

接口路径：GET /v1/open/doc/id

功能描述：根据文档ID查询文档状态

请求参数：

参数名	类型	必填	描述
id	Long	是	文档ID

响应：

文档状态：

UPLOADED：已上传
QUEUED：已队列
PROCESSING：解析中
PARSED：已解析
ERROR：解析失败

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "kbId": 456,
    "fileName": "example.pdf",
    "status": "PARSED"
  }
}

3.9 知识问答

接口路径：POST /v1/open/chat/stream

功能描述：基于知识库内容与大模型进行对话，流式返回

请求体：

{
  "query": "如何使用AI知识中心",
  "kbIds": [123, 456],
  "docIds": [789, 101],
  "enableThinking": false,
  "enableQueryRewrite": false,
  "enableRerank": false,
  "rerankCount": 5,
  "llmMode": "quality",
  "retrieveOptions": {
    "type": "hybrid",
    "top": 10
  }
}

请求参数说明：

参数名	类型	必填	描述
query	String	是	查询语句
kbIds	`List<Long>`	是	知识库id列表
docIds	`List<Long>`	否	文档id列表
enableThinking	Boolean	否	是否开启深度思考，默认false
enableQueryRewrite	Boolean	否	是否开启查询重写，默认false
enableRerank	Boolean	否	是否开启重排，默认false
rerankCount	Integer	否	重排取top数，默认5
llmMode	String	否	LLM模式，速度优先speed，质量优先quality
retrieveOptions	RetrieveOptions	否	检索选项

响应：

流式响应（Content-Type: text/event-stream）：

data: {"type":"text","data":"根据"}

data: {"type":"text","data":"知识库"}

data: {"type":"text","data":"内容"}

data: {"type":"text","data":"，"}

data: {"type":"text","data":"我"}

data: {"type":"text","data":"认为"}

... 

data: {"type":"text","data":"。"}

data: {"type":"end","data":"\n"}

4. 数据结构

4.1 KBChunk

{
  "kbId": 123,
  "DocId": 456,
  "DocOuterId": "doc_outer_123",
  "DocPath": "/path/to/document.pdf",
  "chunkId": "chunk_1",
  "chunkType": "text",
  "content": "知识片段内容",
  "retrievalScore": 0.95,
  "RerankScore": 0.92,
  "extra": {}
}

字段说明：

字段名	类型	描述
kbId	Long	知识库ID
DocId	Long	文档ID
DocOuterId	String	外部文档id
DocPath	String	文档路径
chunkId	String	分块ID
chunkType	String	分块类型
content	String	分块内容
retrievalScore	Double	原始检索分数
RerankScore	Double	重排分数
extra	Object	额外信息

4.2 KnowledgeBaseDTO

{
  "id": 123,
  "name": "知识库名称",
  "description": "知识库描述",
  "type": 1,
  "embeddingModelId": 456,
  "customFields": {}
}

字段说明：

字段名	类型	描述
id	Long	知识库ID
name	String	知识库名称
description	String	知识库描述
type	Integer	知识库类型
embeddingModelId	Long	嵌入模型ID
customFields	`Map<String, Object>`	自定义字段，适用于自定义ES存储

4.3 DocumentDTO

{
  "id": 123,
  "kbId": 456,
  "fileName": "example.pdf",
  "url": "/files/example.pdf",
  "status": "PARSED"
}

字段说明：

字段名	类型	描述
id	Long	文档ID
kbId	Long	知识库ID
fileName	String	文件名称
url	String	文件URL
status	String	文档状态

4.4 DocParseRequest

{
  "docId": 123,
  "parseStrategy": "default",
  "splitOptions": {
    "splitType": "regex",
    "regex": "\\n\\n",
    "separatorList": ["\\n\\n", "\\n"],
    "maxChunkLength": 500,
    "overlapRate": 0.1
  }
}

字段说明：

字段名	类型	描述
docId	Long	文档id
parseStrategy	String	解析策略
splitOptions	SplitOptions	分块选项

4.5 RetrieveRequest

{
  "query": "查询语句",
  "kbIds": [123, 456],
  "docIds": [123, 456],
  "retrieveOptions": {
    "type": "hybrid",
    "threshold": 0.8,
    "top": 10,
    "customQuery": {}
  }
}

字段说明：

字段名	类型	描述
query	String	查询语句
kbIds	`List<Long>`	知识库id列表
docIds	`List<Long>`	文档id列表
retrieveOptions	RetrieveOptions	检索选项

4.6 RetrieveOptions

{
  "type": "hybrid",
  "threshold": 0.8,
  "top": 10,
  "customQuery": {}
}

字段说明：

字段名	类型	描述
type	String	查询类型，fulltext：全文检索；semantic：语义检索；hybrid：混合检索，默认值：hybrid
threshold	Double	相似度阈值
top	Integer	返回Top N结果，默认值：10
customQuery	`Map<String, Object>`	自定义查询参数，ES场景可以传入ES查询语句

4.7 SplitOptions

{
  "splitType": "regex",
  "regex": "\\n\\n",
  "separatorList": ["\\n\\n", "\\n"],
  "maxChunkLength": 500,
  "overlapRate": 0.1
}

字段说明：

字段名	类型	描述
splitType	String	分块类型
regex	String	正则表达式
separatorList	`List<String>`	分隔符列表
maxChunkLength	Integer	最大分块长度
overlapRate	Double	重叠率

4.8 StreamData

{
  "type": "text",
  "data": "根据知识库内容"
}

字段说明：

字段名	类型	描述
type	String	数据类型，text表示文本内容，end表示结束
data	Object	数据内容

5. 响应格式

所有接口的响应格式统一为：

{
  "code": 8000000,
  "message": "success",
  "data": {}
}

6. 状态码说明

状态码	描述
200	操作成功
400	请求参数错误
401	未授权
404	资源不存在
500	服务器内部错误

7. 文档状态说明

状态	描述
UPLOADED	文档已上传
PARSING	文档解析中
PARSED	文档解析完成
FAILED	文档解析失败

8. 注意事项

上传文档时，支持的文件类型包括：PDF、Word、Excel、PowerPoint、TXT等
单个文档大小限制为100MB
解析文档是异步操作，需要通过查询文档解析状态接口获取解析结果
知识检索接口的响应时间取决于知识库大小和检索策略

9. 示例调用

9.1 使用 curl 上传文档

curl -X POST "http://localhost:8080/v1/open/doc/upload" \
  -H "X-Authentication: <apikey>" \
  -F "file=@example.pdf" \
  -F "kbId=123"

9.2 使用 curl 检索知识

curl -X POST "http://localhost:8080/v1/open/retrieve" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d '{"query": "如何使用AI知识中心", "kbIds": [123], "type": "semantic", "top": 5}'

9.3 使用 curl 创建知识库

curl -X POST "http://localhost:8080/v1/open/kb/create" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d '{"name": "技术文档知识库", "description": "存储技术相关文档", "type": 1, "embeddingModelId": 456}'

9.4 使用 curl 解析文档

curl -X POST "http://localhost:8080/v1/open/doc/parse" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d '{"docId": 123, "parseStrategy": "default", "splitOptions": {"splitType": "regex", "maxChunkLength": 500, "overlapRate": 0.1}}'

9.5 完整使用流程示例

以下是一个完整的使用流程，展示了从创建知识库到检索知识的全过程：

# 1. 创建知识库
KB_ID=$(curl -s -X POST "http://localhost:8080/v1/open/kb/create" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d '{"name": "技术文档知识库", "description": "存储技术相关文档", "type": 1}' | \
  grep -o '"id":[0-9]*' | grep -o '[0-9]*')

echo "创建的知识库ID: $KB_ID"

# 2. 上传文档
DOC_ID=$(curl -s -X POST "http://localhost:8080/v1/open/doc/upload" \
  -H "X-Authentication: <apikey>" \
  -F "file=@example.pdf" \
  -F "kbId=$KB_ID" | \
  grep -o '"id":[0-9]*' | grep -o '[0-9]*')

echo "上传的文档ID: $DOC_ID"

# 3. 解析文档
curl -X POST "http://localhost:8080/v1/open/doc/parse" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d "{\"docId\": $DOC_ID, \"parseStrategy\": \"default\", \"splitOptions\": {\"splitType\": \"regex\", \"maxChunkLength\": 500, \"overlapRate\": 0.1}}"

echo "文档解析中..."

# 4. 等待解析完成（实际应用中应该轮询状态）
sleep 30

# 5. 检索知识
curl -X POST "http://localhost:8080/v1/open/retrieve" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"如何使用AI知识中心\", \"kbIds\": [$KB_ID], \"retrieveOptions\": {\"type\": \"hybrid\", \"top\": 10}}"

# 6. 知识问答（流式）
echo "\n=== 知识问答（流式） ==="
curl -X POST "http://localhost:8080/v1/open/chat/stream" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"如何使用AI知识中心\", \"kbIds\": [$KB_ID]}"

# 7. 删除文档
echo "\n=== 删除文档 ==="
curl -X POST "http://localhost:8080/v1/open/doc/remove" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d "{\"id\": $DOC_ID}"

# 8. 删除知识库
echo "\n=== 删除知识库 ==="
curl -X POST "http://localhost:8080/v1/open/kb/remove" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d "{\"id\": $KB_ID}"

9.6 知识问答示例

流式问答：

curl -X POST "http://localhost:8080/v1/open/chat/stream" \
  -H "X-Authentication: <apikey>" \
  -H "Content-Type: application/json" \
  -d '{"query": "如何使用AI知识中心", "kbIds": [123]}'

知识中枢API文档

1. 概述

1.1 基础路径

1.2 接口鉴权

2. 接口列表

3. 详细接口说明

3.1 知识检索

3.2 创建知识库

3.3 删除知识库

3.4 上传文档

3.5 添加文档（外部来源）

3.6 删除文档

3.7 解析文档

3.8 查询文档解析状态

3.9 知识问答

4. 数据结构

4.1 KBChunk

4.2 KnowledgeBaseDTO

4.3 DocumentDTO

4.4 DocParseRequest

4.5 RetrieveRequest

4.6 RetrieveOptions

4.7 SplitOptions

4.8 StreamData

5. 响应格式

6. 状态码说明

7. 文档状态说明

8. 注意事项

9. 示例调用

9.1 使用 curl 上传文档

9.2 使用 curl 检索知识

9.3 使用 curl 创建知识库

9.4 使用 curl 解析文档

9.5 完整使用流程示例

9.6 知识问答示例