RAG documental para assistants
¿Qué hace este módulo?
Da soporte a que los assistants respondan usando conocimiento propio del tenant: el usuario vincula ficheros ya subidos al bucket a un assistant concreto, el sistema los indexa y una skill de consulta recupera solo los fragmentos relevantes en el chat, sin meter el documento completo en cada turno.
Historial de entregas: la primera cubrió la base de entitlement y retención. La segunda añadió los endpoints HTTP para vincular y desvincular ficheros del corpus de un assistant concreto. La tercera añadió el pipeline de indexación real: extracción de texto, trocear en fragmentos, y las transiciones pending → ready/error. Esta entrega añade la skill de consulta en el chat (asignable como cualquier otra skill), las citas (nombre del fichero) y el interruptor de RAG en el widget público, por assistant. La API/SDK para gestionar esos interruptores llega en una entrega posterior (ver "Próximas entregas").
Entitlement distinto de assistants y de storage
RAG documental requiere su propio feature de plan: rag_documental_enabled. Ni tener assistants (ai_assistants) ni tener almacenamiento de objetos (object_storage_enabled) habilita RAG por sí solo — hay que contratarlo aparte (visible en GET /billing/catalog/system-options).
| Situación | Resultado |
|---|---|
Sin rag_documental_enabled | Se rechaza vincular/gestionar el corpus y ejecutar la skill de consulta (chat autenticado y widget) |
Con rag_documental_enabled | Gestión y consulta permitidas (el corpus y la skill se detallan abajo) |
Qué pasa si se pierde el entitlement
El corpus no se borra al instante. Se marca inutilizable y se conserva:
- Pérdida del entitlement → el corpus pasa a
unusable(se registra el momento exacto). Mientras esté así, no es consultable ni gestionable, pero los datos indexados siguen ahí. - Recuperación antes de que se borre → el corpus vuelve a
activeautomáticamente al primer acceso con el plan ya entitled — no hace falta volver a subir los ficheros del bucket. - 90 días sin recuperar el entitlement → un job de mantenimiento interno (purga diaria, mismo patrón que la purga de eventos de clic) borra solo los datos indexados de ese tenant. Los ficheros originales del bucket nunca se tocan aquí. El corpus queda
purged; recuperar el entitlement después de esto ya no restaura nada gratis — haría falta re-indexar.
Sin tope numérico propio
No hay una cuota de "número de ficheros" ni "tamaño indexado" específica de RAG en esta versión — solo aplican los límites ya existentes del bucket.
Corpus por assistant: vincular / desvincular ficheros
El corpus es por assistant, nunca una base de conocimiento compartida a nivel tenant (ver "Fuera de alcance" del spec). Cada fila vinculada apunta a un fichero ya existente en el bucket del mismo alcance que el assistant: un assistant tenant solo puede vincular ficheros del espacio tenant de su propia empresa; un assistant platform solo del espacio platform. No hay forma de mezclar alcances ni de vincular el fichero de otra empresa (aislamiento).
En NimoApps, links y fragmentos del corpus también quedan limitados al entorno autorizado. Los eventos de cambios en objetos incluyen ese entorno, por lo que un archivo con la misma ruta en preview y producción solo actualiza el índice del entorno afectado. El contexto procede de autorización de servidor, no del header selector enviado por el cliente.
Tenant (OWNER/ADMIN; MEMBER/VIEWER → 403 vía RolesGuard):
| Método | Path | Descripción |
|---|---|---|
GET | /ai/assistants/:id/corpus | Lista los links de corpus del assistant |
POST | /ai/assistants/:id/corpus | Vincula un fichero del bucket de la empresa ({ filePath }); idempotente si ya está vinculado |
DELETE | /ai/assistants/:id/corpus?filePath= | Desvincula el fichero; idempotente — 204 aunque no exista el link |
Plataforma (super admin únicamente, resuelto en el servicio — no hay rol de empresa que aplicar):
| Método | Path | Descripción |
|---|---|---|
GET | /ai/platform/assistants/:id/corpus | Lista los links de corpus del assistant de plataforma |
POST | /ai/platform/assistants/:id/corpus | Vincula un fichero del bucket de plataforma |
DELETE | /ai/platform/assistants/:id/corpus?filePath= | Desvincula el fichero — 204 |
Cada link se crea en estado pending (columna status de rag_assistant_corpus_links) y la indexación (ver abajo) arranca en segundo plano — la respuesta HTTP del POST sigue devolviendo pending de forma inmediata; el estado final (ready/error) se consulta con el GET siguiente o forzando un reindex manual.
Rechazo por entitlement: vincular o desvincular en un assistant de tenant exige rag_documental_enabled vigente; sin él, la API devuelve 422 RAG_NOT_ENTITLED antes de tocar el bucket o la tabla de links. Las rutas de plataforma no dependen del entitlement de ningún tenant.
Pipeline de indexación
RagCorpusIndexingService hace todo el trabajo de extracción/chunking. No requiere motor vectorial externo (fuera de alcance del spec): los fragmentos se guardan como texto plano en rag_corpus_chunks, listos para que la futura skill de consulta haga una búsqueda simple por palabra clave/subcadena — suficiente para "fragmentos relevantes".
Formatos soportados — por extensión del filePath:
| Extensión | Extractor |
|---|---|
.txt, .md, .markdown | Lectura directa como UTF-8 |
.pdf | pdf-parse (texto, sin OCR) |
.docx | mammoth (extractRawText) |
Cualquier otra extensión (o ausencia de extensión) se rechaza con un motivo accionable en errorReason nunca falla en silencio.
Ciclo de vida de un link:
- Al vincular — la fila se crea
pending;indexLink()se dispara en segundo plano (fire-and-forget, no bloquea la respuesta HTTP). - Extracción + chunking — lee el objeto del bucket, calcula un hash sha256 del contenido, extrae texto según la extensión, lo trocea (~1000 caracteres, con solape) y reemplaza los
rag_corpus_chunksdel link. Si todo va bien →ready,errorReason: null,indexedAtcon la marca de tiempo. - Fallos de extracción — tipo no soportado, fichero vacío, corrupto o sin capa de texto →
errorcon unerrorReasonlegible en español, consultable por OWNER/ADMIN o super admin vía elGETde la lista. No bloquea el resto del corpus (caso límite del spec). - Cambio de contenido en el bucket —
ObjectStorageServicepublica un evento de dominio (object-storage.object-written) tras cadaPUTde un objeto;RagCorpusReindexListenerlo escucha y, para cada link que apunte a ese fichero exacto (en cualquier assistant), llama areindexIfChanged()— solo hace trabajo real si el hash sha256 del contenido cambió respecto al últimoready. - Borrado/objeto inaccesible — al borrar un fichero u carpeta (
DELETE /object-storage/:space/objects),ObjectStorageServicepublicaobject-storage.object-deleted; el mismo listener invalida (error, "fichero ya no existe o no es accesible") todo link que apuntara a ese fichero o a cualquier fichero bajo esa carpeta borrada.indexLink()también invalida de forma perezosa si el objeto ya no existe cuando se ejecuta. - Mover/renombrar —
POST /object-storage/:space/objects/movepublica ambos eventos tras un move exitoso:object-storage.object-deletedpara la ruta de origen (invalida cualquier link que apuntara ahí, igual que un borrado real) yobject-storage.object-writtenpara la ruta de destino (reindexará cualquier link que ya apunte a esa ruta nueva). Un move no crea ni relinca automáticamente el link al nuevofilePath— sigue siendo necesario unPOST /corpusexplícito para vincular el fichero en su nueva ubicación.
Reindex manual — útil para forzar una reindexación síncrona (por ejemplo tras corregir un fichero que quedó en error), sin esperar al ciclo asíncrono automático:
| Método | Path | Descripción |
|---|---|---|
POST | /ai/assistants/:id/corpus/reindex | Reindexa síncronamente un fichero ya vinculado (tenant, { filePath }) — devuelve el link con el estado final |
POST | /ai/platform/assistants/:id/corpus/reindex | Igual, para assistants de plataforma (super admin) |
404 RAG_CORPUS_LINK_NOT_FOUND si el fichero indicado nunca fue vinculado a ese assistant.
Skill de consulta RAG en el chat
La skill "Query RAG documental corpus" (platform.rag_query, clasificación read, shareable) vive en el catálogo de plataforma de igual que cualquier otra skill: un OWNER/ADMIN la asigna a su assistant de tenant desde PUT /ai/assistants/:id/skills (o el super admin a un assistant de plataforma) exactamente con el mismo flujo que cualquier skill compartible — no hay una API paralela para "activar RAG", es una skill más en la allowlist.
Cuando el modelo la invoca en un chat (autenticado o widget) estando en la allowlist del assistant:
- Busca solo en el corpus de ese assistant concreto, y solo entre los vínculos en estado
readynunca en el de otro assistant ni de otro tenant. - Si no hay ningún vínculo
ready, responde indicando que no hay conocimiento disponible todavía — nunca inventa contenido. - La búsqueda es por coincidencia de palabra clave/subcadena sobre los fragmentos de texto ya indexados (sin motor vectorial, igual que
RagCorpusIndexingService— ver "Fuera de alcance" del spec). - Si el modelo pide la skill sin estar en la allowlist del assistant, no se ejecuta — es la misma regla y el mismo camino de rechazo que cualquier otra skill (
rejectedSkillsen la respuesta del chat). - Toda generación que use fragmentos recuperados pasa por la gobernanza de
(cuotas, rate limit, metering) exactamente igual que cualquier
otro turno de chat — no hay bypass por usar RAG. 6. Sin el entitlement rag_documental_enabled vigente, la ejecución de la skill se rechaza con 422 RAG_NOT_ENTITLED igual que gestionar el corpus.
Citas de fuentes
Por assistant, se puede activar que las respuestas que usaron fragmentos de RAG citen al menos el nombre del fichero de cada fuente. Cuando está activado y la skill devolvió fragmentos, la respuesta final del assistant incluye una línea Fuentes: <fichero1>, <fichero2> de forma determinista (no depende de que el modelo "recuerde" citar). Cuando está desactivado (valor por defecto), no se exige ninguna cita.
RAG en el widget público
El widget público de ya solo ofrece skills marcadas publicSafe, de solo lectura (read) y con serviceKey en la allowlist cerrada (billing.plans.list, rag.query) en la asignación del assistant. RAG añade un interruptor adicional, específico de RAG y por assistant: aunque la skill esté en la allowlist autenticada, marcada publicSafe y sea rag.query, el widget anónimo no la ejecuta salvo que ese interruptor esté también activado (por defecto está apagado). Si está activado, sigue exigiéndose publicSafe + read + — activar el interruptor de RAG no la hace pública por sí sola. El uso de IA del widget (incluida la consulta RAG) se imputa siempre al tenant propietario del assistant, igual que cualquier otro uso del widget.
Config RAG por assistant — API
Los interruptores de widget y citas (widgetEnabled, citationsEnabled) se leen/actualizan por HTTP con el mismo patrón tenant/plataforma que el resto del corpus. Escrituras de tenant están gated por el mismo entitlement de gestión (assertManagementEntitled) que vincular/desvincular/reindexar el corpus; el scope de plataforma no comprueba entitlement de tenant.
Tenant (OWNER/ADMIN):
| Método | Ruta | Descripción |
|---|---|---|
GET | /ai/assistants/:id/rag-config | Config vigente del assistant de tenant; ambos switches false por defecto si no hay fila |
PATCH | /ai/assistants/:id/rag-config | Actualiza widgetEnabled y/o citationsEnabled (patch parcial, idempotente); 422 RAG_NOT_ENTITLED sin el entitlement documental |
Plataforma (super admin):
| Método | Ruta | Descripción |
|---|---|---|
GET | /ai/platform/assistants/:id/rag-config | Config vigente del assistant de plataforma |
PATCH | /ai/platform/assistants/:id/rag-config | Actualiza widgetEnabled y/o citationsEnabled (patch parcial, idempotente) |
Ambas rutas devuelven 404 RAG_ASSISTANT_NOT_FOUND para un id fuera de alcance (otro tenant, u origen tenant/plataforma cruzado), igual que el resto del corpus.
Próximas entregas de
- paridad SDK.