知识库检索
更新时间：2024-12-26
接口描述
从指定的知识库中进行自定义检索。
知识库检索流程示意图
权限说明
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：全文检索。 |
| 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。 |
| top | int | 否 | 返回前多少的条目。 如果检索结果的数量未达到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在数组中的任一值。 not_in：文档id不在数组中。 举例： { "operator": "in", "field": "doc_id", value: ["d-1", "d-2"] } |
| field | string | 否 | 字段名。目前仅支持doc_id。 |
| value | string / array | 是 | 取值。 当operator的值为in/not_in时，value为数组。 当operator的值为==时，value为字符串。 |
QueryPipelineConfig
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| id | string | 否 | 配置唯一标识。如果用这个id，则引用已经配置好的QueryPipeline。 |
| pipeline | list[object] | 否 | 配置的Pipeline。如果没有配置id，可以用这个对象指定一个新的配置。 |
| elastic_search | ElasticSearchRetrieveConfig | 否 | 全文检索配置。 type 值为 fulltext 时生效。 推荐使用默认配置，保证与线上命中测试效果相同。 |
| elastic_search \ name | string | 是 | 该配置的自定义名称。如：step1。 |
| elastic_search \ type | string | 是 | elastic_search标志。 可选值： 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。 |
| ranking | RankingConfig | 否 | 精排配置。 |
| ranking \ name | string | 是 | 该配置的自定义名称。 |
| ranking \ type | string | 是 | ranking标志。该节点为ranking节点。 |
| ranking \ inputs | [string] | 是 | 输入的节点名。 如上面elastic_search检索配置的name为step1，则该inputs为["step1"]。 |
| ranking \ top | int | 否 | 取切片top进行排序。 取值范围：[1, 400]。 默认20。 |
响应头域
除公共头域外，无其它特殊头域。
响应参数
| 字段 | 类型 | 必然存在 | 说明 |
|---|---|---|---|
| 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时存在。 |
| chunk_type | string | 是 | chunk类型。 |
| content | string | 是 | chunk内容。 |
| create_time | time | 是 | 创建时间。 |
| update_time | time | 是 | 更新时间。 |
| retrieval_score | float | 是 | 粗检索分值。 |
| rank_score | float | 是 | rerank分值。 |
| locations | [ChunkLocation] | 否 | 切片在文档中出现的位置。 |
| children | [Chunk] | 否 | 子切片。 |
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": [
"8d5393c8-42f8-44d7-9a76-2c42fb0f81bd"
],
"metadata_filters": {
"filters": [
{
"operator": "==",
"field": "doc_id",
"value": "2c9c05ca-a778-4edf-af77-baa90facbe0b"
}
],
"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"],
"top": 20
}
]
},
"top": 2,
"skip": 0
}
'正确响应示例
HTTP/1.1 200 OK
{
"chunks": [
{
"chunk_id": "cdd6ff91-ce3b-4e27-a819-d8bc5573fcd3",
"knowledgebase_id": "8d5393c8-42f8-44d7-9a76-2c42fb0f81bd",
"document_id": "2c9c05ca-a778-4edf-af77-baa90facbe0b",
"document_name": "msg",
"meta": {
"coord": "{\"box\": [[90, 73, 415, 387]], \"page_num\": [3], \"parent_list\": [], \"parent_last\": 0}",
"page_nums": [
3
],
"tokens": 200,
"word_count": 261,
"title": "msg"
},
"chunk_type": "paragraph",
"content": "调入初唐，时带六朝\n锦色。”作品风格播报编辑初唐四杰他们都是初唐中后期很有才华的诗文作家，\n四人才名早享，在青少年时代就获得“四杰”的美誉。他们都是官小而名大，年\n少而才高的诗人，他们在初唐诗坛的地位很重要，上承梁陈，下启沈宋，其中\n卢、骆长于歌行，王、杨长于五律。后人所说的声律风骨兼备的唐诗，从他们\n才开始定型。他们开始把诗歌从宫廷移到了市井，从台阁移到了江山和塞漠，\n题材扩大，思想严肃，五言八句的律诗形式由他们开始了初步的定型。他们怀\n着变革文风的自觉意识，有一种十分明确的审美追求：反对纤巧绮靡，提倡刚\n健骨气。",
"create_time": "2024-12-15T22:44:10.403000",
"update_time": "2024-12-15T22:44:10.403000",
"retrieval_score": 0.0,
"rank_score": 0.5511208176612854,
"locations": {
"page_num": [
3
],
"box": [
[
90,
73,
415,
387
]
]
},
"children": []
},
{
"chunk_id": "05376069-4076-44c1-adbe-afef58c9d5eb",
"knowledgebase_id": "8d5393c8-42f8-44d7-9a76-2c42fb0f81bd",
"document_id": "2c9c05ca-a778-4edf-af77-baa90facbe0b",
"document_name": "msg",
"meta": {
"coord": "{\"box\": [[90, 73, 415, 683]], \"page_num\": [2], \"parent_list\": [], \"parent_last\": 0}",
"page_nums": [
2
],
"tokens": 254,
"word_count": 331,
"title": "msg"
},
"chunk_type": "paragraph",
"content": "四杰名次，亦记载不一。宋之问《祭杜学士审言文》说，唐开国后“复\n有王杨卢骆”，并以此次序论列诸人，为现所知最早的材料。张说《赠太尉裴公\n神道碑》称：“在选曹，见骆宾王、卢照邻、王勃、杨炯”，则以骆为首。杜甫\n诗句“王杨卢骆当时体”，一本作“杨王卢骆”；《旧唐书·裴行俭传》亦以杨王卢\n骆为序。四杰的诗文虽未脱齐梁以来绮丽余习，但已初步扭转文学风气。王勃\n明确反对当时“上官体”，“思革其弊”，得到卢照邻等人的支持(杨炯《王勃集\n序》)。他们的诗歌扭转了唐朝以前萎靡浮华的宫廷诗歌风气,使诗歌题材从亭\n台楼阁、风花雪月的狭小领域扩展到江河山川、边塞江漠的辽阔空间，赋予诗\n以新的生命力。卢、骆的七言歌行趋向辞赋化，气势稍壮；王、杨的五言律绝\n开始规范化，音调铿锵。",
"create_time": "2024-12-15T22:44:10.402000",
"update_time": "2024-12-15T22:44:10.402000",
"retrieval_score": 0.0,
"rank_score": 0.5508489608764648,
"locations": {
"page_num": [
2
],
"box": [
[
90,
73,
415,
683
]
]
},
"children": []
}
],
"total_count": 2
}错误响应示例
HTTP/1.1 400
{
"code": "InvalidRequest",
"message": "knowledgebase_id Not Found",
"requestId": "87d595db-b1b6-476c-85f8-813397c7f421"
}