Governança de Inteligência Artificial

Nível de acesso requerido

Super Admin

O AI Governance Dashboard (Painel de Governança de IA) é uma ferramenta exclusiva para o Super Administrador da plataforma Flowi Agentic. Seu objetivo principal é fornecer transparência e controle sobre o consumo financeiro da Inteligência Artificial em toda a infraestrutura.

Quem administra apenas um tenant não abre esta tela: mesmo digitando o endereço, é levado de volta ao Dashboard.

Nota

O Flowi Agentic foi projetado em uma arquitetura Single-Client, Multi-Tenant. Isso significa que a organização matriz paga a fatura das APIs de Inteligência Artificial (ex: OpenAI, Google Gemini), e o painel de governança serve para repassar, auditar e controlar os custos de cada departamento ou cliente isolado (Tenants).

O Sistema de Cotas (Quotas)

Para garantir que a fatura da IA não saia do controle, o sistema implementa dois níveis de barreira:

1. Cota do Tenant (Nível 1)

Cada Tenant recebe um limite máximo de tokens mensais (ou por período configurado). Quando esse limite é atingido, o Tenant é imediatamente bloqueado de realizar operações interativas com a IA (como conversas com os agentes ou criação de formulários via IA).

Todo Tenant nasce com cota de 1 milhão de tokens, criada junto com ele. Ajuste o valor em Tenants → (o tenant) → Cota de Tokens de IA.

Tenant sem cota não usa IA — nenhuma

A barreira é a existência da cota, não só o valor dela. Um Tenant sem linha de cota é recusado antes da primeira chamada, com a mesma mensagem de quem estourou o limite. Se um agente responder que não há cota configurada, é isto — e a correção é abrir a tela acima e salvar.

2. Cota de Usuário (Nível 2)

Dentro de um Tenant é possível definir sub-limites para usuários específicos, o que previne que um único colaborador consuma toda a verba mensal destinada ao departamento inteiro. Hoje quem grava esse sub-limite é o Super Admin — a rota que o salva (PUT /api/admin/users/{id}/ai-quota) exige esse papel, e o Admin do tenant não a alcança.

O que conta para o sub-limite de uma pessoa: apenas os copilots das telas. É o gasto que ela escolhe conscientemente — abriu o copiloto, escreveu a pergunta, apertou enviar.

O que uma etapa de IA gasta é do processo, não de quem apertou iniciar. Quem inicia um processo não escolheu o modelo, não escreveu o prompt e não pode reduzir aquela conta; além disso a etapa pode rodar horas depois, retomada por um temporizador, ou ser refeita pela plataforma. Por isso o consumo de etapa entra na cota do Tenant — de onde sai a fatura — e aparece no relatório identificado pelo processo que o gastou, ao lado das pessoas.

Como ler a tabela Consumo por pessoa e por processo

Linhas com nome e e-mail são pessoas, e o que elas gastaram nos copilots. Linhas marcadas como Processo são etapas de IA, somadas por processo. Sem pessoa atribuída sobra apenas para o consumo que não tem nem processo — aquele que chegou ao modelo sem declarar de onde veio, e que é um alerta, não uma categoria normal.

Soft Limits vs Hard Limits

• Hard Limit (Bloqueio Automático): Ações engatilhadas manualmente por humanos (interações no Copilot) são estritamente bloqueadas se a cota acabar.
• Soft Limit (Overage): Ações agendadas ou em andamento executadas de forma invisível pelo sistema (robôs, Java Delegates, ou automações de background) não são interrompidas quando a cota acaba. Isso evita que processos vitais da empresa falhem pela metade. Os tokens gastos além do limite entram no banco como Overage Tokens (Uso Excedente), para posterior acerto de contas.

A validação de BPMN por IA é Hard Limit, e só o administrador do tenant a dispara

O botão de validação semântica do modelador chama o modelo e gasta a cota do tenant como qualquer copiloto. Por isso a rota (POST /a/ai-validation/bpmn) exige Admin do tenant ou Super Admin — gerente e usuário comum recebem 403. Sem cota, a chamada é recusada com 402 e a mensagem nomeia o tenant; ela não volta disfarçada de parecer sobre o diagrama. Se alguém relatar que a validação "não conseguiu concluir a análise", isso é falha do provedor, não cota.

