知识库检索
更新时间：2025-01-23
接口描述
从指定的知识库中进行自定义检索。
知识库检索流程示意图
权限说明
Authorization需要填写密钥。
接口定义
| Path | /v2/knowledgebases/query |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Authorization | 请求签名(此签名为应用工作台密钥) |
请求结构
POST /v2/knowledgebases/query HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: authorization string
Content-Type: application/json
{
"type": "fulltext",
"query": "query_str",
"knowledgebase_ids": [
"knowledgebase_id"
],
"metadata_filters": {
"filters": [
{
"operator": "==",
"field": "doc_id",
"value": "123###789"
}
],
"condition": "or"
},
"pipeline_config": {
"id": "pipeline_001",
"pipeline": [
{
"name": "step1",
"type": "elastic_search",
"threshold": 0.01,
"top": 400,
"pre_ranking": {
"bm25_weight": 0.25,
"vec_weight": 0.75,
"bm25_b": 0.75,
"bm25_k1": 1.2,
"bm25_max_score": 100
}
},
{
"name": "step2",
"type": "ranking",
"inputs": ["step1"],
"top": 20
}
]
},
"top": 10,
"skip": 0
}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| type | string | 否 | 检索策略。 可选值： fulltext：全文检索。 semantic：语义检索。 hybrid：混合检索。 |
| query | string | 是 | 检索query。 最长为1024字符，超过自动截断。 |
| knowledgebase_ids | [string] | 是 | 指定知识库的id集合。 例如：["kb-1", "kb-2"]。 |
| metadata_filters | MetadataFilters | 否 | 元数据过滤条件，详细见MetadataFilters。 例如： { "filters": [ { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] }, { "operator": "==", "field": "doc_id", "value": "d1" }, ], "condition": "or" } |
| pipeline_config | QueryPipelineConfig | 否 | 检索配置，详细见QueryPipelineConfig。 |
| rank_score_threshold | number | 否 | 重排序匹配分阈值。只有rank_score大于等于该分值的切片重排序时才会被筛选出来。 当且仅当，pipeline_config中配置了ranking节点时，该过滤条件生效。 取值范围： [0, 1]。 默认0.4 |
| top | int | 否 | 返回前多少的条目。默认值6。 如果检索结果的数量未达到top值，则按实际检索到的结果数量返回。 |
| skip | int | 否 | 跳过条目数。通过top和skip可以实现类似分页的效果。 例如：top 10 skip 0，取第一页的10个，top 10 skip 10，取第二页的10个。 |
MetadataFilters
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| filters | [MetadataFilter] | 是 | 过滤条件。 例如： "filters": [ { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] }, { "operator": "==", "field": "doc_id", "value": "d1" }, ] |
| condition | string | 是 | 文档组合条件。决定每一个 MetadataFilter 对象之间的关系。 可选值: and：所有条件均满足，才会返回结果。 or：任一条件满足，则返回结果。 |
MetadataFilter
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| operator | string | 是 | 操作符名称。 可选值： ==：文档id等于value。 in：文档id在数组中的任一值。 notin：文档id不在数组中。 举例： { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] } |
| field | string | 否 | 字段名。目前仅支持doc_id。 |
| value | string / array | 是 | 取值。 当operator的值为in/notin时，value为数组。 当operator的值为==时，value为字符串。 |
QueryPipelineConfig
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| id | string | 否 | 配置唯一标识。如果用这个id，则引用已经配置好的QueryPipeline。 |
| pipeline | list[object] | 否 | 配置的Pipeline。如果没有配置id，可以用这个对象指定一个新的配置。 |
| elastic_search | ElasticSearchRetrieveConfig | 否 | 托管资源为共享资源 或 BES资源时使用该配置。 推荐使用默认配置，保证与线上命中测试效果相同。 |
| elastic_search \ name | string | 是 | 该节点的自定义名称。如：step1。 |
| elastic_search \ type | string | 是 | 该节点的类型。默认为elastic_search。 |
| elastic_search \ threshold | float | 否 | 得分阈值。 取值范围： [0, 1]。 默认0.1。 |
| elastic_search \ top | int | 否 | 召回数量。 取值范围： [0, 800]。 默认400 。 |
| elastic_search \ pre_ranking | object | 否 | 粗排配置。bm25_weight 与 vec_weight 的和为1。 该字段未填写，则不会进行粗排。 该字段有值，但不填写具体二级参数内容，则使用默认值进行粗排。 |
| elastic_search \ pre_ranking \ bm25_weight | number | 否 | 粗排bm25分比重。 取值范围： [0, 1]。 默认0.75。 |
| elastic_search \ pre_ranking \ vec_weight | number | 否 | 粗排向量余弦分比重。 取值范围： [0, 1]。 默认0.25。 |
| elastic_search \ pre_ranking \ bm25_b | number | 否 | 控制文档长度对评分影响的参数。 取值范围： [0, 1]。 默认0.75。 |
| elastic_search \ pre_ranking \ bm25_k1 | number | 否 | 词频饱和因子，控制词频（TF）对评分的影响。 取值范围： [1.2, 2.0]。 默认1.5。 |
| elastic_search \ pre_ranking \ bm25_max_score | number | 否 | 得分归一化参数。不建议修改。 默认50。 |
| vector_db | VectorDBRetrieveConfig | 否 | 托管资源为VDB资源时使用该配置。 |
| vector_db \ name | string | 是 | 该节点的自定义名称。如：step2。 |
| vector_db \ type | string | 是 | 该节点的类型。默认为vector_db。 |
| vector_db \ threshold | float | 否 | 得分阈值。 取值范围： [0, 1]。 默认0.1。 |
| vector_db \ top | int | 否 | 召回数量。 取值范围： [0, 800]。 默认400 。 |
| vector_db \ pre_ranking | object | 否 | 粗排配置。bm25_weight 与 vec_weight 的和为1。 该字段未填写，则不会进行粗排。 该字段有值，但不填写具体二级参数内容，则使用默认值进行粗排。 |
| vector_db \ pre_ranking \ bm25_weight | number | 否 | 粗排bm25分比重。 取值范围： [0, 1]。 默认0.75。 |
| vector_db \ pre_ranking \ vec_weight | number | 否 | 粗排向量余弦分比重。 取值范围： [0, 1]。 默认0.25。 |
| vector_db \ pre_ranking \ bm25_b | number | 否 | 控制文档长度对评分影响的参数。 取值范围： [0, 1]。 默认0.75。 |
| vector_db \ pre_ranking \ bm25_k1 | number | 否 | 词频饱和因子，控制词频（TF）对评分的影响。 取值范围： [1.2, 2.0]。 默认1.5。 |
| vector_db \ pre_ranking \ bm25_max_score | number | 否 | 得分归一化参数。不建议修改。 默认50。 |
| ranking | RankingConfig | 否 | 精排配置。 |
| ranking \ name | string | 是 | 该节点的自定义名称。 |
| ranking \ type | string | 是 | 该节点的类型。 默认为ranking。 |
| ranking \ inputs | [string] | 是 | 输入的节点名。 如上面elastic_search检索配置的name为step1，则该inputs为["step1"]。 |
| ranking \ top | int | 否 | 取切片top进行排序。 取值范围：[1, 400]。 默认20。 |
| small_to_big | SmallToBigConfig | 否 | 切片上下文扩展配置。 |
| small_to_big / name | string | 是 | 该节点的自定义名称。 |
| small_to_big / type | string | 是 | 该节点的类型。 默认为small_to_big。 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 字段 | 类型 | 必然存在 | 说明 |
|---|---|---|---|
| requestId | dict | 否 | 导致错误的请求requestId，当发生异常时返回。 注意requestId总是在header中返回。 |
| code | string | 否 | 错误代码，公共错误参考公共错误码，当发生异常时返回 |
| message | string | 否 | 错误消息，公共错误参考公共错误码，当发生异常时返回 |
| chunks | [Chunk] | 是 | 切片信息。详情见Chunk对象。 |
| total_count | int | 是 | chunk数量。 |
Chunk
| 字段 | 类型 | 必然存在 | 说明 |
|---|---|---|---|
| chunk_id | string | 是 | chunk id。由于历史兼容问题，部分旧数据集可能会出现长度超过36的情况，需要截取最后36位作为chunk_id。 |
| knowledgebase_id | string | 是 | 知识库id。 |
| document_id | string | 是 | 文档id。 |
| document_name | string | 否 | 文档名。 |
| meta | object | 否 | 根据chunk_type不同，meta字段内容也不一样。 |
| meta \ row_line | list[RowLine] | 否 | 检索到的表格型知识数据中的行的信息。 当chunk_type为table时存在，结构参考RowLine。 |
| meta \ title | string | 否 | 文档名称。当chunk_type为sentence或者paragraph时存在。 |
| meta \ coord | string | 否 | 文本内容信息。包含位置，页面等。 当chunk_type为paragraph时存在，详细可查看locations。 |
| meta \ page_nums | [int] | 否 | 页面。当chunk_type为paragraph时存在。详细可查看locations。 |
| meta \ tokens | int | 否 | 段落token。当chunk_type为paragraph时存在。 |
| meta \ word_count | int | 否 | 段落字数。当chunk_type为paragraph时存在。 |
| meta \ leftneighbors | [ string ] | 否 | 该切片的左邻居切片chunk_id。 |
| meta \ rightneighbors | [ string ] | 否 | 该切片的右邻居切片chunk_id。 |
| chunk_type | string | 是 | chunk类型。 |
| content | string | 是 | chunk内容。 |
| create_time | time | 是 | 创建时间。 |
| update_time | time | 是 | 更新时间。 |
| retrieval_score | float | 是 | 粗检索分值。 |
| rank_score | float | 是 | rerank分值。 |
| locations | [ChunkLocation] | 否 | 切片在文档中出现的位置。 |
| children | [Chunk] | 否 | 子切片。 |
| neighbour_chunks | [Chunk] | 否 | 开启切片扩展后，所扩展的邻居切片。 |
| original_chunk_id | string | 否 | 关联的原始切片，仅扩展切片才会包含该字段。 |
| original_chunk_offset | int | 否 | 扩展切片相对原始切片的关联位置，仅扩展切片才会包含该字段。 枚举值： -1 ：原始切片的前一个切片。 1 ：原始切片的后一个切片。 |
RowLine
| 字段 | 类型 | 必然存在 | 说明 |
|---|---|---|---|
| key | String | 是 | 列名。 |
| index | int | 是 | 列顺序。 |
| value | String | 是 | 列值。 |
| enable_indexing | bool | 是 | 是否参与索引。 可选值： true：参与索引。 false：不参与索引。 |
| enable_response | bool | 是 | 是否参与问答（即该列数据是否对大模型可见）。当前值固定为true。 可选值： true：参与问答。 false：不参与问答。 |
ChunkLocation
| 字段 | 类型 | 必然存在 | 说明 |
|---|---|---|---|
| page_num | [int] | 是 | 页面。 |
| box | [[ int ]] | 是 | 文本内容位置。格式是长度为4的int数组[x, y, width, height]，x与y代表坐标， width与height代表宽度和高度。 |
请求curl 示例
curl --location 'https://qianfan.baidubce.com/v2/knowledgebases/query' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data '{
"type": "fulltext",
"query": "党的二十大报告讲了哪些内容",
"knowledgebase_ids": ["c17f9dca-9b38-4dd3-aae6-4cc19c2088e8"],
"metadata_filters": {
"filters": [
{
"operator": "==",
"field": "doc_id",
"value": "b4541f76-e8b1-46e3-8b20-a535ab73a149"
}
],
"condition": "or"
},
"pipeline_config": {
"id": "pipeline_001",
"pipeline": [
{
"name": "step1",
"type": "elastic_search",
"threshold": 0.1,
"top": 400,
"pre_ranking": {
"bm25_weight": 0.25,
"vec_weight": 0.75,
"bm25_b": 0.75,
"bm25_k1": 1.5,
"bm25_max_score": 50
}
},
{
"name": "step2",
"type": "ranking",
"inputs": ["step1"],
"model_name": "ranker-v1",
"top": 20
},
{
"name": "step3",
"type": "small_to_big"
}
]
},
"top": 1,
"skip": 0,
"rank_score_threshold": 0.5
}'正确响应示例
{
"chunks": [
{
"chunk_id": "1f073ffe-3186-4df1-8020-934501892c5a",
"knowledgebase_id": "c17f9dca-9b38-4dd3-aae6-4cc19c2088e8",
"document_id": "b4541f76-e8b1-46e3-8b20-a535ab73a149",
"document_name": "msg",
"meta": {
"coord": "{\"box\": [[56, 179, 482, 72]], \"page_num\": [24, 25], \"parent_list\": [\"1\、\政\策\顶\层\设\计\指\明\方\向 \\n\", \"\（\二\）\主\要\机\遇 \\n\", \"\二\、2023 \年\宏\观\经\济\展\望 \\n\", \"\图\目\录 \\n\"], \"parent_last\": 1061}",
"page_nums": [
24,
25
],
"tokens": 452,
"word_count": 588,
"title": "msg",
"para_format": "txt",
"para_type": "text",
"chart_img_key_id": "",
"left_neighbors": [
"83b1a508-3df6-4f1b-aad9-c9d3730bb609"
],
"right_neighbors": [
"50ed7057-4a4a-4b50-80fe-d20b5cd684c2"
]
},
"chunk_type": "paragraph",
"content": " \n（1）党的二十大报告 \n二十大报告为未来五年的高质量发展制定了战略方向。做出了以下几点战略部署：1）着力构建新发展格局。\n2）着力提高全要素生产率。3）着力提升产业链供应链韧性和安全水平。4）着力推进城乡融合发展和区域协调\n发展。5）着力构建高水平社会主义市场经济体制。6）着力推进高水平对外开放。7）着力推动绿色低碳发展。",
"create_time": "2025-01-08T22:49:32.327000",
"update_time": "2025-01-08T22:49:32.327000",
"retrieval_score": 0.0,
"rank_score": 0.5597112774848938,
"locations": {
"page_num": [
24,
25
],
"box": [
[
56,
112,
482,
25
]
]
},
"children": [
{
"chunk_id": "9a0ede81-e2ad-43ac-82c0-07ed96535d15",
"knowledgebase_id": "c17f9dca-9b38-4dd3-aae6-4cc19c2088e8",
"document_id": "b4541f76-e8b1-46e3-8b20-a535ab73a149",
"document_name": "msg",
"meta": {
"title": "msg"
},
"chunk_type": "sentence",
"content": " \n（1）党的二十大报告 \n二十大报告为未来五年的高质量发展制定了战略方向。做出了以下几点战略部署：1）着力构建新发展格局。",
"create_time": "2025-01-08T22:49:32.327000",
"update_time": "2025-01-08T22:49:32.327000",
"retrieval_score": 45.635006,
"rank_score": 0.7578274865456178,
"children": []
}
],
"neighbour_chunks": [
{
"chunk_id": "83b1a508-3df6-4f1b-aad9-c9d3730bb609",
"knowledgebase_id": "c17f9dca-9b38-4dd3-aae6-4cc19c2088e8",
"document_id": "b4541f76-e8b1-46e3-8b20-a535ab73a149",
"document_name": "msg",
"meta": {
"coord": "{\"box\": [[501, 390, 17, 7]], \"page_num\": [23, 24, ], \"parent_list\": [\"\（3\）\\n\", \"2\、\国\内 \\n\", \"\（\一\）\主\要\问\题\和\挑\战 \\n\", \"\二\、2023 \年\宏\观\经\济\展\望 \\n\", \"\图\目\录 \\n\"], \"parent_last\": 1045}",
"page_nums": [
23,
24
],
"tokens": 455,
"word_count": 592,
"title": "msg",
"para_format": "txt",
"para_type": "text",
"chart_img_key_id": "",
"left_neighbors": [
"a990f209-9b7a-4d0c-bdce-6ee5913edd45"
],
"right_neighbors": [
"1f073ffe-3186-4df1-8020-934501892c5a"
]
},
"chunk_type": "paragraph",
"content": " \n2018 年，国务院办\n公厅印发《关于保持基础设施领域补短板力度的指导意见》。\n政策深度报告 \n（二）主要机遇 \n1、政策顶层设计指明方向 \n",
"create_time": "2025-01-08T22:49:32.326000",
"update_time": "2025-01-08T22:49:32.326000",
"retrieval_score": 0.0,
"rank_score": 0.0,
"locations": {
"page_num": [
23,
24
],
"box": [
[
56,
474,
142,
12
]
]
},
"children": [],
"original_chunk_id": "1f073ffe-3186-4df1-8020-934501892c5a",
"original_chunk_offset": -1
},
{
"chunk_id": "50ed7057-4a4a-4b50-80fe-d20b5cd684c2",
"knowledgebase_id": "c17f9dca-9b38-4dd3-aae6-4cc19c2088e8",
"document_id": "b4541f76-e8b1-46e3-8b20-a535ab73a149",
"document_name": "msg",
"meta": {
"coord": "{\"box\": [[56, 179, 482, 72]], \"page_num\": [25], \"parent_list\": [\"\（4\）2023 \年\政\府\工\作\报\告 \\n\", \"1\、\政\策\顶\层\设\计\指\明\方\向 \\n\", \"\（\二\）\主\要\机\遇 \\n\", \"\二\、2023 \年\宏\观\经\济\展\望 \\n\", \"\图\目\录 \\n\"], \"parent_last\": 1065}",
"page_nums": [
25
],
"tokens": 421,
"word_count": 548,
"title": "msg",
"para_format": "txt",
"para_type": "text",
"chart_img_key_id": "",
"left_neighbors": [
"1f073ffe-3186-4df1-8020-934501892c5a"
],
"right_neighbors": [
"a4a87e25-25e5-4c9a-8ce6-39abaff6fdf3"
]
},
"chunk_type": "paragraph",
"content": "财政方面强调“积极的财政政策要加力提效”，\n进一步加大减税缴费、发行政府专项债券等积极财政政策的实施力度。稳增长目标以扩大内需和促进科技创新\n作为两个抓手，通过促进消费和产业转型升级实现高质量的稳增长。报告重点强调了布局三大领域工作：数字\n化转型、国资国企改革及促进民营经济发展、吸引和利用外资。 ",
"create_time": "2025-01-08T22:49:32.327000",
"update_time": "2025-01-08T22:49:32.327000",
"retrieval_score": 0.0,
"rank_score": 0.0,
"locations": {
"page_num": [
25
],
"box": [
[
56,
407,
482,
87
]
]
},
"children": [],
"original_chunk_id": "1f073ffe-3186-4df1-8020-934501892c5a",
"original_chunk_offset": 1
}
]
}
],
"total_count": 1
} 错误响应示例
HTTP/1.1 400
{
"code": "InvalidRequest",
"message": "knowledgebase_id Not Found",
"requestId": "87d595db-b1b6-476c-85f8-813397c7f421"
}