Come creare osservabilità LLM neutrale rispetto al fornitore con OpenTelemetry

L'osservabilità LLM si interrompe quando ogni team dell'applicazione registra le risposte del fornitore nel proprio formato. Durante un incidente, i team della piattaforma devono rispondere a domande concrete: quale team ha effettuato la richiesta, quale ambito chiave API è stato utilizzato, quale modello è stato richiesto, quale fornitore lo ha effettivamente servito, se si è verificato un nuovo tentativo o un fallback, quanti token sono stati consumati, quale bucket di latenza è cambiato e quale classe di errore ha causato l'errore. Hanno anche bisogno di queste risposte senza copiare richieste grezze, completamenti, chiavi del fornitore o identificatori del cliente in archivi di log generici.

La risposta pratica è utilizzare il gateway multi-modello API come punto di controllo dell'osservabilità. Il tracciamento a livello di applicazione è ancora importante, ma il gateway è il punto in cui è possibile normalizzare la selezione del provider, i nuovi tentativi, i fallback, la contabilità dell'utilizzo, la proprietà delle richieste e l'applicazione della privacy prima che la telemetria raggiunga gli strumenti a valle. Per i team che gestiscono un LLM aziendale API, questa diventa la differenza tra dati di debug sparsi e un modello operativo indipendente dal fornitore.

Definisci innanzitutto il contratto di osservabilità

Inizia con un contratto di attributi scritto, non con screenshot della dashboard. Il contratto dovrebbe definire i metadati minimi che ogni richiesta LLM deve emettere, quali campi possono lasciare il gateway, quali campi sono limitati e quali campi non vengono mai esportati.

Un contratto di base utile include proprietà, routing, modello, utilizzo, latenza e metadati dei risultati. Gli attributi di proprietà identificano l'organizzazione, il team, l'ambiente, il carico di lavoro, l'applicazione e l'ambito della chiave API. Gli attributi di instradamento identificano il percorso del gateway, la versione della policy, il provider richiesto, il modello richiesto, il provider selezionato, il modello selezionato, il numero di tentativi, il numero di fallback e se è stato utilizzato lo streaming. Gli attributi di utilizzo acquisiscono token di input, token di output, token di input memorizzati nella cache, token di ragionamento quando disponibili, conteggio delle richieste e classe di costo stimata. Gli attributi del risultato acquisiscono lo stato, il codice di errore del fornitore quando è sicuro, la classe di errore normalizzata, il risultato della convalida, lo stato di timeout e il modello di risposta finale.

Mantieni il contratto neutrale rispetto al fornitore. Un errore specifico del provider, ad esempio una risposta al limite di velocità, una risposta del modello sovraccarico, un errore di convalida dello schema, un rifiuto di sicurezza, un timeout o un errore della finestra di contesto, dovrebbe essere associato a una classe di errore normalizzata che i dashboard possono raggruppare tra provider. Il codice di errore del provider originale può essere utile, ma deve essere trattato come dati diagnostici limitati, non come dimensione primaria del dashboard.

Utilizza un modello di span centrato sul gateway

Una struttura di traccia chiara impedisce che la telemetria LLM diventi una pila piatta di span. Utilizza un intervallo di richieste dell'applicazione in entrata, un intervallo di operazioni LLM logiche e intervalli secondari per il lavoro eseguito dal gateway.

Una gerarchia tipica è simile a questa:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

L'intervallo di richieste in entrata rappresenta la richiesta del chiamante al gateway. L'intervallo di operazioni LLM logiche rappresenta l'attività LLM visibile all'utente, anche se il gateway effettua più tentativi del provider. Gli intervalli di tentativi del provider acquisiscono ogni chiamata effettiva a un modello upstream API. Gli intervalli di recupero, strumento e convalida dovrebbero essere elementi secondari dell'operazione logica quando fanno parte della produzione della risposta finale.

Questa separazione è importante durante gli incidenti. Se una richiesta passa da un modello a un altro, l'operazione logica potrebbe riuscire mentre il primo tentativo del provider fallisce. Se l'output finale non supera la convalida dello schema, il tentativo del provider potrebbe avere successo tecnicamente mentre l'operazione logica fallisce. Senza intervalli separati, le dashboard nascondono gli errori del provider dietro risposte corrette dell'utente finale o sovrastimano gli errori che sono stati ripristinati con successo.