A avaliação de modelos (MODEL_EVALUATION) é Hard Limit, mas espera na fila

Comparar modelos, na aba Casos de referência do agente, roda os casos em vários modelos — ver Agentes → Avaliar modelos com casos de referência. É gasto opcional pedido por uma pessoa, então a cota é conferida a cada chamada: se acabar no meio, os pares restantes não rodam e a avaliação termina Parcial; o que já foi gasto fica contado. Ao contrário dos copilotos, a avaliação não fura a fila do modelo — espera como uma etapa de processo. No consumo por etapa ela aparece com a funcionalidade MODEL_EVALUATION, a chave do processo do agente e o nome do caso no lugar da etapa; o tenant vê só tokens, o Super Admin vê também o custo.

A avaliação de busca (RETRIEVAL_EVALUATION) é Hard Limit e espera na fila

Avaliar busca, na aba Perguntas de referência da base, embute cada pergunta uma vez e mede a busca — ver Bases de Conhecimento → Medindo a busca. A cota é conferida a cada pergunta: se acabar no meio, as restantes não rodam e a avaliação termina Parcial; o que já foi gasto fica contado, e uma chamada que falhou no provedor depois do envio também aparece, com zero token. No consumo por etapa ela aparece com a funcionalidade RETRIEVAL_EVALUATION, sem processo, e o texto da pergunta no lugar da etapa — não se mistura com RAG_EMBEDDING, que segue sendo o embedding da ingestão e da busca dos agentes. O tenant vê só tokens; o Super Admin vê também o custo.

A geração de robô (ROBOT_GENERATION) é Hard Limit e interativa

Gerar um robô a partir de uma descrição, e cada pedido de Refinar, é uma chamada ao modelo do copiloto, pedida por um administrador do tenant. Sem cota, o pedido é recusado antes de chegar ao provedor e nenhuma revisão é gravada. Uma resposta que não serve (não é o JSON pedido) já foi contada e consome o clique; uma falha do provedor depois do envio também aparece, com zero token. Se o modelo principal falhar e o de contingência responder, são duas linhas da mesma geração, não duas gerações. Editar o código à mão, aprovar, testar e ativar não chamam o modelo. No consumo por etapa ela aparece com a funcionalidade ROBOT_GENERATION, sem processo, e Robô <nome> (<chave>) no lugar da etapa — também para um rascunho descartado. O tenant vê só tokens; o Super Admin vê também o custo.

Chamada que não produz resposta também é cobrada

Um agente pode chamar o modelo e receber de volta uma resposta vazia — o provedor recusa, ou termina sem escrever nada. Os tokens de entrada foram cobrados pelo provedor de qualquer forma, porque ele processou o prompt. A plataforma registra essas chamadas e debita a cota do tenant por elas, para que o número do painel não fique abaixo do que o provedor fatura.

Na lista de auditoria isso aparece como consumo sem contrapartida de resultado. Se um tenant tem uso alto e poucos processos concluídos, chamadas estéreis são a primeira coisa a investigar.

Quando a plataforma não consegue contar, o copiloto recusa

Os copilotos respondem em fluxo, e o provedor só informa a contagem de tokens nos últimos pedaços da resposta. Se essa contagem não chegar, a plataforma não entrega a resposta nos copilotos e no playground: sem contar não há como debitar a cota, e um teto que nunca fecha não é um teto. O usuário recebe uma mensagem dizendo exatamente isso, e a chamada é registrada na lista de auditoria com contagem zero e a origem resposta-sem-contagem-de-tokens — o gasto real dela é maior que zero.

Nos processos a decisão é a oposta e pela mesma razão de sempre: a etapa entrega o resultado e a lacuna fica registrada. Parar um processo por causa de um buraco no relatório trocaria um problema de contabilidade por uma parada de produção.

Se esse aviso aparecer com frequência, o provedor configurado em Plataforma → Configurações de IA é o lugar de olhar primeiro.

O mesmo vale para a etapa que termina em impedimento declarado pelo agente: o modelo leu o documento, concluiu que o trabalho não pode ser feito e encerrou a etapa com um código. A etapa falha, nada é gravado na variável de resultado — e a chamada é contada e debitada como qualquer outra, porque o provedor cobrou por ela. O que a tela não mostra é o código do impedimento: essa lista de falhas é lida hoje pela API, não por aqui.

