Documentos

Objetivo

Construye y gestiona tu base de conocimiento de IA. Sube documentos para que tus agentes respondan preguntas con tu propio contenido usando RAG (Retrieval Augmented Generation). Helios guarda cada archivo original y lo indexa en el índice de conocimiento propio de tu workspace: lee el texto, detecta la estructura del documento (títulos, capítulos, artículos) y lo hace buscable tanto por significado como por palabras exactas. Cada documento puede asignarse a uno o varios agentes.

Acceso

Sidebar -> Documents Ruta: /app/{tenant}/documents

Roles

• owner, admin, agent — abren el módulo, suben documentos, reintentan documentos fallidos y actualizan la estructura de un documento.
• owner, admin — eliminan documentos y asignan o quitan documentos a los agentes. Los agents ven las asignaciones en modo solo lectura y no ven la acción de eliminar.
• viewer — sin acceso a este módulo.

Requisitos previos

• Ninguna API key con créditos de IA gestionados. Un workspace que funciona con su propia key indexa con su API key de OpenAI (conectada en Integraciones o en API keys); la Google AI key no se usa para documentos. En Free sin una key propia, Helios cubre la indexación hasta un cupo mensual de indexación.
• Un email verificado. La subida se bloquea hasta verificar tu email en los planes que lo requieren.
• Una suscripción activa. La subida se bloquea mientras la suscripción esté restringida o suspendida.
• Espacio libre en la base de conocimiento de tu plan, que se mide en páginas de conocimiento (ver Planes y límites).

Planes y límites

Tu plan vende la base de conocimiento en páginas de conocimiento: 1 página de conocimiento = 2.500 caracteres de texto leídos de tus documentos, más o menos una página impresa. El límite cuenta el texto, no la cantidad de archivos ni los megabytes.

Uso de la base de conocimiento

La página Documents muestra un medidor de la base de conocimiento con tu uso, por ejemplo "120 of 200 knowledge pages used", con el recordatorio "1 knowledge page = 2,500 characters of text read from your documents". En Enterprise muestra las páginas en uso, sin límite.

• Cuando queda menos de una página, el medidor avisa de que solo se puede indexar un documento muy corto.
• Cuando la base de conocimiento está llena, el medidor lo indica y Upload Document abre el diálogo Knowledge base full en lugar del formulario de subida. El aviso del medidor ofrece a owner y admin la acción Upgrade plan; al resto de roles se les pide contactar con un admin del workspace.
• Si tu workspace usa más páginas de las que incluye su plan (por ejemplo, tras pasar a un plan más pequeño), tus documentos siguen funcionando, pero los nuevos no se indexan hasta que elimines documentos o mejores el plan.
• Cuando un documento no cabe en las páginas que quedan, no se indexa: su fila muestra Failed con un mensaje que indica cuántas páginas de conocimiento necesita y cuántas de las páginas de tu plan ya están en uso. Elimina los documentos que ya no necesites, o elige Upgrade plan, y después elige Retry indexing en ese documento.

Subir un documento

Pasos:

1. Pulsa Upload Document.
2. Arrastra un archivo al área de subida, o haz clic para buscarlo.
3. Completa los campos.
4. (Opcional) Abre Advanced settings para ajustar el chunking.
5. Pulsa Upload Document.

Campos:

Tipos de archivo soportados:

• PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, JSON, HTML, PNG, JPEG, DOC, XLS, RTF, ODT

Algunos formatos reconocibles no están soportados y se rechazan con un mensaje específico que nombra el formato y sugiere a qué convertirlo: imágenes HEIC/HEIF, WEBP y TIFF (convertir a JPEG o PNG), PowerPoint antiguo PPT (convertir a PPTX), OpenDocument Spreadsheet ODS (convertir a XLSX o CSV) y exportaciones de email EML (convertir a PDF o texto plano).

El contenido del archivo se valida contra su tipo real al subir, no solo por la extensión. Un archivo renombrado o corrupto se rechaza aunque declare un tipo soportado.

Tras subirlo, el documento aparece como Processing y la indexación empieza en segundo plano en unos segundos; puedes cerrar el diálogo mientras corre. Helios lee el texto, detecta la estructura y divide el documento de modo que ningún artículo quede partido. Los documentos legales conservan su estructura (títulos, capítulos, artículos), así que un agente puede citar un artículo verbatim por su número, y un documento dejado en General se lee igualmente como texto legal cuando su contenido lo es.

Tipos de documento (presets de chunking)

El Document Type controla cómo se divide el archivo en chunks para la búsqueda. Elige el que mejor se ajuste al contenido.

Si dejas el Document Type en su valor por defecto General, Helios elige automáticamente un preset mejor para algunos archivos: hojas de cálculo, CSV y JSON se trocean con el preset Technical para que una fila o registro completo nunca quede partido a la mitad. Una elección explícita de cualquier tipo siempre se respeta y nunca se sobrescribe.

Ajustes avanzados de chunking

Abre Advanced settings en el diálogo de subida para sobrescribir el preset en casos técnicos. Con Advanced activado, se usan sus valores en lugar del preset del Document Type.

Los valores personalizados se ajustan a límites seguros antes de procesar.

Procesamiento y estados

Cada documento muestra un estado:

Cada fila lleva además una insignia de la base de conocimiento que indica si los agentes pueden encontrar el contenido: Indexed (buscable), Indexing, Failed o Not indexed (la indexación terminó, pero del archivo no salió texto buscable). La vista de detalle muestra el mismo estado en su campo Knowledge base.

Cómo corre la indexación:

