# 知识库在线检索接口文档
## 一、接口概述
`/api/knowledge/collection/search_knowledge`接口用于对已创建的知识库进行检索及前后处理，默认对原始文本加工后的知识内容检索。相比原`search`接口，支持多轮改写、文档聚合排序等新功能，可与`chat_completions`接口联动实现标准检索生成链路。

## 二、前提条件
1. 完成知识库创建。
2. 完成文档导入且处理完毕。
3. 在“签名鉴权方式”页面完成注册账号、实名认证、AK/SK密钥获取和签名获取。

## 三、请求接口
|参数|详情|描述|
|---|---|---|
|URI|`/api/knowledge/collection/search_knowledge`|统一资源标识符|
|请求方法|POST|客户端对向量数据库服务器请求的操作类型|
|请求头|`Content-Type: application/json`<br>`Authorization: HMAC-SHA256 ***`|请求消息类型<br>鉴权|

## 四、请求参数
|参数|子参数|类型|是否必选|默认值|参数说明|
|---|---|---|---|---|---|
|name|--|string|否|--|知识库名称，由英文字母、数字、下划线组成，以英文字母开头，不能为空，长度在1 - 64之间|
|project|--|string|否|default|知识库所属项目，在【访问控制】-【资源管理】-【项目】中创建|
|resource_id|--|string|否|--|知识库唯一id，可单独传该参数，或同时传name和project作为唯一标识|
|query|--|string|是|--|检索文本，最大输入长度8000。超8000接口报错；小于所选embedding模型输入最大长度且大于8000时自动截断；小于模型输入最大长度时正常检索|
|limit|--|int|否|10|检索结果数量，取值范围为1 - 200|
|query_param|--|json|否|--|检索的过滤和返回设置|
|doc_filter|map|否|--|检索过滤条件，支持对doc的meta信息过滤，使用方式和支持字段见filter表达式，可筛选doc_id，需在创建知识库时将过滤字段添加到index_config的fields中|
|dense_weight|--|float|否|0.5|混合检索中稠密向量的权重，取值范围0.2 - 1，1表示纯稠密检索，0表示纯字面检索，仅在索引算法为hnsw_hybrid时有效|
|pre_processing|--|json|否|--|检索预处理|
|need_instruction|--|bool|否|False|是否拼接instruction进行检索|
|rewrite|--|bool|否|False|是否对query进行改写（仅改写非首轮问题）|
|return_token_usage|--|bool|否|False|是否返回search流程中各阶段的token使用量|
|messages|--|json|开启改写时必选|--|多轮对话信息，根据历史对话内容改写问题，参与者角色包括system、user、assistant|
|post_processing|--|json|否|--|检索后处理|
|rerank_switch|--|bool|否|False|是否自动对结果做rerank，开启后自动请求rerank模型排序|
|retrieve_count|--|int|否|25|进入重排的切片数量，仅在rerank_switch为True时生效，需大于等于limit，否则报错|
|chunk_diffusion_count|--|int|否|0|检索阶段返回命中文本片上下几片文本片，取值范围0 - 5，0表示不进行chunk diffusion|
|chunk_group|--|bool|否|False|文本聚合，默认不聚合，非结构化文件可开启，开启后按文档及顺序对切片重新聚合排序返回|
|rerank_model|--|string|否|`"m3-v2-rerank"`|rerank模型选择，仅在rerank_switch为True时生效，可选`"m3-v2-rerank"`（轻量小模型，多语言能力强，推理速度快）|
|rerank_only_chunk|--|bool|否|False|是否仅根据chunk内容计算重排分数，True为只根据chunk内容计算，False为根据chunk title + 内容一起计算|
|get_attachment_link|--|bool|否|False|是否获取切片中图片的临时下载链接|

## 五、响应消息
|参数|参数说明|
|---|---|
|code|状态码|
|message|返回信息|
|request_id|标识每个请求的唯一标识符|
|data|检索召回切片信息|

