Osservabilità LLM in un gateway API multimodello: tracce, registri dei token, analisi dei tenant e registrazione sicura dei prompt

Il conteggio delle richieste aggregate e la spesa mensile non sono sufficienti quando un cliente chiede perché ieri un flusso di lavoro è diventato più lento, più costoso o meno affidabile. Un gateway API multimodello può rispondere a questa domanda se tratta l'osservabilità come parte del piano di controllo: ogni richiesta ottiene una traccia, ogni chiamata del modello aggiorna un registro di utilizzo, ogni tenant e flusso di lavoro sono attribuibili e i contenuti sensibili sono protetti per impostazione predefinita.

Questo articolo descrive un progetto pratico per l'analisi dell'utilizzo dell'AI e l'osservabilità LLM in un gateway che si interfaccia con più provider tramite un'API compatibile con OpenAI. Il modello è utile anche se non utilizzi alcun fornitore specifico: strumentalizza una volta al gateway, normalizza la telemetria del modello, preserva l'attribuzione della fatturazione e acquisisci i contenuti dei prompt solo in base a criteri espliciti.

Il problema del lettore: "Quale tenant, modello, prompt o percorso di recupero ha causato la modifica?"

La maggior parte dei team alla fine si trova ad affrontare la stessa lacuna di debug. I registri dell'applicazione mostrano che una funzionalità non è riuscita. I dashboard dei fornitori mostrano che l'utilizzo dei token è aumentato. La finanza vede una fattura. Nessuna di queste visualizzazioni, da sola, spiega il percorso completo dalla richiesta del tenant alla chiamata del modello fino al contesto di recupero per riprovare al costo fatturato.

L'obiettivo non è un'altra dashboard con il totale dei token. L'obiettivo è rispondere a domande operative come:

• Quale tenant o chiave API ha causato un picco di spesa?
• La latenza è aumentata dopo la modifica dell'alias di un modello?
• I nuovi tentativi o i fallback contano due volte i costi?
• Quale versione del prompt brucia la maggior parte del budget di errori?
• Un flusso di lavoro RAG è diventato costoso perché il recupero ha aggiunto troppi token di contesto?
• È possibile supportare il debug di un incidente senza leggere le richieste dell'utente privato?

Fatti, consigli e previsioni

Fatti: OpenTelemetry documenta convenzioni semantiche e attributi dell'intelligenza artificiale generativa per le operazioni del modello, inclusi nomi di operazioni come chat, generate_content e text_completion. La stessa documentazione avverte che gli attributi dei messaggi di input e output di GenAI potrebbero contenere informazioni riservate o PII e potrebbero richiedere filtri o troncamenti. I principali fornitori di modelli espongono anche dashboard di utilizzo, API o esportazioni che possono supportare la riconciliazione lato fornitore, sebbene i dettagli differiscano in base al fornitore.

Consigli: utilizza OpenTelemetry per tracce indipendenti dal fornitore, ma mantieni le dimensioni aziendali di proprietà del gateway nei tuoi attributi e nei tuoi registri. Non archiviare prompt o output non elaborati per impostazione predefinita. Archiviare prima i metadati, gli hash, i conteggi dei token, gli ID dei modelli di prompt, i nomi degli schemi, le classi di errore e le etichette di sicurezza. Aggiungi l'acquisizione dei contenuti solo come funzionalità di debug con attivazione e controllo dell'accesso e di breve conservazione.

Previsione: l'osservabilità LLM riguarderà meno dashboard di fornitori isolati e più piani di controllo tra fornitori. I team si aspetteranno un unico luogo in cui analizzare latenza, costi, qualità, eventi legati alle policy, comportamento dei tenant e delta di fatturazione tra i modelli.

Architettura di riferimento: osservare l'intero percorso della richiesta

Un gateway può visualizzare l'intero ciclo di vita della richiesta senza richiedere a ogni team dell'applicazione di creare telemetria personalizzata. Un modello di traccia utile inizia con uno span principale per la richiesta del cliente in entrata e intervalli secondari per i passaggi che influiscono su costi, latenza e qualità.

Struttura dell'intervallo consigliata

