资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

知识库检索

接口描述

从指定的知识库中进行自定义检索。

知识库检索流程示意图

流程图-202501101557.png

权限说明

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,可以用这个对象指定一个新的配置。
data_source ElasticSearchRetrieveConfig 托管资源为共享资源 或 BES资源时使用该配置。
推荐使用默认配置,保证与线上命中测试效果相同。
data_source \ name string 该节点的自定义名称。如:step1。
data_source \ type string 该节点的类型。
可选值:
elastic_search:数据源来自BES。
vector_db:数据源来自VDB
无默认值,必须填写数据源来源。
data_source \ threshold float 得分阈值。
取值范围: [0, 1]。
默认0.1。
data_source \ top int 召回数量。
取值范围: [0, 800]。
默认400 。
data_source \ pre_ranking object 粗排配置。bm25_weight 与 vec_weight 的和为1。
该字段未填写,则不会进行粗排。
该字段有值,但不填写具体二级参数内容,则使用默认值进行粗排。
data_source \ pre_ranking \ bm25_weight number 粗排bm25分比重。
取值范围: [0, 1]。
默认0.75。
data_source \ pre_ranking \ vec_weight number 粗排向量余弦分比重。
取值范围: [0, 1]。
默认0.25。
data_source \ pre_ranking \ bm25_b number 控制文档长度对评分影响的参数。
取值范围: [0, 1]。
默认0.75。
data_source \ pre_ranking \ bm25_k1 number 词频饱和因子,控制词频(TF)对评分的影响。
取值范围: [1.2, 2.0]。
默认1.5。
data_source \ 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"
}
上一篇
组件
下一篇
创建知识库