Hugging Face

使用 Hugging Face embedding model 通常要求你的应用管理凭据、单独调用模型，并为插入数据和搜索查询一致地生成 Embedding。借助 Text Embedding Function，Milvus 会调用托管的 Hugging Face Inference Providers，在 insert 和 search 期间将原始文本转换为 vectors。

此集成使用托管的 Hugging Face router。要将 Milvus 连接到单独部署的 Text Embedding Inference (TEI) 服务，请参阅 Hugging Face TEI。

Limits

• Function 输出字段必须使用 FLOAT_VECTOR 数据类型。Milvus 中的 Hugging Face embedding 不支持 INT8_VECTOR、BINARY_VECTOR、FLOAT16_VECTOR 或 BFLOAT16_VECTOR 输出字段。
• Function 输出字段的维度必须与所选模型的输出维度一致。

工作原理

该工作流包含三个阶段：

1. 发送原始文本。 你的应用在 insert 或 search 请求中提供原始文本。
2. 生成 Embedding。 Text Embedding Function 通过 hf-inference 将文本发送到 Hugging Face feature-extraction Pipeline。Function 使用 model_name 选择模型，并可传入受支持的推理选项，例如归一化和截断。
3. 使用 Embedding。 Hugging Face 会为每段输入文本返回一个浮点 Embedding。执行 insert 时，Milvus 会将向量存储到 Function 输出字段中。执行 search 时，Milvus 会将该向量用作查询向量。

相同的 Function 配置同时处理 insert 和 search，确保这两种操作中的模型和推理参数保持一致。

Before you start

在使用托管 Hugging Face 文本 Embedding 前，请确保你具备：

• 2.6 release line 中的 Milvus 2.6.20 或更高版本。
• PyMilvus 2.6.16 或更高版本。
• 可调用 Inference Providers 的 Hugging Face User Access Token。
• 当前由 hf-inference 为 feature-extraction 任务提供服务的模型。

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

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

Configure credentials

Milvus 需要 Hugging Face User Access Token 才能调用托管的 router。你可以在 milvus.yaml 中配置该 token，也可以通过环境变量配置。

凭证优先级如下：

Text

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

Option 1: Configuration file

在 milvus.yaml 的顶层 credential 区块下定义 token，然后将 Hugging Face embedding provider 指向该 credential label：

YAML

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

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

你也可以在 Function 参数中设置 credential。该值必须是顶层 credential 区块中定义的 label，而不是 token 本身。Function 级别的 credential label 优先级高于 provider 级别的 label。

Option 2: Environment variable

如果 Function 和 provider 配置都未指定 credential label，Milvus 会从 MILVUS_HUGGINGFACE_API_KEY 读取 token。

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

YAML

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

有关应用 Docker Compose 设置的详细信息，参见 Configure Milvus with Docker Compose。

使用 Hugging Face 文本 Embedding

Step 1: Create a collection with a Text Embedding Function

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

Python

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 Function，将 document 中的 Embedding 写入 dense：

Python

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)

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

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

Python

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 专用的 Function 参数：

参数	是否必需	说明
provider	是	Embedding 模型提供方。将该值设置为 huggingface。
model_name	是	通过 hf-inference 为 feature-extraction 任务提供服务的模型对应的 Hugging Face model ID。
hf_provider	否	Hugging Face Inference Provider 路由。Milvus 2.6.20 中默认且唯一支持的值为 hf-inference。
credential	否	在 milvus.yaml 顶层 credential 部分定义的 credential 标签。该值不是 token 本身。
normalize	否	Hugging Face 是否应返回归一化后的 Embedding。支持的值为 true 和 false。如果省略，Milvus 不会在请求中设置此选项。
prompt_name	否	所选模型的 Sentence Transformers 配置中定义的 prompt 名称。
truncate	否	Hugging Face 是否应截断超过模型支持长度的输入。支持的值为 true 和 false。
truncation_direction	否	Hugging Face 截断输入的方向。支持的值为 left 和 right。
max_client_batch_size	否	单个 Hugging Face 请求中发送的输入文本最大数量。默认值为 128，且该值必须大于 0。

Step 2: Insert raw text

插入文本时无需提供向量。Milvus 会调用 Hugging Face，并将生成的 Embedding 写入 dense。

Python

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.",
        },
    ],
)

Step 3: Search with raw text

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

Python

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)

结果包含与查询文本最相关的文档，并按 cosine similarity 排序。

Troubleshooting

模型不可用于 feature extraction

打开 Hugging Face 上的模型页面，查看 Inference Providers 部分。确认 hf-inference 是否为 feature-extraction 提供该模型服务。如果不是，请选择其他模型，并在必要时更新向量字段维度。

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

检查模型输出维度，并将其与 Function 输出字段上的 dim 进行比较。如果响应中的向量维度与 FLOAT_VECTOR 字段维度不同，Milvus 会拒绝该响应。

Milvus reports missing Hugging Face credentials

确认 Function credential label 存在于顶层 credential section 中，provider 级别的 label 有效，或 Milvus 服务环境中存在 MILVUS_HUGGINGFACE_API_KEY。

Next steps

• 如需了解通用 Function 概念以及 insert/search 行为，请参阅 Embedding Function Overview。
• 如需使用托管的 Hugging Face sentence-similarity 分数对 vector-search 候选结果进行 rerank，请参阅 Hugging Face Ranker。