Kako izgraditi vidljivost LLM-a neutralnu prema pružatelju usluga s OpenTelemetryjem

LLM vidljivost se prekida kada svaki aplikacijski tim bilježi odgovore pružatelja usluga u vlastitom formatu. Tijekom incidenta, platformski timovi moraju odgovoriti na konkretna pitanja: koji je tim uputio zahtjev, koji API opseg ključa je korišten, koji je model zatražen, koji ga je pružatelj zapravo poslužio, je li došlo do ponovnog pokušaja ili vraćanja, koliko je tokena potrošeno, koja se latencija promijenila i koja je klasa pogreške uzrokovala neuspjeh. Oni također trebaju te odgovore bez kopiranja neobrađenih upita, dovršetaka, ključeva pružatelja ili identifikatora korisnika u generičke pohrane dnevnika.

Praktični odgovor je instrumentirati pristupnik s više modela API kao kontrolnu točku promatranja. Praćenje na razini aplikacije i dalje je važno, ali pristupnik je mjesto gdje se odabir pružatelja, ponovni pokušaji, zamjenski podaci, obračun korištenja, vlasništvo zahtjeva i provedba privatnosti mogu normalizirati prije nego što telemetrija dosegne nizvodne alate. Za timove koji vode poduzeće LLM API, to postaje razlika između raspršenih podataka za otklanjanje pogrešaka i operativnog modela koji je neutralan prema davatelju usluga.

Najprije definirajte ugovor o promatranju

Počnite s pisanim ugovorom o atributima, a ne snimkama zaslona nadzorne ploče. Ugovor bi trebao definirati minimalne metapodatke koje svaki LLM zahtjev mora emitirati, koja polja smiju napustiti gateway, koja su polja ograničena, a koja se polja nikada ne izvoze.

Korisni osnovni ugovor uključuje metapodatke o vlasništvu, usmjeravanju, modelu, korištenju, kašnjenju i ishodu. Atributi vlasništva identificiraju organizaciju, tim, okruženje, radno opterećenje, aplikaciju i API opseg ključa. Atributi usmjeravanja identificiraju rutu pristupnika, verziju pravila, traženog pružatelja, traženi model, odabranog pružatelja, odabrani model, broj ponovnih pokušaja, rezervni broj i je li korišten streaming. Atributi upotrebe bilježe ulazne tokene, izlazne tokene, predmemorirane ulazne tokene, tokene obrazloženja kada su dostupni, broj zahtjeva i procijenjenu klasu troškova. Atributi ishoda bilježe status, kôd pogreške pružatelja kada je siguran, normaliziranu klasu pogreške, rezultat provjere valjanosti, stanje vremenskog ograničenja i model konačnog odgovora.

Držite ugovornog dobavljača neutralnim. Pogreška specifična za davatelja kao što je odgovor ograničenja brzine, odgovor preopterećenog modela, neuspjeh provjere valjanosti sheme, sigurnosno odbijanje, vremensko ograničenje ili pogreška kontekstnog prozora trebala bi se preslikati na normaliziranu klasu pogreške koju nadzorne ploče mogu grupirati po davateljima. Izvorni kôd pogreške davatelja može biti koristan, ali treba ga tretirati kao ograničene dijagnostičke podatke, a ne kao primarnu dimenziju nadzorne ploče.

Koristite model raspona usmjerenog na pristupnik

Jasna struktura praćenja sprječava da telemetrija LLM-a postane ravna hrpa raspona. Upotrijebite jedan raspon zahtjeva za dolaznu aplikaciju, jedan raspon logičke operacije LLM-a i podređene raspone za posao koji pristupnik obavlja.

Tipična hijerarhija izgleda ovako:

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

Raspon dolaznih zahtjeva predstavlja zahtjev pozivatelja prema pristupniku. Logički raspon rada LLM-a predstavlja zadatak LLM-a vidljiv korisniku, čak i ako gateway čini više pokušaja pružatelja. Rasponi pokušaja pružatelja hvataju svaki stvarni poziv prema uzvodnom modelu API. Rasponi za dohvaćanje, alat i provjeru valjanosti trebaju biti djeca logičke operacije kada su dio proizvodnje konačnog odgovora.

Ovo odvajanje je važno tijekom incidenata. Ako se zahtjev vrati s jednog modela na drugi, logička operacija može uspjeti dok prvi pokušaj pružatelja ne uspije. Ako konačni izlaz ne prođe provjeru valjanosti sheme, pokušaj pružatelja može biti tehnički uspješan dok logička operacija ne uspijeva. Bez zasebnih raspona, nadzorne ploče ili skrivaju kvarove pružatelja iza uspješnih odgovora krajnjeg korisnika ili preuveličavaju kvarove koji su uspješno oporavljeni.

