SearchKnowledgeBase - 检索知识库

更新时间:
复制 MD 格式

检索知识库

接口说明

按问题或图片检索指定知识库。版本使用 DRAFT、LATEST_PUBLISHED 或 vN 展示名,标签过滤条件按后端实际操作符传入。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求语法

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}

枚举值:

  • raw
  • wiki_page
  • wiki_section
  • graph_fact

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"
    }
  ]
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息,参考变更详情。