Observabilitat de LLM en una passarel·la d'API multimodel: traces, registres de testimonis, anàlisi de llogaters i registre segur d'avís

Els recomptes de sol·licituds agregats i la despesa mensual no són suficients quan un client pregunta per què un flux de treball es va fer més lent, més car o menys fiable ahir. Una passarel·la d'API multimodel pot respondre aquesta pregunta si tracta l'observabilitat com a part del pla de control: cada sol·licitud rep un rastre, cada trucada de model actualitza un registre d'ús, cada inquilí i flux de treball és atribuïble i el contingut sensible està protegit de manera predeterminada.

Aquest article descriu un disseny pràctic per a l'analítica d'ús d'IA i l'observabilitat de LLM en una passarel·la que s'enfronta a diversos proveïdors mitjançant una API compatible amb OpenAI. El patró és útil fins i tot si no utilitzeu cap proveïdor específic: instrumenteu-vos una vegada a la passarel·la, normalitzeu la telemetria del model, preserveu l'atribució de facturació i captureu contingut de sol·licitud només sota una política explícita.

El problema del lector: "Quin inquilí, model, indicació o camí de recuperació va provocar el canvi?"

La majoria dels equips s'enfronten al mateix buit de depuració. Els registres de l'aplicació mostren que una funció ha fallat. Els taulers de control dels proveïdors mostren que l'ús de testimonis ha augmentat. Finances veu una factura. Cap d'aquestes visualitzacions, per si sola, explica el camí complet des de la sol·licitud de l'inquilí fins a la trucada del model fins al context de recuperació per tornar a intentar el cost facturat.

L'objectiu no és un altre tauler amb fitxes totals. L'objectiu és respondre preguntes operatives com ara:

• Quin inquilí o clau d'API ha provocat un augment de la despesa?
• La latència va augmentar després de canviar un àlies de model?
• Els reintents o les alternatives tenen un doble recompte?
• Quina versió de la sol·licitud grava més pressupost d'error?
• Un flux de treball RAG s'ha tornat car perquè la recuperació ha afegit massa fitxes de context?
• És compatible amb la depuració d'un incident sense llegir les sol·licituds de l'usuari privat?

Fets, recomanacions i prediccions

Fets: OpenTelemetry documenta les convencions i els atributs semàntics d'IA generativa per a les operacions del model, inclosos els noms d'operacions com ara xat, generate_content i text_completion. La mateixa documentació adverteix que els atributs de missatges d'entrada i sortida de GenAI poden contenir informació confidencial o PII i poden requerir filtratge o truncat. Els principals proveïdors de models també exposen taulers d'ús, API o exportacions que poden donar suport a la conciliació del proveïdor, tot i que els detalls difereixen segons el proveïdor.

Recomanacions: utilitzeu OpenTelemetry per a traces neutrals per al proveïdor, però manteniu les dimensions empresarials de la passarel·la als vostres atributs i llibres majors. No emmagatzemeu les indicacions o sortides en brut per defecte. Emmagatzemeu primer les metadades, els hash, els recomptes de testimonis, els identificadors de plantilles de sol·licitud, els noms dels esquemes, les classes d'error i les etiquetes de seguretat. Afegiu la captura de contingut només com a funció d'activació, control d'accés i depuració de retenció curta.

Predicció: l'observabilitat de LLM serà menys sobre taulers de control de proveïdors aïllats i més sobre plans de control entre proveïdors. Els equips esperaran un lloc per investigar la latència, el cost, la qualitat, els esdeveniments de la política, el comportament dels inquilins i els deltas de facturació en tots els models.

Arquitectura de referència: observeu tot el camí de la sol·licitud

Una passarel·la pot veure el cicle de vida complet de la sol·licitud sense requerir que tots els equips d'aplicacions creïn telemetria personalitzada. Un model de traça útil comença amb un interval principal per a la sol·licitud del client entrant i un interval secundari per als passos que afecten el cost, la latència i la qualitat.

Estructura d'abast recomanada

• Interval de sol·licitud de passarel·la: sol·licitud acceptada, autenticada, autoritzada, amb tarifes limitats i encaminada.
• Model d'interval de trucades: proveïdor, model, operació, ús del testimoni, estat de resposta i latència.
• Interval de recuperació: índex consultat, identificadors de documents o identificadors hash, recompte de fragments, latència de recuperació i compartició de testimonis de context.
• Interval de trucades a l'eina: nom de l'eina, estat, latència, classe d'error i classificació d'efectes secundaris.
• Interval de reintent: motiu del reintent, número d'intent, estat del proveïdor i cost incremental.
• Interval de reserva: model original, model de reserva, activador, política de compatibilitat i resultat final.
• Barra de protecció o de moderació: política invocada, decisió, etiquetes i si la sortida s'ha bloquejat o transformat.
• Interval de postprocessament: validació JSON, reparació d'esquemes, comprovacions de cites o format final.