Mapiranje OpenTelemetry GenAI atributa iza internog mapera

Postoje semantičke konvencije OpenTelemetryja tako da proizvođači telemetrije koriste uobičajena imena i atribute u bazama koda, bibliotekama i platformama.Projekt OpenTelemetry sada usmjerava Generative AI konvencije na zasebno GenAI repozitorij, a te konvencije definiraju atribute zahtjeva i odgovora modela kao što su naziv davatelja usluga, traženi model, model odgovora, tokeni unosa, tokeni izlaza, tokeni obrazloženja i predmemorirani tokeni unosa.

Koristite te GenAI atribute tamo gdje odgovaraju, ali nemojte razbacivati ​​sirova imena atributa po kodu pristupnika. Zamotajte ih iza malog telemetrijskog mapera. Taj maper treba prihvatiti interni zapis zahtjeva i proizvesti standardizirane atribute raspona.

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
}

Maper može emitirati atribute OpenTelemetry GenAI za standardna polja i atribute privatnog pristupnika za poslovni kontekst. Držite privatne atribute pod kontroliranim prostorom imena, na primjer llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy i llm_gateway.workload_class.

Ovaj dizajn daje vam telemetriju neutralnu prema dobavljaču, a istovremeno štiti bazu koda od odljeva. GenAI konvencije još uvijek se razvijaju, tako da je maper mjesto gdje se imena mogu mijenjati bez uređivanja svakog rukovatelja, modula za ponovni pokušaj, adaptera za strujanje i komponente provjere valjanosti.

Odvojite metapodatke od osjetljivog sadržaja

Tragovi LLM-a su neobično osjetljivi jer najkorisniji podaci za otklanjanje pogrešaka mogu biti isti oni podaci koji se ne bi trebali široko zadržavati: upita, dohvaćeni dokumenti, alat parametri, dovršeci, identifikatori korisnika, identifikatori kupaca i sirove vjerodajnice pružatelja usluga. Zadana pozicija trebala bi biti vidljivost na prvom mjestu metapodataka.

Preporučena zadana polja uključuju raspršivanje upita, ID predloška upita, verziju odziva, ID sheme, naziv alata, zbirku dohvaćanja, naziv rute, broj tokena, latenciju, normaliziranu klasu pogreške i status provjere valjanosti. Ova polja odgovaraju na mnoga operativna pitanja bez izvoza neobrađenog sadržaja.

Snimanje neobrađenih upita i dovršetka treba uključiti, vremenski ograničiti, kontrolirati pristup i redigirati prije izvoza. Nemojte ga omogućiti globalno kao značajku pogodnosti. Kada je snimanje sadržaja potrebno za proizvodni incident, priložite oznaku za otklanjanje pogrešaka uskom skupu zahtjeva, usmjerite te tragove na ograničenu pozadinu i postavite kratki period zadržavanja.

Hashing identifikatora nije automatska anonimizacija. Ako je ulazni prostor malen ili predvidljiv, raspršene vrijednosti mogu se poništiti pogađanjem. Za osjetljive identifikatore kupaca ili korisnika razmislite o brisanju, zamjenskim ID-ovima, segmentiranju, skraćivanju ili ključnom raspršivanju sa strogim kontrolama ključa. Koristite raspršivače prvenstveno za stabilnu korelaciju kada se razumije rizik, a ne kao opći odgovor o privatnosti.

Provedba privatnosti u Collectoru

Smjernice OpenTelemetry kažu da se osjetljivim podacima treba rukovati prije izvoza. Sakupljač može ukloniti, raspršiti, filtrirati, redigirati ili transformirati telemetrijske atribute pomoću procesora kao što su atributi, filtriranje, redigiranje i transformacija. To čini Collector drugom linijom obrane nakon same instrumentacije pristupnika.

Praktični cjevovod Collector-a trebao bi koristiti listu dopuštenih za atribute niskog rizika, prema zadanim postavkama brisati neobrađena polja upita i odgovora, maskirati vrijednosti koje odgovaraju blokiranim obrascima i odvojeno usmjeravati više osjetljive tragove kada je snimanje sadržaja izričito omogućeno. Procesor atributa OpenTelemetry Collector podržava radnje poput brisanja i raspršivanja. Procesor za uređivanje dizajniran je za brisanje atributa koji nisu na popisu dopuštenih i maskiranje vrijednosti koje odgovaraju blokiranim obrascima.

Na primjer, pristupnik može izbjeći emitiranje neobrađenog sadržaja prema zadanim postavkama, dok Collector i dalje briše atribute kao što su llm.prompt.raw, llm.completion.raw, provider.api_key, authorization i cookie ako se pojave zbog greške ili integracije biblioteke. Tretirajte ovo kao dubinsku kontrolu obrane, a ne kao razlog za ležerno emitiranje nesigurnih podataka.

