Visão geral da função de incorporaçãoCompatible with Milvus 2.6.x

O módulo «Função» do Milvus permite-lhe transformar dados de texto brutos em representações vetoriais, recorrendo automaticamente a prestadores de serviços de incorporação externos (como a OpenAI, o AWS Bedrock, o Google Vertex AI, etc.). Com o módulo «Função», já não é necessário interagir manualmente com as APIs de incorporação — o Milvus trata de todo o processo de envio de pedidos aos fornecedores, receção das incorporações e armazenamento das mesmas nas suas coleções. Para a pesquisa semântica, basta fornecer apenas os dados brutos da consulta, e não um vetor de consulta. O Milvus gera o vetor de consulta com o mesmo modelo que utilizou para a ingestão, compara-o com os vetores armazenados e devolve os resultados mais relevantes.

Limites

• Qualquer campo de entrada que o módulo Function incorpore deve conter sempre um valor; se for fornecido um valor nulo, o módulo irá gerar um erro.

• O módulo «Function» processa apenas os campos explicitamente definidos no esquema da coleção; não gera representações para campos dinâmicos.

• Os campos de entrada a incorporar devem ser do tipo « VARCHAR ».

• O módulo «Function» pode incorporar um campo de entrada para:

  • FLOAT_VECTOR

  • INT8_VECTOR

  Não são suportadas conversões para « BINARY_VECTOR », « FLOAT16_VECTOR » ou « BFLOAT16_VECTOR ».

Provedores de serviços de incorporação suportados

Provedor	Modelos típicos	Tipo de incorporação	Método de autenticação
OpenAI	text-embedding-3-*	FLOAT_VECTOR	Chave API
Azure OpenAI	Baseada na implementação	FLOAT_VECTOR	Chave da API
DashScope	text-embedding-v3	FLOAT_VECTOR	Chave API
Yandex Cloud	Modelos de vetorização de texto do Yandex Cloud AI Studio	FLOAT_VECTOR	Chave da API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Par AK/SK
Vertex AI	text-embedding-005	FLOAT_VECTOR	Conta de serviço GCP Credencial JSON
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Chave API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Chave API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	Chave API
Hugging Face TEI	Qualquer modelo servido pelo TEI	FLOAT_VECTOR	Chave API opcional
Hugging Face	Modelos disponibilizados através de hf-inference para extração de características	FLOAT_VECTOR	Chave de API

Como funciona

O diagrama seguinte mostra como a Função funciona no Milvus.

1. Texto de entrada: os utilizadores inserem dados brutos (por exemplo, documentos) no Milvus.

2. Gerar embeddings: O módulo «Função» no Milvus chama automaticamente o fornecedor de modelos configurado para converter os dados brutos em embeddings vetoriais.

3. Armazenar representações: As representações resultantes são armazenadas em campos vetoriais explicitamente definidos nas coleções do Milvus.

4. Texto da consulta: Os utilizadores enviam consultas de texto ao Milvus.

5. Pesquisa semântica: O Milvus converte internamente as consultas em representações vetoriais, realiza pesquisas de similaridade em relação às representações armazenadas e recupera resultados relevantes.

6. Devolução de resultados: O Milvus devolve os resultados mais relevantes à aplicação.

Visão geral da função de incorporação

Configurar credenciais

Antes de utilizar uma função de representação com o Milvus, configure as credenciais do serviço de representação para o acesso ao Milvus.

O Milvus permite-lhe fornecer as credenciais do serviço de representação de duas formas:

• Ficheiro de configuração (milvus.yaml):

  O exemplo neste tópico demonstra a configuração recomendada utilizando milvus.yaml.

• Variáveis de ambiente:

  Para obter detalhes sobre a configuração de credenciais através de variáveis de ambiente, consulte a documentação do fornecedor do serviço de incorporação (por exemplo, OpenAI ou Azure OpenAI).

O diagrama seguinte ilustra o processo de configuração das credenciais através do ficheiro de configuração do Milvus (milvus.yaml) e, em seguida, a chamada da Função no Milvus.

Configuração de credenciais no Overflow

Passo 1: Adicionar credenciais ao ficheiro de configuração do Milvus

No seu ficheiro milvus.yaml, edite o bloco « credential » com entradas para cada fornecedor ao qual precisa de aceder:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

Passo 2: Configurar as definições do fornecedor

No mesmo ficheiro de configuração (milvus.yaml), edite o bloco function para indicar ao Milvus qual a chave a utilizar para incorporar chamadas de serviço:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Para mais informações sobre como aplicar a configuração do Milvus, consulte «Configurar o Milvus em tempo real».

Utilizar a função de incorporação

Depois de configurar as credenciais no seu ficheiro de configuração do Milvus, siga estes passos para definir e utilizar funções de incorporação.

Passo 1: Definir campos do 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 obrigatórios:

• O campo primário que identifica de forma única 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 vetoriais 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" para armazenar as incorporações a serem geradas pelo módulo «Function». Lembre-se de definir a dimensão do vetor (dim) de forma a corresponder à saída do modelo de incorporação escolhido.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

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