Chamada interrompida no meio: cobrada pelo provedor, não medida aqui

Há um caso em que a plataforma sabe que gastou e não sabe quanto. Quando uma ferramenta do agente falha no meio da conversa — banco fora, armazenamento indisponível — a chamada é abortada. O prompt já foi enviado e o provedor já cobrou por ele, mas a resposta que carrega a contagem de tokens nunca chega, e não há de onde tirar o número.

Essas chamadas aparecem no relatório com zero tokens e sem produção de saída. O zero não é o consumo real: é a marca de que houve consumo não medido. Preferimos a linha com zero à ausência da linha, porque uma lacuna invisível não se investiga.

O que isso significa para a conciliação

Se a fatura do provedor vier acima do que o painel soma, as chamadas com zero tokens são o primeiro lugar a olhar. Quanto mais falhas de ferramenta um tenant tiver no período, maior a diferença.

Cota recusada é caso diferente e não gera registro nenhum: a verificação acontece antes do envio, então nada foi transmitido e nada foi cobrado.

O desconto de tokens não volta atrás se o processo falhar depois

O desconto na cota acontece em transação própria, separada da transação do processo que disparou a chamada. Na prática: se a tarefa falhar depois que a IA respondeu, os tokens continuam descontados.

É o comportamento correto, e vale explicar por quê. O provedor cobrou no momento em que respondeu — o gasto existiu, independentemente do que aconteceu com o processo em seguida. Se o desconto voltasse atrás junto com a tarefa, o painel mostraria menos consumo do que a fatura, exatamente nos tenants com mais falhas.

Essa separação também é o que permite processar vários documentos ao mesmo tempo: a linha de cota do tenant fica travada apenas pelo instante do desconto. Se ela ficasse travada durante toda a chamada à IA — cerca de vinte segundos —, as demais chamadas do mesmo tenant esperariam em fila, uma de cada vez, por mais threads que houvesse.

Quantas etapas de IA correm ao mesmo tempo

As etapas de IA esperam o provedor numa pool própria, separada da fila de tarefas do motor de processos — enquanto o modelo pensa, a etapa não ocupa vaga de execução nem conexão de banco. Quantas correm ao mesmo tempo é AI_STEP_CORE_SIZE, que vale 8 por padrão.

O teto é por instalação, não por tenant: a mesma pool atende os dois motores, então as vagas são disputadas por todos os tenants, por etapa de processo e etapa de caso juntas. Passando das vagas, as etapas esperam numa fila de 100 (AI_STEP_QUEUE_CAPACITY); passando da fila, a etapa é encerrada como falha e fica disponível para reprocesso, em vez de parar em silêncio.

Quando o provedor limita a taxa

O provedor limita quantas requisições por minuto e por dia um modelo aceita. Uma rajada de etapas — uma importação, um timer que dispara para muitas instâncias — passa por um limitador por modelo antes de chegar a ele. Enquanto espera vaga, a etapa aparece Em andamento, sem erro, e não consome cota nem tentativa. Se o provedor responder que o limite por minuto estourou, a etapa espera o tempo que ele pediu e tenta de novo. Se a cota do dia ou do plano acabou, a etapa vai para Com erro com esse motivo, porque esperar segundos não resolve. O limite de cada modelo é configuração da instalação — ver Deploy → Dimensionamento pela IA.

De onde vem o número de vazão

A conta é etapas simultâneas × 60 ÷ latência da chamada, em segundos. Com as 8 vagas padrão e uma chamada de cerca de 20 s, dá cerca de 24 etapas por minuto na instalação inteira.

É aritmética, não medição da sua instalação. A bancada que produziu os números publicados rodou com o desenho anterior, de 2 vagas, e num teste em que a chamada ao modelo é uma espera artificial de duração fixa: nenhum provedor é contatado, e banco e RAG ficam fora do caminho. Os ~20 s de latência, esses vieram de uma observação real, mas de uma única carga de documentos fiscais, em 2026-08-12.

Use o número como ordem de grandeza para dimensionar, nunca como capacidade contratada: a vazão real depende do modelo, do tamanho do prompt e do que mais estiver rodando na instalação. Antes de prometer um número a alguém, meça com a sua própria carga.

O Dashboard

O teto não é o gasto do tenant

