AI Chat — Guía del usuario

Para qué sirve el módulo «AI Chat»

El módulo es el lugar único para conversar con IA dentro de YoBench. Conecta OpenAI, Anthropic Claude, YandexGPT o cualquier LLM local compatible con OpenAI (LM Studio, Ollama, vLLM, llama.cpp), corre conversaciones paralelas, vincula contextos RAG y deja que el modelo use un kit de herramientas de producción — navegador, terminal, sistema de archivos, búsqueda web y generación de Word / Excel / PowerPoint / PDF — bajo tu control con permisos explícitos.

Lo que obtienes:

Núcleo IA basado en agente — el asistente funciona como un agente con diálogos de permiso explícitos, una línea de tiempo de ejecución unificada y un logger estructurado del chat con filtrado y exportación.
Kit de herramientas de producción — generar y editar documentos Word, Excel, PowerPoint y PDF, extraer imágenes, manejar un terminal y un sistema de archivos endurecidos multiplataforma (clasificación de rutas, resolución de symlinks, protección SSRF).
Búsqueda web pluggable — Brave, DuckDuckGo o Tavily como backend de búsqueda, intercambiable por workspace.
Experiencia de voz unificada — un único botón de micrófono más dos toggles. TTS en streaming por frases, detección automática de idioma (en/ru/de/fr/pt/es), reinicio automático del micrófono para diálogo manos libres.
Cancelación como resultado de primera clase — Cancelado por el usuario aparece en la línea de tiempo y los logs como un estado distinto del error, con limpieza correcta de las herramientas largas.
Soporte de visión — los resultados de herramientas con imágenes (capturas, imágenes extraídas) son visibles para el asistente en el siguiente turno.
Múltiples conversaciones paralelas — cada una con su proveedor, modelo, system prompt, contexto RAG.
Streaming — los tokens llegan en chunks, no al final.
Contextos RAG — respuestas desde tus documentos vía búsqueda híbrida (vector + BM25).
Logs — cada evento (peticiones LLM, streaming, ejecución de tools) registrado por separado, con enmascaramiento de claves.
Compactación de contexto — el historial antiguo se resume automáticamente en context_summary para no chocar con los límites de tokens.

Proveedores soportados

Implementados en el código:

OpenAI — API oficial vía OpenAIAdapter.
Anthropic Claude — vía ClaudeAdapter.
YandexGPT — vía YandexGPTAdapter.
LLMs locales compatibles OpenAI — LM Studio, Ollama, vLLM, llama.cpp; enrutados a través de OpenAIAdapter.

Parámetros del proveedor:

API key — la clave.
API URL — URL base (opcional, por defecto la del proveedor).
Modelo — identificador.
Temperature — creatividad (0–2, por defecto 0.7).
Max tokens — tope de tokens de salida (por defecto 4096).
Frequency penalty — penalización de repeticiones (0–2, por defecto 0). Para LLMs locales se recomienda 0.3–0.5.
Presence penalty — penalización de temas nuevos (0–2, por defecto 0).
Proxy — opcional, para peticiones salientes.

Parámetros de la conversación

Al crear (chat_conversations):

Title — nombre visible; puede auto-generarse desde el primer mensaje.
Provider — qué proveedor IA.
System prompt — instrucciones para el modelo.
Temperature — sobrescribe el valor global.
Tools enabled — tool use on/off.
Max auto-iterations — cuántas iteraciones tool→resultado se permiten (por defecto 3).
Web search provider — proveedor separado para búsqueda web.
Context — contexto RAG vinculado del Gestor de contextos.

Los mensajes viven en chat_messages (role: user / assistant / system, content).

Tool use

Con Tools enabled, el modelo funciona como agente y puede llamar herramientas registradas en el ToolRegistry. En el código vienen:

browser — acciones navigate, click, fill, type, key, screenshot, wait_for_selector, wait_for_navigation, wait_for_url_change, evaluate, get_content, close. Chromium headless.
terminal — ejecución de comandos en un shell endurecido y multiplataforma.
file system — read / write / list con clasificación de rutas (proyecto / sistema / usuario) y resolución de symlinks.
web — operaciones web a través de adaptadores de búsqueda intercambiables (Brave, DuckDuckGo, Tavily) más fetch.
documents — generar y editar Word (DOCX), Excel (XLSX), PowerPoint (PPTX) y PDF; extraer imágenes de los documentos.

Flujo: el modelo elige tool__action → el ExecutionEngine ejecuta → el resultado vuelve al contexto → puede haber otra iteración (hasta max_auto_iterations).

Permisos

Las acciones sensibles disparan un diálogo de permiso explícito antes de ejecutarse:

Escrituras de sistema de archivos fuera del scope del proyecto.
Comandos de terminal que parecen destructivos.
Llamadas de red salientes a dominios fuera de la lista permitida.

Puedes pulsar Allow once, Allow for this conversation o Deny. La denegación se registra como un resultado limpio cancelled — el agente no reintenta y la línea de tiempo conserva la decisión.

Cancelación

La cancelación es un resultado de primera clase, no un error:

Detén la ejecución en cualquier momento → la scope key se cancela y las herramientas largas (browser, terminal) se cierran ordenadamente.
La línea de tiempo distingue cancelled de error, con un motivo en texto («Cancelled by user», «Permission denied», etc.).
Los logs conservan el estado parcial para que puedas retomar desde donde estabas.

Visión y resultados con imágenes

Las herramientas que devuelven imágenes (browser__screenshot, documents__extract_images) emiten resultados con imágenes. En el siguiente turno el asistente ve esas imágenes junto al texto, así los modelos con visión razonan sobre capturas y figuras extraídas sin que tengas que readjuntarlas.

Voz

La experiencia de voz es unificada — un único botón de micrófono más dos toggles para leer respuestas en voz alta y modo de auto-diálogo:

TTS en streaming por frases — la respuesta del modelo empieza a sonar en cuanto la primera frase está lista, sin esperar al final.
Detección automática de idioma — en / ru / de / fr / pt / es. La voz toma tu idioma sin selección manual.
Reinicio automático del micrófono — en modo auto-diálogo el micrófono se rearma cuando el asistente termina de hablar, así puedes mantener la conversación manos libres.
Offline por defecto — speech-to-text vía Whisper, text-to-speech vía Piper. Sin servicios externos salvo que tú los conectes explícitamente.

Contexto RAG

En los ajustes de la conversación eliges un contexto del Gestor de contextos. En el primer mensaje el módulo recupera chunks relevantes y los inyecta en el system prompt. En turnos posteriores el retrieval no se repite — el contexto ya está.

Cada sesión también puede cambiar el modo de búsqueda:

Rápido (por defecto) — la búsqueda híbrida (vector + palabra clave) devuelve resultados en una fracción de segundo.
Preciso — añade un paso de reranker tras la búsqueda híbrida. Más lento, claramente mejor en consultas largas o ambiguas.

Ajustes globales

En Ajustes → AI Chat:

chatDefaultProviderId — proveedor por defecto para nuevas conversaciones.
chatDefaultContextId — contexto RAG por defecto.
chatDefaultSystemPrompt — system prompt por defecto.
chatDefaultTemperature — temperature por defecto (0.7).
chatDefaultToolsEnabled — tool use activo por defecto (por defecto on).
chatDefaultMaxAutoIterations — tope de auto-iteraciones (por defecto 3).
chatDefaultWebSearchProviderId — proveedor de búsqueda web.
chatDefaultMaxTokens — tope de tokens de salida (por defecto 4096).
chatDefaultFrequencyPenalty / chatDefaultPresencePenalty — penalizaciones (por defecto 0).

Flujo de uso

1. Conecta un proveedor

En Ajustes → Proveedores añade un proveedor: tipo, API key, modelo, base URL y proxy opcionales.

2. Crea una conversación

Abre AI Chat en el menú lateral izquierdo.
Pulsa Nueva conversación.
Elige un proveedor (o usa el por defecto).
Opcionalmente system prompt, temperature, contexto RAG.

3. Envía mensajes

Escribe una petición → la respuesta llega en streaming. Activa/desactiva Tools enabled por conversación.

4. Adjunta imágenes y contextos

Imágenes — arrástralas al composer; el base64 va en la petición (el proveedor debe soportar vision).
Contexto RAG — elegido en los ajustes de la conversación.

5. Controla el tool use

Configura Max auto-iterations en los ajustes. El modelo puede llamar browser__navigate → terminal__run etc. Detalles en los Logs.

6. Inspecciona logs

La pestaña Logs muestra el flujo de eventos: peticiones LLM, streaming, ejecución de tools, errores. Filtros por level, category. Los secretos (claves API, tokens Bearer) se enmascaran automáticamente.

7. Gestiona conversaciones

Renombrar — auto-naming desde el primer mensaje, editable manualmente.
Eliminar — quita la conversación y sus mensajes.
Detener generación — chat:stop-generation interrumpe el stream actual.

Siguientes pasos

Conecta Contextos y RAG para respuestas ancladas en tus datos.
Usa el Web Parser para preparar datos que luego le pidas a la IA.
Para escritura/edición de documentos, el asistente IA integrado en Docs es más rápido.

Ayuda y comentarios

¿Quieres soporte de Gemini, Mistral o más tools? Escríbenos a través del formulario de contacto.