Hugging Face Ranker

Vector search 会按向量距离对结果排序，但初始顺序可能无法准确反映每个候选文本回答查询的相关程度。Hugging Face Ranker 会将查询和候选文本发送到托管的 Hugging Face Inference Providers，并使用 sentence-similarity 分数对 Milvus 返回的候选结果 Reranking。

此集成使用托管的 Hugging Face router。如需使用单独部署的 Text Embedding Inference (TEI) 服务进行 rerank，请参阅 TEI Ranker。

Limits

• Function 必须在 input_field_names 中引用且仅引用一个不可为 NULL 的 VARCHAR 字段。
• queries 中的字符串数量必须等于 search queries 的数量（nq）。

工作原理

Hugging Face Ranker 在初始 vector search 之后运行：

1. 检索候选 Entity。 Milvus 搜索配置的 vector field，并收集候选 Entity。
2. 准备用于 reranking 的文本。 Function 从 params.queries 读取查询文本，并从 input_field_names 指定的 VARCHAR 字段读取候选文本。
3. 请求相似度分数。 Milvus 通过 hf-inference 将查询作为 source_sentence、将候选文本作为 sentences 发送到 Hugging Face sentence-similarity pipeline。
4. 对候选结果进行 rerank。 Hugging Face 为每个候选结果返回一个分数。Milvus 按分数从高到低排序候选结果，并返回 rerank 后的结果。

相似度分数如何计算

Hugging Face model 分三个阶段计算分数：

1. 准备文本输入。 Ranker 从 params.queries 读取查询文本，并从配置的 VARCHAR 字段读取候选文本。
2. 创建独立的 model representations。 Milvus 将查询作为 source_sentence、将候选文本作为 sentences 发送。model 会在内部分别对查询和每个候选文本进行编码。
3. 比较并返回分数。 model 将查询 representation 与每个候选 representation 进行比较，并为每个候选结果返回一个相似度分数。

Hugging Face model 使用的 Embedding 或 representations 是 model 处理过程中的中间结果。Hugging Face 返回的是分数，而不是 vectors。因此，初始 vector retrieval 和 model reranking 使用独立的 representations，并且可能使用不同的 models。

Before you start

在使用 Hugging Face Ranker 前，请确保你已具备：

• 2.6 release line 中的 Milvus 2.6.20 或更高版本。
• PyMilvus 2.6.16 或更高版本。
• 可调用 Inference Providers 的 Hugging Face User Access Token。
• 一个当前由 hf-inference 提供服务、用于 sentence-similarity 任务的模型。
• 一个在非 nullable VARCHAR 字段中存储候选文本的 Collection。

Milvus 无法控制 Hugging Face 模型是否持续可通过 hf-inference 使用，也无法保证该模型是否满足你的稳定性、延迟和输出质量要求。在生产环境中使用前，请先在 Hugging Face 上验证该模型，并针对你的 workload 进行评估。

示例仅使用 sentence-transformers/all-MiniLM-L6-v2 演示配置方式。该模型并非 Milvus 推荐或认证的模型。

配置凭据

你可以在 milvus.yaml 中配置 Hugging Face User Access Token，也可以通过环境变量配置。

凭据优先级如下：

Text

Function credential label -> provider credential label in milvus.yaml -> environment variable

Option 1: Configuration file

在顶层 credential section 下定义 token，然后将 Hugging Face ranker provider 指向该 credential label：

YAML

# milvus.yaml
credential:
  huggingface_apikey:
    apikey: <YOUR_HUGGING_FACE_TOKEN>

function:
  rerank:
    model:
      providers:
        huggingface:
          credential: huggingface_apikey
          # url: https://router.huggingface.co

Function 级别的 credential 参数可以覆盖 provider 级别的 label。它的值必须是在 milvus.yaml 中定义的 credential label，而不是 token 本身。

Option 2: 环境变量

如果 Function 和 provider 配置都未指定 credential label，请在 Milvus 服务环境中设置 MILVUS_HUGGINGFACE_API_KEY：

YAML

# docker-compose.yaml
standalone:
  environment:
    MILVUS_HUGGINGFACE_API_KEY: <YOUR_HUGGING_FACE_TOKEN>

Use Hugging Face Ranker

Hugging Face Ranker 在搜索时定义并应用。你可以为每次搜索更改或省略 ranker，而无需更改 Collection Schema。