Ponovni pokušaji instrumenta, zamjene i provjera valjanosti zasebno

Ponovni pokušaji i zamjene često su nevidljivi u skupnim API metrikama. Ta nevidljivost uzrokuje dva operativna problema. Prvo, kašnjenje se može smanjiti jer uspješan odgovor može sakriti više neuspjelih pokušaja.Drugo, trošak može porasti jer jedan zahtjev korisnika može stvoriti nekoliko poziva uzlaznog modela.

Svaki raspon pokušaja pružatelja treba uključivati ​​broj pokušaja, razlog ponovnog pokušaja, odabranog pružatelja usluga, odabrani model, proračun vremenskog ograničenja, kašnjenje, upotrebu tokena kada je dostupan i ishod. Ako dođe do zamjene, zamjenski raspon treba identificirati izvornu politiku rute, zamjenski razlog i model koji se zapravo koristi za konačni odgovor.

Provjera valjanosti strukturiranog izlaza trebala bi biti vlastiti raspon ili događaj. Snimite ID sheme, verziju sheme, rezultat provjere valjanosti, broj pokušaja popravka i konačni status. Prema zadanim postavkama nemojte pohranjivati ​​puni nevažeći izlaz. Neuspješna provjera valjanosti operativno se razlikuje od pogreške prijenosa pružatelja usluga, a nadzorne ploče ih ne bi trebale zamagliti zajedno.

Napravite nadzorne ploče oko pitanja, a ne pružatelja

Providnost neutralna prema pružatelju trebala bi izravno odgovarati na operativna pitanja. Korisne nadzorne ploče uključuju p95 i p99 kašnjenje prema modelu, pružatelju usluga, timu, okruženju i klasi radnog opterećenja; korištenje tokena od strane tima i rute; stopa neuspjeha prema normaliziranoj klasi pogreške; ponovni pokušaj pojačanja prema politici rute; rezervna učestalost prema traženom modelu; pogreške kontekstnog prozora po predlošku upita; kvarovi provjere valjanosti strukturiranog izlaza po shemi; i uzorkovane primjere praćenja za neuspjele, skupe ili spore zahtjeve.

Zadržite naplatu i izvješća o ukupnoj upotrebi izvan uzorkovanih praćenja. Repno uzorkovanje je korisno za otklanjanje pogrešaka, ali može iskriviti ukupne vrijednosti. Ukupni tokeni, brojevi zahtjeva i knjige troškova trebaju potjecati iz neuzorkovanih brojača, knjiga zahtjeva ili sustava za usklađivanje naplate. Tragovi bi trebali objasniti zašto je došlo do skupog ili sporog zahtjeva; oni ne bi trebali biti jedini izvor financijske istine.

Koristite repno uzorkovanje za tragove visoke vrijednosti

Procesor repnog uzorkovanja OpenTelemetry Collector može donositi odluke o uzorkovanju nakon dovršetka raspona, uključujući pravila temeljena na atributima i numeričkim vrijednostima. To je korisno za LLM promet jer često znate je li praćenje vrijedno tek nakon završetka odgovora.

Zadržite tragove za pogreške pružatelja usluga, neuspjehe provjere valjanosti, vrlo visoku latenciju, neuobičajeno skupu upotrebu tokena, pogreške kontekstnog prozora, povratne pokušaje i ručno označene zahtjeve za uklanjanje pogrešaka. Uzorkujte rutinski uspješan promet po nižoj stopi. Ovo čuva tragove koji će najvjerojatnije objasniti incidente dok kontrolira volumen pohrane.

Razuman model politike je jednostavan: uvijek čuvajte pogreške, uvijek održavajte zahtjeve iznad praga latencije ili tokena, uvijek čuvajte tragove označene debug-om i probabilistički uzorkujte obične uspješne zahtjeve. Ponovno pregledajte pragove kako se promet mijenja. Prag koji je koristan tijekom ranog usvajanja može biti prenizak kada proizvodni promet poraste.

Dodajte ugovorne testove za telemetriju

Telemetriju bi trebalo testirati kao API ugovor jer o njoj ovise nizvodne nadzorne ploče, upozorenja, kontrole troškova i tijek rada za incidente. Dodajte testove koji pokreću reprezentativne zahtjeve pristupnika i potvrđuju da su potrebni rasponi i atributi emitirani.

Testovi bi trebali potvrditi da uspješan zahtjev emitira logički raspon operacije LLM-a, raspon pokušaja pružatelja, zatraženi model, model odgovora, naziv pružatelja, broj tokena kada je dostupan, metapodatke tima ili opsega ključa, verziju pravila rute i konačni status. Testovi ponovnog pokušaja trebali bi potvrditi broj pokušaja i razloge ponovnog pokušaja. Zamjenski testovi trebali bi potvrditi i neuspjeli pokušaj i posljednji uspješni pokušaj pružatelja. Validacijski testovi trebali bi utvrditi ID sheme, status validacije i broj pokušaja popravka.

