知识库检索

POST

https://qianfan.baidubce.com/v2/knowledgebases/query

从指定的知识库中进行自定义切片检索召回。

权限说明

调用本API，需使用API Key鉴权方式。Authorization的值为Bearer <API Key>。获取API Key流程，请查看授权。

请求参数

Headers 参数

除公共头域外，无其它特殊头域

Body 参数

top integer

返回前多少的条目。默认值6。如果检索结果的数量未达到top值，则按实际检索到的结果数量返回。

可选

skip integer

跳过条目数。通过top和skip可以实现类似分页的效果。例如：top 10 skip 0，取第一页的10个，top 10 skip 10，取第二页的10个。

可选

type string

检索策略。可选值： fulltext：全文检索。 semantic：语义检索。 hybrid：混合检索。

可选

query string

检索query。最长为1024字符，超过自动截断。

必选

pipeline_config object {5}

检索配置，详细见QueryPipelineConfig。

可选

显示子属性隐藏子属性

id string

配置唯一标识。如果用这个id，则引用已经配置好的QueryPipeline。

可选

ranking object {4}

精排配置。

可选

显示子属性隐藏子属性

top integer

取切片top进行排序。取值范围：[1, 400]。默认20。

可选

name string

该节点的自定义名称。

必选

type string

该节点的类型。默认为ranking。

必选

inputs array

输入的节点名。如上面elastic_search检索配置的name为step1，则该inputs为["step1"]。

必选

显示子属性隐藏子属性

items string

pipeline array

配置的Pipeline。如果没有配置id，可以用这个对象指定一个新的配置。

可选

显示子属性隐藏子属性

items object {0}

显示子属性隐藏子属性

data_source object {5}

托管资源为共享资源或 BES资源时使用该配置。推荐使用默认配置，保证与线上命中测试效果相同。

可选

显示子属性隐藏子属性

top integer

召回数量。取值范围： [0, 800]。默认400 。

可选

name string

该节点的自定义名称。如：step1。

可选

type string

该节点的类型。可选值： elastic_search：数据源来自BES。 vector_db：数据源来自VDB 无默认值，必须填写数据源来源。

可选

threshold float

得分阈值。取值范围： [0, 1]。默认0.1。

可选

pre_ranking object {5}

粗排配置。bm25_weight 与 vec_weight 的和为1。该字段未填写，则不会进行粗排。该字段有值，但不填写具体二级参数内容，则使用默认值进行粗排。

可选

显示子属性隐藏子属性

bm25_b number

控制文档长度对评分影响的参数。取值范围： [0, 1]。默认0.75。

可选

bm25_k1 number

词频饱和因子，控制词频（TF）对评分的影响。取值范围： [1.2, 2.0]。默认1.5。

可选

vec_weight number

粗排向量余弦分比重。取值范围： [0, 1]。默认0.25。

可选

bm25_weight number

粗排bm25分比重。取值范围： [0, 1]。默认0.75。

可选

bm25_max_score number

得分归一化参数。不建议修改。默认50。

可选

small_to_big object {2}

切片上下文扩展配置。

可选

显示子属性隐藏子属性

name string

该节点的自定义名称。

必选

type string

该节点的类型。默认为small_to_big。

必选

metadata_filters object {2}

元数据过滤条件，详细见MetadataFilters。例如： { "filters": [ { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] }, { "operator": "==", "field": "doc_id", "value": "d1" }, ], "condition": "or" }

可选

显示子属性隐藏子属性

filters object {3}

过滤条件。例如： "filters": [ { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] }, { "operator": "==", "field": "doc_id", "value": "d1" }, ]

必选

显示子属性隐藏子属性

field string

字段名。目前仅支持doc_id。

可选

value anyOf {2}

多选一，只需要符合下列任意一组子节点

取值。当operator的值为in/notin时，value为数组。当operator的值为==时，value为字符串。

必选

显示子属性隐藏子属性

value string

value array

显示子属性隐藏子属性

items string

operator string

操作符名称。可选值： ==：文档id等于value。 in：文档id在数组中的任一值。 notin：文档id不在数组中。举例： { "operator": "in", "field": "doc_id", "value": ["d-1", "d-2"] }

必选

condition string

文档组合条件。决定每一个 MetadataFilter 对象之间的关系。可选值: and：所有条件均满足，才会返回结果。 or：任一条件满足，则返回结果。

必选

knowledgebase_ids array