• Trabaja por pasos (leer el texto, detectar la estructura, dividir, generar los embeddings, escribir en el índice) y guarda su progreso tras cada uno. Un documento grande, como un escaneo largo, puede necesitar varias ejecuciones en segundo plano de unos minutos cada una; sigue en Processing y continúa desde donde se quedó. Un documento nunca se marca como Failed solo porque tarde mucho.
• Si un paso falla por una causa pasajera (un fallo del proveedor o de la red), se reintenta automáticamente unos minutos después. Tras tres intentos fallidos seguidos sin avanzar, el documento se marca como Failed. Los problemas que un reintento no puede resolver, como una base de conocimiento llena, un archivo sin texto legible o no tener una key con la que indexar, lo marcan como Failed de inmediato.
• Los modelos que se usan para indexar y buscar son de OpenAI. Con créditos de IA gestionados, indexar y buscar en tus documentos no suma créditos, solo las páginas escaneadas (ver abajo), pero un workspace sin créditos no puede indexar. Cuando el workspace funciona con su propia key, la indexación y las búsquedas en la base de conocimiento usan su API key de OpenAI.

Para un documento Failed, Retry indexing vuelve a ejecutar la indexación. Un documento cuyo archivo original se guarda se reintenta desde ese archivo guardado, sin tener que seleccionar nada. Un documento antiguo, subido antes de que se guardaran los archivos originales, te pide elegir el archivo otra vez; ese archivo de reemplazo tiene un límite de 4 MB, y uno mayor se rechaza con "This replacement file is larger than 4 MB, the most a reprocess can send. Choose a smaller file." Los reintentos consumen el mismo cupo del ritmo de subida, y un documento que se está indexando en este momento no se puede reintentar hasta que termine esa ejecución.

Una página sin capa de texto, como la página de un PDF escaneado, se lee página por página. Con créditos de IA gestionados, cada página escaneada usa 1 crédito, y las páginas escaneadas también cuentan contra un cupo mensual de páginas escaneadas que depende de tu plan; Free no incluye ninguno. Cuando el cupo se agota, el documento se marca como Failed pero las páginas ya leídas se conservan: elige Retry indexing cuando el cupo se renueve o después de mejorar tu plan, y la indexación continúa desde donde se quedó sin volver a leer ni cobrar esas páginas.

Los documentos subidos antes del sistema de indexación actual que todavía aparecen en Processing se pueden marcar como Failed desde Helio (Mark stalled documents failed, owner o admin) para poder reintentarlos. Solo se aplica a esos registros antiguos, sin cambios desde hace más de dos minutos, y nunca toca un documento que se esté indexando.

Estructura del documento

Cuando un documento está Ready, Refresh structure lee lo que la base de conocimiento tiene de él y lo muestra en la sección Document structure de la vista de detalle: el tipo de documento y cuántos capítulos y artículos se indexaron. No cuesta nada, tarda un momento y recibes una notificación cuando termina. Después de la primera lectura, la fila muestra la insignia Structure read, con un control para volver a leerla tras reindexar el documento.

Detalle del documento

Haz clic en el nombre de un documento para abrir su vista de detalle. Muestra:

• Información del archivo: tamaño, tipo de archivo, fecha de subida y el estado en Knowledge base (Indexed, Indexing, Failed o Not indexed).
• Estructura del documento: el tipo de documento y el número de artículos y capítulos indexados, más el título y el resumen guardados antes para el documento, si los hay.
• Agentes asignados.

Cuando el archivo original se guarda, la vista de detalle ofrece Download original. Un documento subido antes de que se guardaran los archivos originales muestra Original file not downloadable; vuelve a subirlo y la copia se guardará.

Asignar documentos a agentes

Cada fila de documento y la vista de detalle incluyen un control Assign agents.

• Activa un agente para agregar o quitar el documento de su base de conocimiento.
• Asignar el primer documento a un agente activa su base de conocimiento (RAG); quitar el último la desactiva.
• Solo owner y admin pueden cambiar las asignaciones; los agents las ven en modo solo lectura.
• También puedes gestionar las mismas asignaciones por agente desde la sección de base de conocimiento del editor de Agents.

Búsqueda y filtros

• Caja de búsqueda: coincide por nombre de archivo, display name, description y tipo de documento.
• Pills de estado: All statuses, Ready, Processing y Failed, cada uno con su conteo.
• Filtro de tipo: All types, General, Legal / Regulatory, Technical / Code y FAQ / Q&A.
• Los chips de estadística sobre la lista muestran Total Documents y Ready, y también Processing y Failed cuando existen.

Eliminar un documento

Pulsa el icono de eliminar en la fila del documento y confirma. Solo owner y admin ven esta acción. Elimina el documento de forma permanente de tu base de conocimiento, borra el archivo original guardado, libera las páginas de conocimiento que usaba y lo quita de los agentes a los que estaba asignado. No se puede deshacer. Si el documento no puede quitarse de la base de conocimiento, no se elimina nada. Si su archivo guardado no puede borrarse, el documento sigue en la lista pero ya está fuera de la base de conocimiento. En los dos casos, vuelve a eliminarlo.

Buenas prácticas

• Dale a cada documento un Display Name claro.
• Escribe una Description para que el agente sepa cuándo usar el documento.
• Elige el Document Type correcto. Usa Legal para leyes y contratos y habilitar la búsqueda verbatim por artículo.
• Divide los documentos muy largos por tema.
• Actualiza la estructura de un documento legal después de indexarlo para confirmar que entraron todos sus artículos.

Errores comunes

Captura

Relacionado

• Agentes de IA (RAG)
• Integraciones (API key de OpenAI, cuando tu workspace funciona con su propia key)