# Embeddings de IA

Convierte texto en vectores para búsqueda y similitud.

URL base: `https://ai.inovacc.dev`

## Descripción general

Los embeddings de IA convierten texto en vectores: listas de números cuya distancia entre sí sigue el significado del texto. Dos pasajes sobre lo mismo quedan cerca aunque no compartan palabras. El endpoint, `POST /v1/embeddings`, usa el formato de red de embeddings de OpenAI, por lo que un cliente de OpenAI existente puede llamarlo con la URL base `https://ai.inovacc.dev/v1` y dos encabezados adicionales.

El problema que resuelve es la comparación semántica dentro de tus propios sistemas. Con vectores puedes buscar por significado, agrupar elementos similares, encontrar casi duplicados o dirigir un mensaje a la categoría más cercana, con la base de datos o el índice que ya uses.

Usa los embeddings de IA cuando **tú** guardas los vectores. Si prefieres que Inovacc los guarde, los busque y devuelva los pasajes coincidentes, usa la base de datos vectorial administrada de [Conocimiento y búsqueda vectorial](/es/products/knowledge/), que genera los embeddings de tus documentos por ti. Cuando necesites texto generado en lugar de vectores, usa el [Chat con IA](/es/products/ai.chat/).

## Conceptos

**Rutas.** Igual que con el chat, nunca nombras un modelo. A tu organización se le asignan rutas de embeddings, ids opacos configurados por Inovacc. `GET /v1/models` las lista: una entrada cuyo `endpoint` es `/v1/embeddings` es una ruta de embeddings. Envía su id como `model`, o envía `"auto"` (o ningún `model`) para usar la ruta predeterminada de tu organización. Una ruta sirve un solo endpoint; una ruta de chat invocada aquí se rechaza.

**Entrada.** `input` es una cadena no vacía, o un arreglo de cadenas; dentro de un arreglo se acepta una cadena vacía. La respuesta contiene un vector por entrada, en `data[]`, cada uno con el `index` de la entrada a la que pertenece.

**Los vectores de una ruta van juntos.** Un vector solo es comparable con vectores producidos por la misma ruta. Guarda el id de la ruta junto a cada vector que conserves, y genera los embeddings de tus documentos y de tus consultas con la misma ruta.

**Campos opcionales.** `encoding_format` y `dimensions` se pasan al modelo cuando el modelo de la ruta los admite, y se ignoran en caso contrario. `user` se acepta como cadena y, antes de salir de Inovacc, se reemplaza por un valor derivado de tu organización, de modo que dos organizaciones que envían el mismo valor nunca colisionan.

**Uso.** El `usage` de la respuesta contiene `prompt_tokens` y `total_tokens`. Este endpoint no lleva encabezados `x-usage-*`; la ruta que respondió está en `x-route-id`.

## Cómo funciona

Toda llamada lleva `Authorization: Bearer <key>` y un `X-Operation-Id`. Tu organización se obtiene de la clave. El servicio verifica el id de operación y la clave, luego si ese id de operación ya se usó, y después el cuerpo: solo se aceptan `model`, `input`, `encoding_format`, `dimensions` y `user`, y cualquier otro campo se rechaza por su nombre. Resuelve la ruta, verifica que la ruta sirva embeddings, valida `input`, estima el tamaño de la entrada (una cuarta parte de los caracteres de cada cadena de entrada) frente al tope por solicitud de tu organización, y reserva la llamada contra las cuotas de tu organización. Entonces se llama al modelo.

La respuesta es `{"object":"list","data":[{"object":"embedding","index":0,"embedding":[...]}],"model":"<route id>","usage":{...}}`. `model` es siempre el id de la ruta.

No hay streaming. Una respuesta exitosa se almacena durante 24 horas bajo su id de operación: el mismo id enviado de nuevo devuelve los mismos vectores con `x-idempotent-replay: true`, sin una segunda llamada ni cobro. Un error nunca se almacena, así que una llamada fallida puede reintentarse con el mismo id. Lo que se mide son los tokens de entrada.

## Primeros pasos

Necesitas una clave de API y una ruta de embeddings habilitada para tu organización ([Autenticación](/es/guides/authentication/)).

