¶ 知识库问答调用接口
¶ 请求规范
host
headers
Content-Type: application/json
Authorization: Bearer {token}
token 获取
获取token，可以通过聆思大模型平台密钥管理页面生成。注意token生成完妥善保管。
¶ 接口说明
¶ 获取知识库列表
GET /v1/knowledge-bases
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| page | integer | 分页 | 是 | 大于等于1 |
| size | integer | 每页条数 | 是 | 默认20 |
响应示例
- 请求成功
{
"data": [
{
"index_id": "xxxxxx",
"index_name": "测试一下",
"created_at": "2023-08-15T11:41:31.363Z",
"doc_count": "1",
"content_length": "9880",
"documents": [
"智能说明书.txt"
]
}
],
"page": 1,
"size": 20,
"total": "1",
"message": "成功"
}
¶ 创建知识库
POST /v1/knowledge-bases
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_name | string | 知识库名 | 是 | - |
请求示例
{
"index_name": "ls_docs",
}
响应示例
{
"data":{
"index_id": "xxxxxx"
},
"message": "成功"
}
¶ 删除知识库
DELETE /v1/knowledge-bases/:index_id
响应示例
{
"message": "删除成功",
"data": {}
}
¶ 获取文档列表
GET /v1/knowledge-bases/:index_id/documents
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_id | string | 知识库id | 是 | - |
| page | string | 页码 | 否 | |
| size | string | 分页数量 | 否 |
响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_id | string | 知识库id | 是 | - |
| doc_name | string | 文档名称 | 是 | - |
| doc_id | string | 文档id | 是 | - |
| doc_url | string | 文档url | 是 | - |
| status | int | 文档处理状态 | 是 | 1: 处理成功 2: (保留状态,暂时可以忽略) 3: 处理中 4: 处理失败 |
| text_splitter | object | 分片参数 | 是 | - |
| content_length | int | 文档长度 | 是 | - |
| created_at | string | 创建时间 | 是 | - |
响应示例
{
"data": [
{
"user_id": "16",
"index_id": "xxx",
"doc_name": "智能说明书.txt",
"doc_id": "xxx",
"doc_url": "https://cdn.iflyos.cn/xxx/智能说明书.txt",
"text_splitter": {
"method": "audo"
},
"content_length": 9880,
"status": 1,
"created_at": "2023-08-16T06:49:55.820Z",
"executed_at": "2023-08-16T06:49:55.820Z",
"executed_id": "xxx",
"executed_note": ""
}
],
"page": 1,
"size": 20,
"total": "1",
"message": "成功"
}
¶ 文档分片预览
POST /v1/knowledge-bases/:index_id/documents/process_preview
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| documents | Array of objects | 文档数组。每个文档都表示为一个 JSON 对象。 | 是 | 参数详情查看“添加文档”接口参数说明 |
| text_splitter | objects | 文档拆分策略 | 是 | 参数详情查看“添加文档”接口参数说明 |
| limit | int | 输出分片条数 | 否 | 默认值为10 |
请求示例
{
"documents": [
{
"doc_name": "智能说明书.txt",
"doc_url": "https://xxx/智能说明书.txt"
}
],
"text_splitter": {
"method": "auto"
}
}
响应示例
{
"data": [
{
"text": "xxxxxxx",
"length": 100
},
...
],
"message": "成功"
}
¶ 添加文档
POST /v1/knowledge-bases/:index_id/documents
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| documents | Array of objects | 文档数组。每个文档都表示为一个 JSON 对象。 | 是 | - |
| text_splitter | objects | 文档拆分策略 | 是 | - |
请求参数 documents
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| doc_name | string | 文档名称 | 是 | - |
| doc_url | string | 文档读取连接 | 是 | - |
请求参数 text_splitter
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| method | string | 文档分片策略，可选：auto（自动分片）、separator（按分隔符） | 是 | - |
| options | object | 分片策略参数 | 是 | - |
请求参数 text_splitter.options
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| separator | int | 分片重叠长度 | 否，chunk_method是separator时必填 | - |
请求示例
{
"documents": [
{
"doc_name": "文档1",
"doc_url": "http://cdn.xxx.com/wendang.txt",
},
{
"doc_name": "文档2",
"doc_url": "http://cdn.xxx.com/wendang2.txt",
}
],
"text_splitter": {
"method": "auto"
}
}
响应示例
- 请求成功
{
"message": "创建成功",
"data": [
{
"doc_id": "10023", // 文档ID
"doc_name": "文档1"
},
{
"doc_id": "10024", // 文档ID
"doc_name": "文档2"
}
]
}
¶ 获取文档详情
GET /v1/knowledge-bases/:index_id/documents/:doc_id
响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_id | string | 知识库id | 是 | - |
| doc_name | string | 文档名称 | 是 | - |
| doc_id | string | 文档id | 是 | - |
| doc_url | string | 文档url | 是 | - |
| status | int | 文档处理状态 | 是 | 1: 处理成功 2: (保留状态,暂时可以忽略) 3: 处理中 4: 处理失败 |
| text_splitter | object | 分片参数 | 是 | - |
| content_length | int | 文档长度 | 是 | - |
| created_at | string | 创建时间 | 是 | - |
响应示例
- 请求成功
{
"data": {
"user_id": "16",
"index_id": "xxx",
"doc_name": "智能说明书.txt",
"doc_id": "xxx",
"doc_url": "https://cdn.iflyos.cn/xxx/智能说明书.txt",
"text_splitter": {
"method": "auto"
},
"content_length": 9880,
"status": 1,
"created_at": "2023-08-16T06:49:55.820Z",
"executed_at": "2023-08-16T06:49:55.820Z",
"executed_id": "xxx",
"executed_note": ""
},
"message": "成功"
}
¶ 删除文档
DELETE /v1/knowledge-bases/{index_id}/documents
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_id | string | 知识库id | 是 | - |
| doc_ids | array | 文档ID数组 | 是 | - |
请求示例
{
"doc_ids": ["doc_id1", "doc_id2"]
}
响应示例
- 请求成功
{
"message": "删除成功",
"data": {}
}
¶ 知识库通用问答
知识库通用问答
知识库限定问答
¶ 知识库问答
POST /v1/knowledge-bases/:index_id/chat/completions
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| messages | Array<message> | 会话和提问 | 是 | - | 需要自行拼接对话历史信息，数组最后是最新的用户提问 |
| message.role | string | 角色 | 是 | - | 可取值： user，assistant ；其中user表示用户的提问，assistant表示AI的回复 ; 若当前message为messages数组的最后一个元素，role的值需为字符串'user' |
| message.content | string | 文本内容 | 是 | - | 该角色的对话内容 |
| doc_ids | array | 文档ID数组 | 否 | - | 默认检索当前知识库下所有文档 |
| prompt_id | string | 对话prompt | 否 | - | 用于将检索后的知识进行prompt渲染 |
| limit | number | 数量 | 否 | 5 | 用于知识检索时检索出的知识数量 |
| model | string | 模型 | 否 | spark-general-1.5 | 可取值：spark-general-1.5: 基础模型v1.5版本;spark-general-2.0: 基础模型v2.0版本； |
| threshold | float | 阈值 | 否 | - | 用于根据知识检索的分数过滤，最小值是0.1，最大值是1，不传时默认0 |
| temperature | float | 核采样阈值 | 否 | - | 最小值是0.1，最大值是1，不传时默认0.1 |
| stream | boolean | 是否支持流式 | 否 | false | - |
| is_query_reference | boolean | 是否查询知识点关联上下文 | 否 | false | true表示查询，false表示不查询。另外，当此参数开启后，返回的数据会大于limit数量。 |
请求示例
curl --request POST \
--url https://api.listenai.com/v1/knowledge-bases/YOUR_KNOWLEDGE_LIB_ID/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"messages": [
{ "role": "user", "content": "空调怎么开" }
]
}'
响应参数usage说明
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| total_tokens | int | 本次请求总token数 | 是 | - |
| question_tokens | int | 请求参数messages最后一个user的content的token数 | 是 | - |
| prompt_tokens | int | messages总token数 | 是 | - |
| completion_tokens | int | 应用内容的token数 | 是 | - |
响应参数choices说明
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| finish_reason | string | 内容返回停止理由 | 否 | - |
| index | int | 返回内容序号 | 是 | 一般情况都是0 |
| message | object | 结果返回内容 | 是 | - |
| message.content | string | 对话返回内容 | 是 | - |
| message.role | string | assistant | 是 | 固定 assistant |
| message.metadata | object | 知识库溯源内容 | 否 | 对话过程中，使用到的知识库关联知识 |
| message.metadata.knowledge_id | string | 知识库 | 否 | - |
| message.metadata.node_ids | array | 溯源知识点ID数组 | 否 | id: 知识点ID，score: 知识点于输入内容相关性分数 |
响应示例
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "您可以使用遥控器或通过App内的语音控制页面来开启和关闭空调。如果您需要输入新的指令，需要重新唤醒空调。",
"role": "assistant",
"metadata": {
"knowledge_id": "a523f6b3-2539-40c9-9f9b-614c910c3930",
"node_ids": [
{
"id": "fe1f1608-7d8b-4cdd-8a9e-7936cbe1b085",
"score": "0.95"
},
{
"id": "2cce323d-ba0a-4c93-9810-f8a3426748fe",
"score": "0.8"
}
]
}
}
}
],
"created": 1692107109,
"id": "cht000bcd39@dx189f97169419a4b540",
"object": "chat.completion",
"usage": {
"completion_tokens": 72,
"prompt_tokens": 943,
"question_tokens": 943,
"total_tokens": 1015
}
}
¶ 知识库问答对话 - 替换默认Prompt
- 知识库问答API的默认提示词如下，模板使用了
mustache渲染引擎，支持参数传入进行模板内容渲染。如果系统默认提示词的无法满足需求，可以参考此处教程新建提示词模板进行替换。
系统默认模板
你是一个专家问答系统。始终使用所提供的相关信息回答。
## 需要遵循的一些规则: 1. 切勿在答案中直接引用给定的相关信息; 2. 避免类似 "根据相关信息，...... "或 "相关信息...... "或任何类似的表述。
## 相关信息: {{#knowledges}}{{{text}}} {{/knowledges}}
## 根据相关信息而不是先验证知识来回答问题。
## 问题：{{user_input}}
## 答案：
- 知识库问答提示词模板所支持的传入参数：
| 名称 | 类型 | 说明 |
|---|---|---|
| knowledges | array<knowledge> | 根据检索条件，检索出来的知识点数组 |
| user_input | string | 请求对话中messages的用户输入 |
| knowledge.text | string | 知识点的文本 |
| knowledge.score | number | 知识点的分数 |
| knowledge.index | number | 知识点所在knowledges数组的数组下标 |
- 按以下格式请求即可完成默认Prompt模板替换；
curl --request POST \
--url https://api.listenai.com/v1/knowledge-bases/YOUR_KNOWLEDGE_LIB_ID/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"prompt_id": "YOUR_PROMPT_ID",
"messages": [
{ "role": "user", "content": "空调怎么开" }
]
}'
¶ 知识库文本查询
GET /v1/knowledge-bases/:index_id/query
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| index_id | string | 知识库id | 是 | - |
| content | string | 查询文本 | 是 | - |
| doc_ids | string | 查询文档ID | 否，若不传代表查询知识库下所有文档 | 逗号分隔doc_id |
| limit | int | 显示结果条数 | 否 | 默认返回10条 |
| is_query_reference | boolean | 是否查询知识点关联上下文 | 否 | 默认false，true表示查询，false表示不查询。另外，当此参数开启后，返回的数据会大于limit数量。 |
| threshold | float | 阈值 | 否 | 用于根据知识检索的分数过滤，最小值是0，最大值是1。默认0。 |
响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| id | string | 知识点ID | 是 | - |
| text | string | 知识点内容 | 是 | - |
| doc_id | string | 文档ID | 是 | - |
| doc_name | string | 文档名称 | 是 | - |
| score | float | 命中分数 | 是 | 分数范围 0～1 |
| main_node_id | string | 关联的主知识点ID | 否 | 若此参数存在，表示该知识点是关联查询的上下文知识点。 |
| node_index | int | 知识点序号 | 是 | 文档提取的知识点是有序，此参数表示知识点的序列编号。 |
响应示例
- 请求成功
{
"message": "成功",
"data": [
{
"id": "sadfaf95-a13b-4281-b582-acb44sddfsdf5b",
"text": "一、关于购买进阶课顾虑 Q1：学习是在群里学吗？（学习的形式）A1：是的，是语音课程的形式，每天15分钟左右，加上作业大概花20分钟，有不懂的问题，老师和助教会在群里答疑",
"doc_id": "0e5afc081c2f131449278bf2def74c98",
"doc_name": "说明书.docx",
"score": 0.2775,
"main_node_id": "",
"node_index": 20,
},
{
"id": "20d1af95-a13b-4281-b582-acb44406a85b",
"text": "一、关于购买进阶课顾虑 Q1：学习是在群里学吗？（学习的形式）A1：是的，是语音课程的形式，每天15分钟左右，加上作业大概花20分钟，有不懂的问题，老师和助教会在群里答疑",
"doc_id": "0e5afc081c2f131449278bf2def74c98",
"doc_name": "说明书.docx",
"score": 0.2775,
"main_node_id": "sadfaf95-a13b-4281-b582-acb44sddfsdf5b",
"node_index": 21,
}
]
}
¶ 知识点溯源查询
POST /v1/knowledge-bases/:index_id/references/fetch
请求参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| node_ids | array | 知识点ID数组 | 是 | 关联的是“知识库文本查询”接口返回“ID” |
图片响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| type | string | 值为image表示图片数据 | 是 | - |
| content | array | 图片数据数组 | 是 | - |
| content(type) | string | 图片数据类型 | 是 | 目前有两种类型：base64、URL |
| content(content) | string | 图片内容 | 是 | 内容根据content(type)，可分为base64和URL |
表格响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| type | string | 值为table表示表格数据 | 是 | - |
| content | array | 图片数据数组 | 是 | - |
| content(name) | string | 表格名称 | 是 | - |
| content(content) | string | 表格内容 | 是 | markdown格式的表格内容 |
原文上下文响应参数
| 名称 | 类型 | 说明 | 是否必填 | 备注 |
|---|---|---|---|---|
| type | string | 值为source_doc表示原文数据 | 是 | - |
| content | array | 图片数据数组 | 是 | - |
| content(name) | string | 来源文档名称 | 是 | - |
| content(content) | array | 原文上下文内容 | 是 | is_main_node为true代表原文，is_main_node为false代表原文的上下文 |
响应示例
- 请求成功
{
"data": [
{
"type": "image",
"content": [
{
"content": "iVBORw0KGgoAAAANSUhEUgAAAKkAAACcCAYAAAAEYosxAAAABmJLR0QAQm==",
"type": "base64"
},
{
"content": "https://iflyos-external.oss-cn-shanghai.aliyuncs.com/images/glw3.png",
"type": "url"
}
]
},
{
"type": "table",
"content": [
{
"name": "表格1",
"content": "遥控器X1 | 7号电池 X2 | 连接管X1 | 包扎带X2 | 排水接头密封圈 X1\n--- | --- | --- | --- | ---\n遥控器X1 | 排水管X1 | 7号电池 X2 | 墙孔挡板 X1 | 连接管X1 | 安装板X1 | 包扎带X2 | 自攻螺钉 X5 | 排水接头密封圈 X1 | 连接管防拆帽X2\n遥控器X1 | 排水接头 X1 | 7号电池 X2 | 快速指南 X1 | 连接管X1 | 专业手册 X1 | 包扎带X2 | 保温管X1 | 排水接头密封圈 X1 | 新风管附件包X1\n遥控器X1 | HEPA网 X1 | 7号电池 X2 | 塑料胀管 X5 | 连接管X1 | 密封胶泥 X1 | 包扎带X2 | 开 关X1 | 排水接头密封圈 X1 | 新风管附件包X1\n"
}
]
},
{
"type": "source_doc",
"content": [
{
"name": "doc1",
"content": [
{
"text": "ECO",
"is_hight_light": false,
"is_main_node": false
},
{
"text": "关机或制冷模式下，可进入ECO模式，8小时后自动退出。",
"is_hight_light": true,
"is_main_node": true
},
{
"text": "对于热负荷偏大的房间或室外温度偏高的情况，建议谨慎使用ECO节能运行模式，以免影响舒适效果。",
"is_hight_light": false,
"is_main_node": false
}
]
}
]
}
],
"message": "请求成功"
}
¶ 知识库问答对话v2
POST /v2/knowledge-bases/:index_id/chat/completions
请求参数
请求参数参考v1版本，在v1版本基础上，多增加以下参数：
| 名称 | 类型 | 说明 | 是否必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| scene | string | 垂直问答场景 | 否 | - | 用户填入的内容，会做为{{scene}}变量值传入Prompt模板 |
| reject_reply | string | 拒识回复语 | 否 | 抱歉，暂时找不到这个问题的相关资料。 | 相关检索条件过滤后无知识点，则返回该回复语。 |
请求示例
curl --request POST \
--url https://api.listenai.com/v2/knowledge-bases/YOUR_KNOWLEDGE_LIB_ID/chat/completions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REQUEST_TOKEN' \
--data '{
"scene": "空调",
"reject_reply": "抱歉，暂时找不到这个问题的相关资料。",
"messages": [
{ "role": "user", "content": "空调怎么开" }
],
}'
响应示例
{
"choices": [
{
"finish_reason": null,
"index": 0,
"message": {
"content": "抱歉，暂时找不到这个问题的相关资料。",
"role": "assistant"
}
}
],
"created": 1698229052,
"id": "7805bd72-e4ea-93cc-8dfb-4dd909f7fa1d",
"object": "chat.completion",
"usage": {
"completion_tokens": 0,
"prompt_tokens": 0,
"question_tokens": 0,
"total_tokens": 0
}
}