Hugging Face RankerCompatible with Milvus v2.6.20+

向量搜索会根据向量距离对结果进行排序，但初始排序可能无法准确反映每个候选文本对查询的契合程度。Hugging Face Ranker 将查询和候选文本发送至托管的Hugging Face 推理提供商，并利用sentence-similarity 评分对 Milvus 返回的候选结果进行重新排序。

此集成使用托管版的 Hugging Face 路由器。若要使用单独部署的文本嵌入推理（TEI）服务进行重新排序，请参阅TEI Ranker。

限制

• 该函数必须在input_field_names 中精确引用一个不可为空的VARCHAR 字段。
• queries 中的字符串数量必须等于搜索查询的数量（nq ）。

工作原理

Hugging Face Ranker 工作流

Hugging Face Ranker 在初始向量搜索之后运行：

1. 检索候选实体。Milvus 会搜索配置好的向量字段并收集候选实体。
2. 准备用于重新排序的文本。该函数从params.queries 读取查询文本，并从input_field_names 中指定的VARCHAR 字段读取候选文本。
3. 请求相似度评分。Milvus 通过hf-inference 将查询作为source_sentence 以及候选文本作为sentences 发送至 Hugging Face 的sentence-similarity 管道。
4. 对候选文本进行重新排序。Hugging Face 为每个候选文本返回一个相似度分数。Milvus 根据分数从高到低对候选文本进行排序，并返回重新排序后的结果。

相似度评分的计算方式

Hugging Face Ranker 如何计算相似度分数

Hugging Face 模型分三个阶段计算分数：

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

Hugging Face 模型所使用的 Embeddings 或表示形式属于模型处理的中间结果。Hugging Face 返回的是评分，而非向量。因此，初始向量检索和模型重新排序使用的是独立的表示形式，且可能采用不同的模型。

开始之前

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

• 2.6 发布分支中的 Milvus 2.6.20 或更高版本。
• PyMilvus 2.6.16 或更高版本。
• 一个能够调用推理提供程序的 Hugging Face 用户访问令牌。
• 当前由hf-inference 托管的、用于 sentence-similarity 任务提供服务的模型。
• 一个Collection，用于将候选文本存储在VARCHAR 的不可为空字段中。

示例中仅使用 sentence-transformers/all-MiniLM-L6-v2 仅用于演示配置。该模型不代表 Milvus 的推荐或认证。

配置凭据

您可以在milvus.yaml 上配置 Hugging Face 用户访问令牌，或通过环境变量进行配置。

凭据的优先级顺序为：

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

选项 1：配置文件

在顶级credential 部分下定义令牌，然后将 Hugging Face 排序器提供程序指向该凭据标签：

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

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

函数级别的credential 参数可以覆盖提供程序级别的标签。其值必须是milvus.yaml 中定义的凭据标签，而不是令牌本身。

方案 2：环境变量

如果函数和提供程序配置中均未指定凭据标签，请在 Milvus 服务环境中设置MILVUS_HUGGINGFACE_API_KEY ：

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

使用 Hugging Face Ranker

Hugging Face Ranker 在搜索时定义并应用。您可以在不更改 Collection Schema 的情况下，针对每次搜索更改或省略该排序器。

步骤 1：准备一个 Collection

以下示例创建了一个Collection，其中包含用于重新排序的文本字段和用于初始检索的向量字段：

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 函数，该函数从document 读取候选文本，并使用queries 中的查询文本：

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,
    },
)

如果您仅使用提供商级凭据或环境变量，请在函数参数中省略credential 。

下表描述了 Hugging Face Ranker 的参数：

参数	必填？	描述
reranker	是	重新排序的实现方式。请将此值设置为model 。
provider	是	模型提供者。将此值设置为huggingface 。
model_name	是	通过hf-inference 提供的、用于sentence-similarity 任务的 Hugging Face 模型 ID。
queries	是	用于重新排序的查询字符串。每个搜索查询请提供且仅提供一个字符串，即使初始检索使用了查询向量也是如此。
hf_provider	否	Hugging Face 推理提供程序的路由。在 Milvus 2.6.20 中，默认且唯一受支持的值为hf-inference 。
credential	否	在milvus.yaml 文件中，credential 顶级部分定义的凭据标签。此值并非令牌本身。
max_client_batch_size	否	单次 Hugging Face 请求中发送的候选文本最大数量。默认值为32 ，且该值必须大于0 。

步骤 3：使用排名器进行搜索

将该函数作为search() 的ranker 参数传入：

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 得分排序。

故障排除

该模型无法用于句子相似度

请打开 Hugging Face 上的模型页面，并检查“推理提供商”部分。确认hf-inference 是否为sentence-similarity 提供模型服务。若非如此，请选择另一个支持该任务的模型。

查询字符串的数量与搜索请求不匹配

queries 中的字符串数量必须与搜索查询的数量（nq ）相等。对于仅包含一个查询向量的搜索，请提供恰好一个查询字符串。

候选项文本缺失或为可空

请确保 `input_field_names ` 中恰好包含一个不可为空的 `VARCHAR ` 字段，且每个候选实体在该字段中都包含文本。

Milvus 报告 Hugging Face 凭据缺失

请确认milvus.yaml 中存在Function凭证标签，且提供商级别的标签有效，或者Milvus服务环境中存在MILVUS_HUGGINGFACE_API_KEY 。

后续步骤

• 有关共享模型排名器的行为和限制，请参阅《模型排名器概述》。
• 若要通过托管的 Hugging Face 推理提供程序生成 Embeddings，请参阅Hugging Face。
• 若要将排序器应用于混合搜索，请参阅《多向量混合搜索》。