O valor que você configura é o Teto dos Copilots — ele só interrompe as telas assistidas. Os processos continuam rodando depois que o teto é atingido, e o que passa dele entra como Excedente de Processos. Por isso o consumo real de um tenant é usado + excedente, e é esse número que as telas chamam de Consumo Total. Ler o teto como se fosse o total leva à conclusão errada de que processo é de graça.

O painel exibe três métricas globais no topo:

1. Uso Global no Mês (Tokens): soma de tokens de IA no período.
2. Consumo Total (Copilots + Processos): o que a plataforma de fato gastou somando todos os tenants, com o Excedente de Processos logo abaixo, separado.
3. Tenants com Copilots Bloqueados: quantos atingiram o teto — e, na legenda, quantos tenants estão ativos. Bloqueado aqui significa copilots parados, nunca processos parados.

Os cartões são o contador de cota, não o registro de consumo

Os dois primeiros cartões leem o contador de cota de cada tenant: ele é debitado a cada chamada, zerado na virada do ciclo de faturamento e zerado pelo botão Forçar Reset desta mesma tela. O relatório mais abaixo, em Quem está gastando, não lê esses contadores: ele lê o registro de uso, escrito uma vez por chamada, que nenhum reset toca.

Por isso os dois números podem divergir — e divergem bastante depois de um reset ou de uma carga antiga que ainda está dentro da janela do filtro. Nenhum dos dois está errado: o cartão responde quanto já foi debitado do teto neste ciclo, o relatório responde quanto foi gasto de verdade no período escolhido. Apertar Forçar Reset derruba o cartão e não muda uma linha do relatório — isso é o comportamento correto, e é por isso que cada cartão diz na legenda de onde vem.

Abaixo vem a lista de auditoria, com uma linha por tenant e três colunas de número: Consumo Total (usado + excedente), Teto dos Copilots e Excedente de Processos.

Redefinição de Cotas

Ações disponíveis:

• Teto dos Copilots (Máximo de Tokens): em Tenants → (o tenant) → Cota de Tokens de IA, aumenta ou diminui o teto das telas assistidas. Não limita processos.
• Force Reset: zera manualmente os contadores do tenant — tokens usados e excedentes voltam a 0 (usado para correções manuais de faturamento ou extensões de cortesia) e o ciclo reinicia.

A mesma leitura vale na tela do usuário (Usuários → (o usuário) → Cota de IA por Tenant): o número configurado ali é o teto dos copilots daquela pessoa, não uma tampa no que os processos podem gastar em nome dela.

Quem está gastando

Abaixo da lista de tenants, no mesmo painel, a tabela Quem está gastando ordena os clientes pelo que consumiram no período, do maior para o menor. É a pergunta que o painel existe para responder: qual cliente cresceu fora da curva.

Cada linha traz quantas pessoas gastaram, chamadas, tokens e custo. Clicar na linha abre o detalhe daquele tenant, onde ficam as pessoas e as etapas — ver Consumo de IA do tenant, abaixo.

A linha __unknown__ não é um cliente

Se aparecer uma linha com a chave __unknown__, ela é consumo que chegou ao modelo sem declarar de qual tenant veio. Os tokens são reais, a linha entra no total, e não há tela de cliente para abrir — por isso ela não é clicável, e um aviso acima da tabela explica o que é. Trate como falha de instrumentação a reportar, nunca como cliente a faturar.

Filtro de período

As duas telas filtram por período: atalhos de 7, 30 e 90 dias, mês atual, mês anterior, e um intervalo livre em Personalizado.

A cota não segue o filtro, e isso é proposital

A cota de cada tenant conta o ciclo de faturamento e é zerada na virada do período de reposição. Ela não é uma soma do período que você escolheu no filtro. Ao filtrar sete dias e ver a cota anunciando outro número, os dois estão certos: um diz quanto já foi faturado neste ciclo, o outro quanto foi gasto no período escolhido.

Quando o relatório não carrega

Se a consulta falhar — servidor fora, rede, sessão expirada — a tela mostra um aviso vermelho dizendo que não foi possível carregar o relatório. Ela nunca mostra a mensagem de nenhum consumo registrado nessa situação: as duas frases significam coisas opostas, e confundi-las já levou um painel a anunciar que um cliente com 41,8 milhões de tokens não usava IA.

