Table Store Java SDK 向量檢索 - Tablestore

前提條件

安裝Tablestore Java SDK並初始化用戶端。SDK 版本需為 5.17.0 或以上。
如需設定 minScore 或 numCandidates，SDK 版本需為 5.17.5 或以上。

功能說明

向量檢索將查詢向量與多元索引 Vector 欄位中的向量進行近似最近鄰（ANN）計算，按建立索引時配置的距離度量演算法為結果評分，並返回最鄰近的資料。與按欄位值匹配的查詢不同，向量檢索根據向量距離判斷資料的相似程度。

調用 search 方法執行向量檢索，並將 query 設定為 KnnVectorQuery。

SearchResponse search(SearchRequest request)

以下樣本在 embedding 欄位中查詢與 [1.0, 0.0, 0.0, 0.0] 最鄰近的 3 行資料，並按相似性得分從高到低返回結果。

String tableName = "example_table";
String indexName = "example_index";
KnnVectorQuery query = new KnnVectorQuery();
query.setFieldName("embedding");
query.setTopK(3);
query.setFloat32QueryVector(new float[]{1.0f, 0.0f, 0.0f, 0.0f});

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(query);
searchQuery.setLimit(3);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getScore() + ": " + hit.getRow());
}

說明

向量欄位數量、向量維度和 topK 存在限制。有關限制，請參見多元索引使用限制。

參數說明

查詢請求

request 的類型為 SearchRequest，包含以下參數。

名稱	類型	說明
tableName（必選）	String	資料表名稱。
indexName（必選）	String	多元索引名稱。
searchQuery（必選）	SearchQuery	查詢條件和通用查詢配置。
columnsToGet（可選）	SearchRequest.ColumnsToGet	返回列配置。未設定時只返回主鍵列。
timeoutInMillisecond（可選）	int	請求級查詢逾時時間，單位為毫秒。預設值為 `-1`，表示不單獨設定查詢逾時時間。
routingValues（可選）	`List<PrimaryKey>`	自訂路由欄位對應的主索引值列表。未配置自訂路由時無需設定。

查詢配置

request.searchQuery 的類型為 SearchQuery，包含以下參數。

名稱	類型	說明
query（必選）	Query	查詢條件。向量檢索設定為 `KnnVectorQuery`。
offset（可選）	Integer	本次查詢的起始位置。
limit（可選）	Integer	本次查詢返回的最大行數。設定為 `0` 時不返回具體行。
highlight（可選）	Highlight	摘要與高亮配置。Vector 欄位本身不支援摘要與高亮。
collapse（可選）	Collapse	結果摺疊配置，用於按指定列對返回結果去重。
sort（可選）	Sort	返回結果的排序方式。設定為 `ScoreSort` 時按得分排序。
trackTotalCount（可選）	int	期望統計的最大匹配行數。預設值為 `TRACK_TOTAL_COUNT_DISABLED`，表示不統計；設定為 `TRACK_TOTAL_COUNT` 時統計全部匹配行。值越小，查詢效能越高。
filter（可選）	SearchFilter	對 `query` 的查詢結果進行過濾。
aggregationList（可選）	`List<Aggregation>`	統計彙總配置。
groupByList（可選）	`List<GroupBy>`	分組配置。
token（可選）	byte[]	翻頁憑證。將上一次響應的 `nextToken` 設定為該參數可繼續讀取後續資料。服務端每個索引分割區會返回各自最鄰近的 `topK` 個值並在協調節點匯總，因此使用 `token` 翻頁時，累計返回行數與服務端索引分割區數有關。

向量查詢條件

request.searchQuery.query 的類型為 KnnVectorQuery，包含以下參數。

