Paco POR-CORREO b7846d89ed Add upload and bootstrap chat workflow to playground

2026-04-06 15:51:11 +02:00

10 KiB

Raw Blame History

API del RAG

Proyecto: Workspace de tools IA para empresas
Modulo: RAG
Ultima actualizacion: 2026-04-05
Ultima modificacion por: Agente tools IA para potenciar servicios empresariales
Estado: Operativa en VPS2

Proposito

Dejar una referencia rapida y practica de la API del servicio RAG para poder conectarlo facilmente desde modelos, agentes, flujos de n8n y otras aplicaciones.

Base URL actual

Produccion actual en VPS2:

https://rag.por-correo.com

Endpoints disponibles

1. `GET /health`

Sirve para comprobar si el servicio esta levantado y si la conexion con Qdrant esta operativa.

Ejemplo:

curl -sS "https://rag.por-correo.com/health"

Respuesta esperada aproximada:

{
  "ok": true,
  "service": "rag",
  "environment": "production",
  "embeddings": {
    "provider": "openrouter",
    "model": "qwen/qwen3-embedding-8b"
  },
  "answer": {
    "provider": "openrouter",
    "model": "openai/gpt-4.1-mini"
  },
  "vectorStore": {
    "ok": true,
    "kind": "qdrant"
  }
}

2. `POST /ingest`

Sirve para ingerir una fuente en el RAG.

Puede usarse sobre:

un archivo
una carpeta

Payload base:

{
  "sourceType": "folder",
  "sourceRef": "/ruta/a/la/carpeta",
  "mode": "mechanical",
  "tags": ["workspace", "global-docs"]
}

Campos:

sourceId: opcional, permite aislar la fuente en un scope propio
sourceType: file o folder
sourceRef: ruta de la fuente
readPath: uso interno cuando se sube un archivo y el backend lo procesa desde una ruta temporal
mode: mechanical o interactive
tags: etiquetas opcionales para clasificar la fuente

Ejemplo documental:

curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "folder",
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs",
    "mode": "mechanical",
    "tags": ["workspace", "global-docs"]
  }'

Ejemplo codigo:

curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "folder",
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src",
    "mode": "mechanical",
    "tags": ["rag", "module-code"]
  }'

Respuesta esperada aproximada:

{
  "accepted": true,
  "filesDiscovered": 10,
  "documentsProcessed": 10,
  "chunksStored": 45,
  "collectionName": "rag_chunks"
}

Ejemplo de aislamiento en un scope propio:

curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "src:default:manual:pdf-tecnico-cliente-a",
    "sourceType": "file",
    "sourceRef": "/ruta/a/documento.pdf",
    "mode": "mechanical",
    "tags": ["cliente-a", "pdf-tecnico"]
  }'

3. `POST /retrieve`

Sirve para recuperar contexto del RAG sin pedir una respuesta final al modelo.

Es ideal para:

agentes IA
nodos tool de n8n
flujos que quieran contexto rico y trazable

Payload base:

{
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

Campos:

mode:
- documental
- codigo
- auto
intent:
- specific
- bootstrap
query: consulta del usuario o del flujo
scope opcional:
- sourceId
- sourceRef
- tags

Nota util:

si una ingesta se hizo con sourceId propio, despues puedes consultar solo ese material usando scope.sourceId

Ejemplo `retrieve` documental

curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "que tenemos pendiente por hacer en este workspace",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'

Ejemplo `retrieve` bootstrap

curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "bootstrap",
    "query": "dame un mapa inicial del workspace y sus lineas de trabajo principales",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'

Ejemplo `retrieve` codigo

curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "codigo",
    "intent": "specific",
    "query": "como se construye source_id en el rag",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
    }
  }'

Respuesta resumida esperada:

{
  "mode": "documental",
  "intent": "specific",
  "summary": "...",
  "topics": ["PENDIENTES_GENERALES.md"],
  "criticalPoints": [],
  "items": [
    {
      "chunkId": "chk:...",
      "documentId": "doc:...",
      "sourceId": "src:...",
      "title": "PENDIENTES_GENERALES.md",
      "sectionTitle": "Resumen rapido",
      "content": "...",
      "score": 0.87
    }
  ],
  "followUpRefs": ["doc:..."],
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

4. `POST /answer`

Sirve para pedir al RAG una respuesta final apoyada en el contexto recuperado.

Es util para:

agentes conversacionales
respuestas listas para usuario
pruebas rapidas desde n8n o aplicaciones

Tambien permite indicar el modelo de respuesta explicitamente mediante el campo opcional model.

Payload base:

{
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

Ejemplo `answer` documental

curl -sS -X POST "https://rag.por-correo.com/answer" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "que tenemos pendiente por hacer en este workspace",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'

Ejemplo `answer` codigo

curl -sS -X POST "https://rag.por-correo.com/answer" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "codigo",
    "intent": "specific",
    "query": "como se construye source_id en el rag",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
    }
  }'

Respuesta resumida esperada:

{
  "mode": "codigo",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "answer": "...",
  "summary": "...",
  "topics": ["ids.ts"],
  "criticalPoints": [],
  "citations": [
    {
      "chunkId": "chk:...",
      "documentId": "doc:...",
      "title": "ids.ts",
      "sectionTitle": "export function buildSourceId(...)",
      "startLine": 20,
      "endLine": 25
    }
  ],
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
  }
}

5. `POST /answer/direct`

Sirve para pedir una respuesta directa al modelo sin usar contexto del RAG.

Es util para comparar:

respuesta sin RAG
respuesta con RAG

Payload base:

{
  "query": "que es este servicio",
  "model": "openai/gpt-4.1-mini"
}

6. `POST /chat`

Sirve para conversar con un modelo usando:

contexto bootstrap precargado
historial reciente de mensajes
y opcionalmente una consulta adicional al RAG durante la propia conversacion

Payload base:

{
  "message": "y ahora cuales son los siguientes pasos mas naturales?",
  "history": [
    {
      "role": "user",
      "content": "dame un mapa inicial del workspace"
    }
  ],
  "mode": "documental",
  "model": "openai/gpt-4.1-mini",
  "preloadedContext": "<resumen del bootstrap>",
  "allowAdditionalRetrieve": true,
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

7. `POST /ingest/upload`

Sirve para subir un archivo directamente al backend desde una interfaz web o cliente compatible con multipart/form-data.

Es util para:

PDFs o documentos sueltos
pruebas rapidas desde el playground
crear un scope aislado para una carga concreta

Campos esperados del formulario:

file
sourceId opcional
mode
tags

Si se usa sourceId, el archivo subido no se mezcla con otros scopes salvo que elijas reutilizar ese mismo identificador.

Respuesta esperada resumida:

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

Respuesta esperada:

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

Recomendacion practica para n8n

Si quieres probarlo rapido desde n8n:

Usa un nodo HTTP Request
Metodo POST
URL:

https://rag.por-correo.com/retrieve

https://rag.por-correo.com/answer

Body en JSON
Empieza usando answer si quieres una respuesta directa
Usa retrieve si quieres dar el contexto al agente y que el modelo final responda por su cuenta

Payload recomendado para primera prueba en n8n:

{
  "mode": "documental",
  "intent": "specific",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

Nota importante

El scope es clave para no mezclar fuentes distintas.

Ejemplos de scope utiles:

documentacion global del workspace:

{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
}

documentacion del modulo RAG:

{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/docs"
}

codigo del modulo RAG:

{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
}

Siguiente evolucion natural

Mas adelante esta API podra exponerse tambien mediante un MCP, pero a dia de hoy ya puede consumirse directamente por HTTP desde:

modelos
agentes
flujos de n8n
aplicaciones propias

10 KiB Raw Blame History

API del RAG

Proposito

Base URL actual

Endpoints disponibles

1. GET /health

2. POST /ingest

3. POST /retrieve

Ejemplo retrieve documental

Ejemplo retrieve bootstrap

Ejemplo retrieve codigo

4. POST /answer

Ejemplo answer documental

Ejemplo answer codigo

5. POST /answer/direct

6. POST /chat

7. POST /ingest/upload

Recomendacion practica para n8n

Nota importante

Siguiente evolucion natural

10 KiB

Raw Blame History

1. `GET /health`

2. `POST /ingest`

3. `POST /retrieve`

Ejemplo `retrieve` documental

Ejemplo `retrieve` bootstrap

Ejemplo `retrieve` codigo

4. `POST /answer`

Ejemplo `answer` documental

Ejemplo `answer` codigo

5. `POST /answer/direct`

6. `POST /chat`

7. `POST /ingest/upload`