LLM-observabilitet i en multi-model API-gateway: spor, token-ledgers, lejeranalyse og sikker promptlogning

Samlet antal anmodninger og månedligt forbrug er ikke nok, når en kunde spørger, hvorfor en arbejdsgang blev langsommere, dyrere eller mindre pålidelig i går. En multi-model API-gateway kan besvare det spørgsmål, hvis den behandler observerbarhed som en del af kontrolplanet: hver anmodning får et spor, hvert modelkald opdaterer en forbrugsbog, hver lejer og arbejdsgang kan tilskrives, og følsomt indhold er beskyttet som standard.

Denne artikel beskriver et praktisk design for AI-brugsanalyse og LLM-observabilitet i en gateway, der fronter flere udbydere gennem en OpenAI-kompatibel API. Mønsteret er nyttigt, selvom du ikke bruger nogen specifik leverandør: instrument én gang ved gatewayen, normaliser modeltelemetri, bevar faktureringstilskrivning og indfang kun promptindhold under eksplicit politik.

Læserproblemet: "Hvilken lejer, model, prompt eller genfindingssti forårsagede ændringen?"

De fleste teams står til sidst over for det samme fejlfindingsgab. Applikationslogfiler viser, at en funktion mislykkedes. Udbyderens dashboards viser, at tokenbrug steg. Finans ser en regning. Ingen af disse visninger i sig selv forklarer den fulde vej fra lejeranmodning til modelopkald til genfindingskontekst til genforsøg til faktureret pris.

Målet er ikke endnu et betjeningspanel med samlede tokens. Målet er at besvare operationelle spørgsmål som:

• Hvilken lejer eller API-nøgle forårsagede en forbrugsstigning?
• Blev forsinkelsen steget, efter at et modelalias blev ændret?
• Er genforsøg eller reserver dobbelttællende omkostninger?
• Hvilken promptversion brænder det største fejlbudget?
• Blev et RAG-workflow dyrt, fordi hentning tilføjede for mange konteksttokens?
• Kan understøtte fejlretning af en hændelse uden at læse private brugermeddelelser?

Fakta, anbefalinger og forudsigelser

Fakta: OpenTelemetry dokumenterer Generative AI semantiske konventioner og attributter for modeloperationer, herunder operationsnavne såsom chat, generate_content og text_completion. Den samme dokumentation advarer om, at GenAI input- og outputmeddelelsesattributter kan indeholde følsomme oplysninger eller PII og kan kræve filtrering eller trunkering. Større modeludbydere afslører også brugsdashboards, API'er eller eksporter, der kan understøtte afstemning på udbydersiden, selvom detaljerne varierer fra udbyder til udbyder.

Anbefalinger: Brug OpenTelemetry til udbyderneutrale spor, men behold gateway-ejede virksomhedsdimensioner i dine egne attributter og hovedbøger. Gem ikke rå prompter eller output som standard. Gem først metadata, hashes, token-antal, promptskabelon-id'er, skemanavne, fejlklasser og sikkerhedsetiketter. Tilføj kun indholdsindsamling som en tilvalgs-, adgangskontrolleret, kortvarig fejlretningsfunktion.

Forudsigelse: LLM-observabilitet bliver mindre om isolerede udbyder-dashboards og mere om kontrolplaner på tværs af udbydere. Teams forventer ét sted til at undersøge latenstid, omkostninger, kvalitet, politiske begivenheder, lejeradfærd og faktureringsdeltaer på tværs af modeller.

Referencearkitektur: observer hele anmodningsstien

En gateway kan se hele anmodningens livscyklus uden at kræve, at hvert applikationsteam skal bygge tilpasset telemetri. En nyttig sporingsmodel starter med ét overordnet spænd for den indgående kundeanmodning og underordnede spænd for de trin, der påvirker omkostninger, latenstid og kvalitet.

Anbefalet spanstruktur

