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

O módulo Function no Milvus permite-lhe transformar dados de texto em bruto em embeddings vectoriais, chamando automaticamente fornecedores externos de serviços de embedding (como OpenAI, AWS Bedrock, Google Vertex AI, etc.). Com o módulo Function, já não é necessário estabelecer uma interface manual com as APIs de incorporação - o Milvus trata de todo o processo de envio de pedidos aos fornecedores, receção de incorporação e armazenamento nas suas colecções. Para a pesquisa semântica, é necessário fornecer apenas dados de consulta em bruto, 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 vectores armazenados e devolve os resultados mais relevantes.

Limites

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

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

• Os campos de entrada a serem incorporados devem ser do tipo VARCHAR.

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

  • FLOAT_VECTOR

  • INT8_VECTOR

  As conversões para BINARY_VECTOR, FLOAT16_VECTOR, ou BFLOAT16_VECTOR não são suportadas.

Fornecedores de serviços de incorporação suportados

Fornecedor	Modelos típicos	Tipo de incorporação	Método de autenticação
OpenAI	incorporação de texto-3-*	FLOAT_VECTOR	Chave da API
OpenAI do Azure	Baseado na implementação	FLOAT_VECTOR	Chave de API
DashScope	incorporação de texto-v3	FLOAT_VECTOR	Chave de API
Base de dados	amazon.titan-embeded-text-v2	FLOAT_VECTOR	Par AK/SK
Vértice AI	texto-incorporação-005	FLOAT_VECTOR	Credencial JSON da conta de serviço GCP
IA do Voyage	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Chave da API
Coesão	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Chave da API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	Chave API
Cara de abraço	Qualquer modelo servido por TEI	FLOAT_VECTOR	Chave API opcional

Como é que funciona

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

1. Texto de entrada: Os utilizadores inserem dados em bruto (por exemplo, documentos) no Milvus.

2. Gerar embeddings: O módulo Function do Milvus chama automaticamente o fornecedor do modelo configurado para converter os dados em bruto em embeddings vectoriais.

3. Armazenar embeddings: Os embeddings resultantes são armazenados em campos vectoriais explicitamente definidos nas colecções do Milvus.

4. Consultar texto: Os utilizadores submetem consultas de texto ao Milvus.

5. Pesquisa semântica: O Milvus converte internamente as consultas em embeddings vectoriais, efectua pesquisas de semelhança com os embeddings armazenados e obtém os resultados relevantes.

6. Devolver resultados: O Milvus devolve à aplicação os melhores resultados correspondentes.

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

Configurar credenciais

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

O Milvus permite-lhe fornecer credenciais de serviço de incorporação de duas formas:

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

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

• Variáveis de ambiente:

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

O diagrama a seguir mostra o processo de configuração de credenciais por meio do arquivo de configuração do Milvus (milvus.yaml) e, em seguida, a chamada da Função no Milvus.

Estouro de configuração de credenciais

Etapa 1: adicionar credenciais ao arquivo de configuração do Milvus

No seu ficheiro milvus.yaml, edite o bloco credential com entradas para cada fornecedor a que 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 obter mais informações sobre como aplicar a configuração do Milvus, consulte Configurar o Milvus em tempo real.

Usar a função de incorporação

Assim que as credenciais estiverem configuradas no ficheiro de configuração do Milvus, siga estes passos para definir e utilizar 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" para armazenar as incorporaçõ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

# 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 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 (openai_embedding) que converte o campo escalar "document" em embeddings, armazenando os vectores 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	Exemplo Valor
name	Identificador único para a função de incorporação no Milvus.	"openai_embedding"
function_type	Tipo de função utilizada. Para a incorporação de texto, definir o valor para FunctionType.TEXTEMBEDDING. Nota: Milvus aceita FunctionType.BM25 (para transformação de incorporação esparsa) e FunctionType.RERANK (para reranking) para este parâmetro. Consulte Pesquisa de texto integral e Visão geral do Decay Ranker para obter 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 em 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	A etiqueta de uma credencial definida na secção de nível superior credential: de milvus.yaml. Quando fornecido, o Milvus recupera o par de chaves correspondente ou o token da API 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 a etiqueta for desconhecida ou a chave referenciada estiver em falta, a chamada falha.	"apikey1"
dim	O número de dimensões para os embeddings de saída. Para os modelos de terceira geração do OpenAI, é possível encurtar o vetor completo para reduzir o custo e a latência sem uma perda significativa de informações semânticas. Para obter mais informações, consulte a publicação do blogue de anúncio 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 do vetor corresponde à dimensão de saída final da sua função de incorporação.	"1536"
user	Um identificador de nível de utilizador para acompanhar a utilização da API.	"user123"

Passo 3: Configurar o índice

Depois de 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 coleção

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

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

// java

// nodejs

// go

# restful

Etapa 5: inserir dados

Depois de configurar sua coleção e índice, você está pronto para inserir seus dados brutos. Nesse processo, você só precisa 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

Etapa 6: realizar pesquisa de vetor

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

# 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 obter mais informações sobre operações de pesquisa e consulta, consulte Pesquisa e consulta vetorial básica.

PERGUNTAS FREQUENTES

Qual é a diferença entre configurar credenciais em milvus.yaml e variáveis de ambiente?

Ambos os métodos funcionam, mas usar milvus.yaml é a abordagem recomendada, pois fornece gerenciamento centralizado de credenciais e nomeação consistente de credenciais em todos os provedores. Ao usar variáveis de ambiente, os nomes das variáveis variam dependendo do provedor de serviços de incorporação, portanto, consulte a página dedicada de cada provedor para entender os nomes específicos de variáveis de ambiente necessários (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, ele procura a credencial padrão configurada para esse provedor no arquivo milvus.yaml
2. Se não existir nenhuma credencial padrão em milvus.yaml, ele recorre às variáveis de ambiente (se configuradas)
3. Se nem as credenciais milvus.yaml nem as variáveis de ambiente estiverem configuradas, o Milvus apresentará um erro

Como posso verificar se os embeddings estão a ser gerados corretamente?

Pode verificar:

1. Consultando a sua coleção após a inserção para ver se o campo vetorial contém dados
2. Verificar se o comprimento do campo vetorial corresponde às dimensões esperadas
3. Efectuando uma pesquisa de semelhança simples para verificar se os embeddings produzem resultados significativos

Quando efectuo uma pesquisa por semelhança, posso utilizar um vetor de consulta em vez de texto em bruto?

Sim, pode utilizar vectores de consulta pré-computados em vez de texto em bruto para a pesquisa de semelhanças. Embora o módulo Function converta automaticamente as consultas de texto bruto em embeddings, também pode fornecer diretamente dados de vetor 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 dos embeddings de vetor gerados pelo 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