IA de VoyageCompatible with Milvus 2.6.x

Este tema describe cómo configurar y utilizar las funciones de incrustación de Voyage AI en Milvus.

Elegir un modelo de incrustación

Milvus es compatible con los modelos de incrustación proporcionados por Voyage AI. A continuación se muestran los modelos de incrustación disponibles actualmente para una referencia rápida:

Nombre del modelo	Dimensiones	Fichas máximas	Descripción
voyage-3-large	1.024 (por defecto), 256, 512, 2.048	32,000	La mejor calidad de recuperación general y multilingüe.
voyage-3	1,024	32,000	Optimizado para una calidad de recuperación general y multilingüe. Consulte la entrada del blog para obtener más información.
voyage-3-lite	512	32,000	Optimizado para latencia y coste. Consulte la entrada del blog para obtener más información.
voyage-código-3	1.024 (por defecto), 256, 512, 2.048	32,000	Optimizado para la recuperación de códigos. Consulte la entrada del blog para obtener más información.
voyage-finance-2	1,024	32,000	Optimizado para la recuperación de finanzas y RAG. Consulte la entrada del blog para obtener más información.
voyage-ley-2	1,024	16,000	Optimizado para recuperación legal y RAG. También se ha mejorado el rendimiento en todos los dominios. Consulte la entrada del blog para obtener más información.
voyage-code-2	1,536	16,000	Optimizado para la recuperación de código (un 17% mejor que las alternativas) / Generación anterior de incrustaciones de código. Para más detalles, consulte la entrada del blog.

Para más detalles, consulte Modelos de incrustación de texto.

Configurar credenciales

Milvus debe conocer su clave API Voyage AI antes de poder solicitar incrustaciones. Milvus proporciona dos métodos para configurar las credenciales:

• Archivo de configuración (recomendado): Almacene la clave API en milvus.yaml para que cada reinicio y nodo la recoja automáticamente.

• Variables de entorno: Inyectar la clave en el momento del despliegue, ideal para Docker Compose.

Elija uno de los dos métodos siguientes: el archivo de configuración es más fácil de mantener en máquinas virtuales y máquinas sin infraestructura, mientras que la ruta de las variables de entorno se adapta a los flujos de trabajo de los contenedores.

Opción 1: Archivo de configuración (recomendado y de mayor prioridad)

Mantenga sus claves API en milvus.yaml; Milvus las lee al inicio y anula cualquier variable de entorno para el mismo proveedor.

1. **Declare sus claves en credential:

   Puedes listar una o muchas claves API - dale a cada una una etiqueta que inventes y a la que harás referencia más tarde.

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

   Poner las claves API aquí las hace persistentes a través de reinicios y le permite cambiar las claves con sólo cambiar una etiqueta.

2. Indique a Milvus qué clave debe utilizar para las llamadas de servicio

   En el mismo archivo, indique al proveedor Voyage AI la etiqueta que desea que utilice.

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

   Esto vincula una clave específica a cada solicitud que Milvus envía al punto final de incrustaciones Voyage AI.

Opción 2: Variable de entorno

Utilice este método cuando ejecute Milvus con Docker Compose y prefiera mantener los secretos fuera de los archivos e imágenes.

Milvus recurre a la variable de entorno sólo si no se encuentra ninguna clave para el proveedor en milvus.yaml.

Variable	Requerida	Descripción
MILVUSAI_VOYAGEAI_API_KEY	Sí	Tu clave API Voyage AI válida.

En tu archivo docker-compose.yaml, establece la variable de entorno MILVUSAI_VOYAGEAI_API_KEY.

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

El bloque environment: inyecta la clave sólo en el contenedor Milvus, dejando su sistema operativo anfitrión intacto. Para más detalles, consulte Configurar Milvus con Docker Compose.

Utilizar la función de incrustación

Una vez configuradas las credenciales, siga estos pasos para definir y utilizar las funciones de incrustación.

Paso 1: Definir campos de esquema

Para utilizar una función de incrustación, cree una colección con un esquema específico. Este esquema debe incluir al menos tres campos necesarios:

• El campo primario que identifica de forma única a cada entidad de una colección.

• Un campo escalar que almacena los datos brutos que se van a incrustar.

• Un campo vectorial reservado para almacenar las incrustaciones vectoriales que la función generará para el campo escalar.

El siguiente ejemplo define un esquema con un campo escalar "document" para almacenar datos textuales y un campo vectorial "dense" para almacenar las incrustaciones que generará el módulo Función. Recuerde ajustar la dimensión del vector (dim) para que coincida con la salida del modelo de incrustación elegido.

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)

Paso 2: Añadir la función de incrustación al esquema

El módulo Function de Milvus convierte automáticamente los datos brutos almacenados en un campo escalar en incrustaciones y los almacena en el campo vectorial definido explícitamente.

El ejemplo siguiente añade un módulo Function (voya) que convierte el campo escalar "document" en incrustaciones, almacenando los vectores resultantes en el campo vectorial "dense" definido anteriormente.

Una vez que haya definido su función de incrustación, añádala a su esquema de colección. Esto indica a Milvus que utilice la función de incrustación especificada para procesar y almacenar las incrustaciones de sus datos de texto.

# Define embedding function specifically for embedding model provider
text_embedding_function = Function(
    name="voya",                                  # 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": "voyageai",                   # Must be set to "voyageai"
        "model_name": "voyage-3-large",                 # Specifies the embedding model to use
        # Optional parameters:
        # "credential": "apikey_dev",      # Optional: Credential label specified in milvus.yaml
        # "url": "https://api.voyageai.com/v1/embeddings",     # Defaults to the official endpoint if omitted
        # "dim": "1024"                           # Output dimension of the vector embeddings after truncation
        # "truncation": "true"                    # Whether to truncate the input texts to fit within the context length. Defaults to true.
    }
)

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

Pasos siguientes

Después de configurar la función de incrustación, consulte la Descripción general de la función para obtener orientación adicional sobre la configuración del índice, ejemplos de inserción de datos y operaciones de búsqueda semántica.