• Gateway request span: anmodning accepteret, autentificeret, autoriseret, rate-limited og routed.
• Modelopkaldsspændvidde: udbyder, model, drift, tokenbrug, svarstatus og forsinkelse.
• Hentningsspændvidde: indeksforespørgsel, dokument-id'er eller hashed-id'er, chunk count, hentingsforsinkelse og konteksttokenandel.
• Tool call span: værktøjsnavn, status, latens, fejlklasse og bivirkningsklassificering.
• Retry span: genforsøgsårsag, forsøgsnummer, udbyderstatus og inkrementelle omkostninger.
• Fallback span: original model, fallback model, trigger, kompatibilitetspolitik og endeligt resultat.
• Guardrail eller moderation span: politik påberåbt, beslutning, etiketter, og om output blev blokeret eller transformeret.
• Efterbehandlingsspændvidde: JSON validering, skemareparation, citationstjek eller endelig formatering.

Det overordnede spænd skal have stabile korrelations-id'er. Barnespændene skal have normaliserede tekniske egenskaber. Forbrugsregnskabet skal indeholde holdbare fakturerings- og analyseregistreringer. Undgå at tvinge al information ind i metric-etiketter; værdier med høj kardinalitet såsom lejer-id'er, prompt-hasher og dokument-id'er gemmes bedre i spor, logfiler eller hovedbogstabeller og aggregeres derefter i dashboards.

Normaliser de metadata, der registreres ved hvert LLM-opkald

Enhver modelanmodning bør producere en konsistent registrering, uanset udbyder. Det nøjagtige skema vil variere, men et praktisk minimum ser således ud:

{
  "request_id": "req_01J...",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "tenant_id": "tenant_123",
  "team_id": "team_456",
  "app_id": "support_bot",
  "gateway_key_id": "key_789",
  "operation": "chat",
  "provider": "provider_name",
  "model": "provider-model-id",
  "model_alias": "fast-support-chat",
  "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"
}

Hold to ideer adskilt: telemetri forklarer, hvad der skete, mens brugsreskontro registrerer, hvad der skal debiteres, afstemmes og rapporteres. De refererer til hinanden med anmodnings-id'er og sporings-id'er, men de behøver ikke at bo i det samme lagersystem.

Byg en token og en omkostningsbog, ikke kun tællere

Tokentællere er nyttige til diagrammer, men de er ikke nok til fakturering eller undersøgelse af hændelser. En hovedbog skal repræsentere tilstandsovergange. Opret en række, når gatewayen accepterer en anmodning, og opdater den derefter, efterhånden som anmodningen skrider frem.

Nyttige finanstilstande

• accepteret: godkendelses- og politiktjek bestået.
• videresendt: anmodningen blev sendt til en udbyder.
• streaming: udbyderen begyndte at returnere tokens.
• fuldført: svaret blev afsluttet.
• user_aborted: klienten afbrød forbindelsen før fuldførelse.
• genforsøgt: der blev gjort et ekstra udbyderforsøg.
• fallback_used: en anden model eller udbyder blev valgt efter fejl eller politikmatch.
• failed: anmodningen sluttede uden et brugbart svar.
• afstemt: forbrugs- eller omkostningsdata fra udbydersiden blev sammenlignet og anvendt.

Denne tilstandsmodel hjælper med at fange almindelige fakturerings- og analysefejl: streamede svar, hvor klienten afbrød forbindelsen, forsøg igen, der blev debiteret af udbyderen, men skjult for brugeren, reservestier, der talte den forkerte model, og cache-regnskabsforskelle på tværs af udbydere.

Brug OpenTelemetry GenAI-konventioner, og udvid derefter forsigtigt

OpenTelemetry GenAI semantiske konventioner giver et bærbart ordforråd til modeloperationer. Brug disse konventioner til almindelige attributter såsom operationsnavn, udbyder, model, anmodningsparametre, årsager til svarafslutning, tokenbrug og fejlstatus, hvor de gælder.

Men udbyderneutrale konventioner dækker ikke alle forretningsdimensioner i en gateway. Tilføj gateway-ejede attributter eller hovedbogskolonner for:

• lejer-id, team-id, forhandlerkunde-id og app-id;
• gateway API nøgle-id og nøgleomfang;
• faktureringsplan, forbrugsgrænse og budgetpolitik;
• version af modelalias og routingpolitik;
• promptskabelon-id og promptversion;
• workflownavn og workflowtrin;
• estimerede omkostninger, endelige fakturerede omkostninger og afstemningsstatus.

