359 lines
9.8 KiB
Markdown
359 lines
9.8 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"model": "openai/gpt-4.1-mini",
|
|
"answer": "..."
|
|
}
|
|
```
|
|
|
|
## Chat con bootstrap
|
|
|
|
`POST /chat` reutiliza contexto precargado, historial reciente y, opcionalmente, una nueva consulta al RAG:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"model": "openai/gpt-4.1-mini",
|
|
"answer": "...",
|
|
"usedBootstrapContext": true,
|
|
"usedAdditionalRetrieve": true,
|
|
"retrieved": {
|
|
"summary": "...",
|
|
"items": []
|
|
}
|
|
}
|
|
```
|
|
|
|
## Ingesta
|
|
|
|
### Ruta del servidor
|
|
|
|
`POST /ingest` requiere `sourceType` y `sourceRef`:
|
|
|
|
```json
|
|
{
|
|
"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` |
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"scope": {
|
|
"sourceId": "customer-a:manual:v1"
|
|
}
|
|
}
|
|
```
|
|
|
|
Respuesta:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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.
|