AI Chat — Guia do usuário

Para que serve o módulo «AI Chat»

O módulo é o lugar único para conversar com IA dentro do YoBench. Conecte OpenAI, Anthropic Claude, YandexGPT ou qualquer LLM local compatível com OpenAI (LM Studio, Ollama, vLLM, llama.cpp), rode múltiplas conversas em paralelo, vincule contextos RAG a elas e deixe o modelo usar um conjunto de ferramentas de produção — navegador, terminal, sistema de arquivos, busca na web e geração de Word / Excel / PowerPoint / PDF — sob seu controle, com permissões explícitas.

O que você obtém:

AI Core baseado em agente — o assistente roda como um agente com diálogos de permissão explícitos, uma timeline unificada de execução e um logger estruturado de chat com filtros e exportação.
Conjunto de ferramentas de produção — gere e edite documentos Word, Excel, PowerPoint e PDF, extraia imagens, controle um terminal e um sistema de arquivos endurecidos cross-platform (classificação de caminhos, resolução de symlinks, proteção contra SSRF).
Busca na web plugável — Brave, DuckDuckGo ou Tavily como backend de busca, intercambiáveis por workspace.
Voz unificada — um único botão de microfone mais dois toggles. TTS em streaming por frases, detecção automática de idioma (en/ru/de/fr/pt/es), reativação automática do mic para diálogo hands-free.
Cancelamento como resultado de primeira classe — Cancelado pelo usuário aparece separadamente de erros na timeline e nos logs, com encerramento limpo de ferramentas longas.
Suporte a vision — resultados de ferramentas que carregam imagens (screenshots, imagens extraídas) ficam visíveis ao assistente no próximo turno.
Múltiplas conversas paralelas — cada uma com seu provedor, modelo, system prompt, contexto RAG.
Streaming — os tokens chegam em chunks, não no fim.
Contextos RAG — respostas a partir dos seus documentos via busca híbrida (vector + BM25).
Logs — cada evento (requisições LLM, streaming, execução de tools) registrado separado, com mascaramento de chaves.
Compactação de contexto — o histórico antigo é resumido automaticamente em context_summary para não bater nos limites de tokens.

Provedores suportados

Implementados no código:

OpenAI — API oficial via OpenAIAdapter.
Anthropic Claude — via ClaudeAdapter.
YandexGPT — via YandexGPTAdapter.
LLMs locais compatíveis OpenAI — LM Studio, Ollama, vLLM, llama.cpp; roteados via OpenAIAdapter.

Parâmetros do provedor:

API key — a chave.
API URL — URL base (opcional, senão padrão do provedor).
Modelo — identificador.
Temperature — criatividade (0–2, padrão 0.7).
Max tokens — limite de tokens de saída (padrão 4096).
Frequency penalty — penalidade de repetição (0–2, padrão 0). Para LLMs locais recomendam-se 0.3–0.5.
Presence penalty — penalidade de novo tema (0–2, padrão 0).
Proxy — opcional, para requisições de saída.

Parâmetros da conversa

Ao criar (chat_conversations):

Title — nome exibido; pode ser auto-gerado da primeira mensagem.
Provider — qual provedor de IA.
System prompt — instruções para o modelo.
Temperature — sobrescreve o valor global.
Tools enabled — tool use on/off.
Max auto-iterations — quantas iterações tool→resultado são permitidas (padrão 3).
Web search provider — provedor separado para busca na web.
Context — contexto RAG anexado a partir do Gerenciador de contextos.

Mensagens em chat_messages (role: user / assistant / system, content).

Tool use

Com Tools enabled, o modelo roda como agente e pode chamar tools registradas no ToolRegistry. Hoje o código entrega:

browser — ações navigate, click, fill, type, key, screenshot, wait_for_selector, wait_for_navigation, wait_for_url_change, evaluate, get_content, close. Chromium headless.
terminal — execução de comandos em um shell endurecido cross-platform.
file system — read / write / list com classificação de caminhos (project / system / user) e resolução de symlinks.
web — operações web via adaptadores de busca plugáveis (Brave, DuckDuckGo, Tavily) mais fetch.
documents — gere e edite Word (DOCX), Excel (XLSX), PowerPoint (PPTX) e PDF; extraia imagens de documentos.

Fluxo: o modelo escolhe tool__action → o ExecutionEngine executa → o resultado volta ao contexto → pode haver outra iteração (até max_auto_iterations).

Permissões

Ações sensíveis disparam um diálogo de permissão explícito antes de rodar:

Escritas no sistema de arquivos fora do escopo do projeto.
Comandos de terminal que parecem destrutivos.
Chamadas de rede para domínios fora da allow-list.

Você pode escolher Allow once, Allow for this conversation ou Deny. As negações aparecem como um resultado limpo cancelled — o agente não tenta de novo e a timeline registra a decisão.

Cancelamento

O cancelamento é um resultado de primeira classe, não um erro:

Pare a execução a qualquer momento → o scope key é cancelado, ferramentas longas (browser, terminal) são finalizadas com cuidado.
A timeline mostra cancelled separado de error, com uma string de motivo ("Cancelled by user", "Permission denied" etc.).
Os logs preservam o estado parcial para você retomar de onde parou.

Vision e resultados com imagem

Ferramentas que devolvem imagens (browser__screenshot, documents__extract_images) emitem resultados portadores de imagem. No próximo turno o assistente vê essas imagens junto com o texto, então modelos com vision conseguem raciocinar sobre screenshots e figuras extraídas sem você ter que reanexar.

Voz

A experiência de voz é unificada — um botão de microfone mais dois toggles para ler respostas em voz alta e modo de autodiálogo:

TTS em streaming por frases — a resposta do modelo começa a ser falada assim que a primeira frase está pronta, sem esperar a conclusão.
Detecção automática de idioma — en / ru / de / fr / pt / es. A voz pega o seu idioma sem seleção manual.
Reativação automática do mic — em modo autodiálogo o mic é reativado depois que o assistente termina de falar, mantendo a conversa hands-free.
Offline por padrão — speech-to-text via Whisper, text-to-speech via Piper. Nada de serviços externos a não ser que você os configure explicitamente.

Contexto RAG

Nas configurações da conversa você escolhe um contexto do Gerenciador de contextos. Na primeira mensagem o módulo busca chunks relevantes e os injeta no system prompt. Nos turnos seguintes o retrieval não se repete — o contexto já está lá.

Cada sessão também pode trocar o modo de busca:

Rápido (padrão) — a busca híbrida (vetor + palavra-chave) retorna resultados em frações de segundo.
Preciso — adiciona um passo de reranker após a busca híbrida. Mais lento, bem melhor em consultas longas ou ambíguas.

Configurações globais

Em Configurações → AI Chat:

chatDefaultProviderId — provedor padrão para novas conversas.
chatDefaultContextId — contexto RAG padrão.
chatDefaultSystemPrompt — system prompt padrão.
chatDefaultTemperature — temperature padrão (0.7).
chatDefaultToolsEnabled — tool use ligado por padrão (padrão on).
chatDefaultMaxAutoIterations — limite de auto-iterações (padrão 3).
chatDefaultWebSearchProviderId — provedor de busca na web.
chatDefaultMaxTokens — limite de tokens de saída (padrão 4096).
chatDefaultFrequencyPenalty / chatDefaultPresencePenalty — penalidades (padrão 0).

Fluxo de uso

1. Conecte um provedor

Em Configurações → Provedores adicione um provedor: tipo, API key, modelo, base URL e proxy opcionais.

2. Inicie uma conversa

Abra AI Chat no menu lateral esquerdo.
Clique em Nova conversa.
Escolha um provedor (ou use o padrão).
Opcionalmente system prompt, temperature, contexto RAG.

3. Envie mensagens

Digite uma requisição → a resposta chega em streaming. Liga/desliga Tools enabled por conversa.

4. Anexe imagens e contextos

Imagens — arraste para o composer; o base64 vai na requisição (o provedor precisa suportar vision).
Contexto RAG — escolhido nas configurações da conversa.

5. Controle o tool use

Defina Max auto-iterations nas configurações. O modelo pode chamar browser__navigate → terminal__run etc. Detalhes nos Logs.

6. Veja os logs

A aba Logs mostra o fluxo de eventos: requisições LLM, streaming, execução de tools, erros. Filtre por level, category. Segredos (API keys, tokens Bearer) são mascarados automaticamente.

7. Gerencie conversas

Renomear — auto-naming a partir da primeira mensagem, editável manualmente.
Excluir — remove a conversa e suas mensagens.
Parar geração — chat:stop-generation interrompe o stream atual.

Próximos passos

Conecte Contextos e RAG para respostas baseadas nos seus documentos.
Use o Web Parser para preparar dados que depois você pede à IA.
Para escrita/edição de documentos, o assistente de IA embutido em Docs é mais rápido.

Ajuda e feedback

Quer Gemini, Mistral ou mais tools? Escreva para nós pelo formulário de contato.