Hugging FaceCompatible with Milvus v2.6.20+

通常，使用 Hugging Face 嵌入模型需要您的应用程序管理凭据、单独调用模型，并针对插入的数据和搜索查询一致地生成 Embeddings。借助文本嵌入功能，Milvus 会在插入和搜索过程中调用托管的Hugging Face 推理提供程序，将原始文本转换为向量。

此集成使用托管版的 Hugging Face 路由器。若要将 Milvus 连接到单独部署的文本嵌入推理（TEI）服务，请参阅Hugging Face TEI。

限制

• 函数输出字段必须使用FLOAT_VECTOR 数据类型。Milvus中的Hugging Face嵌入功能不支持INT8_VECTOR 、BINARY_VECTOR 、FLOAT16_VECTOR 或BFLOAT16_VECTOR 类型的输出字段。
• “Function”输出字段的维度必须与所选模型的输出维度相匹配。

工作原理

Hugging Face 文本嵌入工作流

该工作流分为三个阶段：

1. 发送原始文本。您的应用程序通过插入或搜索请求提供原始文本。
2. 生成Embeddings。文本嵌入函数将文本通过hf-inference 发送至Hugging Face的feature-extraction 管道。该函数使用model_name 选择模型，并可传递支持的推理选项（如归一化和截断）。
3. 使用嵌入向量。Hugging Face 针对每条输入文本返回一个浮点嵌入向量。在插入操作中，Milvus 将该向量存储在函数的输出字段中；在搜索操作中，Milvus 将该向量用作查询向量。

同一函数配置可同时处理插入和搜索操作，确保模型及推理参数在两种操作中保持一致。

开始之前

在使用托管版 Hugging Face 文本嵌入功能之前，请确保您已具备：

• 2.6 发布分支中的 Milvus 2.6.20 或更高版本。
• PyMilvus 2.6.16 或更高版本。
• 一个能够调用推理提供商的 Hugging Face 用户访问令牌。
• 当前由hf-inference 托管的、用于 feature-extraction 任务提供服务。

示例中使用 sentence-transformers/all-MiniLM-L6-v2，该模型可生成384维的Embeddings。此模型仅用于演示配置，并不代表Milvus的推荐或认证。

配置凭据

Milvus 需要一个 Hugging Face 用户访问令牌来调用托管路由器。您可以在milvus.yaml 上配置该令牌，或通过环境变量进行配置。

凭据的优先级顺序为：

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

选项 1：配置文件

在milvus.yaml 的顶级credential 部分定义令牌，然后将 Hugging Face 嵌入提供程序指向该凭据标签：

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

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

您还可以在函数参数中设置 `credential `。该值必须是 `credential ` 顶级部分中定义的标签，而非令牌本身。函数级凭证标签的优先级高于提供程序级标签。

选项 2：环境变量

如果函数和提供商配置中均未指定凭据标签，Milvus 将从 `MILVUS_HUGGINGFACE_API_KEY` 读取令牌。

对于 Docker Compose，请在 Milvus Standalone 服务中设置该变量：

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

有关应用 Docker Compose 设置的详细信息，请参阅《使用 Docker Compose 配置 Milvus》。

使用 Hugging Face 文本嵌入

步骤 1：创建包含文本嵌入函数的Collection

创建一个包含主字段、VARCHAR 输入字段和FLOAT_VECTOR 输出字段的 Schema。输出维度必须与所选模型匹配。

from pymilvus import DataType, Function, FunctionType, MilvusClient

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

collection_name = "hugging_face_embedding_demo"
schema = client.create_schema()

schema.add_field(
    field_name="id",
    datatype=DataType.INT64,
    is_primary=True,
    auto_id=False,
)
schema.add_field(
    field_name="document",
    datatype=DataType.VARCHAR,
    max_length=9000,
)
schema.add_field(
    field_name="dense",
    datatype=DataType.FLOAT_VECTOR,
    dim=384,
)

定义一个TEXTEMBEDDING 函数，将Embeddings从document 写入dense ：

text_embedding_function = Function(
    name="hugging_face_embedding",
    input_field_names=["document"],
    output_field_names=["dense"],
    function_type=FunctionType.TEXTEMBEDDING,
    params={
        "provider": "huggingface",
        "model_name": "sentence-transformers/all-MiniLM-L6-v2",
        "hf_provider": "hf-inference",
        "credential": "huggingface_apikey",
        "normalize": "true",
        "truncate": "true",
        "max_client_batch_size": 128,
    },
)

schema.add_function(text_embedding_function)

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

为输出字段配置索引，然后创建Collection：

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

下表描述了 Hugging Face 特有的函数参数：

参数	必填？	描述
provider	是	嵌入模型提供商。请将此值设置为huggingface 。
model_name	是	通过hf-inference 提供的、用于feature-extraction 任务的 Hugging Face 模型 ID。
hf_provider	否	Hugging Face 推理提供程序的路由。在 Milvus 2.6.20 中，默认值且唯一受支持的值为hf-inference 。
credential	否	在milvus.yaml 的顶级credential 部分中定义的凭据标签。此值并非令牌本身。
normalize	否	是否应由 Hugging Face 返回归一化 Embeddings。支持的值为true 和false 。若省略，Milvus 不会在请求中设置此选项。
prompt_name	否	在所选模型的 Sentence Transformers 配置中定义的提示词名称。
truncate	否	Hugging Face 是否应截断超过模型支持长度的输入。支持的值为true 和false 。
truncation_direction	否	Hugging Face截断输入的方向。支持的值为left 和right 。
max_client_batch_size	否	单次 Hugging Face 请求中发送的输入文本最大数量。默认值为128 ，且该值必须大于0 。

步骤 2：插入原始文本

插入文本而不提供向量。Milvus 将调用 Hugging Face，并将生成的 Embeddings 写入dense 。

client.insert(
    collection_name=collection_name,
    data=[
        {
            "id": 1,
            "document": "Milvus simplifies semantic search through embeddings.",
        },
        {
            "id": 2,
            "document": "Vector embeddings convert text into searchable numeric data.",
        },
        {
            "id": 3,
            "document": "Semantic search helps users find relevant information quickly.",
        },
    ],
)

步骤 3：使用原始文本进行搜索

使用文本查询进行搜索。Milvus 会应用相同的 Function 配置来创建查询向量，然后执行向量搜索。

results = client.search(
    collection_name=collection_name,
    data=["How does Milvus handle semantic search?"],
    anns_field="dense",
    limit=3,
    output_fields=["document"],
    consistency_level="Strong",
)

print(results)

结果包含与查询文本最相关的文档，并按余弦相似度排序。

故障排除

该模型无法用于特征提取

在 Hugging Face 上打开模型页面，并检查“推理提供商”部分。确认hf-inference 是否为feature-extraction 提供模型服务。如果不是，请选择另一个模型，并在必要时更新向量字段维度。

返回的向量维度与字段不匹配

请检查模型输出维度，并将其与dim 中“函数输出”字段的维度进行对比。若向量维度与FLOAT_VECTOR 字段维度不一致，Milvus将拒绝该响应。

Milvus 报告缺少 Hugging Face 凭据

请确认“Function”凭据标签是否存在于顶级credential 部分中，提供商级别的标签是否有效，或者Milvus服务环境中是否存在MILVUS_HUGGINGFACE_API_KEY 。

后续步骤

• 有关 Function 的通用概念以及插入/搜索行为，请参阅《Embeddings 函数概述》。
• 若要使用托管版 Hugging Face 的句子相似度评分对向量搜索候选项进行重新排序，请参阅《Hugging Face Ranker》。