A regra vale nas quatro telas de consumo — este painel, a aba Consumo de IA do tenant, Administração → Consumo de IA e a aba de consumo de uma definição. Mensagem de vazio só aparece quando a resposta chegou e veio vazia de verdade.

Exportar para Excel

O botão Exportar CSV baixa o que está na tela, para o período filtrado. O arquivo é gerado no servidor e traz o que o banco tem — não apenas as linhas que a página carregou.

O arquivo abre no Excel com duplo clique: é UTF-8 com marca de ordem de byte, para que os acentos apareçam corretamente, e usa ponto e vírgula como separador, que é o que o Excel em português espera. Um campo que contenha ponto e vírgula, aspas ou quebra de linha vem entre aspas.

Consumo de IA do tenant

Dentro de Tenants → (o tenant), a aba Consumo de IA responde a pergunta seguinte: dentro deste cliente, quem e o quê. Ela tem o mesmo filtro de período e duas tabelas, cada uma com seu próprio botão de exportação.

Consumo por pessoa e por processo lista quem gastou naquele tenant, do maior para o menor. Pessoas aparecem com nome e e-mail e respondem pelo que gastaram nos copilots; etapas de IA aparecem somadas pelo processo que as executou.

O gasto do processo nunca é escondido nem colado em alguém

Ele faz parte do total do tenant, e é desse total que sai a fatura. Esconder o consumo automatizado faria o número do cliente ficar menor do que o que o provedor cobrou.

Um id no lugar do nome significa que a pessoa não existe mais no cadastro, ou que quem disparou a chamada não era um usuário da plataforma. A linha é mostrada assim mesmo — gasto que não resolve para um nome continua sendo gasto.

Consumo por etapa do processo é a tabela descrita na seção seguinte, restrita àquele tenant. Ali a coluna Tenant não aparece: dentro da página do cliente, ela seria a mesma em todas as linhas.

Consumo por modelo responde a pergunta que o total sozinho esconde: o cliente custa caro porque usa muito, ou porque usa um modelo caro? São diagnósticos opostos e pedem correções opostas.

Cada linha diz qual modelo cada tarefa usou: processo, etapa, modelo e funcionalidade. Uma mesma etapa aparece duas vezes quando rodou em dois modelos — é assim que uma troca de modelo fica visível, com o antes e o depois lado a lado. O mesmo modelo num copiloto e numa etapa de processo também são linhas separadas: uma pessoa escolheu, a outra roda sozinha.

Por que a etapa aparece na tabela de modelo, e o modelo não aparece na de etapa

As duas tabelas parecem redundantes e não são. A de etapa responde por que esta etapa é cara e carrega Iterações e Contexto, que dividem por execução. A de modelo responde qual modelo esta tarefa usa e carrega apenas somas.

Pôr uma coluna Modelo na tabela de etapa estragaria as duas colunas derivadas: uma execução que atravessa mais de um modelo — um agente que cai para o modelo de reserva depois de uma recusa — seria contada inteira em cada linha, e a média de idas ao modelo sairia inflada nas duas. Somas não têm esse problema, e por isso o caminho inverso funciona.

Um modelo chamado unknown significa chamada que falhou antes de o provedor responder: a plataforma tentou, não soube dizer qual modelo atendeu, e nenhum token foi cobrado. A linha aparece porque a tentativa existiu.

O que o próprio tenant enxerga

O administrador de um tenant tem a sua própria tela: Administração → Consumo de IA. Ela mostra, para o período escolhido, o que aquela operação consumiu — por processo e por pessoa, por etapa e por modelo.

Quem desenha os processos também enxerga, no lugar onde pode agir: a aba Consumo de IA dentro de uma definição mostra o consumo daquele processo, com as colunas que explicam o gasto (iterações, contexto recuperado, desperdício). É para o modelador responder este processo pode gastar menos? — prompt, modelo, ferramentas e base de conhecimento são decisões dele.

O tenant também é avisado de consumo não atribuído

Se alguma linha daquele tenant tiver chegado ao modelo sem declarar a funcionalidade de origem, a tabela por etapa mostra o mesmo aviso que o Super Admin vê, e a funcionalidade aparece marcada como UNATTRIBUTED. Quem administra o cliente é justamente quem pode investigar de onde aquele gasto veio — esconder dele seria esconder de quem tem como agir.

O tenant vê tokens, não dinheiro

