本文介绍如何通过HTTP API在Collection中进行相似性检索。
前提条件
Method与URL
HTTP
POST https://{Endpoint}/v1/collections/{CollectionName}/query使用示例
说明
-
需要使用您的api-key替换示例中的YOUR_API_KEY、您的Cluster Endpoint替换示例中的YOUR_CLUSTER_ENDPOINT，代码才能正常运行。
-
本示例需要参考新建Collection-使用示例提前创建好名称为
quickstart的Collection
根据向量进行相似性检索
Bash
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vector": [0.1, 0.2, 0.3, 0.4],
"topk": 10,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query
# example output:
# {
# "code": 0,
# "request_id": "2cd1cac7-f1ee-4d15-82a8-b65e75d8fd13",
# "message": "Success",
# "output": [
# {
# "id": "1",
# "vector":[
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ],
# "fields": {
# "name": "zhangshan",
# "weight": null,
# "age": 20,
# "anykey": "anyvalue"
# },
# "score": 0.3
# }
# ]
# }根据主键（对应的向量）进行相似性检索
Bash
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"id": "1",
"topk": 1,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query
# example output:
# {
# "code":0,
# "request_id":"fab4e8a2-15e4-4b55-816f-3b66b7a44962",
# "message":"Success",
# "output":[
# {
# "id":"1",
# "vector":[
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ],
# "fields": {
# "name": "zhangshan",
# "weight": null,
# "age": 20,
# "anykey": "anyvalue"
# },
# "score": 0.3
# }
# ]
# }带过滤条件的相似性检索
Bash
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"filter": "age > 18",
"topk": 1,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query
# example output:
# {
# "code":0,
# "request_id":"4c7331d8-fba1-4c3a-8673-124568670de7",
# "message":"Success",
# "output":[
# {
# "id":"1",
# "vector":[
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ],
# "fields": {
# "name": "zhangshan",
# "weight": null,
# "age": 20,
# "anykey": "anyvalue"
# },
# "score": 0.0
# }
# ]
# }带有Sparse Vector的向量检索
Bash
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vector": [0.1, 0.2, 0.3, 0.4],
"sparse_vector":{"1":0.4, "10000":0.6, "222222":0.8},
"topk": 1,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query
# example output:
# {
# "code":0,
# "request_id":"ad84f7a0-b4b2-4023-ae80-b6f092609a53",
# "message":"Success",
# "output":[
# {
# "id":"2",
# "vector":[
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ],
# "fields":{"name":null,"weight":null,"age":null},
# "score":1.46,
# "sparse_vector":{
# "10000":0.6,
# "1":0.4,
# "222222":0.8
# }
# }
# ]
# }向量检索高级参数
说明
详情可参考 向量检索高级参数。
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vector": [0.1, 0.2, 0.3, 0.4],
"vector_param":{ "radius": 0.53, "is_linear": false, "ef": 1000 },
"topk": 10,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart_euclidean/query
#example output:
#{
# "code": 0,
# "request_id": "59df860b-7d29-466b-a345-0bfe9e27329e",
# "message": "Success",
# "output": [
# {
# "id": "2",
# "vector": [
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645,
# 0.5
# ],
# "fields": {
# "anykey1": "str-value",
# "anykey2": 1,
# "name": "zhangshan",
# "weight": null,
# "anykey3": true,
# "anykey4": 3.1415925,
# "age": 70
# },
# "score": 0.04
# },
# {
# "id": "3",
# "vector": [
# 0.30000001192092896,
# 0.4000000059604645,
# 0.5,
# 0.6000000238418579
# ],
# "fields": {
# "name": null,
# "weight": null,
# "age": null
# },
# "score": 0.16000001
# },
# {
# "id": "4",
# "vector": [
# 0.4000000059604645,
# 0.5,
# 0.6000000238418579,
# 0.699999988079071
# ],
# "fields": {
# "name": "zhangsan",
# "weight": null,
# "age": 20
# },
# "score": 0.36
# }
# ]
#}多向量检索
说明
详情可参考 多向量检索。
RrfRanker示例
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vectors": {"title": {"vector": [0.1, 0.2, 0.3, 0.4]}, "content": {"vector": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6], "param": {"num_candidates": 10}}},
"topk": 20,
"rerank": {"ranker_name": "rrf", "ranker_params": {"rank_constant":"100"} }
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/multi_vector_demo/query
# example output:
#{
# "code": 0,
# "request_id": "db20ba2b-9dc6-4c23-9266-430e6fb1a70d",
# "message": "Success",
# "output": [
# {
# "id": "1",
# "fields": {
# "author": null
# },
# "score": 0.019704912
# },
# {
# "id": "2",
# "fields": {
# "author": "zhangsan"
# },
# "score": 0.00990099
# },
# {
# "id": "3",
# "fields": {
# "author": null,
# "anykey": "anyvalue"
# },
# "score": 0.009803922
# }
# ]
#}WeightedRanker示例
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vectors": {"title": {"vector": [0.1, 0.2, 0.3, 0.4]}, "content": {"vector": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6], "param": {"num_candidates": 10}}},
"topk": 20,
"rerank": {"ranker_name": "weighted", "ranker_params": {"weights": "{\"title\":0.2, \"content\":0.8}" }}
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/multi_vector_demo/query
# example output:
#{
# "code": 0,
# "request_id": "c7413fa9-92fd-4493-8f21-6c65c83e7b91",
# "message": "Success",
# "output": [
# {
# "id": "1",
# "fields": {
# "author": null
# },
# "score": 0.8156271
# },
# {
# "id": "3",
# "fields": {
# "author": null,
# "anykey": "anyvalue"
# },
# "score": 0.5880098
# },
# {
# "id": "2",
# "fields": {
# "author": "zhangsan"
# },
# "score": 0.2
# }
# ]
#}使用多向量的一个向量执行检索
curl -XPOST \
-H 'dashvector-auth-token: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vectors": {"title": {"vector": [0.1, 0.2, 0.3, 0.4], "param":{ "radius": 0.1, "is_linear": true, "ef": 1000 }}},
"topk": 20,
"include_vector": true
}' https://YOUR_CLUSTER_ENDPOINT/v1/collections/multi_vector_demo/query
# example output:
#{
# "code": 0,
# "request_id": "b9bc3d5a-8edf-4d5b-916d-0ced6ae570cb",
# "message": "Success",
# "output": [
# {
# "id": "4",
# "vectors": {
# "title": [
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ]
# },
# "fields": {
# "author": "zhangsan"
# },
# "score": 0.0
# },
# {
# "id": "2",
# "vectors": {
# "title": [
# 0.10000000149011612,
# 0.20000000298023224,
# 0.30000001192092896,
# 0.4000000059604645
# ]
# },
# "fields": {
# "author": "zhangsan"
# },
# "score": 0.0
# }
# ]
#}入参描述
说明
vector和id两个入参需要二选一使用，如都不传入，则仅完成条件过滤。
|-----------------------|--------------|--------|--------|--------------------------------------------------------------------------------------------------------------------------|
| 参数 | Location | 类型 | 必填 | 说明 |
| {Endpoint} | path | str | 是 | Cluster的Endpoint，可在控制台Cluster详情中查看 |
| {CollectionName} | path | str | 是 | Collection名称 |
| dashvector-auth-token | header | str | 是 | api-key |
| vector | body | array | 否 | 向量数据 |
| sparse_vector | body | dict | 否 | 稀疏向量 |
| id | body | str | 否 | 主键，表示根据主键对应的向量进行相似性检索 |
| topk | body | int | 否 | 返回topk相似性结果，默认10 |
| filter | body | str | 否 | 过滤条件，需满足SQL where子句规范，详见条件过滤检索 |
| include_vector | body | bool | 否 | 是否返回向量数据，默认false |
| output_fields | body | array | 否 | 返回field的字段名列表，默认返回所有Fields |
| partition | body | str | 否 | Partition名称 |
| vectors | body | dict | 否 | 多个向量检索，类型为Map<String, VectorQuery>，详情参考多向量检索 |
| rerank | body | dict | 否 | 融合排序参数，详情参考多向量检索 |
| vector_param | body | dict | 否 | 高级检索参数，详情参考 向量检索高级参数 |
出参描述
|------------|--------|-----------------------------------------------------------------------------------|--------------------------------------|
| 字段 | 类型 | 描述 | 示例 |
| code | int | 返回值，参考返回状态码说明 | 0 |
| message | str | 返回消息 | success |
| request_id | str | 请求唯一id | 19215409-ea66-4db9-8764-26ce2eb5bb99 |
| output | array | 相似性检索结果，Doc列表 | |
| usage | map | 对Serverless实例（按量付费）集合的Doc检索请求，成功后返回实际消耗的读请求单元数 | { Usage: { read_units: 8 } } |