在指定的知识库中检索信息。
接口说明
- RAM 用户（子账号）需要首先获取百炼的数据权限（需要
AliyunBailianDataFullAccess，已包括 sfm:Retrieve 权限点），然后才能调用本接口，详见为 RAM 用户授予数据权限。阿里云账号（主账号）可直接调用无须授权。建议您通过最新版百炼 SDK来调用本接口。 - 调用本接口前，请确保您的知识库已经创建完成且未被删除（即知识库 ID
IndexId有效）。 - 由于接口调用包含复杂的检索和匹配，响应时间可能较长，建议您合理设置请求的超时与重试策略。
- 本接口具有幂等性。
限流说明： 本接口频繁调用会被限流，频率请勿超过 20 次/秒。如遇限流，请稍后重试。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
- 操作：是指具体的权限点。
- 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
- 资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用
全部资源表示。
- 条件关键字：是指云产品自身定义的条件关键字。
- 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
| 操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
|---|---|---|---|---|
| sfm:Retrieve | none | *全部资源 * |
| 无 |
请求语法
POST /{WorkspaceId}/index/retrieve HTTP/1.1
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| Query | string | 否 | 输入文本（原始输入 prompt）。Query 的长度和字符没有限制。 | 百炼平台介绍 |
| DenseSimilarityTopK | integer | 否 | 向量检索 Top K，通过生成输入文本的向量并在知识库中检索与其向量表示最相似的 K 个文本切片。K 的取值范围[0-100]。
默认值为 100。 | 100 |
| EnableReranking | boolean | 否 | true | |
| EnableRewrite | boolean | 否 | false | |
| Rerank | array<object> | 否 | Rank 配置。 | |
| object | 否 | Rank 配置对象。 | ||
| ModelName | string | 否 | Rank 模型名称。更多信息，请参见知识库。取值范围：
| gte-rerank-hybrid |
| RerankMinScore | float | 否 | 相似度阈值。该阈值表示允许召回的文本切片的最低相似度分数，用于筛选 Rank 模型返回的文本切片，即只有分数超过此数值的文本切片才会被召回。更多信息，请参见知识库。取值范围[0.01-1.00]。此参数的优先级大于知识库相似度阈值配置。 默认值为空，此时以知识库的相似度阈值为准。 | 0.20 |
| RerankTopN | integer | 否 | Rerank 后的 Top N 返回数据。取值范围[1-20]，默认值为 5。 | 5 |
| Rewrite | array<object> | 否 | 会话改写配置。 | |
| object | 否 | 会话改写配置对象。 | ||
| ModelName | string | 否 | 会话改写模型名称。它会基于会话上下文自动调整原始输入 prompt（用户问题）以提升检索效果。取值范围：
默认值为空，采用 conv-rewrite-qwen-1.8b 模型。 | conv-rewrite-qwen-1.8b |
| SparseSimilarityTopK | integer | 否 | 关键词检索 TopK，即在知识库中查找与输入文本的关键词精确匹配的切片。它可以帮助您过滤掉无关的文本切片，提供更准确的结果。
取值范围[0-100]。
默认值为：100。 | 100 |
| WorkspaceId | string | 是 | 知识库所属的业务空间 ID。在百炼的控制台首页，单击页面左上角业务空间详情图标获取。 | llm-3shx2gu255oqxxxx |
| IndexId | string | 是 | 知识库 ID，即 CreateIndex 接口返回的 | 5pwe0mxxxx |
| SaveRetrieverHistory | boolean | 否 | 是否保存历史文本切片召回测试数据。取值范围：
默认值为：false。 | false |
| SearchFilters | array<object> | 否 | 支持通过 SearchFilter 设置个性化的检索条件，对语义检索结果进行过滤，以排除与查询 Query 无关的信息。使用方法请参见 知识库 SearchFilters。 | |
| object | 否 | 检索条件对象。 | ||
| string | 否 | 检索条件。 | 百炼 |
返回参数
示例
正常返回示例
JSON格式
{
"Code": "Index.InvalidParameter",
"Data": {
"Nodes": [
{
"Metadata": "{\n\t\"parent\": \"\",\n\t\"file_path\": \"https://***\",\n\t\"image_url\": [\n\t \"http://***\"\n\t],\n\t\"nid\": \"***\",\n\t\t\"title\": \"阿里云百炼文档\",\n\t\"doc_id\": \"doc_***\",\n\t\"content\": \"阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建\",\n\t\"workspace_id\": \"ws_***\",\n\t\"hier_title\": \"阿里云百炼文档\",\n\t\"doc_name\": \"阿里云百炼文档介绍.pdpf\",\n\t\"pipeline_id\": \"rhd***\",\n\t\"_id\": \"ws_***\"\n\t}",
"Score": 0.3,
"Text": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。"
}
]
},
"Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
"RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
"Status": "200",
"Success": true
}错误码
访问错误中心查看更多错误码。
变更历史
| 变更时间 | 变更内容概要 | 操作 |
|---|---|---|
| 2024-07-23 | OpenAPI 入参发生变更 | 查看变更详情 |