Skip to content

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ónResultado
Sin rag_documental_enabledSe rechaza vincular/gestionar el corpus y ejecutar la skill de consulta (chat autenticado y widget)
Con rag_documental_enabledGestió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:

  1. 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í.
  2. Recuperación antes de que se borre → el corpus vuelve a active automáticamente al primer acceso con el plan ya entitled — no hace falta volver a subir los ficheros del bucket.
  3. 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étodoPathDescripción
GET/ai/assistants/:id/corpusLista los links de corpus del assistant
POST/ai/assistants/:id/corpusVincula 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étodoPathDescripción
GET/ai/platform/assistants/:id/corpusLista los links de corpus del assistant de plataforma
POST/ai/platform/assistants/:id/corpusVincula 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ónExtractor
.txt, .md, .markdownLectura directa como UTF-8
.pdfpdf-parse (texto, sin OCR)
.docxmammoth (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:

  1. Al vincular — la fila se crea pending; indexLink() se dispara en segundo plano (fire-and-forget, no bloquea la respuesta HTTP).
  2. 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_chunks del link. Si todo va bien → ready, errorReason: null, indexedAt con la marca de tiempo.
  3. Fallos de extracción — tipo no soportado, fichero vacío, corrupto o sin capa de texto → error con un errorReason legible en español, consultable por OWNER/ADMIN o super admin vía el GET de la lista. No bloquea el resto del corpus (caso límite del spec).
  4. Cambio de contenido en el bucket — ObjectStorageService publica un evento de dominio (object-storage.object-written) tras cada PUT de un objeto; RagCorpusReindexListener lo escucha y, para cada link que apunte a ese fichero exacto (en cualquier assistant), llama a reindexIfChanged() — solo hace trabajo real si el hash sha256 del contenido cambió respecto al último ready.
  5. Borrado/objeto inaccesible — al borrar un fichero u carpeta (DELETE /object-storage/:space/objects), ObjectStorageService publica object-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.
  6. Mover/renombrar — POST /object-storage/:space/objects/move publica ambos eventos tras un move exitoso: object-storage.object-deleted para la ruta de origen (invalida cualquier link que apuntara ahí, igual que un borrado real) y object-storage.object-written para 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 nuevo filePath — sigue siendo necesario un POST /corpus explí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étodoPathDescripción
POST/ai/assistants/:id/corpus/reindexReindexa síncronamente un fichero ya vinculado (tenant, { filePath }) — devuelve el link con el estado final
POST/ai/platform/assistants/:id/corpus/reindexIgual, 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:

  1. Busca solo en el corpus de ese assistant concreto, y solo entre los vínculos en estado ready nunca en el de otro assistant ni de otro tenant.
  2. Si no hay ningún vínculo ready, responde indicando que no hay conocimiento disponible todavía — nunca inventa contenido.
  3. 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).
  4. 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 (rejectedSkills en la respuesta del chat).
  5. 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étodoRutaDescripción
GET/ai/assistants/:id/rag-configConfig vigente del assistant de tenant; ambos switches false por defecto si no hay fila
PATCH/ai/assistants/:id/rag-configActualiza widgetEnabled y/o citationsEnabled (patch parcial, idempotente); 422 RAG_NOT_ENTITLED sin el entitlement documental

Plataforma (super admin):

MétodoRutaDescripción
GET/ai/platform/assistants/:id/rag-configConfig vigente del assistant de plataforma
PATCH/ai/platform/assistants/:id/rag-configActualiza 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.