search

最近更新时间：2023-12-08 16:15:49

我的收藏

本页目录：

功能介绍
基于相似度匹配的查询方式，/document/search 接口用于查找与给定查询向量相似的向量。
支持根据指定 id 或向量数值进行相似度检索，返回指定的 Top K 个最相似的 Document。
支持根据主键 id（Document ID）或向量数值，搭配自定义的标量字段的 Filter 表达式一并进行相似度检索。
配置 Embedding 参数，支持输入原始文本检索与输入文本相似的文档，同时，支持搭配标量字段的 Filter 表达式一并检索。
接口约束
该接口支持根据主键 id（Document ID）、向量 vector 以及文本进行检索。id、vector、文本仅需指定其中一个即可，若同时指定，或者指定其中两项，将提示如下信息。The?search?condition?must?be?one?of?the?[documentIds,?vectors,?retrieves]
请求示例
注意：
如下示例可直接复制，在 CVM 运行之前，您需在文本编辑器将 api_key=A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X 依据实际情况进行替换。 
根据文本进行向量检索
根据 id（Document ID）进行向量检索
根据 Vector 进行向量检索
如果使用腾讯云向量数据库（Tencent?Cloud?VectorDB）的 Embedding 功能，基于 /document/upsert 写入的原始文本，在集合 book-emb 中，使用 /document/search 接口查询与输入文本'天下大势，分久必合，合久必分'最相似，且满足过滤条件的 Top3 数据。因写入文本数据为高维数据，不便于显示，则设置 retrieveVector 参数为 false，检索信息不显示向量数据。
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/document/search \\
  -d '{
    "database": "db-test",
    "collection": "book-emb",
    "search": {
        "embeddingItems": [
            "天下大势，分久必合，合久必分"
        ],
        "limit": 3,
        "params": {
            "ef": 200
        },
        "retrieveVector": false,
        "filter": "bookName in (\\"三国演义\\",\\"西游记\\")",
        "outputFields": [
            "id",
            "author",
            "text",
            "bookName"
        ]
    }
}'
检索信息如下所示。具体返回参数含义，请参见 返回参数。
说明：
返回 Top K 条相似度计算的结果。其中，K为 limit 设置的数值，如果检索的数据不足 K 条，则返回实际检索的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列，相似度最高的结果会排在最前面，相似度最低的结果则排在最后面。相似程度则通过 L2（欧几里得距离）、IP（内积）或 COSINE（余弦相似度）计算得出的分数来衡量，输出参数 score 表示相似性计算分数。其中，欧式距离（L2）计算所得的分数越小与搜索值越相似；而余弦相似度（COSINE）与 内积（IP） 计算所得的分数越大与搜索值越相似。
{
    "code": 0,
    "msg": "operation success",
    "documents": [
        [
            {
                "id": "0001",
                "score": 0.9792741537094116,
                "bookName": "三国演义",
                "author": "罗贯中",
                "text": "话说天下大势，分久必合，合久必分。"
            },
            {
                "id": "0002",
                "score": 0.7909858226776123,
                "bookName": "西游记",
                "author": "吴承恩",
                "text": "混沌未分天地乱，茫茫渺渺无人间。"
            }
        ]
    ]
}
基于 /document/upsert 写入的向量数据，使用 /document/search 接口在集合 book-vector 中，查询与  id（Document ID）为 0001、 0002、0003 最相似，且满足过滤条件的 Top3 数据。
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/document/search \\
  -d '{
    "database": "db-test",
    "collection": "book-vector",
    "search": {
        "documentIds": [
            "0001",
            "0002",
            "0003"
        ],
        "params": {
            "ef": 200
        },
        "retrieveVector": true,
        "filter": "bookName in (\\"三国演义\\",\\"西游记\\")",
        "limit": 3
    }
}'
检索信息，如下所示。具体返回参数含义，请参见 返回参数。
说明：
每一个查询结果都返回 TopK 条相似度计算的结果。其中，K 为 limit 设置的数值，如果检索的数据不足 K 条，则返回实际的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列，相似度最高的结果会排在最前面，相似度最低的结果则排在最后面。相似程度则通过 L2（欧几里得距离）、IP（内积）或 COSINE（余弦相似度）计算得出的分数来衡量，输出参数 score 表示相似性计算分数。其中，欧式距离（L2）计算所得的分数越小与搜索值越相似；而余弦相似度（COSINE）与 内积（IP） 计算所得的分数越大与搜索值越相似。
{
    "code": 0,
    "msg": "operation success",
    "documents": [
        [
            {
                "id": "0001",
                "vector": [
                    0.21230000257492066,
                    0.23000000417232514,
                    0.21299999952316285
                ],
                "score": 1.0000001192092896,
                "author": "罗贯中",
                "bookName": "三国演义",
                "page": 21
            },
            {
                "id": "0002",
                "vector": [
                    0.21230000257492066,
                    0.2199999988079071,
                    0.21299999952316285
                ],
                "score": 0.9997729659080505,
                "bookName": "西游记",
                "author": "吴承恩",
                "page": 22
            }
        ],
        [
            {
                "id": "0002",
                "vector": [
                    0.21230000257492066,
                    0.2199999988079071,
                    0.21299999952316285
                ],
                "score": 1.000000238418579,
                "author": "吴承恩",
                "page": 22,
                "bookName": "西游记"
            },
            {
                "id": "0001",
                "vector": [
                    0.21230000257492066,
                    0.23000000417232514,
                    0.21299999952316285
                ],
                "score": 0.9997729659080505,
                "bookName": "三国演义",
                "author": "罗贯中",
                "page": 21
            }
        ],
        [
            {
                "id": "0002",
                "vector": [
                    0.21230000257492066,
                    0.2199999988079071,
                    0.21299999952316285
                ],
                "score": 0.9997580051422119,
                "author": "吴承恩",
                "bookName": "西游记",
                "page": 22
            },
            {
                "id": "0001",
                "vector": [
                    0.21230000257492066,
                    0.23000000417232514,
                    0.21299999952316285
                ],
                "score": 0.9990617632865906,
                "page": 21,
                "bookName": "三国演义",
                "author": "罗贯中"
            }
        ]
    ]
}
基于 /document/upsert 写入的向量数据，则可使用 /document/search 接口，在集合 book-vector 中，根据指定向量以及过滤条件，查找 Top 3 个相似性结果。
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/document/search \\
  -d '{
    "database": "db-test",
    "collection": "book-vector",
    "search": {
        "vectors": [
            [
                0.3123,
                0.43,
                0.213
            ]
        ],
        "params": {
            "ef": 200
        },
        "filter": "bookName in (\\"三国演义\\",\\"西游记\\")",
        "retrieveVector": true,
        "limit": 3
    }
}'
检索信息如下所示。具体返回参数含义，请参见 返回参数。
说明：
返回 Top K 条相似度计算的结果。其中，K为 limit 设置的数值，如果检索的数据不足 K 条，则返回实际检索的 Document 数量。
检索结果会按照与查询向量的相似程度进行排列，相似度最高的结果会排在最前面，相似度最低的结果则排在最后面。相似程度则通过 L2（欧几里得距离）、IP（内积）或 COSINE（余弦相似度）计算得出的分数来衡量，输出参数 score 表示相似性计算分数。其中，欧式距离（L2）计算所得的分数越小与搜索值越相似；而余弦相似度（COSINE）与 内积（IP） 计算所得的分数越大与搜索值越相似。
{
    "code": 0,
    "msg": "operation success",
    "documents": [
        [
            {
                "id": "0001",
                "vector": [
                    0.21230000257492066,
                    0.23000000417232514,
                    0.21299999952316285
                ],
                "score": 0.9714228510856628,
                "page": 21,
                "author": "罗贯中",
                "bookName": "三国演义"
            },
            {
                "id": "0002",
                "vector": [
                    0.21230000257492066,
                    0.2199999988079071,
                    0.21299999952316285
                ],
                "score": 0.9668837785720825,
                "bookName": "西游记",
                "author": "吴承恩",
                "page": 22
            }
        ]
    ]
}
请求参数
参数名称
参数含义
子参数
是否必选
配置方法及要求
database
指定要查询的Database 名称。
-
是
使用 /database/list 获取集群中的数据库列表，复制需查询数据的集合所属的数据库名。
collection
指定要查询的Collection 名称。
-
是
使用 /collection/list 获取指定数据库名下的 Collection 列表，复制需查询数据的集合名。
readConsistency
设置检索数据的一致性要求。
-
否
取值如下所示：
strongConsistency：强一致性。
eventualConsistency：最终一致性。
search

