CohereCompatible with Milvus 2.6.x

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

Escolha um modelo de incorporação

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

Nome do modelo	Dimensões	Tokens máximos	Descrição
embed-english-v3.0	1,024	512	Um modelo que permite que o texto seja classificado ou transformado em embeddings. Apenas em inglês.
embed-multilingual-v3.0	1,024	512	Fornece suporte para classificação e incorporação multilíngüe. Veja os idiomas suportados aqui.
embed-english-light-v3.0	384	512	Uma versão mais pequena e mais rápida de embed-english-v3.0. Quase tão capaz, mas muito mais rápida. Apenas em inglês.
embed-multilingual-light-v3.0	384	512	Uma versão mais pequena e mais rápida de embed-multilingual-v3.0. Quase com a mesma capacidade, mas muito mais rápida. Suporta vários idiomas.
embed-english-v2.0	4,096	512	Modelo de embeddings mais antigo que permite que o texto seja classificado ou transformado em embeddings. Apenas em inglês.
embed-english-light-v2.0	1,024	512	Uma versão mais pequena e mais rápida do embed-english-v2.0. Quase tão capaz, mas muito mais rápida. Apenas em inglês.
embed-multilingual-v2.0	768	256	Fornece classificação multilingue e suporte para incorporação. Veja os idiomas suportados aqui.

Para obter detalhes, consulte os modelos de incorporação do Cohere.

Configurar credenciais

O Milvus precisa saber sua chave de API do Cohere para poder solicitar incorporações. O Milvus fornece dois métodos para configurar as credenciais:

• Arquivo de configuração (recomendado): Armazene a chave de 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. Dizer ao Milvus qual a chave a utilizar para as chamadas OpenAI

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

   function:
     textEmbedding:
       providers:
         cohere:
           credential: apikey_dev      # ← choose any label you defined above
           # url: https://api.cohere.com/v2/embed   # (optional) custom url
   

   Isso vincula uma chave específica a cada solicitação que o Milvus envia ao endpoint de embeddings do Cohere.

Opção 2: variável de ambiente

Utilize este método quando executar o Milvus com o Docker Compose e preferir manter os segredos fora dos ficheiros e das 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
MILVUSAI_COHERE_API_KEY	Sim	A sua chave de API Cohere válida.

No seu ficheiro docker-compose.yaml, defina a variável de ambiente MILVUSAI_COHERE_API_KEY.

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

O bloco environment: injeta a chave apenas no contêiner do Milvus, deixando o sistema operacional do host 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=1024)

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 (cohere_func) que converte o campo escalar "document" em embeddings, armazenando os vectores resultantes no campo vetorial "dense" 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.

# Define embedding function specifically for embedding model provider
text_embedding_function = Function(
    name="cohere_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 field(s) for storing embeddings
    params={                                            # Provider-specific embedding parameters (function-level)
        "provider": "cohere",                           # Must be set to "cohere"
        "model_name": "embed-english-v3.0",             # Specifies the embedding model to use
        # Optional parameters:
        # "credential": "apikey_dev",               # Optional: Credential label specified in milvus.yaml
        # "url": "https://api.cohere.com/v2/embed",     # Defaults to the official endpoint if omitted
        # "truncate": "NONE",                           # Specifies how the API will handle inputs longer than the maximum token length.
    }
)

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

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.