Mappatura degli attributi OpenTelemetry GenAI dietro un mappatore interno

Esistono convenzioni semantiche di OpenTelemetry in modo che i produttori di telemetria utilizzino nomi e attributi comuni tra codebase, librerie e piattaforme.Il progetto OpenTelemetry ora punta le convenzioni di intelligenza artificiale generativa a un repository GenAI separato e tali convenzioni definiscono gli attributi di richiesta e risposta del modello come nome del provider, modello richiesto, modello di risposta, token di input, token di output, token di ragionamento e token di input memorizzati nella cache.

Utilizza questi attributi GenAI dove si adattano, ma non disperdere i nomi degli attributi grezzi nel codice del gateway. Avvolgili dietro un piccolo mappatore di telemetria. Il mappatore dovrebbe accettare un record di richiesta interna e produrre attributi di span standardizzati.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

Il mappatore può emettere attributi OpenTelemetry GenAI per i campi standard e attributi del gateway privato per il contesto aziendale. Mantieni gli attributi privati ​​in uno spazio dei nomi controllato, ad esempio llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy e llm_gateway.workload_class.

Questo design ti offre telemetria indipendente dal fornitore proteggendo al tempo stesso la base di codice dall'abbandono. Le convenzioni GenAI sono ancora in evoluzione, quindi il mappatore è il luogo in cui i nomi possono cambiare senza modificare ogni gestore, modulo di ripetizione, adattatore di streaming e componente di convalida.

Separare i metadati dai contenuti sensibili

Le tracce LLM sono insolitamente sensibili perché i dati di debug più utili potrebbero essere gli stessi dati che non dovrebbero essere conservati su larga scala: prompt, documenti recuperati, parametri dello strumento, completamenti, identificatori utente, identificatori cliente, e credenziali grezze del fornitore. La strategia predefinita dovrebbe essere l'osservabilità innanzitutto dei metadati.

I campi predefiniti consigliati includono hash del prompt, ID del modello di prompt, versione del prompt, ID dello schema, nome dello strumento, raccolta di recupero, nome del percorso, conteggi dei token, latenza, classe di errore normalizzata e stato di convalida. Questi campi rispondono a molte domande operative senza esportare contenuti non elaborati.

L'acquisizione di prompt e completamento non elaborati deve essere attivabile, limitata nel tempo, con accesso controllato e oscurata prima dell'esportazione. Non abilitarlo a livello globale come funzionalità di comodità. Quando è necessaria l'acquisizione di contenuti per un incidente di produzione, allega un flag di debug a un insieme ristretto di richieste, instrada tali tracce a un backend limitato e imposta una finestra di conservazione breve.

L'hashing degli identificatori non comporta automaticamente l'anonimizzazione. Se lo spazio di input è piccolo o prevedibile, i valori hash possono essere invertiti tirando a indovinare. Per gli identificatori sensibili di clienti o utenti, prendi in considerazione l'eliminazione, gli ID surrogati, il bucket, il troncamento o l'hashing con chiave con controlli rigorosi delle chiavi. Utilizza gli hash principalmente per una correlazione stabile quando il rischio è compreso, non come una risposta generale alla privacy.

Applica la privacy nel raccoglitore

Le linee guida di OpenTelemetry affermano che i dati sensibili devono essere gestiti prima dell'esportazione. Il servizio di raccolta può rimuovere, eseguire l'hashing, filtrare, oscurare o trasformare gli attributi di telemetria utilizzando processori quali attributi, filtro, oscuramento e trasformazione. Ciò rende il Collector una seconda linea di difesa dopo la strumentazione del gateway stessa.

Una pipeline pratica del Collector dovrebbe utilizzare una lista consentita per gli attributi a basso rischio, eliminare i campi di prompt e risposta non elaborati per impostazione predefinita, mascherare i valori corrispondenti ai modelli bloccati e instradare separatamente le tracce con sensibilità più elevata quando l'acquisizione del contenuto è abilitata esplicitamente. Il processore degli attributi di OpenTelemetry Collector supporta azioni come l'eliminazione e l'hash. Il processore di redazione è progettato per eliminare gli attributi che non sono presenti in una lista consentita e mascherare i valori corrispondenti ai modelli bloccati.

