Visión general de la función de incrustaciónCompatible with Milvus 2.6.x

El módulo Function de Milvus le permite transformar datos de texto sin procesar en incrustaciones vectoriales llamando automáticamente a proveedores externos de servicios de incrustación (como OpenAI, AWS Bedrock, Google Vertex AI, etc.). Con el módulo Function, ya no tendrá que interactuar manualmente con las API de incrustación: Milvus se encarga de todo el proceso de envío de solicitudes a los proveedores, recepción de incrustaciones y almacenamiento en sus colecciones. Para la búsqueda semántica, sólo necesita proporcionar datos de consulta sin procesar, no un vector de consulta. Milvus genera el vector de consulta con el mismo modelo que utilizó para la ingesta, lo compara con los vectores almacenados y devuelve los resultados más relevantes.

Límites

• Cualquier campo de entrada que incorpore el módulo Function debe contener siempre un valor; si se proporciona un valor nulo, el módulo lanzará un error.

• El módulo Function sólo procesa campos definidos explícitamente en el esquema de la colección; no genera incrustaciones para campos dinámicos.

• Los campos de entrada que se incrusten deben ser del tipo VARCHAR.

• El módulo Function puede incrustar un campo de entrada en:

  • FLOAT_VECTOR

  • INT8_VECTOR

  No se admiten conversiones a BINARY_VECTOR, FLOAT16_VECTOR o BFLOAT16_VECTOR.

Proveedores de servicios de incrustación admitidos

Proveedor	Modelos típicos	Tipo de incrustación	Método de autenticación
OpenAI	incrustación de texto-3-*	FLOAT_VECTOR	Clave API
Azure OpenAI	Basado en despliegue	FLOAT_VECTOR	Clave API
DashScope	text-embedding-v3	FLOAT_VECTOR	Clave API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Par AK/SK
Vértice AI	text-embedding-005	FLOAT_VECTOR	Credencial JSON de cuenta de servicio GCP
IA Voyage	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Clave API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Clave API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	Clave API
Cara abrazada	Cualquier modelo servido por TEI	FLOAT_VECTOR	Clave API opcional

Cómo funciona

El siguiente diagrama muestra cómo funciona la Función en Milvus.

1. Texto de entrada: Los usuarios insertan datos en bruto (por ejemplo, documentos) en Milvus.

2. Generación de incrustaciones: El módulo Function dentro de Milvus llama automáticamente al proveedor de modelos configurado para convertir los datos brutos en incrustaciones vectoriales.

3. Almacenar incrustaciones: Las incrustaciones resultantes se almacenan en campos vectoriales definidos explícitamente dentro de las colecciones de Milvus.

4. Consulta de texto: Los usuarios envían consultas de texto a Milvus.

5. Búsqueda semántica: Milvus convierte internamente las consultas en incrustaciones vectoriales, realiza búsquedas de similitud con las incrustaciones almacenadas y recupera los resultados relevantes.

6. Devolución de resultados: Milvus devuelve a la aplicación los resultados más similares.

Descripción general de la función de incrustación

Configurar credenciales

Antes de utilizar una función de incrustación con Milvus, configure las credenciales del servicio de incrustación para el acceso a Milvus.

Milvus le permite suministrar credenciales de servicio de incrustación de dos maneras:

• Archivo de configuración (milvus.yaml):

  El ejemplo de este tema muestra la configuración recomendada utilizando milvus.yaml.

• Variables de entorno:

  Para obtener detalles sobre la configuración de credenciales mediante variables de entorno, consulte la documentación del proveedor del servicio de incrustación (por ejemplo, OpenAI o Azure OpenAI).

El siguiente diagrama muestra el proceso de configuración de credenciales a través del archivo de configuración de Milvus (milvus.yaml) y luego llamando a la Función dentro de Milvus.

Desbordamiento de configuración de credenciales

Paso 1: Agregar credenciales al archivo de configuración de Milvus

En su archivo milvus.yaml, edite el bloque credential con entradas para cada proveedor al que necesite acceder:

# 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>

Paso 2: Configure los ajustes del proveedor

En el mismo archivo de configuración (milvus.yaml), edite el bloque function para indicar a Milvus qué clave debe utilizar para incrustar las llamadas de servicio:

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 más información sobre cómo aplicar la configuración de Milvus, consulte Configurar Milvus sobre la marcha.

Utilizar la función de incrustación

