文档

QueryCollectionData - 召回向量数据

更新时间:

召回向量数据。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
gpdb:QueryCollectionDatacreate
  • Collection
    acs:gpdb:{#regionId}:{#accountId}:collection/{#DBInstanceId}

请求参数

名称类型必填描述示例值
DBInstanceIdstring

实例 ID。

说明 您可以调用 DescribeDBInstances 接口查看目标地域下所有的 AnalyticDB PostgreSQL 实例的详情,包括实例 ID。
gp-xxxxxxxxx
Collectionstring

集合名。

说明 您可以通过 ListCollections 接口查看列表。
document
Namespacestring

命名空间。

说明 您可以通过 ListNamespaces 查看列表。
mynamespace
NamespacePasswordstring

命名空间对应的密码。

testpassword
Contentstring

用于全文检索的内容。即此值为空时,仅使用向量检索;不为空时,使用向量和全文双路检索。

说明 和 Vector 参数不能同时为空。
hello_world
Filterstring

要查询的数据的过滤条件,格式为 SQL 的 WHERE 格式。是一个返回布尔值(真或假)的表达式,条件可以是简单的比较运算符,如等于(=)、不等于(<>或!=)、大于(>), 小于(<)、大于等于(>=)、小于等于(<=),也可以是逻辑运算符(AND, OR, NOT)组合的更复杂的表达式,以及使用 IN、BETWEEN、LIKE 等关键字的条件。

说明
  • 详细语法可参考:https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/
  • response > 200
    TopKlong

    设置返回 top 结果数量。

    10
    Vectorarray

    向量数据,长度和 CreateCollection 接口的维度一致。

    说明 当 vector 为空时,只返回全文检索结果。
    double

    向量数据。

    1.234
    RegionIdstring

    实例所在地域 ID。

    cn-hangzhou
    Metricsstring

    检索时的相似度算法。取值说明:

    • l2:欧氏距离。
    • ip:点积(内积)距离。
    • cosine:余弦相似度。
    说明 此值为空时,则使用构建索引时指定的算法。
    cosine
    IncludeValuesboolean

    是否返回向量数据。取值说明:

    • true:返回向量数据。
    • false:不返回向量数据,用于全文检索场景。
    true
    HybridSearchstring

    双路召回算法,默认为空(即直接将向量和全文的分数比较并排序)。

    可选值:

    • RRF:倒数排序融合(Reciprocal rank fusion),有一个参数 k 控制融合效果,详见 HybridSearchArgs 配置;
    • Weight:比重排序,采用一个参数 alpha 控制向量和全文的分数比重,然后再排序,参数详见 HybridSearchArgs 配置;
    • Cascaded:先全文检索再在其基础上进行向量检索;
    RRF
    HybridSearchArgsobject

    双路召回的算法参数。目前支持 RRF 和 Weight 两种:

    • RRF:指定计算分数的算法的1/(k+rank_i)中的 k 常数,范围大于 1 的正整数,格式为:
    { 
       "RRF": {
        "k": 60
       }
    }
    
    • Weight: 计算公式alpha * vector_score + (1-alpha) * text_score,参数 alpha 表示向量和全文的检索分数比重,范围为 0~1,其中 0 表示只全文,1 表示只向量:
    { 
       "Weight": {
        "alpha": 0.5
       }
    }
    
    object

    双路召回的参数名。

    any

    参数值。

    { "Weight": { "alpha": 0.5 } }
    OrderBystring

    默认为空,表示排序的依据字段。不支持双路召回场景。

    字段必须属于 metadata 或表里的默认字段比如 id,格式支持:

    • 单个字段,如 chunk_id;
    • 多个字段,用逗号连接,如 block_id, chunk_id;
    • 支持反序,如: block_id DESC, chunk_id DESC;
    chunk_id
    Offsetinteger

    默认为空,表示分页查询时的检索起点。不支持双路召回场景。

    范围必须>=0。当此值不为空时,会返回 Total 表示总的命中数。此参数配合 TopK 使用,比如要分页 20 检索 chunk_id 0~44 的 chunks,则要请求 3 次:

    • Offset=0,TopK=20 返回 chunk_id 0~19
    • Offset=20,TopK=20 返回 chunk_id 20~39
    • Offset=30,TopK=20 返回 chunk_id 40~44
    0
    IncludeMetadataFieldsstring

    默认为空,表示要返回的 metadata 字段,多个字段用逗号分隔。

    title,content
    WorkspaceIdstring

    多数据库实例组成的 Workspace 的 Id。此参数和 DBInstanceId 参数不能同时为空,当和 DBInstanceId 同时指定时以此参数为准。

    gp-ws-*****
    RelationalTableFilterobject

    使用另外一张关系表实现向量数据过滤(类似 Join 的功能)。

    说明 关系表的数据可以通过设置 IncludeMetadataFields 参数返回。比如 rds_table_name.id 表示返回关系表的 id 字段。
    CollectionMetadataFieldstring

    向量集的 Metadata 字段,用来和向量表的字段关联。

    doc_id
    TableFieldstring

    关系表的字段,用来和向量集的 Metadata 的字段做关联。

    id
    TableNamestring

    关系表的名称。

    my_rds_table
    Conditionstring

    关系表的过滤条件。

    tags @> ARRAY['art']

    返回参数

    名称类型描述示例值
    object

    召回结果。

    Matchesarray<object>

    数据列表。

    object

    单条记录。

    Idstring

    向量数据的唯一 ID。

    doca-1234
    Metadataobject

    元数据。

    string

    元数据内容。

    {"title":"test title", "content": "test content"}
    Valuesarray

    向量数据列表。

    double

    向量数据。

    1.234
    Scoredouble

    此条数据的相似度分数,其分数算法和创建索引时指定的算法(l2/ip/cosine)相关。

    0.12345
    RequestIdstring

    请求 ID。

    ABB39CC3-4488-4857-905D-2E4A051D0521
    Statusstring

    状态,取值说明:

    • success:成功。
    • fail:失败。
    success
    Messagestring

    请求失败时的详细信息。

    0.1234
    Totalinteger

    当请求 Offset 不为 0 时才返回,返回值为该检索条件的命中总数。

    100

    示例

    正常返回示例

    JSON格式

    {
      "Matches": {
        "match": [
          {
            "Id": "doca-1234",
            "Metadata": {
              "key": "{\"title\":\"test title\", \"content\":  \"test content\"}"
            },
            "Values": {
              "value": [
                1.234
              ]
            },
            "Score": 0.12345
          }
        ]
      },
      "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
      "Status": "success",
      "Message": "0.1234",
      "Total": 100
    }

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2024-08-28OpenAPI 入参发生变更查看变更详情
    2024-08-04OpenAPI 入参发生变更查看变更详情
    2024-04-29OpenAPI 入参发生变更、OpenAPI 返回结构发生变更查看变更详情
    2024-04-22OpenAPI 入参发生变更查看变更详情
    2023-11-07API 内部配置变更,不影响调用查看变更详情
    2023-08-17OpenAPI 入参发生变更查看变更详情
    2023-08-08OpenAPI 返回结构发生变更查看变更详情
    2023-08-01OpenAPI 返回结构发生变更查看变更详情
    2023-08-01API 内部配置变更,不影响调用查看变更详情