Azure OpenAICompatible with Milvus 2.6.x

Este tópico descreve como configurar e usar as funções de incorporação do Azure OpenAI no Milvus.

Escolher um modelo de incorporação

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

Modelo	Dimensões	Tokens máximos	Descrição
incorporação de texto-3-pequeno	Predefinição: 1.536 (truncável para um tamanho de dimensão inferior a 1536)	8,191	Ideal para pesquisa semântica escalável e sensível aos custos - oferece um forte desempenho a um preço mais baixo.
incorporação de texto-3-grande	Predefinição: 3.072 (truncatable para um tamanho de dimensão inferior a 3072)	8,191	Melhor para aplicações que exigem maior precisão de recuperação e representações semânticas mais ricas.
incorporação de texto-ada-002	Fixo: 1.536 (não suporta truncagem)	8,191	Um modelo da geração anterior adequado para pipelines antigos ou cenários que exigem compatibilidade com versões anteriores.

Os modelos de incorporação de terceira geração(text-embedding-3) suportam a redução do tamanho da incorporação através de um parâmetro dim. Normalmente, as incorporações maiores são mais dispendiosas do ponto de vista da computação, da memória e do armazenamento. A possibilidade de ajustar o número de dimensões permite um maior controlo sobre o custo e o desempenho globais. Para obter mais detalhes sobre cada modelo, consulte Embeddings.

Configurar credenciais

Milvus deve saber sua chave de API do Azure OpenAI antes de poder solicitar embeddings. O Milvus fornece dois métodos para configurar 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.

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

Manter 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 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 através de reinicializações e permite-lhe mudar de chave apenas alterando uma etiqueta.

2. Diga ao Milvus qual a chave a utilizar para as chamadas do Azure OpenAI

   No mesmo ficheiro, aponte o fornecedor do Azure OpenAI para a etiqueta que pretende utilizar.

   function:
     textEmbedding:
       providers:
         azure_openai:
           credential: apikey_dev      # ← choose any label you defined above
           resource_name:  # Your azure openai resource name
           # url: # Your azure openai embedding url
   

   Isto liga uma chave específica a cada pedido que Milvus envia para o ponto final de incorporação do Azure OpenAI.

Opção 2: Variáveis de ambiente

Utilize este método quando executa Milvus com Docker Compose e prefere manter segredos fora de ficheiros e imagens.

O Milvus recorre à variável de ambiente apenas se não for encontrada nenhuma chave para o fornecedor em milvus.yaml.

Variável	Necessária	Descrição
MILVUSAI_AZURE_OPENAI_API_KEY	Sim	Torna a chave do Azure OpenAI disponível dentro de cada contentor do Milvus (ignorada quando existe uma chave para o Azure OpenAI em milvus.yaml )
MILVUSAI_AZURE_OPENAI_RESOURCE_NAME	Sim	O nome do seu recurso Azure OpenAI, conforme definido quando criou o seu recurso de serviço Azure OpenAI.

No seu ficheiro docker-compose.yaml, defina as variáveis de ambiente.

# docker-compose.yaml (standalone service section)
standalone:
  # ... other configurations ...
  environment:
    # ... other environment variables ...
    # Set the environment variable pointing to the Azure OpenAI API key inside the container
    MILVUSAI_AZURE_OPENAI_API_KEY: <MILVUSAI_AZURE_OPENAI_API_KEY>
    MILVUSAI_AZURE_OPENAI_RESOURCE_NAME: <MILVUSAI_AZURE_OPENAI_RESOURCE_NAME>

O bloco environment: injecta a chave apenas no contentor Milvus, deixando o seu SO anfitrião intocado. Para obter detalhes, consulte Configurar o Milvus com o Docker Compose.

Usar a função de incorporação

Depois que as credenciais forem configuradas, siga estas etapas para definir e usar funções de incorporação.

Etapa 1: 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 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 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

# 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.
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

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

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

# Define embedding function specifically for Azure OpenAI provider
text_embedding_function = Function(
    name="azopenai",                                # 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 field(s) for storing embeddings
    params={                                        # Provider-specific embedding parameters
        "provider": "azure_openai",                 # Embedding provider name (must be "azure_openai")
        "model_name": "zilliz-text-embedding-3-small",      # Model should be set to the deployment name you chose when you deployed the embedding model
        # Optional parameters (only specify if necessary):
        # "url": "https://{resource_name}.openai.azure.com/" # Optional: Your Azure OpenAI service endpoint
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "dim": "1536",                            # Optional: Shorten the output vector dimension
        # "user": "user123",                        # Optional: identifier for API tracking
    }
)

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

Passos seguintes

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.