Pular para conteúdo

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 apelidos OBJ-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 (exceto tags).
  • O contexto da tela (página, objeto aberto) é anexado à pergunta, limitado a 1.500 caracteres.
  • Com security.audit_reads ativo, cada pergunta é registrada na auditoria (ai_question, com os primeiros 300 caracteres).
  • Para dados que não podem sair da empresa, use openai_compatible apontando 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 300s para /api/.