表示查询条件。

vectors
否
表示要查询的向量列表。
数组元素数量最大为20。
vectors 与 documentIds 两个字段，只需配置其中一个即可。
?
?
documentIds
否
待查询的文档 ID 列表。数组元素数量最大为20。
注意：
vectors 、 documentIds、embeddingItems 三个字段，只需配置其中一个即可。这三个字段任何一个可以结合 filter 字段进行混合检索。
?
?
?

embeddingItems
否
输入文本信息，用于检索与该文本信息相似的数据。
类型：字符串数组。
范围：数组元素最大批量为20 。
?
?
params
否
索引类型不同，检索时，所需配置的参数不同。
FLAT ：无需指定参数。
HNSW 类型：需配置参数 ef，指定需要访问向量的数目。取值范围[1,32768]，默认为10。
IVF 系列：需设置参数 nprobe ，指定所需查询的单位数量。取值范围[1,nlist]，其中 nlist 在创建 Collection 时已设置，可通过/collection/list 查看。
?
?
filter
否
使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 表达式格式为 <field_name><operator><value>，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见 混合检索。其中： 
<field_name>：表示要过滤的字段名。
<operator>：表示要使用的运算符。
string ：匹配单个字符串值（=）、排除单个字符串值（!=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。
uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）。例如：expired_time > 1623388524。
array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。
<value>：表示要匹配的值。
示例：Filter('author="jerry"').And('page>20')
?
?
retrieveVector
否
标识是否需要返回检索结果的向量值。
true：需要。
false：不需要。默认为 false。
?
?
limit
否
指定返回最相似的 Top K 的 K 的值。
?
?
outputFields
否
指定需要输出的字段。若不设置，将返回所有字段。
说明：
retrieveVector 和 outputFields 只要有其中一个配置输出向量字段即可输出 vector。
?
响应消息
HTTP 响应消息体是服务器返回给客户端的数据，通常包含了请求的结果或者所请求的资源。/document/search 接口返回的状态码以及相关信息，如下所示。
状态码
状态码
含义
响应消息
200
查询数据成功
返回信息，请参见 请求示例。具体参数含义，请参见 返回参数。
400
查询数据失败
{
  "code": 400,
  "msg": "operation failed, reason...."
}
返回参数
参数名
参数含义
id
Document 的 ID 信息。
vector
Document 的向量值。
score
表示查询向量与检索结果向量之间的相似性计算分数。
text
如果该 Collection 开启 Embedding 功能，在建表时，指定文本信息的字段名，则显示该字段。
other_scalar_field
Document 其他自定义的标量字段。例如：author、bookName、page等
?

