Hugging FaceCompatible with Milvus v2.6.20+

A utilização de um modelo de embedding do Hugging Face normalmente requer que a sua aplicação gere as credenciais, chame o modelo separadamente e gere embeddings de forma consistente para os dados inseridos e as consultas de pesquisa. Com uma Função de Embedding de Texto, o Milvus recorre aos Provedores de Inferência do Hugging Face alojados para converter texto bruto em vetores durante a inserção e a pesquisa.

Esta integração utiliza o router do Hugging Face alojado. Para ligar o Milvus a um serviço de Inferência de Embeddings de Texto (TEI) implementado separadamente, consulte o Hugging Face TEI.

Limites

• O campo de saída da Função deve utilizar o tipo de dados « FLOAT_VECTOR ». A incorporação do Hugging Face no Milvus não suporta campos de saída do tipo « INT8_VECTOR », « BINARY_VECTOR », « FLOAT16_VECTOR » ou « BFLOAT16_VECTOR ».
• A dimensão do campo de saída «Função» deve corresponder à dimensão de saída do modelo selecionado.

Como funciona

Fluxo de trabalho de embedding de texto do Hugging Face

O fluxo de trabalho tem três etapas:

1. Enviar texto bruto. A sua aplicação fornece texto bruto numa solicitação de inserção ou pesquisa.
2. Gerar uma incorporação. A Função de Incorporação de Texto envia o texto através de hf-inference para o pipeline « feature-extraction » da Hugging Face. A Função utiliza model_name para selecionar o modelo e pode passar opções de inferência suportadas, tais como normalização e truncamento.
3. Utilize a incorporação. O Hugging Face devolve uma incorporação de ponto flutuante por texto de entrada. Durante a inserção, o Milvus armazena o vetor no campo de saída da função. Durante a pesquisa, o Milvus utiliza o vetor como vetor de consulta.

A mesma configuração da Função trata tanto da inserção como da pesquisa, mantendo o modelo e os parâmetros de inferência consistentes em ambas as operações.

Antes de começar

Antes de utilizar a incorporação de texto do Hugging Face hospedada, certifique-se de que possui:

• Milvus 2.6.20 ou posterior da linha de lançamento 2.6.
• PyMilvus 2.6.16 ou posterior.
• Um token de acesso de utilizador do Hugging Face capaz de chamar os fornecedores de inferência.
• Um modelo atualmente disponibilizado pelo hf-inference para a feature-extraction tarefa.

Os exemplos utilizam sentence-transformers/all-MiniLM-L6-v2, que produz embeddings de 384 dimensões. O modelo é utilizado apenas para demonstrar a configuração e não constitui uma recomendação ou certificação do Milvus.

Configurar credenciais

O Milvus requer um token de acesso de utilizador do Hugging Face para aceder ao router alojado. Pode configurar o token em milvus.yaml ou através de uma variável de ambiente.

A ordem de prioridade das credenciais é:

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

Opção 1: Ficheiro de configuração

Defina o token na secção de nível superior « credential » em milvus.yaml e, em seguida, aponte o fornecedor de embeddings do Hugging Face para esse rótulo de credencial:

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

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

Também pode definir « credential » nos parâmetros da função. O valor deve ser o rótulo definido na secção de nível superior « credential », e não o próprio token. Um rótulo de credencial ao nível da função tem precedência sobre o rótulo ao nível do fornecedor.

Opção 2: Variável de ambiente

Se nem a função nem a configuração do fornecedor especificarem um rótulo de credencial, o Milvus lê o token a partir de MILVUS_HUGGINGFACE_API_KEY.

Para o Docker Compose, defina a variável no serviço autónomo do Milvus:

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

Para obter detalhes sobre como aplicar as definições do Docker Compose, consulte «Configurar o Milvus com o Docker Compose».

Utilizar a incorporação de texto do Hugging Face

Passo 1: Criar uma coleção com uma função de incorporação de texto

Crie um esquema com um campo primário, um campo de entrada « VARCHAR » e um campo de saída « FLOAT_VECTOR ». A dimensão de saída deve corresponder ao modelo selecionado.

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

Defina uma função « TEXTEMBEDDING » que escreva as incorporações de « document » para « 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)

Se utilizar apenas a credencial ao nível do fornecedor ou a variável de ambiente, omita « credential » dos parâmetros da função.

Configure um índice para o campo de saída e, em seguida, crie a coleção:

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

A tabela seguinte descreve os parâmetros da função específicos do Hugging Face:

Parâmetro	Obrigatório?	Descrição
provider	Sim	O fornecedor do modelo de embedding. Defina este valor como huggingface.
model_name	Sim	O ID do modelo Hugging Face para um modelo disponibilizado através de hf-inference para a tarefa « feature-extraction ».
hf_provider	Não	A rota do fornecedor de inferência do Hugging Face. O valor predefinido e único suportado no Milvus 2.6.20 é hf-inference.
credential	Não	O rótulo de uma credencial definida na secção de nível superior credential de milvus.yaml. Este valor não é o próprio token.
normalize	Não	Se o Hugging Face deve devolver embeddings normalizadas. Os valores suportados são true e false. Se omitido, o Milvus não define esta opção no pedido.
prompt_name	Não	O nome de um prompt definido na configuração «Sentence Transformers» do modelo selecionado.
truncate	Não	Se o Hugging Face deve truncar uma entrada que exceda o comprimento suportado pelo modelo. Os valores suportados são « true » e « false ».
truncation_direction	Não	A direção a partir da qual o Hugging Face trunca uma entrada. Os valores suportados são « left » e « right ».
max_client_batch_size	Não	O número máximo de textos de entrada enviados numa única solicitação ao Hugging Face. O valor predefinido é 128, e o valor deve ser superior a 0.

Passo 2: Inserir texto bruto

Insira texto sem fornecer vetores. O Milvus chama o Hugging Face e grava as incorporações geradas em 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.",
        },
    ],
)

Passo 3: Pesquisar com texto bruto

Pesquise com uma consulta de texto. O Milvus aplica a mesma configuração da função para criar o vetor de consulta antes de executar a pesquisa por vetores.

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)

O resultado contém os documentos mais relevantes para o texto da consulta, ordenados por similaridade cosinusoidal.

Resolução de problemas

O modelo não está disponível para extração de características

Abra a página do modelo no Hugging Face e verifique a secção «Inference Providers ». Confirme se « hf-inference » fornece o modelo para « feature-extraction ». Caso contrário, selecione outro modelo e atualize a dimensão do campo vetorial, se necessário.

A dimensão do vetor devolvida não corresponde ao campo

Verifique a dimensão de saída do modelo e compare-a com dim no campo «Saída da função». O Milvus rejeita uma resposta cuja dimensão do vetor difira da dimensão do campo FLOAT_VECTOR.

O Milvus indica que faltam credenciais do Hugging Face

Confirme se o rótulo de credenciais da Função existe na secção de nível superior « credential », se o rótulo ao nível do fornecedor é válido ou se « MILVUS_HUGGINGFACE_API_KEY » está presente no ambiente de serviço do Milvus.

Próximos passos

• Para conceitos gerais da Função e comportamento de inserção/pesquisa, consulte Visão geral da Função de incorporação.
• Para reclassificar candidatos de pesquisa vetorial com pontuações de similaridade de frases do Hugging Face alojadas, consulte o «Hugging Face Ranker».