指定知识库的id集合。例如：["kb-1", "kb-2"]。

必选

显示子属性隐藏子属性

items string

rank_score_threshold number

重排序匹配分阈值。只有rank_score大于等于该分值的切片重排序时才会被筛选出来。当且仅当，pipeline_config中配置了ranking节点时，该过滤条件生效。取值范围： [0, 1]。默认0.4

可选

请求结构

POST /v2/knowledgebases/query HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: Bearer <API Key>
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
}

示例代码

curl

curl --location 'https://qianfan.baidubce.com/v2/knowledgebases/query' \
--header 'Authorization: Bearer <API Key>' \
--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
}'

返回响应

Headers 参数

除公共头域外，无其它特殊头域

返回参数

code string

错误代码，公共错误参考公共错误码，当发生异常时返回

可选

chunks object {16}

切片信息。详情见Chunk对象。

必选

显示子属性隐藏子属性

meta object {8}

根据chunk_type不同，meta字段内容也不一样。

可选

显示子属性隐藏子属性

coord string

文本内容信息。包含位置，页面等。当chunk_type为paragraph时存在，详细可查看locations。

可选

title string

文档名称。当chunk_type为sentence或者paragraph时存在。

可选

tokens string

段落token。当chunk_type为paragraph时存在。

可选

row_line object {5}

检索到的表格型知识数据中的行的信息。当chunk_type为table时存在

可选

显示子属性隐藏子属性

key string

列名。

必选

index integer

列顺序。

必选

value string

列值。

必选

enable_indexing boolean

是否参与索引。可选值： true：参与索引。 false：不参与索引。

必选

enable_response boolean

是否参与问答（即该列数据是否对大模型可见）。当前值固定为true。可选值： true：参与问答。 false：不参与问答。

必选

page_nums array

页面。当chunk_type为paragraph时存在。详细可查看locations。

可选

显示子属性隐藏子属性

items integer

word_count string

段落字数。当chunk_type为paragraph时存在。

可选

leftneighbors array

该切片的左邻居切片chunk_id。

可选

显示子属性隐藏子属性

items string

rightneighbors array

该切片的右邻居切片chunk_id。

可选

显示子属性隐藏子属性

items string

content string

chunk内容。

必选

children array

子切片。

可选

显示子属性隐藏子属性

items object {0}

显示子属性隐藏子属性

chunk_id string

chunk id。由于历史兼容问题，部分旧数据集可能会出现长度超过36的情况，需要截取最后36位作为chunk_id。

必选

locations object {2}

切片在文档中出现的位置。

可选

显示子属性隐藏子属性

box array

文本内容位置。格式是长度为4的int数组[x, y, width, height]，x与y代表坐标， width与height代表宽度和高度。

可选

显示子属性隐藏子属性

items array

显示子属性隐藏子属性

items integer

page_num array

页面。

可选

显示子属性隐藏子属性

items integer

chunk_type string

chunk类型。

必选

rank_score float

rerank分值。

可选

create_time number

创建时间。

必选

document_id string

文档id。

必选

update_time number

更新时间。

必选

document_name string

文档名。

可选

retrieval_score float

粗检索分值。

必选

knowledgebase_id string

知识库id。

必选

neighbour_chunks array

开启切片扩展后，所扩展的邻居切片。

可选

显示子属性隐藏子属性

items object {0}

显示子属性隐藏子属性

original_chunk_id string

关联的原始切片，仅扩展切片才会包含该字段。

可选

original_chunk_offset integer

扩展切片相对原始切片的关联位置，仅扩展切片才会包含该字段。枚举值： -1 ：原始切片的前一个切片。 1 ：原始切片的后一个切片。

可选

message string

错误消息，公共错误参考公共错误码，当发生异常时返回

可选

requestId object {0}

导致错误的请求requestId，当发生异常时返回。注意requestId总是在header中返回。

可选

显示子属性隐藏子属性

total_count integer

chunk数量。

必选

正确响应示例错误响应示例

JSON

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

JSON

HTTP/1.1 400
{
    "code": "InvalidRequest",
    "message": "knowledgebase_id Not Found",
    "requestId": "87d595db-b1b6-476c-85f8-813397c7f421"
}

错误码

错误代码，公共错误参考公共错误码，当发生异常时返回

百度智能云

千帆AI应用开发者中心-API参考 qianfan-api

千帆AI应用开发者中心-API参考 qianfan-api

权限说明

请求参数

示例代码

返回响应

错误码