Sign in ☰RAGCli · AI Uniandes
Utilice AI Uniandes desde la terminal: converse con asistentes y RAG institucionales, procese archivos y gestione cargas de documentos. El comando de la aplicación es ai-uniandes.
Esta guía corresponde a la versión 0.2.0 del cliente. Los ejemplos usan el entorno de desarrollo y requieren acceso a las aplicaciones y servicios de ese entorno.
1. ¿Qué puede hacer con RAGCli?
Necesidad
Comando
Resultado
Consultar aplicaciones
app list
Lista asistentes y RAG institucionales, con sus identificadores y conteo de documentos.
Interactuar en chat
chat
Conversaciones multimodelo, con asistentes o con un RAG institucional.
Procesar archivos
rag-ingest
Carga de documentos para asistentes y flujos institucionales individuales o desde Excel.
Consultar OnBase
rag-ingest download-metadata-onbase
Exporta metadatos a Excel para preparar una carga institucional.
Agregar contexto temporal
rag-chat upload-file
Adjunta un archivo a la conversación activa del flujo rag-chat.
2. Instalación
Necesita Python 3.9 o superior, el código fuente de RAGCli suministrado por el equipo y acceso de red a los servicios de AI Uniandes y Microsoft Entra ID. Ejecute la instalación desde la carpeta que contiene pyproject.toml.
Windows · PowerShell
cd AI-Uniandes-RAG-CLI py -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -e . ai-uniandes --help
macOS y Linux
cd AI-Uniandes-RAG-CLI python3 -m venv .venv source .venv/bin/activate python -m pip install -e . ai-uniandes --help
Ajuste el nombre de la carpeta si recibió el proyecto con otro nombre. La instalación incorpora las dependencias del cliente. Active el mismo entorno virtual cada vez que abra una terminal nueva.
3. Primeros pasos
Seleccione el entorno, inicie sesión y consulte los identificadores disponibles. En el inicio de sesión de usuario, siga la dirección y el código que muestra la terminal para autenticarse en el navegador.
ai-uniandes config set env dev ai-uniandes login ai-uniandes whoami ai-uniandes app list
Para probar una conversación multimodelo:
ai-uniandes chat --question "¿Cómo puedes ayudarme?"
Para consultar un asistente, sustituya ASISTENTE_ID por un identificador de app list:
ai-uniandes chat asistente --app-id ASISTENTE_ID --question "¿Qué información puedes consultar?"
Los nombres ASISTENTE_ID, RAG_ID, DOCUMENTO_ID, CLIENT_ID y ONBASE_ID son marcadores de ejemplo: reemplácelos por los valores de su entorno.
4. Autenticación y configuración
Modo
Uso
Inicio de sesión
Usuario
Uso interactivo. Es obligatorio para el chat institucional, que resuelve permisos a partir de la identidad del usuario.
ai-uniandes login
Aplicación
Automatización con una aplicación autorizada, por ejemplo ingesta y consultas administrativas.
ai-uniandes login --app --client-id CLIENT_ID --client-secret -
El valor - solicita el secreto sin escribirlo en el comando. Para el modo aplicación, configure también el usuario cuando la operación administrativa lo necesite. Este valor no sustituye una sesión de usuario para el chat institucional.
ai-uniandes config set username [email protected] ai-uniandes whoami ai-uniandes logout
Entorno de trabajo
El cliente admite dev, staging y prod; el valor predeterminado es staging. La disponibilidad de cada servicio depende del entorno. Para una ejecución puntual, escriba --env antes del comando:
ai-uniandes --env dev login ai-uniandes --env dev app list
Desarrollo usa un tenant diferente de staging. Al cambiar de entorno, autentíquese en el entorno seleccionado. El cliente incluye una aplicación de inicio de sesión de usuario para dev y staging; para prod necesita configurar el client_id que le indique el equipo.
Configuración
Uso
env
Entorno predeterminado.
default_app_id
Asistente predeterminado para chat asistente.
institutional_rag_id
RAG predeterminado para chat institucional.
default_model
Modelo de chat preferido; el valor inicial es gpt-5. Su disponibilidad se valida por flujo.
timeout
Tiempo de espera de las llamadas de chat, inicialmente 180 segundos.
ai-uniandes config list ai-uniandes config set default_app_id ASISTENTE_ID ai-uniandes config set institutional_rag_id RAG_ID ai-uniandes config get env ai-uniandes config unset default_app_id ai-uniandes config path
La configuración se guarda en ~/.ai-uniandes/config.json y las credenciales en ~/.ai-uniandes/credentials.json. No comparta el archivo de credenciales. Para las opciones que admiten estas fuentes, la prioridad es argumento de línea de comandos, variable de entorno, archivo y valor predeterminado.
5. Consultar aplicaciones
ai-uniandes app list ai-uniandes app list --type assistant ai-uniandes app list --type institutional ai-uniandes app list --no-counts ai-uniandes app list --json
Copie el identificador de la aplicación que desea usar. --no-counts omite el conteo de documentos y --json facilita el procesamiento de la salida. Un guion en el conteo indica que el cliente no pudo consultar ese resumen.
El listado institucional depende del filtro del servicio por propietario: pertenecer a un RAG no implica que aparezca en esta lista.
6. Chat con AI Uniandes
Flujo
Ejemplo
Contexto
Multimodelo
ai-uniandes chat
Conversación sin un RAG asociado.
Asistente
ai-uniandes chat asistente --app-id ASISTENTE_ID
Asistente seleccionado y su contexto documental.
Institucional
ai-uniandes chat institucional --rag-id RAG_ID
RAG institucional y documentos accesibles al usuario autenticado.
Sin --question, el chat abre una sesión interactiva: escriba salir para terminar o nueva para reiniciar la conversación. Con --question, envía una pregunta y termina.
ai-uniandes chat institucional --rag-id RAG_ID --question "Resume los documentos disponibles." ai-uniandes chat asistente --app-id ASISTENTE_ID --model gpt-4.1 ai-uniandes chat --question "Explica qué es RAG." --new ai-uniandes chat --question "Explica qué es RAG." --no-stream --raw
El cliente muestra la respuesta a medida que llega mediante streaming. --no-stream espera la respuesta completa; --raw, junto con una pregunta, imprime el JSON final. --verbose agrega información de la ejecución. El catálogo valida los modelos admitidos para cada flujo; si rechaza uno, consulte las alternativas que muestra el cliente.
Para el chat institucional, los permisos de documentos se resuelven con la identidad de usuario. Si esa consulta falla, el cliente avisa y continúa solo con documentos públicos. No cambie los roles del comando para intentar conceder acceso.
7. Procesar documentos de un asistente
Flujo: seleccionar asistente → subir archivo → solicitar procesamiento → consultar estado → conversar cuando el documento esté READY.
ai-uniandes rag-ingest ingest-assistant --app-id ASISTENTE_ID --file ./documento.pdf ai-uniandes rag-ingest list --app-id ASISTENTE_ID ai-uniandes rag-ingest status --document-id DOCUMENTO_ID
La ingesta consulta el estado cada 5 segundos, con un máximo predeterminado de 300 segundos. Puede modificar esos valores:
ai-uniandes rag-ingest ingest-assistant --app-id ASISTENTE_ID --file ./documento.pdf --poll-interval 5 --poll-timeout 600
Verifique READY antes de usar el documento como contexto. La versión actual del cliente también detiene la espera en PROCESSED y puede mostrar “INGESTA COMPLETADA”. PROCESSED no confirma que haya terminado la indexación. Vuelva a consultar el estado hasta obtener READY o un error; la opción status --poll también se detiene en PROCESSED.
Carga de varios archivos
Coloque copias de los archivos en la carpeta upload/ del proyecto RAGCli y ejecute:
ai-uniandes rag-ingest batch-assistant --app-id ASISTENTE_ID
Este comando elimina de upload/ los archivos locales que termina en PROCESSED o READY. Conserve los originales en otra carpeta y verifique después el estado READY de cada documento.
8. Documentos institucionales y OnBase
Cargar un documento
ai-uniandes rag-ingest ingest-institucional --file ./documento.pdf --app-id RAG_ID ai-uniandes rag-ingest ingest-institucional --file ONBASE_ID --app-id RAG_ID --source ONBASE
El comando individual configura visibilidad PUBLIC y ejecuta carga y clasificación. No tiene opciones para usuarios o grupos restringidos: para ese caso use el Excel del flujo batch. Después de la clasificación, consulte el documento y confirme READY.
Preparar metadatos de OnBase
Puede navegar por una carpeta o buscar por texto. La exportación genera metadatos para el Excel; no equivale a descargar los archivos originales.
ai-uniandes rag-ingest download-metadata-onbase --path "Secretaria/Actas/" ai-uniandes rag-ingest download-metadata-onbase --search "Acta" --output ./lote/metadata-institucional.xlsx
Use una carpeta nueva para preparar cada lote y revise el Excel antes de iniciar la ingesta. La ruta predeterminada es workspace/flujo-institucional/metadata-institucional.xlsx.
Procesar un lote desde Excel
La carpeta debe contener metadata-institucional.xlsx y los archivos locales referenciados por las filas PORTAL_WEB. Las filas ONBASE identifican el documento por su ID.
Columnas
Cómo completarlas
source
PORTAL_WEB para archivos locales u ONBASE para documentos de OnBase.
filename / document_onbase_id
Nombre del archivo local o ID de OnBase, según la fuente.
name, typology, category, file_source
Metadatos descriptivos del documento y su origen.
visibility
PUBLIC o RESTRICTED.
users / groups
Valores separados por comas. Una fila restringida requiere al menos un usuario o grupo permitido.
action
NEW para una carga nueva. UPDATE y DELETE se usan para cambios posteriores; el proceso también maneja SYNC y DELETED.
id_application, id_file, id_file_document_group, status_file, status_flow
Campos de seguimiento que completa el cliente. Consérvelos para reanudar el lote.
ai-uniandes rag-ingest batch-institucional --folder ./lote --app-id RAG_ID
Flujo: validar Excel → cargar documentos → sincronizar permisos restringidos → clasificar → consultar estados → actualizar Excel. El cliente guarda avances en el mismo archivo; cierre el Excel antes de ejecutarlo. Para reanudar, utilice la misma carpeta y el mismo RAG_ID.
Los valores predeterminados son 200 filas por bloque, 20 hilos concurrentes y 3600 segundos de espera del polling. Puede ajustar la concurrencia y el tamaño del bloque:
ai-uniandes rag-ingest batch-institucional --folder ./lote --app-id RAG_ID --batch-size 50 --concurrency 5
9. Archivos temporales y chat heredado
El grupo rag-chat usa el flujo de asistentes anterior. Para un archivo temporal, mantenga la carga y la pregunta dentro de ese grupo: no presuponga que comparte conversación con chat asistente.
ai-uniandes rag-chat upload-file --app-id ASISTENTE_ID --file ./manual.pdf ai-uniandes rag-chat list-files --app-id ASISTENTE_ID ai-uniandes rag-chat ask --app-id ASISTENTE_ID --question "Resume el manual adjunto." ai-uniandes rag-chat interactive --app-id ASISTENTE_ID
El archivo se vincula a la conversación activa. La carga espera READY o ERROR, con intervalo de 5 segundos y límite de 120 segundos. list-files consulta el registro local y actualiza los estados desde el servicio; no es un inventario de archivos de todos los usuarios o equipos.
Al iniciar otra conversación, el archivo anterior no se transfiere: vuelva a adjuntarlo. El servicio controla la expiración de los archivos temporales.
10. Eliminar documentos
Confirme el entorno y el identificador antes de ejecutar una eliminación.
# Documento de un asistente ai-uniandes rag-ingest delete --document-id DOCUMENTO_ID # Documento institucional: resuelve también su grupo de permisos ai-uniandes eliminar-archivo-institucional --document-id DOCUMENTO_ID
El comando rag-ingest reset-institucional elimina archivos sincronizados y reinicia el Excel para reprocesar. No lo utilice para reanudar un lote interrumpido: vuelva a ejecutar batch-institucional.
11. Solución de problemas
Situación
Qué revisar
No se encuentra ai-uniandes
Active el entorno virtual donde instaló el paquete y ejecute nuevamente python -m pip install -e . desde la carpeta del proyecto.
No hay sesión activa o se rechaza el token
Revise config get env y whoami. Inicie sesión en el entorno correcto; dev y staging usan tenants distintos.
El chat institucional exige usuario
Ejecute login sin --app. Configurar username no convierte un token de aplicación en uno de usuario.
No aparece un RAG institucional
Verifique el entorno, el usuario y el filtro por propietario. Indique --rag-id si conoce un RAG al que tiene acceso.
Modelo no disponible
Seleccione uno de los modelos que muestra el cliente para ese flujo.
Streaming interrumpido
La respuesta puede estar incompleta. Pruebe la pregunta con --no-stream.
El documento queda en PROCESSED
Consulte status nuevamente. Espere READY antes de probar preguntas sobre su contenido.
Excel inválido o lote de otra aplicación
Revise source, archivo o ID de origen, visibility, users/groups e id_application. Reanude con el mismo --app-id.
No se recuperan documentos restringidos
Revise la sesión de usuario y los avisos de resolución de permisos. El cliente puede haber continuado solo con documentos públicos.
Si la instalación solicita credenciales de un feed privado de Azure DevOps o informa invalid command 'bdist_wheel', el README del cliente contempla esta alternativa usando PyPI:
python -m pip install --isolated --index-url https://pypi.org/simple/ -U "setuptools>=68" wheel python -m pip install --isolated --index-url https://pypi.org/simple/ --no-build-isolation -e .
Para consultar las opciones de cada grupo:
ai-uniandes --help ai-uniandes chat --help ai-uniandes rag-ingest --help ai-uniandes rag-chat --help
El cliente utiliza código de salida 2 para errores de autenticación o de modelo y 130 cuando se cancela con Ctrl+C. En los flujos de ingesta, revise además los estados y el resumen: que el proceso termine no garantiza que todos los documentos estén READY.