1. **Encuentra tu ruta de embeddings.** Llama a `GET /v1/models` y elige una entrada cuyo `endpoint` sea `/v1/embeddings`.
2. **Genera los embeddings de dos pasajes.** Llama a `POST /v1/embeddings` con esa ruta como `model`, un arreglo `input` de dos cadenas y un `X-Operation-Id` nuevo (consulta [los ejemplos](#example)). La respuesta tiene dos entradas en `data`, con `index` 0 y 1, y `model` es el id de tu ruta.
3. **Compáralos.** Calcula la similitud coseno de los dos vectores en tu código. Genera el embedding de un tercer pasaje sobre otro tema y compara de nuevo: su puntuación frente al primero es menor.
4. **Repite.** Envía de nuevo el paso 2 con el mismo id de operación; los vectores son idénticos y la respuesta lleva `x-idempotent-replay: true`.

## Casos de uso

**Búsqueda en tu propia base de datos.** Un catálogo de productos guarda un vector por cada descripción de producto en la base de datos que ya usa. La pregunta de un comprador se convierte en embedding con la misma ruta al momento de la consulta, y se muestran los productos más cercanos, incluidos aquellos cuya descripción usa otras palabras.

**Detección de casi duplicados.** Un sistema de tickets genera el embedding de cada ticket nuevo y lo compara con los abiertos; una puntuación por encima de un umbral que tú calibras vincula el ticket con el caso existente en lugar de abrir un segundo caso.

**Enrutamiento por similitud.** Un conjunto pequeño de mensajes de ejemplo por equipo se convierte en embeddings una sola vez. De cada mensaje entrante se genera el embedding y se envía al equipo cuyos ejemplos estén más cerca, sin ninguna llamada a un modelo por mensaje aparte del embedding.

## Límites y precios

| Límite | Valor |
|---|---|
| Cuerpo de la solicitud | 1 MiB por defecto; tu organización puede configurarse entre 1 KiB y 20 MiB |
| Tokens de entrada por solicitud | el tope de tu organización (`400 input_too_large` por encima de él) |
| Tiempo hasta la primera respuesta del modelo | 60 segundos |
| Respuesta almacenada para una repetición | 24 horas |
| Solicitudes, tokens, costo, concurrencia, presupuestos diarios | según lo configurado para tu organización |

**Precios:** a consultar. La unidad de precio son los **tokens**.

## Errores

| Estado | Código | Qué significa y qué hacer |
|---|---|---|
| 400 | `missing_operation_id`, `invalid_operation_id` | Envía un `X-Operation-Id` válido. |
| 400 | `unsupported_field` | Un campo distinto de `model`, `input`, `encoding_format`, `dimensions`, `user`; quítalo. |
| 400 | `invalid_body` | JSON mal formado, `input` con una forma incorrecta, o un `user` que no es cadena. |
| 400 | `model_not_allowed` | `model` no es un id de ruta válido. |
| 400 | `input_too_large` | La entrada supera tu tope por solicitud; divídela en varias llamadas. |
| 401 | `missing_credentials`, `invalid_credentials` | Envía una clave válida. |
| 403 | `route_forbidden` | La ruta no es tuya, está deshabilitada o no sirve embeddings. |
| 403 | `key_disabled`, `organization_disabled` | Revisa la clave. |
| 409 | `operation_in_progress` | Ese id de operación sigue en ejecución; espera y reintenta. |
| 413 | `request_too_large` | El cuerpo supera tu tope de tamaño. |
| 429 | `rate_limited`, `budget_exhausted` | Espera los segundos de `Retry-After`. |
| 429 | `quota_exceeded`, `concurrency_limited` | Se agotó una asignación; sin `Retry-After`. |
| 502, 503, 504 | `upstream_error`, `service_unavailable`, `timeout_error` | Reintenta con el mismo id de operación y espera creciente. |

Consulta [Errores](/es/guides/errors/) para el envoltorio.

## Buenas prácticas

- **Agrupa las entradas en lotes**: envía muchos pasajes en un solo arreglo `input`, dentro de tus topes de tamaño y de tokens, en lugar de una llamada por pasaje.
- **Conserva el id de la ruta junto con el vector**, y vuelve a generar todos los embeddings si cambias de ruta: los vectores de dos rutas no son comparables.
- **Divide los documentos largos en fragmentos** de unos pocos párrafos antes de generar los embeddings; un solo vector para un documento completo difumina su significado.
- **Deriva el id de operación del contenido** (por ejemplo, un hash del lote) para que un trabajo reiniciado repita la respuesta en lugar de volver a pagar.
- **Reintenta `502`, `503` y `504` con el mismo id de operación**; espera `Retry-After` en `429 rate_limited`.
- **Calibra los umbrales con tus propios datos**: las puntuaciones de similitud son relativas, no probabilidades.

## Relacionados

- [Conocimiento y búsqueda vectorial](/es/products/knowledge/): la base de datos vectorial administrada que genera los embeddings y busca por ti
- [Chat con IA](/es/products/ai.chat/)
- [Autenticación](/es/guides/authentication/), [Errores](/es/guides/errors/), [Límites](/es/guides/limits/)

## Endpoints

- POST /v1/embeddings

## Ejemplo

```sh
curl -X POST "https://ai.inovacc.dev/v1/embeddings" -H "Authorization: Bearer $INOVACC_API_KEY" -H "X-Operation-Id: $(uuidgen)" -H "Content-Type: application/json" -d '{}'
```