paco/rag-service
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rag-service/docs/API_RAG.md

9.8 KiB
Raw Blame History

API del RAG

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-09-08 Ultima modificacion por: Agente RAG 2 Estado: Operativa y validada en produccion

Esta guia explica como descubrir y consumir la API. El contrato tecnico completo y canonico se publica en OpenAPI 3.1.1; este documento prioriza el camino rapido, las decisiones de uso y los ejemplos habituales.

Acceso rapido

Base URL de produccion:

https://rag.por-correo.com
Recurso URL Uso
Ayuda resumida GET /help Descubrimiento rapido para personas y agentes
Contrato OpenAPI GET /openapi.json Esquemas, parametros, respuestas y errores
Playground GET /playground Pruebas manuales desde navegador

GET /help indica expresamente que debe consultarse /openapi.json para obtener los parametros, cuerpos, respuestas, errores y ejemplos completos de cada endpoint.

La API no requiere autenticacion actualmente. No debe asumirse que esta situacion es definitiva: la autenticacion y la proteccion de operaciones sensibles forman parte del pendiente 5.

Elegir la operacion correcta

Necesidad Endpoint recomendado
Comprobar servicio y capacidades GET /health
Ver scopes ingeridos GET /sources
Recuperar contexto para otro agente POST /retrieve
Obtener una respuesta final con citas POST /answer
Comparar una respuesta sin RAG POST /answer/direct
Conversar con bootstrap e historial POST /chat
Ingerir una ruta accesible por el servidor POST /ingest
Subir un archivo o carpeta ZIP POST /ingest/upload
Eliminar una fuente antes de reingestar POST /cleanup
Consultar o actualizar evaluaciones /logs/*

Catalogo completo

La API queda formada por 16 operaciones tras incorporar el descubrimiento:

Metodo Ruta Descripcion
GET /help Catalogo resumido derivado de OpenAPI
GET /openapi.json Contrato OpenAPI 3.1.1
GET /playground Interfaz web de prueba
GET /health Estado, proveedores, parsers y chunking
GET /sources Scopes disponibles en Qdrant
GET /models/answer Modelo por defecto y modelos seleccionables
POST /ingest Ingesta desde una ruta del servidor
POST /ingest/upload Upload multipart/form-data
POST /cleanup Borrado controlado por scope
POST /retrieve Recuperacion de contexto
POST /answer Respuesta apoyada en retrieval
POST /answer/direct Respuesta del modelo sin retrieval
POST /chat Conversacion con contexto opcional
GET /logs/recent Logs recientes de evaluacion
POST /logs/manual Registro manual de una evaluacion
PATCH /logs/{id} Seguimiento y resolucion de un log

Contratos comunes

Scope

Permite limitar una consulta o una operacion a fuentes concretas:

{
  "sourceId": "customer-a:manual:v1",
  "sourceRef": "customer-a-errors.md",
  "tags": ["customer-a", "support"]
}

Todos los campos son opcionales en consultas. Para POST /cleanup es obligatorio enviar al menos sourceId o sourceRef; las etiquetas solas no autorizan un borrado.

Modos e intents

Campo Valores Default
mode en retrieval y answer documental, codigo, auto auto
mode en chat documental, codigo, auto documental
intent specific, bootstrap specific
mode en ingesta mechanical, interactive mechanical

Errores

Los errores JSON siguen esta forma:

{
  "ok": false,
  "error": "Description of the error"
}

Actualmente la mayoria de fallos de validacion o de proveedores se devuelven como 500. POST /cleanup y POST /ingest/upload tambien pueden devolver 400, y PATCH /logs/{id} devuelve 404 si no encuentra el log. Mejorar la validacion queda fuera de este bloque para no cambiar silenciosamente el comportamiento existente.

Recuperar contexto

POST /retrieve es la operacion recomendada cuando otro agente o flujo generara la respuesta final.

curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "What does error FAT07 mean?",
    "scope": {
      "sourceId": "customer-a:manual:v1"
    },
    "useModelInRetrieve": false
  }'

Campos principales:

Campo Requerido Funcion
query Si Consulta de recuperacion
mode No Tipo de conocimiento
intent No Consulta concreta o mapa bootstrap
scope No Limita las fuentes
useModelInRetrieve No Añade modelSummary generado por un modelo
model No Override usado solo para modelSummary
bootstrapMeta No Trazabilidad del bootstrap en logs

Respuesta resumida:

{
  "mode": "documental",
  "intent": "specific",
  "summary": "Retrieved 5 relevant chunks.",
  "topics": ["support-errors.md"],
  "criticalPoints": [],
  "items": [
    {
      "chunkId": "chk:example",
      "documentId": "doc:example",
      "sourceId": "customer-a:manual:v1",
      "title": "support-errors.md",
      "content": "...",
      "score": 0.87
    }
  ],
  "followUpRefs": ["doc:example"],
  "scope": {
    "sourceId": "customer-a:manual:v1"
  }
}

Obtener una respuesta

POST /answer ejecuta retrieval y genera una respuesta final con citas.

{
  "mode": "documental",
  "intent": "specific",
  "query": "Explain the documented resolution for FAT07",
  "scope": {
    "sourceId": "customer-a:manual:v1"
  },
  "model": "openai/gpt-4.1-mini"
}

Tambien acepta preloadedContext y bootstrapMeta. La respuesta incluye model, answer, resumen del retrieval, temas, puntos criticos, citas y scope.

POST /answer/direct no consulta el vector store:

{
  "query": "Explain what a RAG service is",
  "model": "openai/gpt-4.1-mini",
  "preloadedContext": "Optional context supplied by the caller"
}

Su respuesta real solo contiene:

{
  "model": "openai/gpt-4.1-mini",
  "answer": "..."
}

Chat con bootstrap

POST /chat reutiliza contexto precargado, historial reciente y, opcionalmente, una nueva consulta al RAG:

{
  "message": "What should I check next?",
  "history": [
    {
      "role": "user",
      "content": "Give me an initial map of this project"
    },
    {
      "role": "assistant",
      "content": "The project contains..."
    }
  ],
  "mode": "documental",
  "preloadedContext": "Previously loaded bootstrap",
  "allowAdditionalRetrieve": true,
  "scope": {
    "sourceId": "project-docs"
  }
}

Respuesta:

{
  "model": "openai/gpt-4.1-mini",
  "answer": "...",
  "usedBootstrapContext": true,
  "usedAdditionalRetrieve": true,
  "retrieved": {
    "summary": "...",
    "items": []
  }
}

Ingesta

Ruta del servidor

POST /ingest requiere sourceType y sourceRef:

{
  "sourceId": "project-docs",
  "sourceType": "folder",
  "sourceRef": "/data/project-docs",
  "mode": "mechanical",
  "tags": ["project", "documentation"]
}

readPath es un campo interno para separar la ruta fisica de lectura de la referencia logica. Los consumidores normales no deben enviarlo.

Upload

POST /ingest/upload usa multipart/form-data:

Campo Requerido Formato
file Si Archivo binario o ZIP
sourceId No Identificador logico
mode No mechanical o interactive
tags No Lista separada por comas
isZipFolder No Texto true o false 
curl -sS -X POST "https://rag.por-correo.com/ingest/upload" \
  -F "file=@./support-errors.md" \
  -F "sourceId=customer-a:manual:v1" \
  -F "mode=mechanical" \
  -F "tags=customer-a,support"

Ambas variantes responden 202 con el origen aceptado, archivos descubiertos, documentos procesados, chunks almacenados y coleccion. El upload añade uploadedResource.

Limpieza controlada

POST /cleanup elimina los chunks que coinciden con un scope:

{
  "scope": {
    "sourceId": "customer-a:manual:v1"
  }
}

Respuesta:

{
  "ok": true,
  "deleted": 36
}

Esta operacion es destructiva. Verifica primero el scope con GET /sources.

Evaluacion

GET /logs/recent?limit=20 devuelve los logs recientes. Si no se indica limit, usa 20.

POST /logs/manual registra una observacion humana:

{
  "operation": "retrieve",
  "reason": "manual_review_requested",
  "query": "What does error FAT07 mean?",
  "mode": "documental",
  "intent": "specific",
  "scope": {
    "sourceId": "customer-a:manual:v1"
  },
  "note": "The first result is too generic"
}

PATCH /logs/{id} actualiza su seguimiento:

{
  "reviewStatus": "resolved",
  "severity": "high",
  "reviewedBy": "maintainer",
  "resolutionNote": "Retrieval ranking adjusted and validated.",
  "fixReference": "commit-or-ticket-reference"
}

Valores admitidos:

Campo Valores
reviewStatus pending, in_progress, resolved, ignored
severity low, medium, high

Integracion recomendada con n8n

Para una HTTP Request Tool conectada a un AI Agent:

  1. Usa POST /retrieve.
  2. Fija mode, intent y scope en el nodo.
  3. Permite que el agente complete solo query.
  4. Mantiene useModelInRetrieve=false para evitar procesar la consulta con dos modelos.
  5. Entrega items[].content y sus metadatos al agente final.

Usa POST /answer solamente cuando el propio RAG deba generar la respuesta final.

Fuente de verdad y mantenimiento

  • GET /openapi.json es el contrato publico para integraciones y herramientas.
  • GET /help es el indice rapido derivado del mismo contrato.
  • Este documento explica flujos y decisiones de uso.
  • src/app.ts contiene la implementacion efectiva.
  • Cualquier cambio de endpoint debe actualizar OpenAPI y esta guia en el mismo bloque de trabajo.