You need to enable JavaScript to run this app.
导航
search_knowledge(新)
最近更新时间:2024.12.16 16:46:18首次发布时间:2024.12.16 16:46:18

本节将说明如何基于一个已创建的知识库做在线检索。

说明

  • 知识库创建完成、文档导入且处理完成后,即代表可以进行在线检索了
  • 调用接口前请先完成“对接指南“页面的注册账号、实名认证、AK/SK 密钥获取和签名获取
  • search 和 search_knowledge 接口的区别:search_knowledge 接口是知识库在线链路升级后的最新接口,在原本 search 接口的基础上支持了多轮改写、文档聚合排序等新功能,与 chat_completions 接口联动,可以完成标准的检索生成链路

概述

/api/knowledge/collection/search_knowledge 接口用于对知识库进行检索和前后处理,当前会默认对原始文本加工后的知识内容进行检索。

前提条件
  • 知识库创建完成。
  • 文档导入且处理完成。
  • 完成“对接指南“页面的注册账号、实名认证、AK/SK 密钥获取和签名获取后,可调用 API 接口实现知识库的检索查询等功能。

请求接口

URI

/api/knowledge/collection/search_knowledge

统一资源标识符

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

参数

子参数

类型

是否必选

默认值

参数说明

name

--

string

知识库名称

  • 只能使用英文字母、数字、下划线_,并以英文字母开头,不能为空
  • 长度要求:[1, 64]

project

--

string

default

知识库所属项目
即在【访问控制】-【资源管理】-【项目】中创建的项目

resource_id

--

string

--

知识库唯一 id
可选择直接传 resource_id,或同时传 name 和 project 作为知识库的唯一标识

query

--

string

检索文本,最大可输入长度为 8000:

  • query 长度 > 8000 时,接口报错
  • 所选 embedding 模型输入最大长度 < query 长度 < 8000 时,query 按所选模型自动截断
  • query 长度 < 所选 embedding 模型输入最大长度 时,正常检索返回要检索的文本,最大可输入长度为 8000 ;

limit

--

int

10

检索结果数量

  • 数量要求:[1, 200]

query_param

json

检索的过滤和返回设置

doc_filter

map

检索过滤条件,支持对 doc 的 meta 信息过滤

  • 使用方式和支持字段见filter 表达式,可支持对 doc_id 做筛选
  • 此处用过过滤的字段,需要在 collection/create 时添加到 index_config 的fields 上

dense_weight

--

float

0.5

混合检索中稠密向量的权重
1 表示纯稠密检索 ,0 表示纯字面检索,范围 [0.2, 1]
只有在请求的知识库使用的是混合检索时有效,即索引算法为 hnsw_hybrid

pre_processing

json

检索预处理

need_instruction

bool

False

是否拼接 instruction 进行检索

rewrite

bool

False

是否对 query 进行改写

return_token_usage

bool

False

是否返回 search 流程中各阶段的token使用量

messages

json

多轮对话信息
仅开启改写时需要上传,可根据历史对话内容进行问题改写
发出消息的对话参与者角色,可选值包括:

  • system:System Message 系统消息
  • user:User Message 用户消息
  • assistant:Assistant Message 对话助手消息
[
    {"role": "system", "content": "你是一个智能助手。"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好!有什么我可以帮助你的?"}
]

post_processing

json

检索后处理

rerank_switch

bool

False

自动对结果做 rerank
说明:打开后,会自动请求 rerank 模型排序

retrieve_count

int

25

进入重排的切片数量,默认为 25
只有在 rerank_switch 为 True 时生效。retrieve_count 需要大于等于 limit,否则会抛出错误

chunk_diffusion_count

int

0

检索阶段返回命中文本片上下几片文本片。
默认为 0,表示不进行 chunk diffusion。范围 [0, 5]

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

检索向量化阶段的 token 用量

{
    "prompt_tokens": 16,
    "completion_tokens": 0,
    "total_tokens": 16
}

rerank_token_usage

int

在重排阶段的 token 用量

result_list

list

返回切片信息

id

string

索引的主键

content

string

切片内容
1、非结构化文件:content 返回切片内容
2、faq 文件:content 返回答案
3、结构化文件:content 返回参与索引的字段和取值,以 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

list

文档信息

{
    "doc_id": "_sys_auto_gen_doc_id-134144883689", //文档 id
    "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\"}]", //文档相关元信息(此处是一个包含文档 id 信息的列表形式的字符串)
    "source": "tos_fe", //知识来源
    "title": "Revisiting Code Similarity Evaluation with Abstract Syntax Tree Edit Distance" //知识所属文档的标题
}

recall_position

int

检索召回位次

rerank_position

int

重排位次

table_chunk_fields

list<object>

结构化数据检索返回单行全量数据

original_question

string

faq 数据检索召回答案对应的原始问题

chunk_type

string

切片所属类型

chunk_attachment

list<object>

检索召回附件(原始图片等)的临时下载链接,chunk_type 为 image 时有效

table_chunk_fields 返回值

字段

字段类型

说明

field_name

string

结构化数据的表字段名称

field_value

--

结构化数据的表字段取值
字段类型以创建知识库时表字段定义为准

chunk_attachment 返回值

字段

字段类型

说明

uuid

string

附件的唯一标识

caption

string

图片所属标题,若未识别到标题则值为"\n"

type

string

image 等

link

string

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 不存在

完整示例

请求消息

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
        }
    }
  }
}'

响应消息

执行成功返回:

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

执行失败返回:

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000003, "message":"invalid request:%s", "request_id": "021695029757920fd001de6666600000000000000000002569b8f"}