本文介绍如何通过Java SDK在Collection中进行相似性检索。
前提条件
已创建Cluster:创建Cluster。
已获得API-KEY:API-KEY管理。
已安装最新版SDK:安装DashVector SDK。
接口定义
// class DashVectorCollection
// 同步接口
public Response<List<Doc>> query(QueryDocRequest queryDocRequest);
// 异步接口
public ListenableFuture<Response<List<Doc>>> queryAsync(QueryDocRequest queryDocRequest);
使用示例
需要使用您的api-key替换示例中的YOUR_API_KEY、您的Cluster Endpoint替换示例中的YOUR_CLUSTER_ENDPOINT,代码才能正常运行。
本示例需要参考新建Collection-使用示例提前创建好名称为
quickstart
的Collection,并参考插入Doc提前插入部分数据。
根据向量进行相似性检索
import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorCollection;
import com.aliyun.dashvector.common.DashVectorException;
import com.aliyun.dashvector.models.Doc;
import com.aliyun.dashvector.models.Vector;
import com.aliyun.dashvector.models.requests.QueryDocRequest;
import com.aliyun.dashvector.models.responses.Response;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void main(String[] args) throws DashVectorException {
DashVectorClient client = new DashVectorClient("YOUR_API_KEY", "YOUR_CLUSTER_ENDPOINT");
DashVectorCollection collection = client.get("quickstart");
// 构建Vector
Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
// 构建QueryDocRequest
QueryDocRequest request = QueryDocRequest.builder()
.vector(vector)
.topk(100)
.includeVector(true)
.build();
// 进行Doc检索
Response<List<Doc>> response = collection.query(request);
// 判断请求是否成功
// assert response.isSuccess()
System.out.println(response);
// example output:
// {
// "code":0,
// "message":"Success",
// "requestId":"b26ce0b8-0caf-4836-8136-df889d79ae91",
// "output":[
// {
// "id":"1",
// "vector":{
// "value":[
// 0.10000000149011612,
// 0.20000000298023224,
// 0.30000001192092896,
// 0.4000000059604645
// ]
// },
// "fields":{
// "name":"zhangsan",
// "age":20,
// "weight":100.0,
// "anykey1":"String",
// "anykey2":1,
// "anykey3":true,
// "anykey4":3.1415926
// },
// "score":1.1920929E-7
// }
// ]
// }
}
}
根据主键(对应的向量)进行相似性检索
// 构建QueryDocRequest
QueryDocRequest request = QueryDocRequest.builder()
.id("1")
.topk(100)
.outputFields(Arrays.asList("name", "age")) // 仅返回name、age这2个Field
.includeVector(true)
.build();
// 根据主键(对应的向量)进行相似性检索
Response<List<Doc>> response = collection.query(request);
// 判断检索是否成功
assert response.isSuccess()
带过滤条件的相似性检索
Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
// 构建QueryDocRequest
QueryDocRequest request = QueryDocRequest.builder()
.vector(vector) // 向量检索,也可设置主键检索
.topk(100)
.filter("age > 18") // 条件过滤,仅对age > 18的Doc进行相似性检索
.outputFields(Arrays.asList("name", "age")) // 仅返回name、age这2个Field
.includeVector(true)
.build();
// 根据向量或者主键进行相似性检索 + 条件过滤
Response<List<Doc>> response = collection.query(request);
// 判断检索是否成功
assert response.isSuccess()
带有Sparse Vector的向量检索
Sparse Vector(稀疏向量)可用于关键词权重表示,实现带关键词感知能力的向量检索。
Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
// 构建带有Sparse Vector的QueryDocRequest
QueryDocRequest request = QueryDocRequest.builder()
.vector(vector) // 向量检索
.sparseVector(
new Map<Integer, Float>() {
{
put(1, 0.4f);
put(10000, 0.6f);
put(222222, 0.8f);
}
}) // 稀疏向量
.build();
// 根据向量进行相似性检索 + 稀疏向量
Response<List<Doc>> response = collection.query(request);
// 判断检索是否成功
assert response.isSuccess()
通过过滤条件进行匹配查询
// 构建只携带过滤条件,不包含主键或向量的QueryDocRequest
QueryDocRequest request = QueryDocRequest.builder()
.topk(100)
.filter("age > 18") // 条件过滤,仅对age > 18的Doc进行相似性检索
.outputFields(Arrays.asList("name", "age")) // 仅返回name、age这2个Field
.includeVector(true)
.build();
// 支持向量和主键都不传入,那么只进行条件过滤
Response<List<Doc>> response = collection.query(request);
// 判断检索是否成功
assert response.isSuccess()
入参描述
可通过QueryDocRequestBuilder
构造QueryDocRequest
对象,其可用方法如下表所示:
vector
和id
两个入参需要二选一使用,如都不传入,则仅完成条件过滤。
方法 | 必填 | 默认值 | 描述 |
vector(Vector vector) | 否 | - | 向量数据 |
sparseVector(Map(Integer, Float)) | 否 | - | 稀疏向量 |
id(String id) | 否 | - | 主键,表示根据主键对应的向量进行相似性检索 |
topk(int topk) | 否 | 10 | 返回topk相似性结果 |
filter(String filter) | 否 | - | 过滤条件,需满足SQL where子句规范,详见 |
includeVector(bool includeVector) | 否 | false | 是否返回向量数据 |
partition(String partition) | 否 | default | 分区名称 |
outputFields(List<String> outputFields) | 否 | - | 返回文档字段列表,默认返回所有文档字段 |
outputField(String field) | 否 | - | |
build() | - | - | 构造 |
出参描述
返回结果为Response<List<Doc>>
对象,Response<List<Doc>>
对象中可获取本次操作结果信息,如下表所示。
方法 | 返回类型 | 描述 | 示例 |
getCode() | int | 返回值,参考返回状态码说明 | 0 |
getMessage() | String | 返回消息 | success |
getRequestId() | String | 请求唯一id | 19215409-ea66-4db9-8764-26ce2eb5bb99 |
getOutput() | List<Doc> | 返回相似性检索结果, Doc 参见Doc |
|
getUsage() | 对Serverless实例(按量付费)集合的Doc检索请求,成功后返回实际消耗的读请求单元数 | ||
isSuccess() | Boolean | 判断请求是否成功 | true |