Afvejningen er kardinalitet. Disse felter er værdifulde til undersøgelse, men de kan gøre målinger dyre og støjende, hvis de bruges som metriske etiketter overalt. En praktisk regel er: aggregater med lav kardinalitet går til metrics; identifikatorer med høj kardinalitet går til spor, logfiler og hovedbøger.

Design sikker prompt og outputlogning

Fuld prompt logning gør fejlfinding nemmere, men det øger privatlivets fred, overholdelse, opbevaring og eksponering for insiderrisiko. Den mere sikre standard er metadata-first observability.

Standard: kun metadata

For det meste produktionstrafik, butik:

• prompt skabelon-id og version;
• hashes af normaliserede prompter og output;
• antal input, output, cachelagret og konteksttoken;
• navn på svarskema og valideringsresultat;
• sikkerhedsetiketter og politiske beslutninger;
• fejloversigter og udbyderfejlklasser;
• hentningsmetadata, ikke rådokumenter.

Tilvalg: kontrolleret indholdsfangst

Hvis du har brug for råt eller redigeret indhold til dyb debugging, skal du kræve en eksplicit politik. Gode kontroller omfatter miljøtilladelseslister, lejersamtykke, prøveudtagning, maksimal nyttelastlængde, automatisk redaktion, korte opbevaringsvinduer, kryptering, rollebaseret adgang, revisionslogfiler og en godkendelsessti for følsomme hændelser.

Behandl ikke redaktion som perfekt. Det reducerer risikoen; det eliminerer det ikke. For regulerede eller højfølsomme arbejdsbelastninger bør du overveje kun at gemme hashes og genafspilningsproblemer i en syntetisk sele med godkendte testdata.

Tilføj RAG-observerbarhed som et separat lag

Generering med udvidet genfinding kan ændre både kvalitet og pris. Logning af kun det endelige modelkald skjuler hovedårsagen, når retrieveren returnerer for mange bidder, forældede dokumenter eller irrelevant kontekst.

For hvert genfindingstrin skal du fange:

• indeks eller samlingsnavn;
• hentningsstrategi og indlejringsmodel;
• dokument-id'er eller hashed-id'er;
• chunk count og total context tokens;
• hentningsforsinkelse;
• topscorefordeling, hvis tilgængelig;
• citatdækning;
• om den hentede kontekst blev brugt i det endelige svar.

Dette giver dig mulighed for at skelne "modellen blev værre" fra "retrieveren begyndte at sende lav kvalitet eller overdreven kontekst." Det hjælper også med at identificere arbejdsgange, hvor konteksttokens dominerer de samlede omkostninger.

Afstem gatewaybrug med udbyderfakturering

Gateway-estimater er tilgængelige med det samme. Faktureringsdata på udbydersiden er normalt langsommere, men mere autoritative. Brug begge dele.

Et dagligt afstemningsjob bør sammenligne gateway-ledger-rækker med udbyderbrugs-API'er, omkostnings-API'er, dashboard-eksporter eller fakturaeksport. Gruppér deltaer efter udbyder, model, projekt og tidsvindue. Spor forskelle separat for inputtokens, outputtokens, cachelagrede tokens, anmodningstællinger og omkostninger.

Almindelige afstemningsforskelle

• Streaming afbrydes: gatewayen kan muligvis se en afbrudt klient, mens udbyderen stadig fakturerer genererede tokens.
• Forsøg igen: flere forsøg kan blive faktureret, selvom kun ét endeligt svar returneres.
• Prompt caching: udbydere kan eksponere cache-token-konti på en anden måde.
• Afrunding: små forskelle pr. anmodning kan blive synlige i skala.
• Batch- eller niveaurabatter: udbyderfakturaer kan anvende priser, som realtidsestimatet endnu ikke kendte.
• Ændringer på udbydersiden: modelprissætning, tokeniseringsadfærd eller faktureringseksport kan ændre sig over tid.

Når afstemning finder et delta, skal du undgå lydløst at overskrive din finansbog. Gem det oprindelige estimat, den udbyder-afstemte værdi, afstemningskilden og årsagskoden, hvis den er kendt.

Dashboards, der besvarer operationelle spørgsmål

Start dashboards fra læserproblemer, ikke forfængeligheds-metrics. Nyttige visninger omfatter:

• pris pr. lejer, team, app og workflow;
• pris pr. succesfuld opgave, ikke kun pris pr. anmodning;
• p50, p95 og p99 latens efter udbyder, model og modelalias;
• tilbagegangsfrekvens og genforsøgsfrekvens efter rute;
• timeoutrate og udbyderfejlklassetendenser;
• cache-hitforhold og cache-token-besparelsesestimat;
• fejlrate ved validering af struktureret output;
• toppromptversioner efter fejlbudgetforbrænding;
• RAG-konteksttokendeling efter arbejdsgang;
• rækværksblokke og prompt-indsprøjtning klassificerende hits.

For at advare skal du kombinere tekniske og forretningsmæssige signaler. En pludselig stigning i lejerforbruget kan være mere presserende end en lille global latensstigning. Et fallback-ratespring efter en modelaliasændring kan indikere et kompatibilitetsproblem. Gentagne 401-, 429- eller 5xx-svar kan pege på vigtige problemer, kvoteopbrug eller udbyderens ustabilitet.

Minimalt implementeringsflow for en OpenAI-kompatibel proxy

For en /chat/completions proxy kan flowet være enkelt:

1. Modtag anmodningen og tildel request_id og spor kontekst.
2. Godkend gatewaynøglen og afgør lejer, team, app og politikomfang.
3. Opret det overordnede gateway-spænd.
4. Opret en finansrække med tilstand accepted.
5. Løs modelalias til udbydermodel og routingpolitikversion.
6. Optag metadata: handling, promptskabelon-id, skemanavn, prompt-hash og politik for indholdsfangst.
7. Start modelopkaldsspændvidden ved at bruge GenAI semantiske attributter, hvor det er relevant.
8. Videresend anmodningen til den valgte udbyder.
9. For streaming skal du opdatere tilstanden, når den første del ankommer, og tælle brugen så nøjagtigt, som udbyderens svar tillader det.
10. Parse udbyderbrug, slutårsag, status og fejlklasse ved afslutning.
11. Opdater hovedbogen med tokens, estimerede omkostninger, gentagelses-/faldbackdetaljer og endelig anmodningstilstand.
12. Emit metrics fra finans- og spandata.
13. Kør daglig afstemning og butiksudbyderbekræftede omkostninger separat fra det oprindelige estimat.

Tjekliste for udrulning

• Definer kanoniske anmodnings-id'er og sporings-id'er.
• Adopter OpenTelemetry GenAI-attributter til almindelig telemetrimodel.
• Opret en gateway-brugsreskontro med overgange til anmodningstilstand.
• Normaliser udbyder-, model-, modelalias-, lejer-, app- og workflow-dimensioner.
• Hold undersøgelsesdata med høj kardinalitet ude af metriske etiketter.
• Gør rå prompt og output capture deaktiveret som standard.
• Tilføj eksplicitte politikker for prøveudtagning, redigering, opbevaring og adgangskontrol.
• Fangst metadata for hentning af RAG-arbejdsgange.
• Byg betjeningspaneler for omkostninger, ventetid, pålidelighed, validering og lejeradfærd.
• Afstem gateway-estimater med udbyderbrug og omkostningseksport.
• Advarsel om forbrugsstigninger, forsinkelsesregressioner, fallback-spring, valideringsfejl og sikkerhedsrelevante hændelser.

Konklusion

En multi-model gateway er det rigtige sted at implementere LLM observerbarhed, fordi den ser anmodninger, før de når nogen udbyder og kan tilknytte forretningskontekst, som udbyderne ikke kender. Det stærkeste design er ikke "log alt". Det er en lagdelt model: udbyderneutrale spor til eksekvering, et holdbart token og omkostningsregnskab til fakturering, lejeranalyse til styring, RAG-metadata til genfindingskvalitet og logning af privatlivets fred først for sikker fejlretning.

Start med metadata, tilstandsovergange og afstemning. Tilføj kun indholdsfangst, når politik, opbevaring og adgangskontrol er klar. Denne sekvens giver udviklere de beviser, de har brug for til at fejlsøge latenstid, kvalitet og forbrug uden at gøre observerbarhed til en ny dataeksponeringsrisiko.

Relateret læsning

• genforsøg og fallback-adfærd i LLM API routing
• prompt-caching-kontrol og batch-omkostningskontrol mønstre
• teamAPI nøgleadministration og forbrugsgrænser