• Intervallo di richieste del gateway: richiesta accettata, autenticata, autorizzata, con velocità limitata e instradata.
• Intervallo di chiamate del modello: provider, modello, operazione, utilizzo del token, stato della risposta e latenza.
• Intervallo di recupero: indice interrogato, ID documento o ID con hash, conteggio blocchi, latenza di recupero e condivisione token di contesto.
• Intervallo di chiamate dello strumento: nome dello strumento, stato, latenza, classe di errore e classificazione degli effetti collaterali.
• Intervallo di tentativi: motivo dei tentativi, numero di tentativi, stato del fornitore e costo incrementale.
• Intervallo di riserva: modello originale, modello di riserva, attivatore, criteri di compatibilità e risultato finale.
• Intervallo di guardia o moderazione: policy invocata, decisione, etichette e se l'output è stato bloccato o trasformato.
• Intervallo di post-elaborazione: convalida JSON, riparazione dello schema, controlli delle citazioni o formattazione finale.

L'intervallo principale deve contenere identificatori di correlazione stabili. Le campate figlie dovrebbero avere attributi tecnici normalizzati. Il registro di utilizzo dovrebbe contenere registrazioni durevoli di fatturazione e analisi. Evitare di forzare tutte le informazioni nelle etichette delle metriche; valori ad alta cardinalità come ID tenant, hash di prompt e ID di documenti vengono archiviati meglio in tracce, log o tabelle contabili e quindi aggregati in dashboard.

Normalizza i metadati acquisiti su ogni chiamata LLM

Ogni richiesta di modello dovrebbe produrre un record coerente, indipendentemente dal fornitore. Lo schema esatto varierà, ma un minimo pratico è simile a questo:

{
  "request_id": "req_01J...",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tenant_id": "tenant_123",
  "team_id": "team_456",
  "app_id": "support_bot",
  "gateway_key_id": "chiave_789",
  "operation": "chat",
  "fornitore": "nome_fornitore",
  "modello": "id-modello-provider",
  "model_alias": "chat di supporto veloce",
  "prompt_template_id": "refund_policy_v5",
  "prompt_hash": "sha256:...",
  "response_schema": "support_answer_v2",
  "status": "completed",
  "error_class": null,
  "latency_ms": 1842,
  "input_tokens": 2110,
  "output_tokens": 384,
  "cached_input_tokens": 1200,
  "estimated_cost_usd": "0.00492",
  "final_billed_cost_usd": null,
  "finish_reason": "stop",
  "retry_count": 0,
  "fallback_used": false,
  "content_capture_policy": "metadata_only"
}

Keep two ideas separate: telemetry explains what happened, while the usage ledger records what should be charged, reconciled, and reported. Si riferiscono a vicenda con ID di richiesta e ID di traccia, ma non devono necessariamente vivere nello stesso sistema di archiviazione.

Costruisci un token e un registro dei costi, non solo contatori

I contatori di token sono utili per i grafici, ma non sono sufficienti per la fatturazione o l'indagine sugli incidenti. Un registro dovrebbe rappresentare le transizioni di stato. Crea una riga quando il gateway accetta una richiesta, quindi aggiornala man mano che la richiesta procede.

Stati contabili utili

• accettato: controlli di autenticazione e criteri superati.
• inoltrata: la richiesta è stata inviata a un fornitore.
• streaming: il fornitore ha iniziato a restituire i token.
• completato: la risposta è stata completata con successo.
• user_aborted: il client si è disconnesso prima del completamento.
• riprovato: è stato effettuato un tentativo da parte di un ulteriore fornitore.
• fallback_used: è stato selezionato un modello o fornitore diverso dopo un errore o una corrispondenza con le norme.
• non riuscita: la richiesta è terminata senza una risposta utilizzabile.
• riconciliato: i dati sull'utilizzo o sui costi lato fornitore sono stati confrontati e applicati.

This state model helps catch common billing and analytics errors: streamed responses where the client disconnected, retry attempts that were charged by the provider but hidden from the user, fallback paths that counted the wrong model, and cache accounting differences across providers.

Utilizza le convenzioni OpenTelemetry GenAI, quindi estendile con attenzione

Le convenzioni semantiche di OpenTelemetry GenAI forniscono un vocabolario portatile per le operazioni del modello. Use those conventions for common attributes such as operation name, provider, model, request parameters, response finish reasons, token usage, and error status where they apply.

Tuttavia, le convenzioni indipendenti dal fornitore non copriranno tutte le dimensioni aziendali in un gateway. Aggiungi attributi di proprietà del gateway o colonne del libro mastro per:

• ID tenant, ID team, ID cliente rivenditore e ID app;
• ID della chiave API del gateway e ambito della chiave;
• piano di fatturazione, limite di spesa e politica di budget;
• alias del modello e versione della policy di routing;
• ID modello prompt e versione prompt;
• nome del flusso di lavoro e passaggio del flusso di lavoro;
• costo stimato, costo finale fatturato e stato di riconciliazione.

