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

11 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.

8. GET /logs/recent

Devuelve los logs recientes de evaluacion guardados por el sistema.

Sirve para revisar:

  • consultas con contexto insuficiente
  • respuestas problemáticas
  • logs manuales marcados por el usuario

Ejemplo:

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

9. POST /logs/manual

Permite registrar manualmente una consulta o respuesta que quieras revisar despues.

Es util cuando:

  • la respuesta no te convence
  • detectas una carencia del RAG
  • quieres dejar una nota humana asociada a una consulta

Payload base:

{
  "operation": "answer",
  "reason": "manual_review_requested",
  "query": "prueba de log manual",
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "note": "la respuesta parece demasiado generica",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}

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:

  1. Usa un nodo HTTP Request
  2. Metodo POST
  3. URL:
https://rag.por-correo.com/retrieve

o

https://rag.por-correo.com/answer
  1. Body en JSON
  2. Empieza usando answer si quieres una respuesta directa
  3. 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