Monitoraggio costi AI

Ultimo aggiornamento: 2026-05-12 Owner: Product Writer Audience: platform owner, super_admin, ops_admin

Scopo

Spiegare come usare la dashboard Workspace › Platform › AI Usage per monitorare i costi delle chiamate AI (LLM, embedding, reranker) per tenant, modello e tipo di chiamata.

Prerequisiti

• ruolo platform super_admin oppure permission platform.ai.global_policy.manage
• migration 0071_ai_usage_events applicata sul progetto Supabase (di norma fatta dal DBA platform)

Concetti chiave

• AI Usage event: ogni chiamata a modelli AI (Sonnet, Haiku, OpenAI embedding, Cohere rerank) viene registrata in ai_usage_events con tenant, utente, sessione, modello, token in/out, latenza, costo in USD micros, eventuale errore
• Cost in USD micros: il costo e' stoccato come bigint in micros (1 USD = 1.000.000 micros) per evitare drift floating point su grandi volumi
• Ingestion non bloccante: il logging avviene fire-and-forget — se il DB e' lento o la tabella manca, la pipeline chat-hr continua a funzionare senza errori utente
• Group by: la dashboard aggrega per day (trend), model (breakdown), tenant (per cliente), kind (chat_main, haiku_off_topic, haiku_entity, embedding, haiku_rerank, cohere_rerank)

Cosa trovi nella dashboard

• 10 sessioni con costo piu alto nel range
• Colonne: session id (troncato), org (troncato), cost, calls

Passi operativi base

1. Vai a Workspace → Platform → AI Usage
2. Scegli un intervallo (default ultimi 30 giorni)
3. Imposta Primario = day per vedere il trend, Secondario = model per il breakdown
4. Verifica i KPI in alto per il costo totale del periodo
5. Identifica nel chart breakdown il modello/tenant/tipo con costo maggiore
6. Apri la tabella top sessioni per investigare le conversazioni piu costose

Tipi di chiamata tracciate (`kind`)

• chat_main — agente principale Sonnet 4.6 nel turno chat-hr
• haiku_off_topic — classificatore AI 02 W02 (Haiku 4.5)
• haiku_entity — extractor entity 8-dim AI 02 W03 (Haiku 4.5)
• haiku_summary — summarizer episodic memory AI 01 (Haiku 4.5)
• embedding — embedding OpenAI text-embedding-3-large AI 02 W01
• haiku_rerank — reranker Sonnet/Haiku W04
• cohere_rerank — reranker Cohere W04 (scaffold)

Modelli e pricing (riferimento 2026)

| Modello | Input $/M tok | Output $/M tok | Note | |---|---|---|---| | claude-sonnet-4-5 | 3.00 | 15.00 | agent principale | | claude-haiku-4-5 | 1.00 | 5.00 | classifier, entity, rerank | | text-embedding-3-large | 0.13 | n/a | embedding semantico | | rerank-multilingual-v3.0 | n/a | n/a | $1 per 1000 search units |

Il pricing reale e' allineato alle tariffe pubblicate dai provider. Se le tariffe cambiano, aggiornare la tabella TOKEN_PRICING / UNIT_PRICING in apps/web/src/lib/ai-cost-tracking.ts.

Risultato atteso

Il platform owner riesce a:

• monitorare il costo totale AI giornaliero/mensile
• identificare quale modello pesa di piu sul budget (di norma Sonnet chat_main)
• vedere quali tenant generano piu chiamate AI
• spotlight su sessioni anomale (costo molto alto)
• decidere data-driven su attivazione/disattivazione reranker e altre LLM feature

Errori frequenti

• Dashboard vuota con warning "ai_usage_events table not yet provisioned"
• causa: migration 0071 non applicata su Supabase
• soluzione: applicare la migration via Supabase Studio (SQL Editor) o supabase db push

• Costo zero per chiamate visibili
• causa: il modello non e' nella tabella pricing (es. nuovo provider non mappato)
• soluzione: aggiornare TOKEN_PRICING o UNIT_PRICING in ai-cost-tracking.ts

• 403 Missing permission
• causa: l'utente non ha platform.ai.global_policy.manage
• soluzione: assegnare il permission via Platform IAM o usare super_admin

Out of scope (limiti noti W05)

• Nessun backfill storico: il logging parte dal momento in cui la migration e' applicata
• Nessun alert via email su soglia (decisione data-driven post-W06)
• Nessun export CSV (decisione data-driven)
• Nessuna granularita user-finale (solo per tenant + globale)
• Nessuna dashboard tenant-side (solo platform owner per ora)

Guide collegate

• roles/owner

FAQ

Posso vedere i costi solo del mio tenant?

In questa versione la dashboard e' platform-side. Una dashboard tenant-side (owner del tenant vede solo i propri costi) e' nel backlog futuro.

Cosa significa "haiku_rerank" vs "cohere_rerank"?

Il reranker semantico W04 ha due provider configurabili:

• haiku_rerank usa Anthropic Haiku 4.5 (default quando attivato)
• cohere_rerank usa Cohere Rerank API (richiede cohere_api_key configurata)

Cosa succede se la tabella `ai_usage_events` non esiste?

Il logging fail-soft: la chiamata AI continua a funzionare, solo non viene tracciata. La dashboard mostra empty state + warning.

I costi sono in tempo reale?

Lo storico e' aggiornato live (ogni call viene loggata entro 1-2 secondi via fire-and-forget). Pero' la dashboard fa un query SELECT a ogni reload, quindi non c'e' streaming/websocket.