L'abast principal hauria de portar identificadors de correlació estables. Els trams secundaris han de tenir atributs tècnics normalitzats. El llibre de registre d'ús ha de contenir registres de facturació i anàlisi duradors. Eviteu forçar tota la informació a les etiquetes de mètriques; els valors de cardinalitat alta, com ara els identificadors d'inquilí, els hash d'indicadors i els identificadors de documents, s'emmagatzemen millor en traces, registres o taules de registre i després s'agreguen en taulers de control.

Normalitzeu les metadades capturades a cada trucada de LLM

Cada sol·licitud de model hauria de produir un registre coherent, independentment del proveïdor. L'esquema exacte variarà, però un mínim pràctic és el següent:

{
  "request_id": "req_01J...",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tenant_id": "arrendatari_123",
  "team_id": "team_456",
  "app_id": "support_bot",
  "gateway_key_id": "key_789",
  "operation": "xerrar",
  "proveïdor": "nom_proveïdor",
  "model": "id-model-proveïdor",
  "model_alias": "xat de suport ràpid",
  "prompt_template_id": "refund_policy_v5",
  "prompt_hash": "sha256:...",
  "response_schema": "support_answer_v2",
  "status": "completat",
  "error_class": nul,
  "latency_ms": 1842,
  "input_tokens": 2110,
  "output_tokens": 384,
  "cached_input_tokens": 1200,
  "estimated_cost_usd": "0,00492",
  "final_billed_cost_usd": nul,
  "finish_reason": "atura",
  "retry_count": 0,
  "fallback_used": fals,
  "content_capture_policy": "només metadades"
}

Mantingueu dues idees separades: la telemetria explica què va passar, mentre que el llibre d'ús registra què s'ha de cobrar, conciliar i informar. Es refereixen entre si amb identificadors de sol·licitud i identificadors de traça, però no han de viure al mateix sistema d'emmagatzematge.

Creeu un registre de fitxes i costos, no només comptadors

Els comptadors de testimonis són útils per als gràfics, però no són suficients per a la facturació o la investigació d'incidències. Un llibre major hauria de representar les transicions d'estat. Creeu una fila quan la passarel·la accepti una sol·licitud i, a continuació, actualitzeu-la a mesura que avança la sol·licitud.

Estats del llibre major útils

• acceptat: s'han superat les comprovacions d'autenticació i de polítiques.
• reenviat: la sol·licitud s'ha enviat a un proveïdor.
• Transmissió en temps real: el proveïdor va començar a retornar fitxes.
• completada: la resposta s'ha acabat correctament.
• user_aborted: el client s'ha desconnectat abans de finalitzar.
• S'ha tornat a intentar: s'ha fet un intent addicional del proveïdor.
• fallback_used: s'ha seleccionat un model o proveïdor diferent després d'un error o una coincidència amb la política.
• Error: la sol·licitud ha finalitzat sense una resposta utilitzable.
• conciliat: s'han comparat i aplicat les dades d'ús o de cost del proveïdor.

Aquest model d'estat ajuda a detectar errors de facturació i d'anàlisi habituals: respostes en temps real on el client es va desconnectar, intents de reintentar que el proveïdor va cobrar però ocults per a l'usuari, camins alternatius que comptaven el model incorrecte i diferències de comptabilitat de memòria cau entre els proveïdors.

Utilitzeu les convencions d'OpenTelemetry GenAI i, a continuació, amplia amb cura

Les convencions semàntiques d'OpenTelemetry GenAI proporcionen un vocabulari portàtil per a operacions de models. Utilitzeu aquestes convencions per als atributs habituals, com ara el nom de l'operació, el proveïdor, el model, els paràmetres de sol·licitud, els motius de finalització de la resposta, l'ús del testimoni i l'estat d'error quan s'apliquen.

No obstant això, les convencions neutrals per al proveïdor no cobreixen totes les dimensions empresarials d'una passarel·la. Afegiu atributs propietat de la passarel·la o columnes del llibre major per a:

• Identificador de llogater, identificador d'equip, identificador de client de distribuïdor i identificador d'aplicació;
• ID de clau de l'API de passarel·la i abast de la clau;
• pla de facturació, límit de despesa i política pressupostària;
• àlies del model i versió de la política d'encaminament;
• ID de plantilla de sol·licitud i versió de sol·licitud;
• nom del flux de treball i pas del flux de treball;
• cost estimat, cost facturat final i estat de conciliació.