As telas do tenant mostram consumo em tokens e a cota, nunca valor em moeda. O preço por token é o que a plataforma paga ao provedor; o custo em dinheiro aparece apenas neste painel de governança, para quem paga a fatura. Não é a tela que esconde o número: ele não é enviado ao navegador do cliente.

Consumo por etapa do processo

Esta tabela vive na aba Consumo de IA do tenant. Ela existe porque a contagem de tokens sozinha não diz o que mudar: saber que uma etapa gastou 41 mil tokens não distingue modelo caro de prompt inchado de agente em laço, e as correções são opostas.

Cada linha é uma etapa, ordenada pela mais cara primeiro. A mesma etapa rodando para dois clientes são duas linhas, cada uma na página do seu tenant — nunca uma soma. Etapa aqui é tanto uma tarefa de um processo quanto uma etapa de IA dentro de um caso — a coluna Funcionalidade distingue as duas, AI_DELEGATE para processo e AI_CASE_DELEGATE para caso. Vale reparar nisso antes de procurar a chave da linha no catálogo de processos: numa linha de caso ela é a chave do caso.

Além de chamadas, tokens e custo, três colunas explicam o gasto:

• Iterações — quantas idas ao modelo, em média, uma única execução daquela etapa consumiu. Valor alto significa que o prompt ou a descrição das ferramentas não está levando o modelo aonde ele precisa chegar. Trocar por um modelo mais barato não corrige isso. Uma etapa repetida pelo motor não infla esse número: as retentativas da mesma etapa continuam sendo uma execução só, e o que as separa é o número da tentativa gravado em cada chamada.
• Contexto — quanto do prompt é contexto recuperado da base de conhecimento. Percentual alto aponta o custo para a recuperação, não para o modelo: a correção é buscar menos, ou buscar melhor.
• Desperdício — fração dos tokens gasta em chamadas que não produziram resposta. É o primeiro lugar a olhar, antes de mexer em qualquer prompt.

Linhas que cruzam um limiar de atenção aparecem destacadas com um ícone. As demais ficam neutras de propósito: uma tabela em que toda linha grita não comunica nada.

Quando o custo aparece incompleto

O selo não precificado ao lado do custo significa que alguma chamada daquele grupo usou um modelo sem preço em vigor; passe o mouse para ver quantas chamadas e quantos tokens. O custo mostrado é parcial — e não precificado nunca aparece como zero: sem o selo a etapa pareceria barata justamente por faltar informação, que é o contrário do que o número deveria dizer.

Moeda, estimativa e centavos

Todo valor em dinheiro aparece na moeda do preço, com o símbolo: um grupo que gastou em dois modelos de moedas diferentes mostra US$ 12,40 · R$ 3,10, lado a lado. A plataforma não converte câmbio e nunca soma duas moedas num número só. Abaixo de uma unidade aparecem até quatro casas, para que uma chamada de US$ 0,0004 não vire 0,00. Custos preenchidos pelo primeiro preço do modelo levam o selo estimado — ver Agentes → Preço do modelo.

A contagem de tokens segue o que o provedor cobra: o raciocínio do Gemini entra na saída, e a entrada lida do cache do provedor é registrada à parte e cobrada pela taxa de cache, quando o modelo tem uma.

Totais por tenant e por funcionalidade

A tabela Quem está gastando traz, para cada tenant, duas quantidades sem preço: o armazenamento em uso (anexos não apagados, em GB) e os minutos em robôs globais no período. A plataforma não atribui preço a elas — servem para o operador montar a própria conta.

Abaixo, a tabela Por funcionalidade soma o período por tipo de uso (copilotos, etapas de agente, embedding…), com o custo por moeda. Exportar totais por tenant e Exportar totais por funcionalidade baixam o mesmo em CSV. Os CSVs de pessoas, etapas e modelos ganharam as colunas currency, estimated, unpricedTokens, cachedInputTokens, reasoningTokens e costsByCurrency: uma linha por grupo, como antes — costMicros e currency só vêm preenchidos quando o grupo tem uma moeda, e costsByCurrency lista todas (BRL=5000 USD=1000).

Troca de modelo por classe

