Hugging Face TEICompatible with Milvus 2.6.x

O Hugging Face Text Embeddings Inference (TEI) é um servidor de inferência de alto desempenho especificamente concebido para modelos de incorporação de texto. Este guia explica como utilizar o Hugging Face TEI com o Milvus para uma geração eficiente de incorporação de texto.

O TEI funciona com muitos modelos de incorporação de texto do Hugging Face Hub, incluindo:

• Série BAAI/bge-*

• série sentence-transformers/*

• modelos E5

• Modelos GTE

• E muitos mais

Implementação TEI

Antes de configurar o Milvus com a função TEI, é necessário ter um serviço TEI a funcionar. O Milvus suporta duas abordagens para a implementação do TEI:

Implementação standard (externa)

Pode implementar o TEI como um serviço autónomo utilizando os métodos oficiais da Hugging Face. Esta abordagem dá-lhe o máximo de flexibilidade e controlo sobre o seu serviço TEI.

Para obter instruções detalhadas sobre a implantação do TEI usando o Docker ou outros métodos, consulte a documentação oficial da Hugging Face Text Embeddings Inference.

Após a implantação, anote o ponto de extremidade do serviço TEI (por exemplo, http://localhost:8080), pois você precisará dele ao usar a função TEI no Milvus.

Implantação do Milvus Helm Chart (integrado)

Para ambientes Kubernetes, Milvus oferece uma opção de implantação integrada por meio de seu gráfico Helm. Isso simplifica o processo ao implantar e configurar o TEI junto com o Milvus.

Para ativar o TEI na sua implantação do Milvus Helm:

1. Configurar o values.yaml para ativar o TEI:

   tei:
     enabled: true
     image:
       repository: ghcr.io/huggingface/text-embeddings-inference
       tag: "1.7" # Modify based on hardware
     model: "BAAI/bge-large-en-v1.5" # Modify based on requirements
     # revision: "main"
     # hfTokenSecretName: "my-huggingface-token-secret"
     # apiKey: "your_secure_api_key"
     # apiKeySecret:
     #   name: "my-tei-api-key-secret"
     #   key: "api-key"
     resources:
       requests:
         cpu: "1"
         memory: "4Gi"
         # nvidia.com/gpu: "1" # For GPU
       limits:
         cpu: "2"
         memory: "8Gi"
         # nvidia.com/gpu: "1" # For GPU
     extraArgs: []
   
   

2. Implantar ou atualizar o Milvus:

   helm install my-release milvus/milvus -f values.yaml -n <your-milvus-namespace>
   # or
   helm upgrade my-release milvus/milvus -f values.yaml --reset-then-reuse-values -n <your-milvus-namespace>
   

   Ao usar a implantação do gráfico Helm, o serviço TEI estará acessível dentro do seu cluster Kubernetes em http://my-release-milvus-tei:80 (usando seu nome de versão). Use isso como seu ponto de extremidade na configuração da função TEI.

Configuração no Milvus

Depois de implantar seu serviço TEI, você precisará fornecer seu endpoint ao definir uma função de incorporação TEI. Na maioria dos casos, não é necessária qualquer configuração adicional, uma vez que o TEI está ativado por defeito no Milvus.

Se o seu serviço TEI foi implementado com autenticação de chave API (--api-key flag), no entanto, terá de configurar o Milvus para usar esta chave:

1. Definir as chaves da API na secção credential:

   # milvus.yaml
   credential:
     tei_key:  # You can use any label name
       apikey: <YOUR_TEI_API_KEY>
   

2. Referenciar a credencial em milvus.yaml:

   function:
     textEmbedding:
       providers:
         tei:
           credential: tei_key      # ← choose any label you defined above
           enable: true # enabled by default. no action required.
   

Usar a função de incorporação

Depois que o serviço TEI estiver configurado, siga estas etapas para definir e usar as funções de incorporação.

Passo 1: Definir campos de esquema

Para utilizar uma função de incorporação, crie uma coleção com um esquema específico. Este esquema deve incluir pelo menos três campos necessários:

• O campo primário que identifica de forma exclusiva cada entidade numa coleção.

• Um campo escalar que armazena os dados brutos a serem incorporados.

• Um campo vetorial reservado para armazenar as incorporações vectoriais que a função irá gerar para o campo escalar.

O exemplo seguinte define um esquema com um campo escalar "document" para armazenar dados textuais e um campo vetorial "dense_vector" para armazenar incrustações a serem geradas pelo módulo Function. Não se esqueça de definir a dimensão do vetor (dim) para corresponder ao resultado do modelo de incorporação escolhido.

from pymilvus import MilvusClient, DataType, Function, FunctionType, CollectionSchema, FieldSchema

# Assume you have connected to Milvus
# client = MilvusClient(uri="http://localhost:19530")

# 1. Create Schema
schema = MilvusClient.create_schema()

# 2. Add fields
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)
schema.add_field("document", DataType.VARCHAR, max_length=9000) # Store text data
# IMPORTANT: Set dim to exactly match the TEI model's output dimension
schema.add_field("dense_vector", DataType.FLOAT_VECTOR, dim=1024) # Store embedding vectors (example dimension)

Passo 2: Adicionar a função de incorporação ao esquema

O módulo Function em Milvus converte automaticamente os dados brutos armazenados num campo escalar em embeddings e armazena-os no campo vetorial explicitamente definido.

O exemplo abaixo adiciona um módulo Function (tei_func) que converte o campo escalar "document" em embeddings, armazenando os vectores resultantes no campo vetorial "dense_vector" definido anteriormente.

Depois de ter definido a sua função de incorporação, adicione-a ao seu esquema de coleção. Isto instrui o Milvus a utilizar a função de incorporação especificada para processar e armazenar os embeddings dos seus dados de texto.

# 3. Define TEI embedding function
text_embedding_function = Function(
    name="tei_func",                            # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING,   # Indicates a text embedding function
    input_field_names=["document"],             # Scalar field(s) containing text data to embed
    output_field_names=["dense_vector"],        # Vector field(s) for storing embeddings
    params={                                    # TEI specific parameters (function-level)
        "provider": "TEI",                      # Must be set to "TEI"
        "endpoint": "http://your-tei-service-endpoint:80", # Required: Points to your TEI service address
        # Optional parameters:
        # "truncate": "true",                   # Optional: Whether to truncate long input (default false)
        # "truncation_direction": "right",      # Optional: Truncation direction (default right)
        # "max_client_batch_size": 64,          # Optional: Client max batch size (default 32)
        # "ingestion_prompt": "passage: ",      # Optional: (Advanced) Ingestion phase prompt
        # "search_prompt": "query: "            # Optional: (Advanced) Search phase prompt
    }
)

# Add the configured embedding function to your existing collection schema
schema.add_function(text_embedding_function)

Parâmetro	Necessário?	Descrição	Exemplo Valor
provider	Sim	O fornecedor do modelo de incorporação. Definir como "TEI".	"TEI"
endpoint	Sim	O endereço de rede que aponta para o seu serviço TEI implementado. Se for implementado através do Milvus Helm Chart, este é normalmente o endereço interno do serviço.	"http://localhost:8080", "http://my-release-milvus-tei:80"
truncate	Não	Se deve truncar os textos de entrada que excedam o comprimento máximo do modelo. O valor predefinido é falso.	"true" (verdadeiro)
truncation_direction	Não	Efetivo quando o truncamento é verdadeiro. Especifica se o truncamento deve ser feito a partir da esquerda ou da direita. A predefinição é a direita.	"esquerda"
max_client_batch_size	Não	O tamanho máximo do lote que o cliente Milvus envia para a TEI. A predefinição é 32.	64
prompt_name	Não	(Avançado) Especifica uma chave no dicionário de avisos de configuração dos transformadores de frases. Utilizado para determinados modelos que requerem formatos específicos de avisos. O suporte TEI pode ser limitado e depende da configuração do modelo no Hub.	"sua_chave_de_prompt"
ingestion_prompt	Não	(Avançado) Especifica o comando a utilizar durante a fase de inserção (ingestão) de dados. Depende do modelo TEI utilizado; o modelo tem de suportar prompts.	"passage: "
search_prompt	Não	(Avançado) Especifica o comando a utilizar durante a fase de pesquisa. Depende do modelo TEI utilizado; o modelo deve suportar prompts.	"query: "

Próximos passos

Depois de configurar a função de incorporação, consulte a Visão geral da função para obter orientações adicionais sobre a configuração do índice, exemplos de inserção de dados e operações de pesquisa semântica.