El compromís és la cardinalitat. Aquests camps són valuosos per a la investigació, però poden fer que les mètriques siguin cares i sorolloses si s'utilitzen com a etiquetes de mètriques a tot arreu. Una regla pràctica és: els agregats de baixa cardinalitat van a mètriques; els identificadors d'alta cardinalitat van a traces, registres i llibres majors.

Dissenyeu un registre segur de missatges i sortida

El registre d'avís complet facilita la depuració, però augmenta la privadesa, el compliment, l'emmagatzematge i l'exposició al risc intern. El valor predeterminat més segur és l'observabilitat de metadades primer.

Per defecte: només metadades

Per a la majoria del trànsit de producció, emmagatzema:

• identificador i versió de la plantilla sol·licitada;
• hash de sol·licituds i sortides normalitzades;
• Recomptes d'entrada, sortida, memòria cau i testimoni de context;
• nom de l'esquema de resposta i resultat de la validació;
• etiquetes de seguretat i decisions polítiques;
• resums d'errors i classes d'error del proveïdor;
• metadades de recuperació, no documents en brut.

Opt-in: captura de contingut controlada

Si necessiteu contingut en brut o redactat per a una depuració profunda, necessiteu una política explícita. Els bons controls inclouen llistes permeses d'entorn, consentiment de l'arrendatari, mostreig, durada màxima de càrrega útil, redacció automàtica, finestres de retenció curtes, encriptació, accés basat en rols, registres d'auditoria i una ruta d'aprovació de trencament de vidre per a incidents sensibles.

No tracteu la redacció com a perfecta. Redueix el risc; no l'elimina. Per a càrregues de treball regulades o d'alta sensibilitat, penseu a emmagatzemar només els hash i a reproduir problemes en un arnès sintètic amb dades de prova aprovades.

Afegiu observabilitat RAG com a capa separada

La generació augmentada amb la recuperació pot canviar tant la qualitat com el cost. El registre només de la trucada final del model amaga la causa principal quan el recuperador retorna massa fragments, documents obsolets o context irrellevant.

Per a cada pas de recuperació, captureu:

• nom de l'índex o de la col·lecció;
• estratègia de recuperació i model d'inserció;
• IDs de document o identificadors hash;
• recompte de fragments i fitxes de context total;
• latència de recuperació;
• distribució de la puntuació màxima, si està disponible;
• cobertura de citacions;
• si s'ha utilitzat el context recuperat a la resposta final.

Això us permet distingir "el model va empitjorar" de "el retriever va començar a enviar un context de baixa qualitat o excessiu". També ajuda a identificar els fluxos de treball on els testimonis de context dominen el cost total.

Concilia l'ús de la passarel·la amb la facturació del proveïdor

Les estimacions de la passarel·la estan disponibles immediatament. Les dades de facturació del proveïdor solen ser més lentes, però amb més autoritat. Utilitzeu tots dos.

Una tasca de conciliació diària hauria de comparar les files del registre de la passarel·la amb les API d'ús del proveïdor, les API de costos, les exportacions de taulers de control o les exportacions de factures. Agrupeu deltes per proveïdor, model, projecte i finestra de temps. Feu un seguiment de les diferències per separat per als testimonis d'entrada, els testimonis de sortida, els testimonis en memòria cau, els recomptes de sol·licituds i el cost.

Diferències de conciliació habituals

• La transmissió es desconnecta: la passarel·la pot veure un client avortat mentre el proveïdor encara factura els testimonis generats.
• Reintents: es poden facturar diversos intents encara que només es torni una resposta final.
• Messa en memòria cau ràpida: els proveïdors poden exposar la comptabilitat dels testimonis a la memòria cau de manera diferent.
• Arrodoniment: es poden veure petites diferències per sol·licitud a escala.
• Descomptes per lots o nivells: les factures dels proveïdors poden aplicar preus que l'estimació en temps real encara no coneixia.
• Canvis del proveïdor: els preus del model, el comportament de tokenització o les exportacions de facturació poden canviar amb el temps.

Quan la reconciliació trobi un delta, eviteu sobreescriure en silenci el vostre llibre major. Emmagatzemeu l'estimació original, el valor conciliat amb el proveïdor, la font de conciliació i el codi de motiu, si es coneix.

Taulers que responen a preguntes operatives

Comenceu els taulers a partir de problemes de lectors, no de mètriques vanitàries. Les vistes útils inclouen:

