Hugging Face

使用 Hugging Face embedding model 通常需要你的应用自行管理凭证、单独调用模型，并确保插入数据和搜索查询以一致方式生成 Embedding。借助 Text Embedding Function，Milvus 会在插入和搜索期间调用托管的 Hugging Face Inference Providers，将原始文本转换为向量。

此集成使用托管的 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，确保这两类操作中的模型和推理参数保持一致。

准备工作

在使用托管式 Hugging Face text 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 上验证该模型，并针对你的 workload 进行评估。

示例使用 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 标签：

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 部分中定义的标签，而不是 token 本身。Function 级别的 credential 标签优先于 provider 级别的标签。

Option 2: Environment variable

如果 Function 和 provider configuration 都未指定凭据标签，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 text embedding

Step 1: 使用 Text Embedding Function 创建 Collection

创建一个 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 级别的凭证或环境变量，请从 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 模型 provider。将该值设置为 huggingface。
model_name	是	通过 hf-inference 为 feature-extraction 任务提供服务的 Hugging Face 模型 ID。
hf_provider	否	Hugging Face Inference Provider 路由。在 Milvus 2.6.20 中，默认且唯一支持的值为 hf-inference。
credential	否	在 milvus.yaml 顶层 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: 插入原始文本

插入文本时无需提供向量。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

The model is unavailable for feature extraction

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

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

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

Milvus reports missing Hugging Face credentials

确认 Function credential 标签存在于顶层 credential section 中，provider-level 标签有效，或者 Milvus 服务环境中存在 MILVUS_HUGGINGFACE_API_KEY。

Next steps

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