Ad esempio, il gateway può evitare di emettere contenuti non elaborati per impostazione predefinita, mentre il raccoglitore elimina comunque attributi come llm.prompt.raw, llm.completion.raw, provider.api_key, authorization e cookie se compaiono a causa di un bug o dell'integrazione della libreria. Considera questo come un controllo approfondito di difesa, non come un motivo per emettere dati non sicuri in modo casuale.

Ripetimenti, fallback e convalida dello strumento separatamente

I tentativi e i fallback sono spesso invisibili nei API parametri aggregati. Questa invisibilità causa due problemi operativi. Innanzitutto, la latenza può peggiorare perché una risposta riuscita può nascondere più tentativi falliti.In secondo luogo, i costi possono aumentare perché una singola richiesta dell'utente può creare diverse chiamate al modello upstream.

Ogni intervallo di tentativi del fornitore deve includere il numero del tentativo, il motivo del nuovo tentativo, il fornitore selezionato, il modello selezionato, il budget di timeout, la latenza, l'utilizzo del token quando disponibile e il risultato. Se si verifica un fallback, l'intervallo di fallback dovrebbe identificare la policy di instradamento originale, il motivo del fallback e il modello effettivamente utilizzato per la risposta finale.

La convalida dell'output strutturato dovrebbe essere un proprio intervallo o evento. Acquisisci l'ID dello schema, la versione dello schema, il risultato della convalida, il conteggio dei tentativi di riparazione e lo stato finale. Per impostazione predefinita, non archiviare l'intero output non valido. Un errore di convalida è operativamente diverso da un errore di trasporto del provider e i dashboard non dovrebbero confonderli insieme.

Crea dashboard attorno alle domande, non ai provider

L'osservabilità neutrale del provider dovrebbe rispondere direttamente alle domande operative. Dashboard utili includono la latenza p95 e p99 per modello, fornitore, team, ambiente e classe di carico di lavoro; utilizzo dei token per squadra e percorso; tasso di guasto per classe di errore normalizzata; riprovare l'amplificazione in base alla policy del percorso; frequenza di fallback per modello richiesto; errori della finestra di contesto in base al modello di prompt; errori di convalida dell'output strutturato per schema; ed esempi di tracce campionate per richieste non riuscite, costose o lente.

Mantieni la fatturazione e i report sull'utilizzo totale lontani dalle tracce campionate. Il campionamento finale è utile per il debug, ma può distorcere i totali. I totali dei token, i conteggi delle richieste e i registri dei costi devono provenire da contatori, registri delle richieste o sistemi di riconciliazione della fatturazione non campionati. Le tracce dovrebbero spiegare perché si è verificata una richiesta costosa o lenta; non dovrebbero essere l'unica fonte di verità finanziaria.

Utilizza il campionamento della coda per tracce di valore elevato

Il processore di campionamento della coda di OpenTelemetry Collector può prendere decisioni di campionamento una volta completati gli intervalli, incluse policy basate su attributi e valori numerici. Ciò è utile per il traffico LLM perché spesso sai se una traccia è utile solo al termine della risposta.

Conserva le tracce per errori del provider, errori di convalida, latenza molto elevata, utilizzo di token insolitamente costoso, errori della finestra di contesto, tentativi di fallback e richieste con tag di debug manuale. Campiona il traffico di routine di successo a una tariffa inferiore. In questo modo, le tracce che più probabilmente spiegano gli incidenti controllano il volume di archiviazione.

Un modello di policy ragionevole è semplice: mantieni sempre gli errori, mantieni sempre le richieste al di sopra di una soglia di latenza o token, mantieni sempre tracce con tag di debug e campiona probabilisticamente le normali richieste riuscite. Rivisitare le soglie man mano che il traffico cambia. Una soglia utile durante l'adozione iniziale potrebbe essere troppo bassa una volta cresciuto il traffico di produzione.

Aggiungi test contrattuali per la telemetria

La telemetria dovrebbe essere testata come un contratto API perché da essa dipendono dashboard, avvisi, controlli dei costi e flussi di lavoro degli incidenti downstream. Aggiungi test che eseguono richieste gateway rappresentative e asseriscono che vengono emessi gli intervalli e gli attributi richiesti.