Uma etapa de agente amarrado a uma classe de modelo que foi atendida pelo modelo seguinte da classe (o primeiro estava sem cota, no limite ou fora do ar) aparece no consumo com duas linhas quando as duas chamadas chegaram ao provedor: a tentativa que falhou, no modelo que falhou, e a resposta, marcada como FALLBACK, no modelo que respondeu — que é o que dá o preço dela. As duas têm o mesmo id de correlação, então a etapa conta uma vez em execuções. A troca por falta de vaga neste servidor não gera linha nenhuma: o provedor não foi chamado.

A tabela Troca de modelo por classe, abaixo de Por funcionalidade, mostra para cada classe quantas etapas rodaram no período, quantas foram atendidas pelo modelo seguinte e a fatia. Uma fatia que cresce diz que o primeiro modelo da classe está pequeno para a demanda — aumente a cota no provedor ou reordene a classe. O motivo de cada troca fica na linha de uso (selection_reason): cota esgotada, limite de taxa, indisponível, demora, modelo aposentado ou sem vaga.

Consultas a bases externas

Uma base externa (Elasticsearch ou OpenSearch consultado na origem) não chama modelo nenhum: a consulta ao índice não gasta token e não entra no relatório de consumo de IA. Ela é contada à parte, na tabela Consultas a bases externas, logo abaixo de Troca de modelo por classe, pelo período escolhido: por tenant e por base, quantas consultas houve, quantas foram respondidas, quantas falharam (fora do ar, tempo esgotado, credencial recusada), quantas nem foram enviadas (base classificada acima do nível de quem buscou, ou destino não permitido), a taxa de falha e a latência média das respondidas. Não há moeda: o Flowi não sabe quanto o cliente paga por consulta ao próprio índice. A contagem é guardada por hora e mantida por 400 dias.

No modo vetorial a pergunta usa o mesmo vetor da busca local, então o custo de embedding continua sendo o da linha RAG_EMBEDDING de sempre. Na etapa, o registro de auditoria da busca diz quantas consultas externas ela fez, mesmo quando nenhum token foi gasto.

Consumo não atribuído

Se aparecer um aviso de consumo não atribuído, ele significa que chamadas chegaram ao modelo sem declarar de que funcionalidade vieram. Os tokens são reais e foram cobrados; o que faltou foi a marcação de origem, que fica registrada no log da aplicação. É uma falha de instrumentação a reportar, não um erro de cobrança.

Embeddings também aparecem aqui

Os embeddings gerados na ingestão de bases de conhecimento e na busca RAG são medidos e aparecem como um grupo RAG_EMBEDDING na tabela, sem processo nem etapa associados — um embedding não roda dentro de um passo do fluxo. O preço vem da configuração global de embedding, na aba Banco de Vetores (RAG) da tela de Configuração de IA — não do catálogo de modelos de chat: um embedding não tem tokens de saída, então o custo é calculado só sobre os tokens de entrada. O preço pertence à configuração que atendeu a chamada: trocar o modelo de embedding começa uma configuração nova, sem preço até receber um.

Desde o acesso por documento (#206), mantido pela busca híbrida (#203), cada busca RAG embute a pergunta uma vez e reaproveita o vetor para a base do tenant e a global; antes eram duas chamadas por busca. Por isso o volume de RAG_EMBEDDING de busca cai pela metade a partir dessa versão, sem que nada tenha deixado de ser medido. A busca por palavra-chave do modo híbrido e a troca de idioma de uma base não chamam modelo e não aparecem aqui.

Quanto custou cada versão de um documento

Cada linha de embedding da ingestão de uma base carrega a versão do documento e o número da tentativa (kb_document_version_id e ingestion_attempt em ai_usage_logs). Com isso dá para responder quanto custou a v4 de uma política e distinguir uma nova tentativa — o provedor caiu no meio e a ingestão tentou de novo — de uma versão nova. A gaveta de versões da base de conhecimento mostra a soma de tokens de embedding de cada versão; a fonte de verdade continua sendo esta tabela.

O que não custa embedding: reenviar o mesmo arquivo, reenviar um arquivo com o mesmo texto, restaurar uma versão dentro da janela de órfãos e um PDF digitalizado que ficou como Precisa de OCR. O OCR da instalação também não aparece aqui: ele roda no Tesseract, dentro do servidor, e não é uma chamada a modelo. Os tokens de uma tentativa que falhou depois de o provedor responder já foram cobrados e ficam registrados com o número da tentativa.