Inteligência artificial¶
A IA generativa é opcional (ai.enabled, desligada por padrão). Sem ela, a engine continua
gerando saúde, achados e o resumo diário por regras e estatística. A IA adiciona:
| Função | Onde | Endpoint |
|---|---|---|
| Assistente conversacional | página Assistente IA e painel flutuante em todas as telas | POST /api/v1/ai/ask |
| Explicar achado | botão Explicar com IA no detalhe do insight | POST /api/v1/ai/findings/{id}/explain |
| Resumo executivo diário | Insights › Relatórios executivos | job summary da engine |
Assistente com ferramentas¶
O LLM não acessa o banco diretamente. Ele chama ferramentas que reutilizam a camada de
consulta da API, com o escopo de tenants do usuário que perguntou (ai/assistant.py):
| Ferramenta | O que faz |
|---|---|
search_entities |
busca objetos por nome parcial, WWPN ou NAA e por tipo. Retorna id, tipo, nome, dispositivo e saúde |
get_entity |
atributos, hierarquia (5 níveis), saúde por métrica, até 10 achados abertos e previsão |
query_metrics |
topn, timeseries (resumida: mín, máx, média, horário de pico, últimos 6 pontos) ou stat via QueryEngine |
get_topology |
caminho ponta a ponta (até 150 nós) com saúde |
list_findings |
achados abertos por severidade, categoria ou objeto, ordenados por prioridade |
capacity_forecast |
objetos mais próximos do esgotamento |
environment_overview |
contagem de objetos, distribuição de saúde, achados e dispositivos |
O prompt de sistema obriga a usar as ferramentas antes de afirmar qualquer coisa, seguir o caminho de I/O em diagnósticos de lentidão, citar números com unidade e período, terminar com recomendações priorizadas e dizer o que falta quando os dados forem insuficientes.
sequenceDiagram
participant U as Usuário
participant API as API (/ai/ask)
participant L as LLM
participant T as Ferramentas (escopo do usuário)
U->>API: "Por que a vm-0042 está lenta?"
API->>L: system prompt + histórico (6 turnos) + pergunta + contexto da tela
L->>T: search_entities("vm-0042")
T-->>L: id, saúde
L->>T: get_topology(id) / query_metrics(lat_ms...)
T-->>L: nós e séries resumidas
L-->>API: resposta final (Markdown)
API-->>U: resposta + ferramentas usadas + tokens
Limites: até 8 rodadas de ferramentas por pergunta (depois disso o assistente pede para refinar a
pergunta), saída de cada ferramenta truncada em 30 mil caracteres, ai.max_tokens (4096) por
resposta e histórico de 6 turnos por conversa. As conversas ficam em chat_sessions e são
visíveis apenas ao próprio usuário.
Provedores¶
ai.provider |
Implementação | Uso típico |
|---|---|---|
anthropic (padrão) |
SDK oficial anthropic, Messages API com tool use. ai.base_url opcional (proxy/gateway) |
Claude na nuvem. Modelo padrão em ai.model: claude-sonnet-5-5 |
openai_compatible |
POST {ai.base_url}/chat/completions com tools no formato de funções |
Azure OpenAI, vLLM, Ollama ou LLM on-premise (ambientes sem internet). ai.api_key é opcional |
Ambos são normalizados para o mesmo formato interno, e o modelo precisa suportar chamada de
ferramentas. A saída para a internet passa pelo proxy corporativo se QV_HTTPS_PROXY estiver definido
(o compose repassa como HTTPS_PROXY, que o httpx respeita).
Privacidade e anonimização¶
- Com
ai.share_entity_names = false, os nomes de objetos (hosts, VMs, arrays, dispositivos) são trocados por apelidosOBJ-001,OBJ-002… antes de ir ao provedor, inclusive dentro de títulos e detalhes de achados, e restaurados na resposta mostrada ao usuário. - IDs (UUID), tipos, métricas e valores numéricos continuam sendo enviados. Atributos com
listas/dicionários não são enviados em
get_entity(excetotags). - O contexto da tela (página, objeto aberto) é anexado à pergunta, limitado a 1.500 caracteres.
- Com
security.audit_readsativo, cada pergunta é registrada na auditoria (ai_question, com os primeiros 300 caracteres). - Para dados que não podem sair da empresa, use
openai_compatibleapontando para um modelo on-premise.
Explicação de achados¶
A explicação é gerada uma vez e armazenada no próprio achado (evidence.ai_explanation),
sendo reaproveitada enquanto o achado não for atualizado pela engine (last_seen). Se a IA estiver
desligada ou sem chave, o endpoint devolve o texto da engine (título, detalhe e recomendação) com
fallback: true, e a interface continua funcional.
Limitações conhecidas¶
- A qualidade depende do modelo. Modelos locais pequenos podem não usar ferramentas de forma confiável.
- O assistente só enxerga o que as ferramentas expõem (não lê logs, não executa ações). A automação é sempre iniciada por um usuário, com aprovação quando o runbook exige.
- Respostas podem levar dezenas de segundos. O nginx usa
proxy_read_timeout 300spara/api/.