名稱	類型	說明
fieldName（必選）	String	向量欄位名稱。欄位類型必須為 Vector，查詢向量維度必須與建立多元索引時配置的欄位維度相同。
topK（必選）	Integer	要查詢的最鄰近向量數量，最大值為 `1000`。值越大，返回的候選越多，召回率可能提高，但查詢延遲和費用也可能增加。
float32QueryVector（必選）	float[]	用於計算相似性的 Float32 查詢向量。數組長度必須與向量欄位維度相同。
filter（可選）	Query	向量檢索結果必須同時滿足的非向量查詢條件。支援組合多個非向量 `Query`。
weight（可選）	Float	向量查詢的相關性權重，必須大於或等於 `0`，預設值為 `1.0`。值越大，向量查詢得分對最終相關性得分的貢獻越高，不改變匹配範圍。
minScore（可選）	Float	最小得分閾值，必須大於或等於 `0`，預設值為 `0`。僅返回得分嚴格大於該值的資料。
numCandidates（可選）	Integer	每個索引分割區計算近鄰時訪問的候選數量，取值範圍為 `[topK, 1000]`。值越大，召回率可能提高，但查詢耗時也可能增加。

返回列

request.columnsToGet 的類型為 SearchRequest.ColumnsToGet，包含以下參數。

名稱	類型	說明
columns（可選）	`List<String>`	要返回的屬性列名稱。僅 `returnAll` 和 `returnAllFromIndex` 均為 `false` 時需要設定；未設定時只返回主鍵列。
returnAll（可選）	boolean	是否返回資料表中的全部屬性列。預設值為 `false`。
returnAllFromIndex（可選）	boolean	是否返回已建立索引的全部屬性列。預設值為 `false`。不能與 `returnAll` 同時設定為 `true`。

傳回值

查詢響應

search 方法返回 SearchResponse。核心欄位如下。

名稱	類型	說明
totalCount	long	匹配行數，通過 `getTotalCount()` 擷取。傳回值取決於 `trackTotalCount` 配置。
rows	`List<Row>`	本次查詢返回的行資料，通過 `getRows()` 擷取。返回數量不超過 `limit`。
searchHits	`List<SearchHit>`	查詢命中結果，通過 `getSearchHits()` 擷取。可從該欄位讀取命中行及其得分。
nextToken	byte[]	下一頁憑證，通過 `getNextToken()` 擷取。值不為 `null` 時，將其設定到下一次請求的 `token` 中繼續讀取。
isAllSuccess	boolean	是否已成功查詢全部索引分割區，通過 `isAllSuccess()` 擷取。值為 `false` 時，返回的是部分結果，`totalCount` 可能小於實際匹配行數。

查詢命中

response.searchHits[] 的類型為 SearchHit，包含以下核心欄位。

名稱	類型	說明
row	Row	命中的行資料，通過 `getRow()` 擷取。
score	Double	向量查詢得分，通過 `getScore()` 擷取。距離度量演算法和 `weight` 會影響該值。

情境樣本

按非向量條件和最小得分過濾

設定 filter 要求近鄰資料同時滿足非向量查詢條件，並通過 minScore 排除得分不高於閾值的資料。以下樣本只返回 category 等於 book、price 小於 4 且向量得分大於 0.6 的資料。

KnnVectorQuery filteredQuery = new KnnVectorQuery();
filteredQuery.setFieldName("embedding");
filteredQuery.setTopK(10);
filteredQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
filteredQuery.setMinScore(0.6f);
filteredQuery.setFilter(QueryBuilders.bool()
        .must(QueryBuilders.term("category", "book"))
        .must(QueryBuilders.range("price").lessThan(4)));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(filteredQuery);
searchQuery.setLimit(10);

調整候選數量

設定 numCandidates 可擴大每個索引分割區計算近鄰時訪問的候選範圍。以下樣本從 4 個候選中查詢最鄰近的 3 個向量。

KnnVectorQuery candidateQuery = new KnnVectorQuery();
candidateQuery.setFieldName("embedding");
candidateQuery.setTopK(3);
candidateQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
candidateQuery.setNumCandidates(4);

SearchQuery candidateSearchQuery = new SearchQuery();
candidateSearchQuery.setQuery(candidateQuery);
candidateSearchQuery.setLimit(3);

Tablestore：向量檢索