I test devono verificare che una richiesta riuscita emetta l'intervallo di operazioni LLM logiche, un intervallo di tentativi del provider, il modello richiesto, il modello di risposta, il nome del provider, i conteggi dei token quando disponibili, i metadati dell'ambito del team o della chiave, la versione della policy di instradamento e lo stato finale. I test di ripetizione dovrebbero accertare il numero dei tentativi e le ragioni dei tentativi. I test di fallback dovrebbero accertare sia il tentativo fallito che il tentativo finale riuscito del provider. I test di convalida dovrebbero accertare l'ID dello schema, lo stato di convalida e il conteggio dei tentativi di riparazione.

I test di sicurezza sono altrettanto importanti. Dichiarare che le chiavi non elaborate del fornitore, le intestazioni di autorizzazione, i cookie, le richieste non elaborate, i completamenti non elaborati e gli identificatori dei clienti non approvati sono assenti dalla telemetria esportata.Questi test non dovrebbero riuscire a chiudersi quando uno sviluppatore aggiunge un nuovo attributo span senza classificarlo.

Elenco di controllo dell'implementazione

• Contratto di attributo: definire attributi obbligatori, facoltativi, limitati e proibiti.
• Gerarchia degli span: Richieste in entrata separate, operazioni LLM logiche, tentativi del provider, tentativi, fallback, recupero chiamate agli strumenti e convalida.
• Mappatura semantica: utilizza gli attributi OpenTelemetry GenAI dove si adattano e gli attributi del gateway privato per la proprietà e il contesto di routing.
• Norme sulla privacy: Per impostazione predefinita hash, ID modello, ID schema, nomi strumento, conteggi token, latenza e classi di errore anziché raw contenuto.
• Processori di raccolta: eliminano i campi vietati, oscurano i pattern bloccati, elencano gli attributi a basso rischio nella lista consentita e instradano le tracce sensibili separatamente.
• Criteri di campionamento: campionano in coda le tracce con valori elevati e mantengono le metriche aggregate non campionato.
• Dashboard: crea visualizzazioni in base a latenza, utilizzo, errori, tentativi, fallback, convalida e fattori di costo.
• Avvisi: avvisi su classi di errore normalizzate, spostamenti di latenza p99, amplificazione dei tentativi, picchi di fallback, errori di convalida e token anomalie.
• Test del contratto: Dichiara che la telemetria richiesta è presente e la telemetria sensibile è assente.

Compromessi per decidere in modo esplicito

La strumentazione a livello di gateway fornisce rapidamente metadati coerenti, ma può perdere il contesto specifico dell'applicazione a meno che i team non trasmettano metadati di richiesta strutturati come tenant, flusso di lavoro, modello di prompt e funzionalità nome. Rendi tali metadati parte del contratto di richiesta del gateway invece di fare affidamento su log in formato libero.

L'acquisizione completa dei contenuti migliora il debug e la valutazione, ma aumenta il carico di privacy, sicurezza, conservazione e controllo degli accessi. Molti team dovrebbero iniziare solo con hash, ID modello, ID schema ed estratti oscurati.

Le classi di errore indipendenti dal provider rendono le dashboard utilizzabili su più API di modelli, ma comprimono i dettagli specifici del provider. Conserva i codici di errore del provider non elaborati solo quando sono sicuri e limita l'accesso ad essi.

Le convenzioni di OpenTelemetry GenAI riducono il lock-in, ma continueranno a evolversi. Un mappatore interno offre i vantaggi della standardizzazione senza lasciare che nomi di attributi instabili trapelano attraverso la base di codice.

Conclusione

L'osservabilità LLM indipendente dal provider non è solo il tracciamento aggiunto alle chiamate del modello. Si tratta di un contratto operativo a livello del gateway: intervalli coerenti, modello normalizzato e metadati del provider, contesto di proprietà, utilizzo dei token, visibilità dei nuovi tentativi e del fallback, controlli sulla privacy, regole di campionamento e test che impediscono la fuga di dati sensibili.

Inizia con il gateway perché vede già le decisioni più importanti: chi ha effettuato la richiesta, quale policy l'ha instradata, quale provider l'ha servita, quanto è costato in token, quanto tempo ha impiegato, se la logica di ripristino è stata eseguita e cosa non è riuscita. Una volta che le basi sono stabili, i team applicativi possono aggiungere un contesto del flusso di lavoro più ricco senza che ciascun team inventi il ​​proprio sistema di osservabilità LLM.

Leggi correlati

• telemetria del routing di fallback