# 检索知识库数据 #### 功能介绍 检索知识库数据，根据用户提供的检索信息，返回命中的信息数据。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-appstage/appstage_07_0008.html)。 #### URI POST https://aiae.appstage.myhuaweicloud.com/v1/knowledge-bases/{knowledge_base_id}/embed-datas 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | knowledge_base_id | 是 | String | **参数解释：** 知识库id。获取方式： 1.可从创建知识库接口返回获取； 2.进入[AI原生应用引擎](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0638.html#section0)，在左侧导航栏选择"知识中心 \> 知识库"，可从页面知识库ID栏获取。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母、数字以及"-"组成，且长度为36个字符。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Authorization | 是 | String | **参数解释：** 鉴权信息。获取平台API Key，并为API Key添加前缀Bearer，得到标准鉴权信息，例如Bearer sk-74e4157\*\*\*。API Key获取方法请参见[创建API Key](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0704.html)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | keyword | 否 | String | **参数解释：** 搜索关键字，用于检索匹配结果。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，字符串长度介于0到2048之间。 **默认取值：** 不涉及。 | | similarity_min | 否 | Float | **参数解释：** 相似度最小值，数值越大表示相似度越高。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，取值\[0, 1\]。 **默认取值：** 不涉及。 | | limit | 是 | Integer | **参数解释：** 检索返回切片限制数量。 **约束限制：** 不涉及。 **取值范围：** 非空，取值\[1, 100\]，默认上限100。 **默认取值：** 不涉及。 | | filter | 否 | Object | **参数解释：** 过滤条件。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，则为SearchSqlFilter类对象。 **默认取值：** 不涉及。 | | order_by | 否 | Object | **参数解释：** 排序规则。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，则为SqlOrder对象。 **默认取值：** 不涉及。 | | data_sets | 否 | Array of [DataSetSearchInfo] objects | **参数解释：** 检索的数据集信息，用于指定检索知识库中部分数据集。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，则为DataSetSearchInfo对象列表，且数量介于1到10之间。 **默认取值：** 不涉及。 | 表4SearchSqlFilter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | group_type | 否 | String | **参数解释：** 过滤条件运算符。 **约束限制：** 只有一个expression时，不需要group_type，group_type可以为null。 **取值范围：** 可以为null，如果不为null，枚举值AND和OR。 **默认取值：** 不涉及。 | | expressions | 是 | Array of [Expression] objects | **参数解释：** 过滤条件。 **约束限制：** 不涉及。 **取值范围：** 非空，条件数量介于1到10之间。 **默认取值：** 不涉及。 | 表5Expression | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | field | 是 | String | **参数解释：** 过滤字段。 **约束限制：** 需以"metadata."开头，后续可接上path、order、file_name以及索引配置时配置的文本过滤字段，如metadata.path、metadata.answer（假设answer为配置的文本过滤字段）。 **取值范围：** 非空，字段名称长度介于1到100之间。 **默认取值：** 不涉及。 | | field_type | 是 | String | **参数解释：** 过滤字段类型。 **约束限制：** 不涉及。 **取值范围：** 非空，枚举值：INT、FLOAT、BOOLEAN和STRING，取值视field的类型而定。 **默认取值：** 不涉及。 | | operator | 是 | String | **参数解释：** 过滤操作符。 **约束限制：** 不涉及。 **取值范围：** 非空，枚举值：EQUAL（等于）、NOT_EQUAL（不等于）、GREAT_THAN（大于）、GREAT_EQUAL（大于等于）、LESS_THAN（小于）、LESS_EQUAL（小于等于）、IN（在xxx之间）、NOTIN（不在xxx之间）和STARTS_WITH（以xxx开头）。 **默认取值：** 不涉及。 | | values | 是 | Array of strings | **参数解释：** 过滤值。 **约束限制：** 当operator参数的值为EQUAL（等于）、NOT_EQUAL（不等于）、GREAT_THAN（大于）、GREAT_EQUAL（大于等于）、LESS_THAN（小于）、LESS_EQUAL（小于等于）和STARTS_WITH（以xxx开头）时，数量限制为1。 **取值范围：** 非空，数量介于1到100之间，每个字符串长度最大不超过2000。 **默认取值：** 不涉及。 | 表6SqlOrder | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | order_items | 是 | Array of [OrderItem] objects | **参数解释：** 排序规则。 **约束限制：** 不涉及。 **取值范围：** 非空，数量介于1到10之间。 **默认取值：** 不涉及。 | 表7OrderItem | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | field | 是 | String | **参数解释：** 排序字段。 **约束限制：** 不涉及。 **取值范围：** 非空，字符串长度介于1到100之间。 **默认取值：** 不涉及。 | | field_type | 否 | String | **参数解释：** 排序字段类型。 **约束限制：** 不涉及。 **取值范围：** 可以为null，如果不为null，枚举值：INT、FLOAT、BOOLEAN和STRING。 **默认取值：** STRING。 | | order_type | 是 | String | **参数解释：** 排序类型。 **约束限制：** 不涉及。 **取值范围：** 不为null，枚举值：ASC（升序）和DESC（降序）。 **默认取值：** 不涉及。 | 表8DataSetSearchInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | data_set_id | 否 | String | **参数解释：** 知识数据集id，获取方式： 1.创建知识数据集接口返回值即为知识数据集id。 2.进入[AI原生应用引擎](https://support.huaweicloud.com/usermanual-wiseagent/appstage_04_0638.html#section0)，在左侧导航栏选择"知识中心 \> 知识库"，选择页面右上角的"... \> 知识数据集"，在数据集列表中，单击数据集名称，进入详情页即可获取数据集ID。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母、数字以及"-"组成，且长度为36个字符。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | data | Array of [ChunkData] objects | **参数解释：** 知识库检索响应数据。 **取值范围：** 不涉及。 | 表10ChunkData | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 切片id。 **取值范围：** 由数字、字母和中划线组成，长度36。 | | document | String | **参数解释：** 向量化内容。 **取值范围：** 不涉及。 | | chunk | String | **参数解释：** 完整切片内容。若用户在创建索引时配置了chunk作为检索附加字段，则检索时在此返回。 **取值范围：** 不涉及。 | | chunk_fragments | Map\ | **参数解释：** 附加返回字段及内容（map类型，key为附加返回字段名称，value为附加返回字段内容），若用户在创建索引时配置了除chunk之外的附加返回字段，则字段名称及内容检索时在此返回。 **取值范围：** 不涉及。 | | similarity | Float | **参数解释：** 向量化内容（document）和检索关键字（keyword）的向量相似度门槛，只有相似度大于等于similarity才会返回。 **取值范围：** 大小为\[0,1\]。 | | metadata | [metadata] object | **参数解释：** 切片元数据信息，若用户在创建索引时选择文本过滤字段，则该字段及其内容会作为元数据一部分返回。 **取值范围：** 不涉及。 | | download_addresses | Map\ | **参数解释：** 图片或视频临时下载地址（map类型，key为文件路径，value为下载地址）。 **取值范围：** 不涉及。 | | download_address | String | **参数解释：** 废弃字段，请使用download_addresses。 **取值范围：** 不涉及。 | | data_set_id | String | **参数解释：** 切片所属知识数据集id。 **取值范围：** 由数字、字母和中划线组成，长度36。 | 表11metadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | order | Integer | **参数解释：** 切片序号。 **取值范围：** 不涉及。 | | file_name | String | **参数解释：** 文件名称。 **取值范围：** 不涉及。 | | path | String | **参数解释：** 文件相对路径。 **取值范围：** 不涉及。 | **状态码：500** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 异常错误码。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 异常错误信息。 **取值范围：** 不涉及。 | #### 请求示例 ``` { "keyword" : "户外", "similarity_min" : "0.78", "limit" : 10, "filter" : { "group_type" : "AND", "expressions" : [ { "field" : "metadata.answer", "field_type" : "STRING", "operator" : "EQUAL", "values" : [ "我是xxx。" ] } ] }, "order_by" : { "order_items" : [ { "field" : "metadata.order", "field_type" : "INT", "order_type" : "DESC" } ] }, "data_sets" : [ { "data_set_id" : "a31ed909-xxxx-xxxx-xxxx-10958c90b3f7" } ] } ``` #### 响应示例 **状态码：200** OK。 ``` { "data" : [ { "id" : "812857ef-xxxx-xxxx-xxxx-24ba9fd5e95c", "document" : "问题：你是谁。回答：我是xxx。回答用户id：000。", "chunk" : "问题：你是谁。回答：我是xxx。回答用户id：000。", "chunk_fragments" : { "question" : "你是谁。", "answer" : "我是xxx。" }, "similarity" : 0.87, "metadata" : { "order" : 10, "file_name" : "户外运动热度大大带动各相关产业发展.docx", "path" : "户外运动热度大大带动各相关产业发展.docx", "question" : "你是谁。", "answer" : "我是xxx。" }, "download_addresses" : { "xxx.png" : "https://xxxx" }, "download_address" : null, "data_set_id" : "3967c49d-xxxx-xxxx-xxxx-5eda056a1f1b" } ] } ``` **状态码：500** 服务器内部错误或三方服务器内部错误。 ``` { "error_code" : "AIAE.00001500", "error_msg" : "系统内部错误。" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK。 | | 500 | 服务器内部错误或三方服务器内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-appstage/ErrorCode.html)。