範囲検索
範囲検索は、返されるエンティティの距離またはスコアを特定の範囲内に制限することで、検索結果の関連性を高めます。このページでは、範囲検索とは何か、および範囲検索を実行する手順について説明します。
概要
範囲検索リクエストを実行するとき、Zilliz Cloud は ANN 検索結果からクエリベクトルに最も類似するベクトルを中心とし、検索リクエストで指定した radius を外側の円の半径、range_filter を内側の円の半径として、2 つの同心円を描きます。この 2 つの同心円によって形成される環状領域内に類似度スコアが収まるすべてのベクトルが返されます。ここで、range_filter を 0 に設定すると、指定した類似度スコア(radius)内のすべてのエンティティが返されることを示します。

上の図は、範囲検索リクエストに radius と range_filter の 2 つのパラメーターが含まれていることを示しています。範囲検索リクエストを受信すると、Zilliz Cloud は次の処理を行います。
-
指定したメトリクスタイプ(COSINE)を使用して、クエリベクトルに最も類似するすべてのベクトル埋め込みを検索します。
-
クエリベクトルに対する distances または scores が、radius および range_filter パラメーターで指定された範囲内に収まるベクトル埋め込みをフィルタリングします。
-
フィルタリングされたエンティティから top-K のエンティティを返します。
radius と range_filter の設定方法は、検索のメトリクスタイプによって異なります。次の表に、メトリクスタイプごとにこれら 2 つのパラメーターを設定する際の要件を示します。
メトリクスタイプ | 表記 | radius と range_filter を設定するための要件 |
|---|---|---|
| L2 距離が小さいほど、類似度が高いことを示します。 | 最も類似するベクトル埋め込みを無視するには、次の条件を満たす必要があります。
|
| IP 距離が大きいほど、類似度が高いことを示します。 | 最も類似するベクトル埋め込みを無視するには、次の条件を満たす必要があります。
|
| COSINE 距離が大きいほど、類似度が高いことを示します。 | 最も類似するベクトル埋め込みを無視するには、次の条件を満たす必要があります。
|
| Jaccard 距離が小さいほど、類似度が高いことを示します。 | 最も類似するベクトル埋め込みを無視するには、次の条件を満たす必要があります。
|
| Hamming 距離が小さいほど、類似度が高いことを示します。 | 最も類似するベクトル埋め込みを無視するには、次の条件を満たす必要があります。
|
例
このセクションでは、範囲検索を実行する方法を説明します。次のコードスニペットの検索リクエストにはメトリクスタイプが含まれていないため、デフォルトのメトリクスタイプ COSINE が適用されます。この場合、radius の値が range_filter の値より小さくなるようにしてください。
次のコードスニペットでは、radius を 0.4、range_filter を 0.6 に設定して、Zilliz Cloud がクエリベクトルに対する距離またはスコアが 0.4 から 0.6 の範囲内に収まるすべてのエンティティを返すようにします。
- Python
- Java
- Go
- Rust
- C++
- NodeJS
- CSharp
- cURL
- Zilliz CLI
from pymilvus import MilvusClient
client = MilvusClient(
uri="YOUR_CLUSTER_ENDPOINT",
token="YOUR_CLUSTER_TOKEN"
)
query_vector = [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592]
res = client.search(
collection_name="my_collection",
data=[query_vector],
limit=3,
search_params={
"params": {
"radius": 0.4,
"range_filter": 0.6
}
}
)
for hits in res:
print("TopK results:")
for hit in hits:
print(hit)
import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.vector.request.SearchReq;
import io.milvus.v2.service.vector.request.data.FloatVec;
import io.milvus.v2.service.vector.response.SearchResp;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
.uri("YOUR_CLUSTER_ENDPOINT")
.token("YOUR_CLUSTER_TOKEN")
.build());
FloatVec queryVector = new FloatVec(new float[]{0.3580376395471989f, -0.6023495712049978f, 0.18414012509913835f, -0.26286205330961354f, 0.9029438446296592f});
Map<String,Object> extraParams = new HashMap<>();
extraParams.put("radius", 0.4);
extraParams.put("range_filter", 0.6);
SearchReq searchReq = SearchReq.builder()
.collectionName("my_collection")
.data(Collections.singletonList(queryVector))
.topK(5)
.searchParams(extraParams)
.build();
SearchResp searchResp = client.search(searchReq);
List<List<SearchResp.SearchResult>> searchResults = searchResp.getSearchResults();
for (List<SearchResp.SearchResult> results : searchResults) {
System.out.println("TopK results:");
for (SearchResp.SearchResult result : results) {
System.out.println(result);
}
}
// Output
// TopK results:
// SearchResp.SearchResult(entity={}, score=0.5975797, id=4)
// SearchResp.SearchResult(entity={}, score=0.46704385, id=5)
import (
"context"
"fmt"
"github.com/milvus-io/milvus/client/v2/index"
"github.com/milvus-io/milvus/client/v2/entity"
"github.com/milvus-io/milvus/client/v2/milvusclient"
)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
milvusAddr := "YOUR_CLUSTER_ENDPOINT"
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
Address: milvusAddr,
})
if err != nil {
fmt.Println(err.Error())
// handle error
}
defer client.Close(ctx)
queryVector := []float32{0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592}
annParam := index.NewCustomAnnParam()
annParam.WithRadius(0.4)
annParam.WithRangeFilter(0.6)
resultSets, err := client.Search(ctx, milvusclient.NewSearchOption(
"my_collection", // collectionName
5, // limit
[]entity.Vector{entity.FloatVector(queryVector)},
).WithConsistencyLevel(entity.ClStrong).
WithANNSField("vector").
WithAnnParam(annParam))
if err != nil {
fmt.Println(err.Error())
// handle error
}
for _, resultSet := range resultSets {
fmt.Println("IDs: ", resultSet.IDs.FieldData().GetScalars())
fmt.Println("Scores: ", resultSet.Scores)
}
use milvus::v2::prelude::*;
let config = ConnectConfig::new().uri("YOUR_CLUSTER_ENDPOINT").token("YOUR_CLUSTER_TOKEN");
let client = ClientV2::new(&config).await?;
let query_vector = vec![0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592];
let response = client
.search(
SearchRequest::builder()
.collection_name("my_collection")
.vector_field("vector")
.vectors(SearchVectors::Float(vec![query_vector]))
.limit(5)
.radius(0.4)
.range_filter(0.6)
.build()?,
)
.await?;
println!("TopK results:");
for result in response.results() {
for row in result.rows()? {
println!("{:?}", row.to_entity_row()?);
}
}
#include <iostream>
#include <vector>
#include "milvus/MilvusClientV2.h"
auto client = milvus::MilvusClientV2::Create();
auto status = client->Connect(milvus::ConnectParam("YOUR_CLUSTER_ENDPOINT", "YOUR_CLUSTER_TOKEN"));
if (!status.IsOk()) {
std::cerr << "Failed to connect: " << status.Message() << std::endl;
return;
}
std::vector<float> queryVector = {
0.35803764F, -0.60234958F, 0.18414013F, -0.26286206F, 0.90294385F
};
auto searchRequest = milvus::SearchRequest()
.WithCollectionName("my_collection")
.WithAnnsField("vector")
.WithLimit(5)
.WithRadius(0.4)
.WithRangeFilter(0.6)
.AddFloatVector(queryVector);
milvus::SearchResponse searchResponse;
status = client->Search(searchRequest, searchResponse);
if (!status.IsOk()) {
std::cerr << "Search failed: " << status.Message() << std::endl;
return;
}
for (const auto& result : searchResponse.Results().Results()) {
const auto ids = result.Ids().IntIDArray();
for (size_t i = 0; i < result.Scores().size(); ++i) {
std::cout << "id=" << ids[i] << ", score=" << result.Scores()[i] << std::endl;
}
}
import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";
const address = "YOUR_CLUSTER_ENDPOINT";
const token = "YOUR_CLUSTER_TOKEN";
const client = new MilvusClient({address, token});
var query_vector = [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592]
res = await client.search({
collection_name: "my_collection",
data: [query_vector],
limit: 5,
params: {
"radius": 0.4,
"range_filter": 0.6
}
})
using Milvus.Client.V2;
using Milvus.Client.V2.Requests.Dql;
using Milvus.Client.V2.Types;
MilvusClientV2 client = new(new ConnectConfig
{
Uri = "YOUR_CLUSTER_ENDPOINT",
ApiKey = "YOUR_CLUSTER_TOKEN"
});
await client.ConnectAsync();
float[] queryVector = [0.3580376395471989f, -0.6023495712049978f, 0.18414012509913835f, -0.26286205330961354f, 0.9029438446296592f];
SearchResp res = await client.SearchAsync(new SearchReq
{
CollectionName = "my_collection",
VectorFieldName = "vector",
Vectors = [queryVector],
Limit = 5,
Parameters = new SearchParameters
{
Radius = "0.4",
RangeFilter = "0.6",
OutputFields = { "color" }
}
});
export CLUSTER_ENDPOINT="YOUR_CLUSTER_ENDPOINT"
export TOKEN="YOUR_CLUSTER_TOKEN"
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/search" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
"collectionName": "my_collection",
"data": [
[0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592]
],
"annsField": "vector",
"limit": 5,
"searchParams": {
"params": {
"radius": 0.4,
"range_filter": 0.6
}
}
}'
# {"code":0,"cost":0,"data":[]}
# Zilliz CLI
# Prerequisite: run zilliz login and select your cluster with zilliz context set.
zilliz vector search \
--collection my_collection \
--body '{
"data": [
[
0.3580376395471989,
-0.6023495712049978,
0.18414012509913835,
-0.26286205330961354,
0.9029438446296592
]
],
"annsField": "vector",
"limit": 3,
"searchParams": {
"params": {
"radius": 0.4,
"range_filter": 0.6
}
}
}' \
--output json
クエリベクトルがターゲットコレクションにすでに存在する場合は、検索前に取得する代わりに ids を使用することを検討してください。詳細は、プライマリキー検索 を参照してください。