Sigurnosni testovi su jednako važni. Utvrdite da neobrađeni ključevi pružatelja usluga, zaglavlja autorizacije, kolačići, neobrađeni upiti, neobrađena dovršavanja i neodobreni identifikatori korisnika nedostaju u izvezenoj telemetriji.Ovi testovi ne bi trebali biti zatvoreni kada razvojni programer doda novi rasponski atribut bez da ga je klasificirao.

Kontrolni popis implementacije

• Atributski ugovor: Definirajte obavezne, neobavezne, ograničene i zabranjene atribute.
• Span hijerarhija: Odvojite dolazne zahtjeve, logičke operacije LLM-a, pokušaji pružatelja usluga, ponovni pokušaji, vraćanja, pozivi za dohvaćanje, pozivi alata i provjera valjanosti.
• Semantičko mapiranje: Koristite atribute OpenTelemetry GenAI tamo gdje odgovaraju i atribute privatnog pristupnika za vlasništvo i kontekst usmjeravanja.
• Pravila o privatnosti: Zadani su hashevi, ID-ovi predložaka, ID-ovi shema, nazivi alata, brojevi tokena, latencija i klase grešaka umjesto sirovog sadržaja.
• Procesori sakupljača: Brisanje zabranjenih polja, redigiranje blokiranih uzoraka, popis dopuštenih niskorizičnih atributa i zasebno usmjeravanje osjetljivih tragova.
• Uzorkovanje pravilo: Pratite uzorke praćenja visoke vrijednosti i čuvajte agregatne metrike neuzorkovane.
• Nadzorne ploče: Izgradite prikaze oko latencije, upotrebe, neuspjeha, ponovnih pokušaja, zamjena, provjere valjanosti i pokretača troškova.
• Upozorenja: Upozorenje o normaliziranoj pogrešci klase, p99 pomaci latencije, pojačanje ponovnog pokušaja, zamjenski skokovi, neuspjesi provjere valjanosti i anomalije tokena.
• Testovi ugovora: Tvrdi da je potrebna telemetrija prisutna, a osjetljiva telemetrija odsutna.

Kompromisi o kojima treba odlučiti Eksplicitno

Instrumentacija na razini pristupnika brzo daje konzistentne metapodatke, ali može propustiti kontekst specifičan za aplikaciju osim ako timovi ne proslijede metapodatke strukturiranih zahtjeva kao što su stanar, tijek rada, predložak upita i naziv značajke. Neka ti metapodaci budu dio ugovora o zahtjevu pristupnika umjesto da se oslanjaju na zapisnike slobodnog oblika.

Snimanje potpunog sadržaja poboljšava otklanjanje pogrešaka i procjenu, ali povećava privatnost, sigurnost, zadržavanje i opterećenje kontrole pristupa. Mnogi bi timovi trebali započeti samo s hashovima, ID-ovima predložaka, ID-ovima shema i redigiranim izvatcima.

Klase pogrešaka neutralne prema pružatelju čine nadzorne ploče upotrebljivima na više API-ja modela, ali sažimaju detalje specifične za pružatelja. Čuvajte neobrađene kodove pogrešaka pružatelja usluga samo kada je to sigurno i ograničite im pristup.

Konvencije OpenTelemetry GenAI smanjuju zaključavanje, ali će se konvencije nastaviti razvijati. Interni mapper daje vam prednosti standardizacije bez dopuštanja da nestabilni nazivi atributa procure kroz bazu koda.

Zaključak

Mobilnost LLM-a neutralna prema dobavljaču nije samo praćenje koje se dodaje pozivima modela. To je operativni ugovor na sloju pristupnika: dosljedni rasponi, normalizirani model i metapodaci pružatelja, kontekst vlasništva, upotreba tokena, ponovni pokušaj i vidljivost povratka, kontrole privatnosti, pravila uzorkovanja i testovi koji sprječavaju curenje osjetljivih podataka.

Počnite s pristupnikom jer on već vidi odluke koje su najvažnije: tko je podnio zahtjev, koja ga je politika usmjerila, koji ga je pružatelj poslužio, što koštalo je u tokenima, koliko je trajalo, je li se pokrenula logika oporavka i što nije uspjelo. Jednom kada je temelj stabilan, aplikacijski timovi mogu dodati bogatiji kontekst tijeka rada bez da svaki tim izmišlja svoj vlastiti LLM sustav za promatranje.

Povezano čitanje

• telemetrija rezervnog usmjeravanja