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

El módulo «Function» de Milvus te permite transformar datos de texto sin procesar en representaciones vectoriales mediante la llamada automática a proveedores de servicios de incrustación externos (como OpenAI, AWS Bedrock, Google Vertex AI, etc.). Con el módulo «Función», ya no es necesario interactuar manualmente con las API de incrustación: Milvus se encarga de todo el proceso de enviar solicitudes a los proveedores, recibir las incrustaciones y almacenarlas en tus colecciones. Para la búsqueda semántica, solo tienes que proporcionar los datos de consulta sin procesar, no un vector de consulta. Milvus genera el vector de consulta con el mismo modelo que utilizaste para la ingesta, lo compara con los vectores almacenados y devuelve los resultados más relevantes.

Límites

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

• El módulo «Function» solo procesa los campos que están definidos explícitamente en el esquema de la colección; no genera representaciones para campos dinámicos.

• Los campos de entrada que se vayan a incrustar deben ser del tipo « VARCHAR ».

• El módulo «Function» puede integrar un campo de entrada para:

  • FLOAT_VECTOR

  • INT8_VECTOR

  No se admiten conversiones a « BINARY_VECTOR », « FLOAT16_VECTOR » o « BFLOAT16_VECTOR ».

Proveedores de servicios de incrustación compatibles

Proveedor	Modelos típicos	Tipo de integración	Método de autenticación
OpenAI	text-embedding-3-*	FLOAT_VECTOR	Clave de API
Azure OpenAI	Basada en la implementación	FLOAT_VECTOR	Clave de API
DashScope	text-embedding-v3	FLOAT_VECTOR	Clave de API
Yandex Cloud	Modelos de vectorización de texto de Yandex Cloud AI Studio	FLOAT_VECTOR	Clave de API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Par AK/SK
Vertex AI	text-embedding-005	FLOAT_VECTOR	Cuenta de servicio de GCP Credencial JSON
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	Clave de API
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Clave de API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	Clave de API
Hugging Face TEI	Cualquier modelo alojado en TEI	FLOAT_VECTOR	Clave de API opcional
Hugging Face	Modelos alojados en hf-inference para la extracción de características	FLOAT_VECTOR	Clave de API

Cómo funciona

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

1. Texto de entrada: los usuarios introducen datos sin procesar (por ejemplo, documentos) en Milvus.

2. Generación de representaciones vectoriales: el módulo «Function» de Milvus invoca automáticamente al proveedor de modelos configurado para convertir los datos sin procesar en representaciones vectoriales.

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

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

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

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

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

Configurar credenciales

Antes de utilizar una función de representación con Milvus, configura las credenciales del servicio de representación para que Milvus pueda acceder a él.

Milvus te permite proporcionar las credenciales del servicio de incrustación de dos formas:

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

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

• Variables de entorno:

  Para obtener más información sobre cómo configurar las credenciales mediante variables de entorno, consulta la documentación del proveedor del servicio de integración (por ejemplo, OpenAI o Azure OpenAI).

El siguiente diagrama muestra el proceso de configuración de las credenciales mediante el archivo de configuración de Milvus (milvus.yaml) y, a continuación, la llamada a la función dentro de Milvus.

Configuración de credenciales en Overflow

Paso 1: Añadir credenciales al archivo de configuración de Milvus

En el archivo milvus.yaml, edita el bloque « credential » con las entradas correspondientes a cada proveedor al que necesites 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: Configurar los ajustes del proveedor

En el mismo archivo de configuración (milvus.yaml), edita el bloque function para indicar a Milvus qué clave debe utilizar para integrar las llamadas al 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 obtener más información sobre cómo aplicar la configuración de Milvus, consulta «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 los campos del esquema

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

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

• Un campo escalar que almacene los datos sin procesar que se van a incrustar.

• Un campo vectorial reservado para almacenar las representaciones 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 representaciones que generará el módulo «Function». Recuerda configurar la dimensión del vector (dim) para que coincida con la salida del modelo de representació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 sin procesar almacenados en un campo escalar en representaciones y los almacena en el campo vectorial definido explícitamente.

