Inferencias

Una inferencia es una llamada suelta y sin estado: entra un prompt, sale una respuesta. No recuerda nada entre llamadas. Es la herramienta para clasificar, extraer, resumir o generar JSON estructurado — si lo que quieres es conversar, ve a Agentes.

Se configura en el panel (prompt de sistema, modelo, RAGs vinculados) y se ejecuta desde tu backend.

Listar las disponibles

curl https://ur.tuempresa.com/api/inferences \
  -H "Authorization: Bearer $UR_TOKEN"

[
  {
    "name": "Clasificador de tickets",
    "identifier": "clasificador-tickets",
    "url": "https://ur.tuempresa.com/api/inferences/clasificador-tickets",
    "createdAt": "2026-03-01T09:00:00.000Z",
    "fileSources": [
      {
        "ragIdentifier": "ventas-docs",
        "ragName": "Documentación de ventas",
        "identifier": "drive-ventas",
        "provider": "google_drive"
      }
    ]
  }
]

Devuelve solo las que tu token tiene permitidas. El campo fileSources te dice qué RAGs lleva vinculados cada una — eso determina si tienes que mandar semanticSearch.

Ejecutar una inferencia

curl -X POST https://ur.tuempresa.com/api/inferences/clasificador-tickets \
  -H "Authorization: Bearer $UR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Clasifica este ticket: no me llega la factura de marzo",
    "semanticSearch": ["facturación", "envío de facturas"]
  }'

prompt y semanticSearch son cosas distintas

Este es el error más común

prompt es lo que se le manda al modelo. semanticSearch es lo que se busca en tus documentos. El prompt no interviene en la búsqueda.

Si la inferencia tiene RAGs vinculados y no mandas semanticSearch, la respuesta es 400. Si no los tiene, semanticSearch se ignora.

Puedes mandar hasta 10 queries. Cada una se busca por separado y los resultados se deduplican. Es útil cuando una sola formulación no cubre el tema: ["plazo de devolución", "política de reembolso"].

Cuerpo

Campo	Tipo	Por defecto	Descripción
prompt	string	—	Obligatorio. Lo que recibe el modelo
semanticSearch	string[]	—	Queries de búsqueda, máximo 10. Obligatorio si hay RAGs vinculados
topK	int 1–100	5	Fragmentos a recuperar
useReranking	bool	false	Reordena los resultados, si el RAG tiene reranker
candidateMultiplier	int 2–10	2	Candidatos antes de reordenar (topK × este valor)
similarityThreshold	number 0–1	—	Descarta fragmentos por debajo de este parecido
includeDuplicates	bool	false	Incluye fragmentos marcados como duplicados
jsonSchema	string	—	Fuerza la forma de la respuesta. Ver abajo
useAllFiles	bool	true	A false, restringe a selectedFiles/selectedFolders
selectedFiles	array	—	Ficheros concretos por RAG
selectedFolders	array	—	Carpetas por RAG; se expanden a sus ficheros
providerFilter	array	—	Filtro por metadatos del proveedor (etiquetas…)
includeSystemPrompt	bool	false	Devuelve el prompt de sistema en la respuesta

Los campos de RAG solo valen si la inferencia los usa

semanticSearch, similarityThreshold, selectedFiles, selectedFolders y providerFilter solo se aceptan si la inferencia tiene activado el RAG nativo. Mandarlos si no, devuelve 400 — explícito, en vez de ignorarlos en silencio.

Respuesta estructurada

jsonSchema es un JSON Schema serializado como string, no un objeto:

{
  "prompt": "Clasifica este ticket: no me llega la factura de marzo",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"categoria\":{\"type\":\"string\"}}}"
}

Con él, response es un objeto que sigue ese esquema. Sin él, es un array de bloques de contenido.

Respuesta

{
  "response": { "categoria": "facturacion" },
  "inference": "clasificador-tickets",
  "params": { "prompt": "...", "topK": 5 },
  "items": [
    { "text": "Las facturas se envían el día 5 de cada mes...", "score": 0.82 }
  ],
  "toolCalls": []
}

Campo	Descripción
response	Objeto si usaste jsonSchema; array de bloques de contenido si no
inference	El identifier ejecutado
params	Los parámetros que recibió, ya con los valores por defecto aplicados
items	Fragmentos usados como contexto, con su parecido (0–1)
toolCalls	Una entrada por invocación de tool
systemPrompt	Solo si pediste includeSystemPrompt
degraded	Solo si algo se degradó. Ver abajo

Degradación

La recuperación de documentos nunca lanza un error. Si el reranker está caído, la clave del proveedor agotada o se supera el tiempo máximo, se devuelve lo que se pudo recuperar y aparece el campo degraded.

Mira degraded antes de fiarte del resultado

Una respuesta con degraded es válida, pero se construyó con menos contexto del pedido. Si tu proceso depende de la calidad de la recuperación, compruébalo.

El detalle textual de cada degradación (message) solo aparece con sesión de administrador. Con un token Bearer ves que hubo degradación, pero no el motivo.

Solo recuperar contexto, sin LLM

Si únicamente quieres los fragmentos relevantes, sin gastar una llamada al modelo:

curl -X POST https://ur.tuempresa.com/api/inferences/clasificador-tickets/retrieve \
  -H "Authorization: Bearer $UR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"semanticSearch": ["plazo de devolución"], "topK": 10}'

Acepta el mismo cuerpo que ejecutar, menos prompt y jsonSchema, y devuelve:

{
  "systemPrompt": "...",
  "chunks": [{ "text": "...", "score": 0.87 }]
}

Si lo que quieres es buscar en un RAG sin pasar por una inferencia, la vía directa es POST /api/rags/{identifier}/retrieve.

Ficheros indexados

Qué documentos respaldan una inferencia y en qué estado están:

curl "https://ur.tuempresa.com/api/inferences/clasificador-tickets/files?page=1&limit=20" \
  -H "Authorization: Bearer $UR_TOKEN"

Parámetro	Por defecto	Notas
page	—	Obligatorio
limit	20	Máximo 100
ragIdentifier	—	Restringe a un RAG

total cuenta ficheros, no grupos

La respuesta agrupa por RAG, pero la paginación es por fichero. Un RAG grande puede aparecer partido entre dos páginas: si recorres todas las páginas, agrupa tú por ragIdentifier al juntar los resultados.

{
  "data": [
    {
      "ragIdentifier": "ventas-docs",
      "ragName": "Documentación de ventas",
      "files": [
        {
          "filePath": "documentos/informe.pdf",
          "name": "informe.pdf",
          "status": "indexed",
          "indexedAt": "2026-03-01T10:00:00.000Z",
          "size": 182344,
          "mimeType": "application/pdf",
          "errorMessage": null
        }
      ]
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 20
}

Los estados posibles son pending, processing, indexed, error y deleted. Cuando es error, errorMessage dice por qué.

Estado de un fichero concreto

Para comprobar si un documento llegó a indexarse, sin recorrer páginas:

curl "https://ur.tuempresa.com/api/inferences/clasificador-tickets/file-sources/drive-ventas?file=documentos/informe.pdf" \
  -H "Authorization: Bearer $UR_TOKEN"

El parámetro file es la ruta relativa (en fuentes de sistema de ficheros) o el identificador externo (en Google Drive, S3 o SharePoint) — se busca contra los dos.

{
  "name": "informe.pdf",
  "size": 182344,
  "status": "indexed",
  "indexedAt": "2026-03-01T10:00:00.000Z",
  "errorMessage": null
}

Es el endpoint natural para un flujo "he subido un documento, ¿ya puedo preguntar por él?".