Embeddings con la API de Ollama

Qué son los embeddings y para qué sirven

Un embedding es una representación vectorial de un texto: una lista de números (dimensiones) que captura el significado semántico. Textos parecidos en significado suelen tener vectores cercanos en el espacio. Textos muy distintos, vectores alejados. Eso permite comparar fragmentos de texto por similitud (búsqueda semántica, recuperación de documentos) o usarlos como entrada para un modelo en un flujo RAG (Retrieval-Augmented Generation): recuperar los fragmentos más relevantes y pasarlos como contexto al LLM.

Ollama expone esta capacidad a través del endpoint /api/embed. Necesitas un modelo de embeddings (por ejemplo nomic-embed-text, mxbai-embed-large o el que recomiende la documentación actual). Esos modelos están optimizados para producir vectores. No se usan para generar texto largo como los de chat.

Los modelos de generación (llama3.2, qwen, etc.) no suelen usarse para embeddings. Usa un modelo específico de embeddings para obtener vectores de calidad y dimensiones adecuadas.

Llamar a /api/embed

El endpoint POST /api/embed acepta un JSON con model (nombre del modelo de embeddings) e input: puede ser una cadena (un solo texto) o un array de cadenas (varios textos en una sola petición). La respuesta incluye los vectores generados.

Ejemplo con un solo texto:

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "¿Por qué el cielo es azul?"
}'

La respuesta es JSON con un array embeddings: cada elemento es el vector (array de números) correspondiente a cada entrada. Para una sola cadena en input, tendrás un solo vector. Para un array de N cadenas, N vectores en el mismo orden.

Ejemplo con varios textos en una petición:

{
  "model": "nomic-embed-text",
  "input": [
    "Instalación de Ollama en Windows",
    "Cómo descargar modelos con ollama pull",
    "Recetas de cocina mediterránea"
  ]
}

Así obtienes tres vectores de una vez, útil para indexar párrafos o documentos y luego compararlos con una consulta.

Parámetros opcionales

• truncate: si es true (por defecto), el texto se trunca cuando supera la longitud máxima que admite el modelo. Si lo pones en false y el texto es muy largo, la petición puede fallar.
• dimensions: algunos modelos permiten reducir o fijar la dimensión del vector (por ejemplo 256 en lugar de 768). Depende del modelo. Consulta la documentación del modelo concreto.
• keep_alive: controla cuánto tiempo se mantiene el modelo cargado en memoria después de la petición (igual que en generate/chat).

Uso típico: RAG y búsqueda semántica

En un flujo RAG básico:

1. Indexar: divides tus documentos (o párrafos) en fragmentos y llamas a /api/embed para cada fragmento (o por lotes con input como array). Guardas los vectores en una base vectorial o en memoria.
2. Consultar: cuando el usuario hace una pregunta, generas el embedding de esa pregunta con /api/embed.
3. Recuperar: comparas el vector de la pregunta con los vectores indexados (por ejemplo con similitud coseno o producto escalar) y eliges los fragmentos más similares.
4. Generar: pasas esos fragmentos como contexto a /api/chat o /api/generate para que el modelo responda usando esa información.

flowchart LR
  D[Documentos] --> E["/api/embed"]
  E --> V[(Vectores)]
  Q[Pregunta usuario] --> E2["/api/embed"]
  E2 --> V
  V --> R[Recuperar similares]
  R --> C[Contexto]
  C --> G["/api/chat"]
  G --> Resp[Respuesta]

Los documentos se convierten en vectores con /api/embed y se almacenan. La pregunta del usuario también se convierte en vector. Se recuperan los fragmentos más similares y se envían como contexto al modelo para generar la respuesta.

Para búsqueda semántica sin RAG: generas embeddings de una colección de textos (títulos, descripciones, etc.) y de la consulta del usuario. Ordenas por similitud y devuelves los más cercanos. No hace falta llamar a generate/chat, solo comparar vectores.

/api/embed te da los vectores que necesitas para RAG y búsqueda semántica. Usa un modelo de embeddings, envía uno o varios textos en input y trabaja con el array embeddings de la respuesta.