El ejemplo siguiente añade un módulo «Function» (openai_embedding) que convierte el campo escalar « "document" » en representaciones, 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	Valor de ejemplo
name	Identificador único de la función de incrustación dentro de Milvus.	"openai_embedding"
function_type	Tipo de función utilizada. Para la incrustación de texto, establece el valor en FunctionType.TEXTEMBEDDING. Nota: Milvus acepta FunctionType.BM25 (para la transformación de incrustación dispersa) y FunctionType.RERANK (para la reordenación) para este parámetro. Consulte la Descripción general de la búsqueda de texto completo y el clasificador de decaimiento para obtener más detalles.	FunctionType.TEXTEMBEDDING
input_field_names	Campo escalar que contiene los datos sin procesar que se van a incrustar. Actualmente, este parámetro solo admite un nombre de campo.	["document"]
output_field_names	Campo vectorial para almacenar las incrustaciones generadas. Actualmente, este parámetro solo admite un nombre de campo.	["dense"]
params	Diccionario que contiene las configuraciones de incrustación. Nota: Los parámetros dentro 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 se debe 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 el token de API correspondiente y firma la solicitud en el lado del servidor. Si se omite (None), Milvus recurre a la credencial configurada explícitamente para el proveedor de modelos de destino en milvus.yaml. Si la etiqueta es desconocida o falta la clave a la que se hace referencia, la llamada falla.	"apikey1"
dim	El número de dimensiones de las representaciones de salida. En el caso de los modelos de tercera generación de OpenAI, puedes acortar el vector completo para reducir el coste y la latencia sin una pérdida significativa de información semántica. Para obtener más información, consulta la entrada del blog con el anuncio de OpenAI. Nota: Si acortas la dimensión del vector, asegúrate de que el valor de « dim » especificado en el método « add_field » del esquema para el campo vectorial coincida con la dimensión de salida final de tu función de incrustación.	"1536"
user	Un identificador a nivel de usuario para el seguimiento del uso de la API.	"user123"

Paso 3: Configurar el índice

Tras definir el esquema con los campos necesarios y la función integrada, configura el índice para tu colección. Para simplificar este proceso, utiliza « 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 tus 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 crea la colección utilizando los parámetros de esquema e í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

Una vez configuradas la colección y el índice, ya estás listo para insertar tus datos sin procesar. En este proceso, solo tienes que proporcionar el texto sin procesar. El módulo «Function» que hemos definido 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 una búsqueda vectorial

Tras la inserción de datos, realiza una búsqueda semántica utilizando el texto de consulta sin procesar. Milvus convierte automáticamente tu consulta en un vector de incrustación, recupera los documentos relevantes en función de la similitud y devuelve los resultados que mejor coinciden.

# 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, consulta «Búsqueda vectorial básica y consultas».

Preguntas frecuentes

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

Ambos métodos funcionan, pero se recomienda utilizar « milvus.yaml », ya que permite una gestión centralizada de las credenciales y una nomenclatura coherente de las mismas en todos los proveedores. Al utilizar variables de entorno, los nombres de las variables varían en función del proveedor del servicio de incrustación, por lo que debes consultar la página específica de cada proveedor para conocer los nombres concretos de las variables de entorno requeridas (por ejemplo, OpenAI o Azure OpenAI).

¿Qué ocurre 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. En primer lugar, busca la credencial predeterminada configurada para ese proveedor en el archivo « milvus.yaml »
2. Si no existe ninguna credencial predeterminada en milvus.yaml, recurre a las variables de entorno (si están configuradas)
3. Si no se han configurado ni las credenciales de ` milvus.yaml ` ni las variables de entorno, Milvus generará un error

¿Cómo puedo comprobar que las representaciones se están generando correctamente?

Puedes comprobarlo de la siguiente manera:

1. Consultar tu colección tras la inserción para comprobar si el campo vectorial contiene datos
2. Comprobando que la longitud del campo vectorial coincide con las dimensiones esperadas
3. Realizar una búsqueda de similitud sencilla para comprobar que las representaciones producen resultados significativos

Cuando realizo una búsqueda de similitud, ¿puedo utilizar un vector de consulta en lugar de texto sin procesar?

Sí, puedes utilizar vectores de consulta precalculados en lugar de texto sin procesar para la búsqueda de similitud. Aunque el módulo de función convierte automáticamente las consultas de texto sin procesar en representaciones vectoriales, también puedes proporcionar directamente datos vectoriales al parámetro « data » en tu operación de búsqueda. Nota: El tamaño de las dimensiones del vector de consulta proporcionado debe coincidir con el tamaño de las dimensiones de los vectores de incrustación generados por el módulo de función.

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