• cost per inquilí, equip, aplicació i flux de treball;
• cost per tasca reeixida, no només cost per sol·licitud;
• Latència p50, p95 i p99 per proveïdor, model i àlies de model;
• percentatge de retorn i percentatge de reintents per ruta;
• Temps d'espera i tendències de classe d'error del proveïdor;
• ràtio d'accés a la memòria cau i estimació d'estalvi de testimonis en memòria cau;
• taxa d'errors de validació de sortida estructurada;
• Versions d'indicacions principals per error de gravació del pressupost;
• Compartició de testimonis de context RAG per flux de treball;
• Blocs de baranes i cops de classificador d'injecció ràpida.

Per avisar, combineu senyals tècnics i comercials. Un augment sobtat de la despesa dels inquilins pot ser més urgent que un petit augment de la latència global. Un salt de la taxa de retorn després d'un canvi d'àlies de model pot indicar un problema de compatibilitat. Les respostes 401, 429 o 5xx repetides poden indicar problemes clau, esgotament de les quotes o inestabilitat del proveïdor.

Flux d'implementació mínim per a un servidor intermediari compatible amb OpenAI

Per a un proxy /chat/completions, el flux pot ser senzill:

1. Rebeu la sol·licitud i assigneu request_id i traceu el context.
2. Autentiqueu la clau de la passarel·la i resoleu l'abast de l'inquilí, l'equip, l'aplicació i la política.
3. Creeu l'abast de la passarel·la principal.
4. Creeu una fila del llibre major amb l'estat acceptat.
5. Resol l'àlies del model al model del proveïdor i la versió de la política d'encaminament.
6. Enregistrar metadades: operació, identificador de plantilla de sol·licitud, nom de l'esquema, hash de sol·licitud i política de captura de contingut.
7. Inicieu l'abast de la trucada del model utilitzant els atributs semàntics GenAI quan escaigui.
8. Reenvia la sol·licitud al proveïdor seleccionat.
9. Per a la reproducció en temps real, actualitzeu l'estat quan arribi el primer tros i compta l'ús amb la precisió que ho permeti la resposta del proveïdor.
10. En finalitzar, analitzeu l'ús del proveïdor, el motiu de finalització, l'estat i la classe d'error.
11. Actualitzeu el llibre major amb fitxes, cost estimat, detalls de reintentar/retorn i estat de la sol·licitud final.
12. Emet mètriques de les dades del llibre major i de l'abast.
13. Executa la conciliació diària i emmagatzema el cost confirmat pel proveïdor per separat de l'estimació original.

Llista de comprovació del llançament

• Definiu identificadors de sol·licituds canònics i identificadors de traça.
• Adopta els atributs OpenTelemetry GenAI per a la telemetria del model comú.
• Creeu un registre d'ús de passarel·la amb transicions d'estat de sol·licitud.
• Normalitzeu les dimensions de proveïdor, model, àlies de model, inquilí, aplicació i flux de treball.
• Mantingueu les dades d'investigació d'alta cardinalitat fora de les etiquetes de mètriques.
• Desactiva la captura d'indicacions en brut i de sortida de manera predeterminada.
• Afegiu polítiques explícites de mostreig, redacció, retenció i control d'accés.
• Captura metadades de recuperació per a fluxos de treball RAG.
• Creeu taulers de control de costos, latència, fiabilitat, validació i comportament dels inquilins.
• Concilia les estimacions de la passarel·la amb l'ús del proveïdor i les exportacions de costos.
• Alerta sobre pics de despesa, regressió de latència, salts alternatius, errors de validació i esdeveniments rellevants per a la seguretat.

Conclusió

Una passarel·la multimodel és el lloc adequat per implementar l'observabilitat de LLM perquè veu les sol·licituds abans que arribin a qualsevol proveïdor i pot adjuntar un context empresarial que els proveïdors no coneixen. El disseny més fort no és "registrar-ho tot". Es tracta d'un model en capes: traces d'execució neutres per al proveïdor, un testimoni durador i un registre de costos per a la facturació, anàlisis dels inquilins per a la governança, metadades RAG per a la qualitat de la recuperació i registre d'indicadors de privadesa per a una depuració segura.

Comenceu amb metadades, transicions d'estat i reconciliació. Afegiu la captura de contingut només quan la política, la retenció i els controls d'accés estiguin a punt. Aquesta seqüència ofereix als desenvolupadors l'evidència que necessiten per depurar la latència, la qualitat i la despesa sense convertir l'observabilitat en un nou risc d'exposició de dades.

Lectura relacionada

• memorització ràpida i patrons de control de costos per lots
• Gestió de claus de l'API d'equip i límits de despesa