Il compromesso è la cardinalità. Questi campi sono utili per l'indagine, ma possono rendere le metriche costose e rumorose se utilizzate come etichette metriche ovunque. Una regola pratica è: gli aggregati a bassa cardinalità vanno alle metriche; gli identificatori ad alta cardinalità vanno a tracce, log e registri.

Progettare una registrazione sicura di prompt e output

La registrazione completa dei prompt semplifica il debug, ma aumenta la privacy, la conformità, l'archiviazione e l'esposizione ai rischi interni. L'impostazione predefinita più sicura è l'osservabilità innanzitutto dei metadati.

Predefinito: solo metadati

Per la maggior parte del traffico di produzione, archivia:

• richiedi ID modello e versione;
• hash di prompt e output normalizzati;
• conteggio dei token di input, output, cache e contesto;
• nome dello schema di risposta e risultato della convalida;
• etichette di sicurezza e decisioni politiche;
• riepilogo degli errori e classi di errore del provider;
• metadati di recupero, non documenti grezzi.

Attivazione: acquisizione controllata dei contenuti

Se hai bisogno di contenuti non elaborati o revisionati per il debug approfondito, richiedi una policy esplicita. I buoni controlli includono liste consentite dell'ambiente, consenso del tenant, campionamento, lunghezza massima del payload, redazione automatica, finestre di conservazione brevi, crittografia, accesso basato sui ruoli, registri di controllo e un percorso di approvazione rivoluzionario per gli incidenti sensibili.

Non considerare la redazione come perfetta. Riduce il rischio; non lo elimina. Per carichi di lavoro regolamentati o ad alta sensibilità, valuta la possibilità di archiviare solo hash e riprodurre problemi in un cablaggio sintetico con dati di test approvati.

Aggiungi osservabilità RAG come livello separato

La generazione aumentata di recupero può modificare sia la qualità che i costi. La registrazione solo della chiamata del modello finale nasconde la causa principale quando il retriever restituisce troppi blocchi, documenti obsoleti o contesto irrilevante.

Per ogni passaggio di recupero, acquisisci:

• nome dell'indice o della raccolta;
• strategia di recupero e modello di incorporamento;
• ID documento o ID con hash;
• conteggio dei blocchi e token di contesto totali;
• latenza di recupero;
• distribuzione dei punteggi migliori, se disponibile;
• copertura delle citazioni;
• se il contesto recuperato è stato utilizzato nella risposta finale.

Ciò ti consente di distinguere "il modello è peggiorato" da "il retriever ha iniziato a inviare un contesto di bassa qualità o eccessivo". Aiuta anche a identificare i flussi di lavoro in cui i token di contesto dominano il costo totale.

Riconcilia l'utilizzo del gateway con la fatturazione del fornitore

Le stime del gateway sono disponibili immediatamente. I dati di fatturazione lato fornitore sono generalmente più lenti ma più autorevoli. Usali entrambi.

Un processo di riconciliazione giornaliero dovrebbe confrontare le righe del libro mastro del gateway con le API di utilizzo del fornitore, le API di costo, le esportazioni del dashboard o le esportazioni delle fatture. Raggruppa i delta per fornitore, modello, progetto e finestra temporale. Tieni traccia delle differenze separatamente per token di input, token di output, token memorizzati nella cache, conteggi delle richieste e costi.

Differenze di riconciliazione comuni

• Lo streaming si disconnette: il gateway potrebbe vedere un client interrotto mentre il provider fattura ancora i token generati.
• Tentativi: potrebbero essere fatturati più tentativi anche se viene restituita una sola risposta finale.
• Richiesta memorizzazione nella cache: i provider possono esporre la contabilità dei token memorizzati nella cache in modo diverso.
• Arrotondamento: piccole differenze per richiesta possono diventare visibili su larga scala.
• Sconti per lotti o livelli: le fatture del fornitore potrebbero applicare prezzi che la stima in tempo reale non conosceva ancora.
• Modifiche lato fornitore: i prezzi dei modelli, il comportamento della tokenizzazione o le esportazioni della fatturazione possono cambiare nel tempo.

Quando la riconciliazione rileva un delta, evita di sovrascrivere silenziosamente il tuo registro. Memorizza la stima originale, il valore riconciliato dal fornitore, l'origine della riconciliazione e il codice motivo, se noto.

Dashboard che rispondono a domande operative

Crea dashboard partendo dai problemi dei lettori e non da metriche di vanità. Le visualizzazioni utili includono:

• costo per tenant, team, app e flusso di lavoro;
• costo per attività riuscita, non solo costo per richiesta;
• Latenza p50, p95 e p99 per provider, modello e alias del modello;
• Tasso di fallback e tasso di tentativi per percorso;
• Tasso di timeout e andamento delle classi di errore del provider;
• rapporto di riscontri nella cache e stima del risparmio dei token memorizzati nella cache;
• tasso di fallimento della convalida dell'output strutturato;
• versioni principali dei prompt per errore di masterizzazione del budget;
• Condivisione token contesto RAG per flusso di lavoro;
• Blocchi guardrail e colpi del classificatore di prompt-injection.

Per gli avvisi, combina segnali tecnici e commerciali. Un improvviso picco di spesa degli inquilini potrebbe essere più urgente di un piccolo aumento della latenza globale. Un aumento della velocità di fallback dopo la modifica dell'alias del modello può indicare un problema di compatibilità. Le risposte ripetute 401, 429 o 5xx potrebbero indicare problemi chiave, esaurimento della quota o instabilità del provider.

Flusso di implementazione minimo per un proxy compatibile con OpenAI

Per un proxy /chat/completions, il flusso può essere semplice:

1. Ricevi la richiesta e assegna request_id e traccia il contesto.
2. Autenticare la chiave del gateway e risolvere l'ambito di tenant, team, app e policy.
3. Crea l'intervallo del gateway principale.
4. Crea una riga del libro mastro con lo stato accettato.
5. Risolvi l'alias del modello nel modello del provider e nella versione della politica di routing.
6. Metadati del record: operazione, ID modello di prompt, nome dello schema, hash del prompt e policy di acquisizione del contenuto.
7. Avvia l'intervallo di chiamate del modello utilizzando gli attributi semantici GenAI, ove applicabile.
8. Inoltra la richiesta al fornitore selezionato.
9. Per lo streaming, aggiorna lo stato quando arriva il primo blocco e conteggia l'utilizzo con la massima precisione consentita dalla risposta del provider.
10. Al termine, analizzare l'utilizzo del provider, il motivo della fine, lo stato e la classe dell'errore.
11. Aggiorna il registro con token, costo stimato, dettagli sui nuovi tentativi/fallback e stato finale della richiesta.
12. Emetti parametri dal registro e dai dati di span.
13. Esegui la riconciliazione giornaliera e memorizza i costi confermati dal fornitore separatamente dalla stima originale.

Rollout checklist

• Definire gli ID di richiesta canonici e gli ID di traccia.
• Adotta gli attributi OpenTelemetry GenAI per la telemetria dei modelli comuni.
• Crea un registro di utilizzo del gateway con le transizioni dello stato delle richieste.
• Normalizza le dimensioni di provider, modello, alias modello, tenant, app e flusso di lavoro.
• Mantieni i dati delle indagini ad alta cardinalità fuori dalle etichette delle metriche.
• Rendi disabilitati il prompt raw e l'acquisizione dell'output per impostazione predefinita.
• Aggiungi policy esplicite per campionamento, redazione, conservazione e controllo degli accessi.
• Acquisisci metadati di recupero per flussi di lavoro RAG.
• Crea dashboard per costi, latenza, affidabilità, convalida e comportamento del tenant.
• Riconcilia le stime del gateway con l'utilizzo del provider e le esportazioni dei costi.
• Avviso su picchi di spesa, regressioni della latenza, salti di fallback, errori di convalida ed eventi rilevanti per la sicurezza.

Conclusione

Un gateway multimodello è il posto giusto per implementare l'osservabilità LLM perché vede le richieste prima che raggiungano qualsiasi fornitore e può collegare un contesto aziendale che i fornitori non conoscono. Il design più forte non è “registra tutto”. Si tratta di un modello a più livelli: tracce indipendenti dal fornitore per l'esecuzione, un token durevole e un registro dei costi per la fatturazione, analisi dei tenant per la governance, metadati RAG per la qualità del recupero e registrazione dei prompt attenta alla privacy per un debug sicuro.

Inizia con metadati, transizioni di stato e riconciliazione. Aggiungi l'acquisizione dei contenuti solo quando i controlli di policy, conservazione e accesso sono pronti. Questa sequenza offre agli sviluppatori le prove di cui hanno bisogno per eseguire il debug di latenza, qualità e spesa senza trasformare l'osservabilità in un nuovo rischio di esposizione dei dati.

Leggi correlati

• comportamento di tentativi e fallback nel routing API LLM
• prompt caching e modelli di controllo dei costi batch
• chiave API del team management and spend limits