Step 1: Prepare a collection

以下示例创建一个 Collection，其中包含一个用于 reranking 的文本字段，以及一个用于初始检索的向量字段：

Python

from pymilvus import DataType, Function, FunctionType, MilvusClient

client = MilvusClient(uri="http://localhost:19530")

collection_name = "hugging_face_rerank_demo"
schema = client.create_schema()
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=1000)
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=4)

index_params = client.prepare_index_params()
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

client.create_collection(
    collection_name=collection_name,
    schema=schema,
    index_params=index_params,
)

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Recent renewable energy developments include improved solar efficiency.",
            "dense": [0.10, 0.20, 0.30, 0.40],
        },
        {
            "id": 2,
            "document": "Climate policy and carbon markets have evolved rapidly in recent years.",
            "dense": [0.11, 0.19, 0.28, 0.39],
        },
        {
            "id": 3,
            "document": "New battery technology helps stabilize wind and solar power generation.",
            "dense": [0.90, 0.10, 0.05, 0.02],
        },
        {
            "id": 4,
            "document": "Vector databases support similarity search for machine learning applications.",
            "dense": [0.01, 0.02, 0.03, 0.04],
        },
    ],
)

第 2 步：定义 rerank Function

定义一个 RERANK Function，从 document 读取候选文本，并使用 queries 中的查询文本：

Python

hugging_face_ranker = Function(
    name="hugging_face_semantic_ranker",
    input_field_names=["document"],
    function_type=FunctionType.RERANK,
    params={
        "reranker": "model",
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "queries": ["renewable energy developments"],
        "credential": "huggingface_apikey",
        "max_client_batch_size": 32,
    },
)

如果你只使用 provider 级 credential 或环境变量，请在 Function 参数中省略 credential。

下表描述了 Hugging Face Ranker 参数：

参数	是否必需	描述
reranker	是	reranking 实现。将此值设置为 model。
provider	是	模型 provider。将此值设置为 huggingface。
model_name	是	通过 hf-inference 为 sentence-similarity 任务提供服务的模型对应的 Hugging Face model ID。
queries	是	用于 reranking 的查询字符串。即使初始检索使用查询向量，也要为每个搜索查询提供且仅提供一个字符串。
hf_provider	否	Hugging Face Inference Provider 路由。Milvus 2.6.20 中默认且唯一支持的值是 hf-inference。
credential	否	在 milvus.yaml 顶层 credential 部分定义的 credential 标签。此值不是 token 本身。
max_client_batch_size	否	单个 Hugging Face 请求中发送的候选文本最大数量。默认值为 32，且该值必须大于 0。

Step 3: 使用 ranker 进行 Search

将 Function 通过 search() 的 ranker 参数传入：

Python

query_vector = [0.12, 0.21, 0.29, 0.41]

results = client.search(
    collection_name=collection_name,
    data=[query_vector],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    ranker=hugging_face_ranker,
    consistency_level="Strong",
)

print(results)

Milvus 首先从 dense 中检索候选项，然后使用 queries 中的查询文本和 document 中的候选文本计算句子相似度分数。返回的候选项会按 Hugging Face 分数排序。

Troubleshooting

The model is unavailable for sentence similarity

打开 Hugging Face 上的模型页面，查看 Inference Providers 区域。确认 hf-inference 是否为 sentence-similarity 提供该模型。如果不是，请选择另一个支持该任务的模型。

The number of query strings does not match the search request

queries 中的字符串数量必须等于搜索查询数量（nq）。对于包含一个 query vector 的搜索，必须恰好提供一个 query string。

Candidate text 缺失或可为 NULL

确保 input_field_names 只包含一个非 nullable 的 VARCHAR 字段，并且每个候选 Entity 都在该字段中包含文本。

Milvus reports missing Hugging Face credentials

确认 milvus.yaml 中存在 Function credential label，provider-level label 有效，或 Milvus 服务环境中存在 MILVUS_HUGGINGFACE_API_KEY。

下一步

• 如需了解共享的 model-ranker 行为和限制，参阅 Model Ranker Overview。
• 如需通过托管的 Hugging Face Inference Providers 生成 Embedding，参阅 Hugging Face。
• 如需将 ranker 应用于 Hybrid Search，参阅 Multi-Vector Hybrid Search。