Una vez configuradas las credenciales en su archivo de configuración de Milvus, 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 almacene 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.
# 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

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 siguiente ejemplo añade un módulo Function (openai_embedding) que convierte el campo escalar "document" en incrustaciones, almacenando los vectores resultantes en el campo vectorial "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	Descripción	Ejemplo Valor
name	Identificador único para la función de incrustación dentro de Milvus.	"openai_embedding"
function_type	Tipo de función utilizada. Para la incrustación de texto, establezca el valor en FunctionType.TEXTEMBEDDING. Nota: Milvus acepta FunctionType.BM25 (para transformación de incrustación dispersa) y FunctionType.RERANK (para reranking) para este parámetro. Refiérase a la Búsqueda de Texto Completo y Decay Ranker Overview para más detalles.	FunctionType.TEXTEMBEDDING
input_field_names	Campo escalar que contiene los datos en bruto que se van a incrustar. Actualmente, este parámetro sólo acepta un nombre de campo.	["document"]
output_field_names	Campo vectorial para almacenar las incrustaciones generadas. Actualmente, este parámetro sólo acepta un nombre de campo.	["dense"]
params	Diccionario que contiene las configuraciones de incrustación. Nota: Los parámetros de params varían en función de los proveedores de modelos de incrustación.	{...}
provider	El proveedor del modelo de incrustación.	"openai"
model_name	Especifica qué modelo de incrustación utilizar.	"text-embedding-3-small"
credential	La etiqueta de una credencial definida en la sección de nivel superior credential: de milvus.yaml. Cuando se proporciona, Milvus recupera el par de claves o token de API coincidente y firma la solicitud en el lado del servidor. Cuando se omite (None), Milvus vuelve a la credencial configurada explícitamente para el proveedor del modelo de destino en milvus.yaml. Si la etiqueta es desconocida o falta la clave referenciada, la llamada falla.	"apikey1"
dim	El número de dimensiones para las incrustaciones de salida. Para los modelos de tercera generación de OpenAI, se puede acortar el vector completo para reducir el coste y la latencia sin una pérdida significativa de información semántica. Para más información, consulte la entrada del blog del anuncio de OpenAI. Nota: Si acorta la dimensión del vector, asegúrese de que el valor dim especificado en el método add_field del esquema para el campo vectorial coincide con la dimensión de salida final de su función de incrustación.	"1536"
user	Un identificador a nivel de usuario para realizar un seguimiento del uso de la API.	"user123"

Paso 3: Configurar el índice

Tras definir el esquema con los campos necesarios y la función incorporada, configure el índice para su colección. Para simplificar este proceso, utilice AUTOINDEX como index_type, una opción que permite a Milvus elegir y configurar el tipo de índice más adecuado en función de la estructura de sus datos.

# 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

Paso 4: Crear la colección

Ahora cree la colección utilizando el esquema y los 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

Paso 5: Insertar datos

Después de configurar tu colección e índice, estás listo para insertar tus datos sin procesar. En este proceso, sólo necesitas proporcionar el texto sin procesar. El módulo Function que definimos anteriormente genera automáticamente el vector disperso correspondiente 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

Paso 6: Realizar la búsqueda de vectores

Después de insertar los datos, realice una búsqueda semántica utilizando el texto de consulta en bruto. Milvus convierte automáticamente su consulta en un vector de incrustación, recupera los documentos relevantes basándose en la similitud y devuelve los resultados más coincidentes.

# 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 obtener más información sobre las operaciones de búsqueda y consulta, consulte Búsqueda y consulta básica de vectores.

PREGUNTAS FRECUENTES

¿Cuál es la diferencia entre configurar las credenciales en milvus.yaml o en variables de entorno?

Ambos métodos funcionan, pero el uso de milvus.yaml es el enfoque recomendado, ya que proporciona una gestión centralizada de credenciales y una nomenclatura de credenciales coherente en todos los proveedores. Cuando se utilizan variables de entorno, los nombres de las variables varían en función del proveedor de servicios de incrustación, así que consulte la página dedicada de cada proveedor para comprender los nombres específicos de las variables de entorno necesarios (por ejemplo, OpenAI o Azure OpenAI).

¿Qué pasa si no especifico un parámetro de credencial en la definición de la función?

Milvus sigue este orden de resolución de credenciales:

1. Primero, busca la credencial por defecto configurada para ese proveedor en el archivo milvus.yaml
2. Si no existe ninguna credencial por defecto en milvus.yaml, recurre a las variables de entorno (si están configuradas).
3. Si no están configuradas ni las credenciales de milvus.yaml ni las variables de entorno, Milvus arrojará un error.

¿Cómo puedo verificar que las incrustaciones se están generando correctamente?

Puede comprobarlo

1. Consultando su colección después de la inserción para ver si el campo vectorial contiene datos
2. Comprobando que la longitud del campo vectorial coincide con las dimensiones esperadas
3. Realizando una simple búsqueda de similitud para verificar que las incrustaciones producen resultados significativos.

Al realizar una búsqueda por similitud, ¿puedo utilizar un vector de consulta en lugar de texto sin procesar?

Sí, puede utilizar vectores de consulta precalculados en lugar de texto sin procesar para la búsqueda de similitudes. Aunque el módulo Function convierte automáticamente las consultas de texto sin procesar en incrustaciones, también puede proporcionar directamente datos vectoriales al parámetro data en su operación de búsqueda. Nota: el tamaño del vector de consulta proporcionado debe coincidir con el tamaño de las incrustaciones vectoriales generadas por el módulo Function.

Ejemplo

# 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