### data返回值
|字段|子字段|字段类型|说明|
|---|---|---|---|
|collection_name|--|string|检索知识库名字|
|count|--|int|检索返回的切片数量|
|rewrite_query|--|string|改写的query|
|token_usage|--|list|token用量信息|
|embedding_token_usage|prompt_tokens<br>completion_tokens<br>total_tokens|int|检索向量化阶段的token用量|
|rerank_token_usage|--|int|在重排阶段的token用量|
|rewrite_token_usage|--|int|query改写的token用量|
|result_list|--|list|返回切片信息|
|id|--|string|索引的主键|
|content|--|string|切片内容（非结构化文件为切片内容；faq文件为答案；结构化文件为参与索引的字段和取值，以K:V对拼接，用\n区隔）|
|score|--|float|检索得分|
|point_id|--|string|切片id|
|chunk_title|--|string|切片的标题|
|chunk_id|--|int|chunk的id|
|process_time|--|int|检索耗时|
|rerank_score|--|float|重排得分|
|doc_info|doc_id<br>doc_name<br>create_time<br>doc_type<br>doc_meta<br>source<br>title|string/int|文档信息（文档id、名字、创建时间、类型、元信息、来源、标题）|
|recall_position|--|int|检索召回位次|
|rerank_position|--|int|重排位次|
|table_chunk_fields|field_name<br>field_value|string|结构化数据检索返回单行全量数据（字段名称、字段取值）|
|original_question|--|string|faq数据检索召回答案对应的原始问题|
|chunk_type|--|string|切片所属类型|
|chunk_attachment|uuid<br>caption<br>type<br>link|string|检索召回附件（原始图片等）的临时下载链接（chunk_type为image时有效，含唯一标识、标题、类型、链接，链接有效期10分钟）|

## 六、状态码说明
|状态码|http状态码|返回信息|状态码说明|
|---|---|---|---|
|0|200|success|成功|
|1000001|401|unauthorized|缺乏鉴权信息|
|1000002|403|no permission|权限不足|
|1000003|400|invalid request：%s|非法参数|
|1000005|400|collection not exist|collection不存在|

## 七、完整示例
### （一）请求消息
```bash
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/collection/search_knowledge \
  -d '{
        "name": "your_collection",
        "query": "test",
        "limit": 2,
        "query_param" : {},
        "dense_weight": 0.5,
        "pre_processing": {
            "need_instruction": true,
            "rewrite": true,
            "messages": [
                {
                    "role": "system",
                    "content": "prompt template"
                },
                {
                    "role": "user",
                    "content": "history content"
                },
                {
                    "role": "assistant",
                    "content": "history content"
                },
                {
                    "role": "user",
                    "content": "history content"
                },
                {
                    "role": "assistant",
                    "content": "history content"
                }
            ],
            "return_token_usage": true
        },
        "post_processing": {
            "rerank_switch": false,
            "rerank_model": "m3-v2-rerank",
            "rerank_only_chunk": false,
            "retrieve_count": 25,
            "endpoint_id": "ep",
            "chunk_group": false,
            "get_attachment_link": false
        }
    }'
```

### （二）响应消息
1. **执行成功返回**
```json
HTTP/1.1 200 OK
Content-Length: 209
Content-Type: application/json

{
    "code": 0,
    "data": {
        "collection_name": "example",
        "count": 2,
        "rewrite_query": "xxx",
        "token_usage": {
            "embedding_token_usage": {
                "prompt_tokens": 16,
                "completion_tokens": 0,
                "total_tokens": 16
            },
            "rerank_token_usage": 0
        },
        "result_list": [
            {
                "id": "_sys_auto_gen_doc_id-13411829101044883689-15",
                "content": "content",
                "score": 0.2639991044998169,
                "point_id": "_sys_auto_gen_doc_id-13411829101044883689-15",
                "chunk_title": "title",
                "chunk_id": 15,
                "process_time": 1727333127,
                "doc_info": {
                    "doc_id": "_sys_auto_gen_doc_id-13411829101044883689",
                    "doc_name": "2404.08817v2.pdf",
                    "create_time": 1727333117,
                    "doc_type": "pdf",
                    "doc_meta": "[{\"field_name\":\"doc_id\",\"field_type\":\"string\",\"field_value\":\"_sys_auto_gen_doc_id-13411829101044883689\"}]",
                    "source": "tos_fe",
                    "title": "title"
                },
                "recall_position": 1,
                "chunk_type": "text"
            },
            {
                "id": "_sys_auto_gen_doc_id-13411829101044883689-7",
                "content": "content",
                "score": 0.2583845257759094,
                "point_id": "_sys_auto_gen_doc_id-13411829101044883689-7",
                "chunk_title": "title",
                "chunk_id": 7,
                "process_time": 1727333127,
                "doc_info": {
                    "doc_id": "_sys_auto_gen_doc_id-13411829101044883689",
                    "doc_name": "2404.08817v2.pdf",
                    "create_time": 1727333117,
                    "doc_type": "pdf",
                    "doc_meta": "[{\"field_name\":\"doc_id\",\"field_type\":\"string\",\"field_value\":\"_sys_auto_gen_doc_id-13411829101044883689\"}]",
                    "source": "tos_fe",
                    "title": "title"
                },
                "recall_position": 2,
                "chunk_type": "text"
            }
        ]
    },
    "message": "success",
    "request_id": "02172740884343900000000000000000000ffff0a00406f8a8861"
}
```
2. **执行失败返回**
```json
HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
{"code":1000003, "message":"invalid request：%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}
```