603 lines
12 KiB
Markdown
603 lines
12 KiB
Markdown
# 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`:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
curl -sS "https://rag.por-correo.com/health"
|
|
```
|
|
|
|
Respuesta esperada aproximada:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"accepted": true,
|
|
"filesDiscovered": 10,
|
|
"documentsProcessed": 10,
|
|
"chunksStored": 45,
|
|
"collectionName": "rag_chunks"
|
|
}
|
|
```
|
|
|
|
Ejemplo de aislamiento en un scope propio:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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. `POST /cleanup`
|
|
|
|
Sirve para eliminar vectores (chunks) ya ingeridos en el RAG segun un scope determinado, permitiendo limpiar contexto viejo antes de una reingesta.
|
|
|
|
Payload base (requiere `sourceId` o `sourceRef` por seguridad):
|
|
|
|
```json
|
|
{
|
|
"scope": {
|
|
"sourceId": "src:default:folder:src_a9df8105"
|
|
}
|
|
}
|
|
```
|
|
|
|
Respuesta esperada:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"deleted": 124
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 9. `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:
|
|
|
|
```bash
|
|
curl -sS "https://rag.por-correo.com/logs/recent"
|
|
```
|
|
|
|
Tambien admite actualizacion posterior del estado de revision mediante `PATCH /logs/:id`.
|
|
|
|
---
|
|
|
|
### 10. `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:
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 11. `PATCH /logs/:id`
|
|
|
|
Permite actualizar el seguimiento de un log ya creado.
|
|
|
|
Ejemplo:
|
|
|
|
```bash
|
|
curl -sS -X PATCH "https://rag.por-correo.com/logs/<id>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"reviewStatus": "resolved",
|
|
"severity": "high",
|
|
"reviewedBy": "Paco POR-CORREO",
|
|
"resolutionNote": "Se ajusto el bootstrap para scopes aislados.",
|
|
"fixReference": "6557aea"
|
|
}'
|
|
```
|
|
|
|
Respuesta esperada resumida:
|
|
|
|
```json
|
|
{
|
|
"model": "openai/gpt-4.1-mini",
|
|
"answer": "...",
|
|
"usedBootstrapContext": true,
|
|
"usedAdditionalRetrieve": true,
|
|
"retrieved": {
|
|
"summary": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
Respuesta esperada:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```text
|
|
https://rag.por-correo.com/retrieve
|
|
```
|
|
|
|
o
|
|
|
|
```text
|
|
https://rag.por-correo.com/answer
|
|
```
|
|
|
|
4. Body en JSON
|
|
5. Empieza usando `answer` si quieres una respuesta directa
|
|
6. 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
|
|
}
|
|
```
|
|
|
|
- documentacion del modulo RAG:
|
|
|
|
```json
|
|
{
|
|
"sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/docs"
|
|
}
|
|
```
|
|
|
|
- codigo del modulo RAG:
|
|
|
|
```json
|
|
{
|
|
"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
|