O módulo «Function» no 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» (openai_embedding) que converte o campo escalar « "document" » em embeddings, armazenando os vetores resultantes no campo vetorial « "dense" » definido anteriormente.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_embedding",                  # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING, # Type of embedding function
    input_field_names=["document"],           # Scalar field to embed
    output_field_names=["dense"],             # Vector field to store embeddings
    params={                                  # Provider-specific configuration (highest priority)
        "provider": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

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

// java

// nodejs

// go

# restful

Parâmetro	Descrição	Valor de exemplo
name	Identificador único da função de embedding no Milvus.	"openai_embedding"
function_type	Tipo de função utilizada. Para a incorporação de texto, defina o valor como FunctionType.TEXTEMBEDDING. Nota: O Milvus aceita « FunctionType.BM25 » (para transformação de incorporação esparsa) e « FunctionType.RERANK » (para reclassificação) para este parâmetro. Consulte a Visão Geral da Pesquisa de Texto Completo e do Decay Ranker para obter mais detalhes.	FunctionType.TEXTEMBEDDING
input_field_names	Campo escalar que contém os dados brutos a serem incorporados. Atualmente, este parâmetro aceita apenas um nome de campo.	["document"]
output_field_names	Campo vetorial para armazenar as incorporações geradas. Atualmente, este parâmetro aceita apenas um nome de campo.	["dense"]
params	Dicionário que contém as configurações de incorporação. Nota: Os parâmetros dentro de « params » variam consoante os fornecedores de modelos de incorporação.	{...}
provider	O fornecedor do modelo de incorporação.	"openai"
model_name	Especifica qual o modelo de incorporação a utilizar.	"text-embedding-3-small"
credential	O rótulo de uma credencial definida na secção de nível superior « credential: » de milvus.yaml. Quando fornecida, o Milvus recupera o par de chaves ou token de API correspondente e assina o pedido no lado do servidor. Quando omitido (None), o Milvus recorre à credencial explicitamente configurada para o fornecedor do modelo de destino em milvus.yaml. Se o rótulo for desconhecido ou se a chave referenciada estiver em falta, a chamada falha.	"apikey1"
dim	O número de dimensões para as incorporações de saída. Para os modelos de terceira geração da OpenAI, pode encurtar o vetor completo para reduzir o custo e a latência sem uma perda significativa de informação semântica. Para mais informações, consulte a publicação no blogue de anúncios da OpenAI. Nota: Se encurtar a dimensão do vetor, certifique-se de que o valor « dim » especificado no método « add_field » do esquema para o campo vetorial corresponde à dimensão de saída final da sua função de incorporação.	"1536"
user	Um identificador ao nível do utilizador para monitorizar a utilização da API.	"user123"

Passo 3: Configurar o índice

Após definir o esquema com os campos necessários e a função incorporada, configure o índice para a sua coleção. Para simplificar este processo, utilize « AUTOINDEX » como « index_type », uma opção que permite ao Milvus escolher e configurar o tipo de índice mais adequado com base na estrutura dos seus dados.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

// java

// nodejs

// go

# restful

Passo 4: Criar a coleção

Agora, crie a coleção utilizando os parâmetros de esquema e de índice definidos.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

// java

// nodejs

// go

# restful

Passo 5: Inserir dados

Depois de configurar a sua coleção e o seu índice, está pronto para inserir os seus dados brutos. Neste processo, basta fornecer o texto bruto. O módulo «Function» que definimos anteriormente gera automaticamente o vetor esparso correspondente para cada entrada de texto.

# Insert sample documents
client.insert('demo', [
    {'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.'},
])

// java

// nodejs

// go

# restful

Passo 6: Efetuar pesquisa vetorial

Após a inserção dos dados, efetue uma pesquisa semântica utilizando o texto bruto da consulta. O Milvus converte automaticamente a sua consulta num vetor de incorporação, recupera documentos relevantes com base na semelhança e devolve os resultados mais pertinentes.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

// java

// nodejs

// go

# restful

Para mais informações sobre operações de pesquisa e consulta, consulte «Pesquisa e consulta vetoriais básicas ».

Perguntas frequentes

Qual é a diferença entre configurar credenciais no ficheiro `milvus.yaml` e através de variáveis de ambiente?

Ambos os métodos funcionam, mas a utilização de « milvus.yaml » é a abordagem recomendada, uma vez que proporciona uma gestão centralizada das credenciais e uma nomenclatura consistente das credenciais em todos os fornecedores. Ao utilizar variáveis de ambiente, os nomes das variáveis variam consoante o fornecedor do serviço de incorporação; por isso, consulte a página dedicada de cada fornecedor para compreender os nomes específicos das variáveis de ambiente necessárias (por exemplo, OpenAI ou Azure OpenAI).

O que acontece se eu não especificar um parâmetro de credencial na definição da função?

O Milvus segue esta ordem de resolução de credenciais:

1. Primeiro, procura a credencial predefinida configurada para esse fornecedor no ficheiro « milvus.yaml »
2. Se não existir nenhuma credencial predefinida no ficheiro milvus.yaml, recorre às variáveis de ambiente (se estiverem configuradas)
3. Se nem as credenciais do ficheiro « milvus.yaml » nem as variáveis de ambiente estiverem configuradas, o Milvus irá gerar um erro

Como posso verificar se as representações estão a ser geradas corretamente?

Pode verificar da seguinte forma:

1. Consultar a sua coleção após a inserção para verificar se o campo vetorial contém dados
2. Verificar se o comprimento do campo vetorial corresponde às dimensões esperadas
3. Realizar uma pesquisa de similaridade simples para verificar se as representações produzem resultados significativos

Quando realizo uma pesquisa de similaridade, posso utilizar um vetor de consulta em vez de texto bruto?

Sim, pode utilizar vetores de consulta pré-calculados em vez de texto bruto para a pesquisa de similaridade. Embora o módulo de função converta automaticamente as consultas de texto bruto em representações vetoriais, também pode fornecer diretamente dados vetoriais ao parâmetro « data » na sua operação de pesquisa. Nota: O tamanho da dimensão do vetor de consulta fornecido deve ser consistente com o tamanho da dimensão das representações vetoriais geradas pelo seu módulo «Function».

Exemplo:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

// java

// nodejs

// go

# restful