Google Gemini

Utilize um modelo de incorporação do Google Gemini com o Milvus, escolhendo um modelo e configurando o Milvus com a sua chave da API Gemini.

Escolher um modelo de incorporação

O Milvus suporta modelos de incorporação fornecidos pelo Google Gemini. Abaixo estão os modelos de incorporação Gemini atualmente disponíveis para referência rápida:

Nome do modelo	Dimensões	Tokens máximos	Descrição
gemini-embedding-001	Predefinição: 3.072 (recomendado: 768, 1.536 ou 3.072)	8,192	Modelo de incorporação de texto com dimensões flexíveis, treinado usando o aprendizado de representação Matryoshka (MRL).
gemini-embedding-2	Predefinição: 3.072 (recomendado: 768, 1.536 ou 3.072)	8,192	O primeiro modelo de incorporação multimodal nativo da Google, que suporta texto, imagens, vídeo, áudio e documentos num espaço de incorporação unificado.

Ambos os modelos são treinados utilizando a técnica de Aprendizagem de Representação Matryoshka (MRL), que permite dimensões de saída flexíveis através do parâmetro dim. Recomenda-se começar com 768 dimensões e aumentar para 1.536 ou 3.072, se necessário. Para obter mais detalhes, consulte Modelos de incorporação Gemini.

Os modelos de incorporação Gemini também suportam um parâmetro de tipo de tarefa que optimiza as incorporações para casos de utilização específicos. Milvus define automaticamente o tipo de tarefa com base na operação:

• Inserir / Upsert: RETRIEVAL_DOCUMENT

• Pesquisar: RETRIEVAL_QUERY

Pode substituir esta definição especificando explicitamente um parâmetro task (por exemplo, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING).

Configurar credenciais

O Milvus tem de saber a sua chave da API Gemini antes de poder pedir incorporações. O Milvus fornece dois métodos para configurar as credenciais:

• Ficheiro de configuração (recomendado): Armazene a chave da API em milvus.yaml para que cada reinicialização e nó a pegue automaticamente.

• Variáveis de ambiente: Injetar a chave no momento da implantação - ideal para o Docker Compose.

Escolha um dos dois métodos abaixo - o arquivo de configuração é mais fácil de manter em bare-metal e VMs, enquanto a rota env-var se encaixa nos fluxos de trabalho do contêiner.

Se uma chave de API para o mesmo fornecedor estiver presente tanto no ficheiro de configuração como numa variável de ambiente, o Milvus utiliza sempre o valor em milvus.yaml e ignora a variável de ambiente.

Opção 1: Ficheiro de configuração (recomendado e de maior prioridade)

Guarde as suas chaves API em milvus.yaml; o Milvus lê-as no arranque e substitui qualquer variável de ambiente para o mesmo fornecedor.

1. Declare as suas chaves em credential:

   Pode listar uma ou várias chaves de API - dê a cada uma delas uma etiqueta que invente e que referenciará mais tarde.

   # milvus.yaml
   credential:
     apikey_dev:            # dev environment
       apikey: <YOUR_DEV_KEY>
     apikey_prod:           # production environment
       apikey: <YOUR_PROD_KEY>    
   

   Colocar as chaves da API aqui torna-as persistentes em todas as reinicializações e permite que você troque as chaves apenas mudando um rótulo.

2. Diga ao Milvus qual chave usar para as chamadas do Gemini

   No mesmo ficheiro, aponte o fornecedor Gemini para a etiqueta que pretende utilizar.

   function:
     textEmbedding:
       providers:
         gemini:
           credential: apikey_dev      # ← choose any label you defined above
   

   Isso vincula uma chave específica a cada solicitação que o Milvus envia ao ponto de extremidade dos embeddings do Gemini.

Opção 2: variável de ambiente

Use este método quando executar o Milvus com o Docker Compose e preferir manter os segredos fora dos arquivos e imagens.

O Milvus recorre à variável de ambiente somente se nenhuma chave para o provedor for encontrada em milvus.yaml.

Variável	Necessária	Descrição
MILVUS_GEMINI_API_KEY	Sim	Torna a chave Gemini disponível dentro de cada contêiner Milvus (ignorado quando uma chave para Gemini existe em milvus.yaml)

No seu arquivo docker-compose.yaml, defina a variável de ambiente MILVUS_GEMINI_API_KEY.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Gemini API key inside the container
    MILVUS_GEMINI_API_KEY: <YOUR_GEMINI_API_KEY>

O bloco environment: injeta a chave apenas no contêiner Milvus, deixando o sistema operacional do host intocado. Para obter detalhes, consulte Configurar o Milvus com o Docker Compose.

Etapa 1: criar uma coleção com uma função de incorporação de texto

Definir campos de esquema

Para usar 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 única cada entidade numa coleção.

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

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

O exemplo seguinte define um esquema com um campo escalar "document" para armazenar dados textuais e um campo vetorial "dense" para armazenar embeddings a serem gerados 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, Gemini's gemini-embedding-001 model outputs 3072-dimensional vectors by default,
# but can be shortened to 768 or 1536 dimensions.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=768)

Definir a função de incorporação de texto

A função de incorporação de texto converte automaticamente os dados brutos armazenados num campo VARCHAR em incorporações e armazena-os no campo vetorial explicitamente definido.

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

# Define embedding function (example: Gemini provider)
text_embedding_function = Function(
    name="gemini_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": "gemini",                       # Embedding model provider
        "model_name": "gemini-embedding-001",       # Embedding model
        # Optional parameters:
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "768",                             # Optional: Output vector dimension (default 3072)
        # "task": "RETRIEVAL_DOCUMENT",             # Optional: Task type for embedding optimization
    }
)

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

Tipos de tarefa suportados para o parâmetro de tarefa:

• RETRIEVAL_DOCUMENT - Optimiza os embeddings para indexação de documentos (predefinição para inserir/upsert).

• RETRIEVAL_QUERY - Otimiza embeddings para recuperação de consulta (padrão para pesquisa).

• SEMANTIC_SIMILARITY - Optimiza os embeddings para medir a semelhança de texto.

• CLASSIFICATION - Optimiza os embeddings para classificação de texto.

• CLUSTERING - Optimiza as incorporações para agrupamento.

Se não for explicitamente definido, o Milvus utiliza automaticamente RETRIEVAL_DOCUMENT durante a inserção/upsert e RETRIEVAL_QUERY durante a pesquisa.

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

Criar a coleção

Crie agora a coleção utilizando 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
)

Passo 2: Inserir dados

Depois de configurar a coleção e o índice, está pronto para inserir os seus dados brutos. Neste processo, só precisa de fornecer o texto em 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.'},
])

Etapa 3: Pesquisar com texto

Após a inserção dos dados, efectue uma pesquisa semântica utilizando o texto de consulta em bruto. 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)

Para mais informações sobre operações de pesquisa e consulta, consulte Pesquisa e consulta vetorial básica.