Quotas e contabilidade de custos: o motor hold-and-settle

Tetos que valem antes do gasto passar

Os tetos de uso numa instalação AI multiusuário costumam viver num painel - um relatório que se lê depois que a conta existe. A quota engine do Simmetric Chat os coloca antes: no caminho do pedido, antes da primeira chamada LLM. O motor cobre três tipos de tetos - tokens, armazenamento e custo (aritmética de dinheiro real, em cents) - e faz isso com a mesma forma em todo lugar: um ledger como verdade do consumo, saldos derivados, travas antes do turno, e uma falha sempre explícita.

Este artigo percorre o projeto: o invariante "nenhum segundo medidor" apoiado no ledger, a cadeia de resolução que decide o teto de cada usuário, como funciona a janela móvel do reset (a história nunca é apagada), e a reserva hold-and-settle em duas fases que torna o teto de custo uma trava real em vez de um alarme adiado.

Uma ferramenta do operador (a classe Community). Fatos: FACT-CENSUS.md F-QUOTA-1.

Nenhum segundo medidor

O único invariante não negociável: a verdade do consumo fica no ledger de token-usage EXISTENTE da plataforma. Saldos, holds e âncoras de reset são estado derivado - jamais uma segunda tabela de contadores que pudesse se deslocar da realidade. As consequências:

• Um reset é uma âncora do ledger, um apagamento. Um reset escreve uma linha-âncora que cerca a janela móvel; a história de uso/custos nunca é apagada nem zerada. O operador pode auditar para trás a qualquer momento.
• As travas são de nível de serviço e antes do turno - rodam onde vivem os dados do domínio (antes da primeira chamada LLM no orquestrador, antes do ingest nos caminhos de carregamento). Não há middleware para esquivar: o cheque está no próprio caminho do serviço.
• A matemática do dinheiro é Decimal-para-cents. Cada conta de custo passa pela camada decimal e pousa em cents INTEIROS - nunca ponto flutuante, nunca deriva de arredondamento.

A cadeia de resolução

O teto de um usuário se resolve por uma cadeia de três níveis, em ordem:

1. A sobrescrita por usuário - o admin fixa diretamente os tetos de token/armazenamento/custo de um usuário nomeado.
2. O padrão de instalação - as chaves de padrões no nível da instalação na configuração do sistema (teto de token, GB de armazenamento, teto de custo em EUR).
3. Ilimitado - o sentinel "0"/vazio = NÃO configurado, e o motor falha aberto: zero mudança de comportamento para as instalações que nunca tocam as quotas.

O fail-open é uma característica com forma explícita: a quota engine é a ferramenta opt-in do operador, e "não configurado" nunca deve virar silenciosamente "bloqueado".

Os três tipos

As quotas de token rolam sobre uma soma de uso em janela desde o ledger, cercada pela âncora de reset mais recente. A resolução devolve um limite e o seu nível de origem - a interface do operador pode apontar qual linha decidiu, por usuário. Ultrapassar = um erro de quota nomeado cujo payload é a chave que a frontend, o widget e os gestores de conectores compartilham.

As quotas de armazenamento se impõem nos caminhos de carregamento antes de despachar ao collector: a sobrescrita por usuário, o padrão da instalação, ou ilimitado.

As quotas de custo - o braço de dinheiro real - são o projeto hold-and-settle, abaixo.

Hold-and-settle

Um gasto em token acontece quando os tokens acontecem; um gasto em euro acontece enquanto o stream corre. A trava de custo por isso reserva ANTES da chamada LLM e liquida na emenda do uso:

1. Reserve (antes da chamada) - uma atualização condicional cujo predicado a base avalia com trava de linha (gasto + estimado ≤ teto): N pedidos concorrentes SE SERIALIZAM em vez de todos passarem pelo mesmo cheque vencido, mais a linha de hold na mesma transação (a reserva é atômica com o cheque).
2. Settle (na emenda) - o hold finaliza e reembolsa estimado menos real. A janela aceita é o sobrepaso em voo (real > estimado) - sem kill no meio do stream por um motivo de custo; o invariante em repouso é exato: gasto liquidado + holds abertos ≤ teto.

Esse par dá ao teto de custo a propriedade que um relatório não pode ter: o teto se aplica antes do gasto se comprometer com o modelo, através de uma reserva com trava de linha honesta sob concorrência.

O pricing: por modelo, congelado por instantâneo, nunca grátis em silêncio

A fonte de pricing por linha: um instantâneo congelado de custos por modelo onde exista (um retoque de tarifa nunca reescreve a história), senão as tarifas de reserva da instalação (a doutrina SC-4: um modelo sem preço nunca esquiva o teto de custo - um piso não-nulo integrado aplica com um log warn-once, assim nada pode parecer grátis por omissão). Moedas: o ledger segue os totais por moeda (USD, EUR, GBP, JPY, CNY, INR na v1 - sem conversão); o custo pousa no evento done do stream.

A configuração vive no caminho dos operadores: Settings → Providers → a ação de pricing do modelo (as tarifas de entrada/saída por 1M tokens + a moeda), ou pricing por usuário para as chaves own-provider. N/A significa "configure uma tarifa"; $0.00 significa explicitamente grátis (os modelos locais devolvidos a 0).

O principal do widget

Visitantes anônimos do widget não são usuários: o consumo do widget se liga ao principal da organização do widget - o tráfego do widget bebe da cadeia de quota dessa organização em vez de inventar identidades por visitante. O tráfego dos conectores e os chats internos compartilham o mesmo único orquestrador, então as travas antes do turno cobrem de forma uniforme as três classes de superfície de conversa.

Para continuar

A guia leva a referência completa do operador - as chaves, os endpoints, o comportamento do reset, o detalhe do pricing - em /pt/docs/quotas-and-costs:

• Quotas and costs - a guia
• Fatos deste post: linha FACT-CENSUS.md F-QUOTA-1 (os três tipos, o ledger sem segundo medidor, o motor hold-and-settle)

Provenance: Simmetric Chat docs/QUOTAS.md (v0.28.1, Phases 207/216) + docs/MODEL_COSTS.md (Phases 203/209/216), quotaService.ts/costQuotaService.ts - no estado documental fixado pelo census (SHA aca5b8ff).