SearchKnowledgeBase - 检索知识库
检索知识库
接口说明
按问题或图片检索指定知识库。版本使用 DRAFT、LATEST_PUBLISHED 或 vN 展示名,标签过滤条件按后端实际操作符传入。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
调试
授权信息
请求语法
POST /api/v1/knowledge-bases/{knowledgeBaseId}/search HTTP/1.1
路径参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| knowledgeBaseId |
string |
否 |
知识库 ID |
kd-620ad908ec651 |
请求参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| body |
object |
否 |
检索请求 |
|
| query |
string |
否 |
检索问题 |
发票的税额是多少? |
| version |
string |
否 |
知识库版本 |
v1 |
| documentIds |
array |
否 |
文档 ID 列表 |
|
|
string |
否 |
文档 ID |
539ddb688fe811f182f637422a0713b5 |
|
| image |
object |
否 |
图片检索输入 |
|
| url |
string |
否 |
图片 URL |
https://example.com/invoice.png |
| base64 |
string |
否 |
图片 Base64 |
data:image/png;base64,iVBORw0KGgoAAA... |
| objectKey |
string |
否 |
图片对象键 |
uploaded/invoice.png |
| pageNumber |
integer |
否 |
页码 |
1 |
| pageSize |
integer |
否 |
每页数量 |
5 |
| retrievalConfig |
object |
否 |
检索配置 |
|
| candidateCount |
integer |
否 |
候选召回数量 |
5 |
| minScore |
number |
否 |
最低相关度 |
0.2 |
| semanticWeight |
number |
否 |
语义相关度权重 |
0.5 |
| enableQueryExpansion |
boolean |
否 |
启用查询扩展 |
true |
| translationLanguages |
array |
否 |
翻译语言列表 |
|
|
string |
否 |
语言 |
English |
|
| enableEvidenceCompletion |
boolean |
否 |
默认关闭。试点知识库可用于 DRAFT 文本检索的第 1 页,pageSize 可取 5、10 或 20,对应 candidateCount 最低 40、48 或 64。开启后按文档返回结果。 |
true |
| tagFilter |
object |
否 |
标签过滤 |
|
| relation |
string |
否 |
条件关系 |
or |
| conditions |
array<object> |
否 |
标签条件列表 |
|
|
object |
否 |
标签条件 |
||
| field |
string |
否 |
标签字段 |
category |
| op |
string |
否 |
操作符 |
in |
| value |
any |
否 |
标签值 |
invoice |
| rerankModelId |
integer |
否 |
重排模型 ID |
123 |
| enableKnowledgeGraph |
boolean |
否 |
启用知识图谱 |
false |
| rerankModelName |
string |
否 |
租户已开通的重排模型名称。同时填写 rerankModelId 时,本参数优先生效。 |
qwen3-rerank |
| includeWiki |
boolean |
否 |
可选/条件返回;兼容新增;缺省 false;true 时另返回统一 evidenceResults,不将 Wiki 伪装成原文;约束:{"default":false} |
true |
| evidencePageToken |
string |
否 |
可选/条件返回;仅 includeWiki=true 可传;首个证据页省略,后续原样传上一页 evidenceNextToken。固定候选池、主体、参数和页大小,5 分钟不续期;失效 409,不自动重搜。pageNumber 仅控制旧 results。;约束:{"minLength":1,"maxLength":4096} |
example-opaque-next-token |
返回参数
|
名称 |
类型 |
描述 |
示例值 |
|
object |
检索结果 |
||
| requestId |
string |
请求 ID |
019FCC42-90DE-56D3-A10D-3C06995DED17 |
| pageNumber |
integer |
页码 |
1 |
| pageSize |
integer |
每页数量 |
5 |
| totalCount |
integer |
结果总数 |
2 |
| queryLabels |
array |
查询标签 |
|
|
string |
查询标签 |
invoice |
|
| results |
array<object> |
检索结果列表 |
|
|
array<object> |
检索结果 |
||
| chunkId |
string |
切片 ID |
7f0de3e041322a1d |
| knowledgeBaseId |
string |
知识库 ID |
kd-xxxxxxxxxx |
| documentId |
string |
文档 ID |
539ddb688fe811f182f637422a0713b5 |
| documentName |
string |
文档名称 |
invoice.pdf |
| content |
string |
切片内容 |
税额 1.59 |
| contentType |
string |
内容类型 |
table |
| score |
number |
综合相关度 |
0.26136884 |
| scoreDetails |
object |
相关度明细 |
|
| semanticScore |
number |
语义相关度 |
0.5227377 |
| keywordScore |
number |
关键词相关度 |
0.0000000014285714 |
| parentChunkId |
string |
父切片 ID |
parent-chunk-id |
| tags |
array |
标签列表 |
|
|
string |
标签 |
invoice |
|
| locations |
array<object> |
文档位置列表 |
|
|
object |
文档位置 |
||
| pageNumber |
integer |
页码 |
1 |
| left |
integer |
左边界 |
13 |
| right |
integer |
右边界 |
566 |
| top |
integer |
上边界 |
12 |
| bottom |
integer |
下边界 |
364 |
| images |
array<object> |
关联图片列表 |
|
|
object |
关联图片 |
||
| imageId |
string |
图片 ID |
kd-620ad908ec651-41253795bafd7a1c |
| url |
string |
临时访问 URL |
https://example.com/signed-image |
| scalarFields |
any |
结构化知识库标量列(按原始列名返回,不参与检索) |
{"question":"How do I reset it?","category":"account"} |
| mediaStartMs |
integer |
音频或视频切片在原始媒体中的开始时间,单位为毫秒;非媒体切片不返回。 |
1250 |
| mediaEndMs |
integer |
音频或视频切片在原始媒体中的结束时间,单位为毫秒;非媒体切片不返回。 |
8400 |
| mediaTimeline |
array<object> |
切片内逐句或逐段内容在原始媒体中的时间范围;非音频切片不返回。 |
|
|
object |
媒体时间轴片段 |
||
| text |
string |
片段文字 |
第一句话。 |
| startMs |
integer |
片段开始时间 |
1250 |
| endMs |
integer |
片段结束时间 |
4200 |
| code |
integer |
返回状态码 |
0 |
| message |
string |
返回消息 |
success |
| accessDeniedDetail |
string |
权限校验失败详情 |
{"PolicyType":"AccountLevelIdentityBasedPolicy","NoPermissionType":"ImplicitDeny","AuthAction":"milvusknowledgebase:SearchKnowledgeBase"} |
| success |
boolean |
请求是否成功 |
true |
| httpStatusCode |
integer |
HTTP 状态码 |
0 |
| evidenceNextToken |
string |
可选/条件返回;includeWiki=true 必返;下一证据页游标,末页 null;不用于旧 results 分页。;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":4096} |
example-opaque-next-token |
| evidenceResults |
array<object> |
可选/条件返回;仅 includeWiki=true 时返回;统一融合后的当前页;约束:{"minItems":0,"maxItems":100} |
[{"evidenceId":"wiki_section_page_1_sec_1_rev_7","kind":"wiki_section","knowledgeBaseId":"example_kb","documentId":null,"chunkId":null,"pageId":"page_1","sectionId":"sec_1","entityId":null,"relationId":null,"revisionId":"rev_7","batchId":"batch_7","title":"保修说明","content":"产品甲保修期为18个月。","score":0.62,"sourceRefs":[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT"}],"sourceRefCount":1,"sourceRefsTruncated":false,"sourceTaskId":"11111111111111111111111111111111"}] |
|
array<object> |
必填/必返;结构化对象;条件必填/跨字段规则由后端校验,见本接口说明与完整契约 |
{"evidenceId":"wiki_section_page_1_sec_1_rev_7","kind":"wiki_section","knowledgeBaseId":"example_kb","documentId":null,"chunkId":null,"pageId":"page_1","sectionId":"sec_1","entityId":null,"relationId":null,"revisionId":"rev_7","batchId":"batch_7","title":"保修说明","content":"产品甲保修期为18个月。","score":0.62,"sourceRefs":[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT"}],"sourceRefCount":1,"sourceRefsTruncated":false,"sourceTaskId":"11111111111111111111111111111111"} |
|
| evidenceId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
wiki_section_page_1_sec_1_rev_7 |
| kind |
string |
必填/必返;真实证据对象类型;约束:{"enum":["raw","wiki_page","wiki_section","graph_fact"],"maxLength":64} 枚举值:
|
wiki_section |
| knowledgeBaseId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
example_kb |
| documentId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
null |
| chunkId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
null |
| pageId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
page_1 |
| sectionId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
sec_1 |
| entityId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
null |
| relationId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
null |
| revisionId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
example_value |
| batchId |
string |
必填/必返;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
null |
| title |
string |
必填/必返;授权后的展示标题;约束:{"maxLength":1024} |
保修说明 |
| content |
string |
必填/必返;有预算的可读证据文本;约束:{"maxLength":65535} |
产品甲保修期为18个月。 |
| score |
number |
必填/必返;统一排序使用的有限数值;hybrid 为现有 Dealer.rerank 相关度,rerank 为现有 Dealer.rerank_by_model 的文本/模型混合相关度,沿 semanticWeight 和 rank feature,不是相关概率;minScore 按既有统一评分规则应用;非排序事实证据可为 null。;允许 null;不等于可以省略 |
0.62 |
| sourceRefs |
array<object> |
必填/必返;实际支持来源;约束:{"minItems":1,"maxItems":1000} |
[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT","contentHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}] |
|
object |
必填/必返;结构化对象 |
{"documentId":"example_value","chunkId":"example_value","sourceRevisionId":"example_value","version":"DRAFT","contentHash":"0000000000000000000000000000000000000000000000000000000000000000"} |
|
| documentId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
example_value |
| chunkId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
example_value |
| sourceRevisionId |
string |
必填/必返;服务端生成的不透明业务 ID;校验归属,不接受任意路径;约束:{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"} |
example_value |
| version |
string |
必填/必返;版本展示名;非法/不可用不回退草稿;约束:{"maxLength":64,"pattern":"^(DRAFT|LATEST_PUBLISHED|v[1-9][0-9]*)$","default":"DRAFT"} |
DRAFT |
| documentName |
string |
可选/条件返回;授权后才可返回的文档名;约束:{"maxLength":1024} |
example_value |
| pageNumber |
integer |
可选/条件返回;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minimum":1,"maximum":9223372036854775807} |
1 |
| mediaStartMs |
integer |
可选/条件返回;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minimum":0,"maximum":9223372036854775807} |
0 |
| mediaEndMs |
integer |
可选/条件返回;允许 null;空值语义按字段说明;允许 null;不等于可以省略;约束:{"minimum":0,"maximum":9223372036854775807} |
0 |
| sourceRefCount |
integer |
必填/必返;完整来源切片引用数;鉴权按全量集合执行;约束:{"minimum":1,"maximum":9223372036854775807} |
1 |
| sourceRefsTruncated |
boolean |
必填/必返;单次 sourceRefs 仅首 1000 条时 true,可按 sourceTaskId 分页核查 |
false |
| sourceTaskId |
string |
必填/必返;完整来源入口。sourceRefsTruncated=true 时必为非空定位;由产物/修订持有的来源操作引用保持可读,Task 详情归档不删除该来源 manifest。;允许 null;不等于可以省略;约束:{"minLength":32,"maxLength":32,"pattern":"^[0-9a-f]{32}$"} |
null |
示例
正常返回示例
JSON格式
{
"requestId": "019FCC42-90DE-56D3-A10D-3C06995DED17",
"pageNumber": 1,
"pageSize": 5,
"totalCount": 2,
"queryLabels": [
"invoice"
],
"results": [
{
"chunkId": "7f0de3e041322a1d",
"knowledgeBaseId": "kd-xxxxxxxxxx",
"documentId": "539ddb688fe811f182f637422a0713b5",
"documentName": "invoice.pdf",
"content": "税额 1.59",
"contentType": "table",
"score": 0.26136884,
"scoreDetails": {
"semanticScore": 0.5227377,
"keywordScore": 1.4285714e-9
},
"parentChunkId": "parent-chunk-id",
"tags": [
"invoice"
],
"locations": [
{
"pageNumber": 1,
"left": 13,
"right": 566,
"top": 12,
"bottom": 364
}
],
"images": [
{
"imageId": "kd-620ad908ec651-41253795bafd7a1c",
"url": "https://example.com/signed-image"
}
],
"scalarFields": "{\"question\":\"How do I reset it?\",\"category\":\"account\"}",
"mediaStartMs": 1250,
"mediaEndMs": 8400,
"mediaTimeline": [
{
"text": "第一句话。",
"startMs": 1250,
"endMs": 4200
}
]
}
],
"code": 0,
"message": "success",
"accessDeniedDetail": "{\"PolicyType\":\"AccountLevelIdentityBasedPolicy\",\"NoPermissionType\":\"ImplicitDeny\",\"AuthAction\":\"milvusknowledgebase:SearchKnowledgeBase\"}",
"success": true,
"httpStatusCode": 0,
"evidenceNextToken": "example-opaque-next-token",
"evidenceResults": [
{
"evidenceId": "wiki_section_page_1_sec_1_rev_7",
"kind": "wiki_section",
"knowledgeBaseId": "example_kb",
"documentId": "null",
"chunkId": "null",
"pageId": "page_1",
"sectionId": "sec_1",
"entityId": "null",
"relationId": "null",
"revisionId": "example_value",
"batchId": "null",
"title": "保修说明",
"content": "产品甲保修期为18个月。",
"score": 0.62,
"sourceRefs": [
{
"documentId": "example_value",
"chunkId": "example_value",
"sourceRevisionId": "example_value",
"version": "DRAFT",
"documentName": "example_value",
"pageNumber": 1,
"mediaStartMs": 0,
"mediaEndMs": 0
}
],
"sourceRefCount": 1,
"sourceRefsTruncated": false,
"sourceTaskId": "null"
}
]
}
错误码
访问错误中心查看更多错误码。
变更历史
更多信息,参考变更详情。