上一篇: query 下一篇: delete

参数名称	参数含义	子参数	是否必选	配置方法及要求
database	指定要查询的Database 名称。	-	是	使用 /database/list 获取集群中的数据库列表，复制需查询数据的集合所属的数据库名。
collection	指定要查询的Collection 名称。	-	是	使用 /collection/list 获取指定数据库名下的 Collection 列表，复制需查询数据的集合名。
readConsistency	设置检索数据的一致性要求。	-	否	取值如下所示： strongConsistency：强一致性。 eventualConsistency：最终一致性。
search	表示查询条件。	vectors	否	表示要查询的向量列表。数组元素数量最大为20。 vectors 与 documentIds 两个字段，只需配置其中一个即可。
		?	?	documentIds	否	待查询的文档 ID 列表。数组元素数量最大为20。注意： vectors 、 documentIds、embeddingItems 三个字段，只需配置其中一个即可。这三个字段任何一个可以结合 filter 字段进行混合检索。 ?
		?	?	embeddingItems	否	输入文本信息，用于检索与该文本信息相似的数据。类型：字符串数组。范围：数组元素最大批量为20 。
		?	?	params	否	索引类型不同，检索时，所需配置的参数不同。 FLAT ：无需指定参数。 HNSW 类型：需配置参数 ef，指定需要访问向量的数目。取值范围[1,32768]，默认为10。 IVF 系列：需设置参数 nprobe ，指定所需查询的单位数量。取值范围[1,nlist]，其中 nlist 在创建 Collection 时已设置，可通过/collection/list 查看。
		?	?	filter	否	使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 表达式格式为 <field_name><operator><value>，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息，请参见混合检索。其中： <field_name>：表示要过滤的字段名。 <operator>：表示要使用的运算符。 string ：匹配单个字符串值（=）、排除单个字符串值（!=）、匹配任意一个字符串值（in）、排除所有字符串值（not in）。其对应的 Value 必须使用英文双引号括起来。 uint64：大于（>）、大于等于（>=）、等于（=）、小于（<）、小于等于（<=）。例如：expired_time > 1623388524。 array：数组类型，包含数组元素之一（include）、排除数组元素之一（exclude）、全包含数组元素（include all）。例如，name include (\\"Bob\\", \\"Jack\\")。 <value>：表示要匹配的值。示例：`Filter('author="jerry"').And('page>20')`
		?	?	retrieveVector	否	标识是否需要返回检索结果的向量值。 true：需要。 false：不需要。默认为 false。
		?	?	limit	否	指定返回最相似的 Top K 的 K 的值。
		?	?	outputFields	否	指定需要输出的字段。若不设置，将返回所有字段。说明： retrieveVector 和 outputFields 只要有其中一个配置输出向量字段即可输出 vector。 ?

状态码	含义	响应消息
200	查询数据成功	返回信息，请参见请求示例。具体参数含义，请参见返回参数。
400	查询数据失败	{ "code": 400, "msg": "operation failed, reason...." }

参数名	参数含义
id	Document 的 ID 信息。
vector	Document 的向量值。
score	表示查询向量与检索结果向量之间的相似性计算分数。
text	如果该 Collection 开启 Embedding 功能，在建表时，指定文本信息的字段名，则显示该字段。
other_scalar_field	Document 其他自定义的标量字段。例如：author、bookName、page等