Účtovanie tokenov streamovania v bráne AI API: konečné použitie, zrušenia a čiastočné odozvy

Streamovanie odpovedí LLM je jednoduché na proxy a je ťažké ich správne účtovať. Ak brána AI API preposiela udalosti odoslané serverom klientovi, ale s prvými časťami zaobchádza ako so záznamom používania, analýzy nájomníkov sa posunú. Odchýlka sa zvyčajne objavuje v sporoch, ako napríklad: „používateľ videl iba polovicu odpovede“, „poskytovateľ účtoval viac, ako ukazuje náš informačný panel“, „kvóta bola uvoľnená príliš skoro“ alebo „vypršanie časového limitu vyprodukovalo tokeny, ale žiadny riadok faktúry.“

Základný problém spočíva v tom, že streamované hovory nie sú jednou udalosťou. Ide o postupnosť: požiadavka prijatá, upstream stream otvorený, bajty doručené, nahlásené konečné využitie, zastavený poskytovateľ, klient odpojený, brána vypršala a fakturácia vyrovnaná. Spoľahlivá brána by mala tieto stavy modelovať explicitne namiesto toho, aby predpokladala, že dokončená odpoveď HTTP je jedinou úspešnou cestou.

Režim zlyhania: streamovanie skryje hranicu účtovania

Nestreamované dokončenia zvyčajne vrátia jeden objekt odpovede s metaúdajmi o použití. Brána dokáže normalizovať toto použitie, zapisovať riadok účtovnej knihy, aktualizovať kvótu a odosielať analýzy v jednom prechode.

Streamovanie mení hranicu. Dojem používateľa je prírastkový, ale pravda o fakturácii sa môže objaviť na konci, v záverečnej udalosti špecifickej pre poskytovateľa, v kumulatívnom rozdiele, prostredníctvom súhrnnej odpovede súpravy SDK alebo neskôr prostredníctvom rozhraní API na vytváranie prehľadov poskytovateľa. Ak sa klient odpojí pred udalosťou konečného použitia, brána mohla doručiť iba časť odpovede, zatiaľ čo poskytovateľ stále generoval a účtoval ďalšie tokeny.

Fakt: OpenAI dokumentuje, že streamujúci volajúci, ktorí chcú údaje o používaní, by mali nastaviť stream_options na include_usage. OpenAI tiež poskytuje koncové body využitia a nákladov na úrovni organizácie, pričom treba poznamenať, že využitie a náklady sa nemusia vždy dokonale zhodovať na finančné účely.

Fakt: Antropické streamovanie využíva udalosti odoslané serverom, ako sú message_start, content_block_delta, message_delta a message_stop. Informácie o použití message_delta sú kumulatívne, takže brána nesmie sčítavať každý rozdiel využitia.

Fakt: Rozhrania API na streamovanie v štýle Gemini a Vertex môžu odhaľovať prírastkové časti, zatiaľ čo súpravy SDK môžu poskytovať aj súhrnný objekt odpovede. V prípade brán môže byť táto súhrnná cesta lepším zdrojom dokončenia použitia ako samotné viditeľné časti.

Použite stroj stavu prúdu, nie boolovský príznak úspechu

Streamovaná požiadavka by mala mať trvalý záznam o používaní pred začatím upstream hovoru. Tento záznam by sa mal pohybovať cez explicitné stavy. Praktické minimum je:

• prijaté: brána overila kľúč, priradila nájomníkovi a vytvorila riadok otvorenej účtovnej knihy.
• first_byte_sent: najmenej jedna výstupná udalosť sa dostala k následnému klientovi.
• provider_completed: poskytovateľ upstream vyslal normálny stop signál alebo dokončený objekt odpovede.
• client_aborted: downstream soket sa zatvoril pred dokončením normálnej brány.
• provider_error: poskytovateľ upstream vrátil chybu po spustení streamu alebo pred konečným použitím.
• gateway_timeout: brána presadila svoj rozpočet latencie a ukončila požiadavku.
• vyrovnané: brána previedla využitie na náklady nájomníka a spotrebu kvóty.
• odsúhlasené: neskoršie údaje o používaní poskytovateľa alebo o nákladoch potvrdili alebo upravili riadok.

Tento model zabraňuje bežnej analytickej chybe: označovanie každého streamu, ktorý vytvoril text, ako „úspešný a presný“. Stream môže byť pre používateľa užitočný, od poskytovateľa neúplný, odhadovaný na fakturáciu a zároveň čaká na vyrovnanie.

Odporúčané polia hlavnej knihy

Riadok času žiadosti ponechajte malý, ale explicitný:

{
  "request_id": "gw_req_...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "poskytovateľ": "openai|antropický|gemini|...",
  "provider_request_id": null,
  "model": "id-model-poskytovateľa",
  "state": "prijaté",
  "stream": pravda,
  "input_tokens": null,
  "output_tokens_billed": null,
  "output_tokens_delivered_estimate": 0,
  "provider_usage_source": null,
  "billing_status": "čaká na vyrovnanie",
  "client_abort_at": null,
  "provider_completed_at": null,
  "settled_at": null,
  "error_class": null
}

Dôležité je oddelenie output_tokens_billed a output_tokens_delivered_estimate. Používateľov zaujíma, čo sa dostalo do ich aplikácie. Financie zaujíma, čo poskytovateľ fakturoval. Tieto čísla sa môžu líšiť po odpojení, streamoch volaní nástrojov, skrytých tokenoch uvažovania, tokenoch uložených vo vyrovnávacej pamäti, bezpečnostných zastávkach alebo uplynutí časového limitu brány.

Pravidlá zachytávania špecifické pre poskytovateľa

Neutrálne voči poskytovateľovi API kompatibilné s OpenAI je užitočné pre vývojárov aplikácií, ale adaptér brány stále potrebuje účtovné pravidlá špecifické pre poskytovateľa.

Streamovanie kompatibilné s OpenAI

V prípade trás OpenAI vystavte možnosť brány, ktorá umožňuje odosielanie správ o používaní, ak je to podporované. Bežným vzorom je akceptovať predvolené nastavenie na úrovni brány, ako napríklad:

{
  "stream": pravda,
  "stream_options": {
    "include_usage": true
  }
}

Ak ho volajúci v smere toku vynechá, brána sa môže rozhodnúť, či ho vloží do trás, kde je to kompatibilné. Zdokumentujte toto správanie, pretože niektorí klienti očakávajú presnú káblovú kompatibilitu a niektoré modely alebo upstreamy nemusia podporovať konečné použitie rovnakým spôsobom.

Odporúčanie: neuhrádzajte náklady nájomcu z počiatočných častí. Ponechajte riadok účtovnej knihy otvorený, kým sa nezaznamená udalosť konečného použitia, kým sa odpoveď poskytovateľa neskončí bez použitia alebo kým sa v streame nedostane chyba alebo cesta zrušenia.

Antropické streamovanie

Kumulatívne využitie Anthropicu si vyžaduje iné pravidlo. Ak brána vidí tri udalosti message_delta s počtom výstupných tokenov 10, 25 a 40, výstupný počet je 40, nie 75.

nech lastUsage = null;
for wait (konštantná udalosť antropického prúdu) {
  if (event.type === "message_delta" && event.usage) {
    if (latestUsage && event.usage.output_tokens < lastUsage.output_tokens) {
      emit("kumulatívne_použitie_regresed", requestId);
    }
    najnovšieUsage = event.usage;
  }
  forwardToClient(udalosť);
}
setttleFromLatestCumulativeUsage(latestUsage);

Odporúčanie: zaznamenajte si najnovšiu kumulatívnu hodnotu používania a v prípade jej regresie vygenerujte udalosť pozorovateľnosti. Regresia môže naznačovať chyby analyzátora, duplicitné udalosti, zmeny poskytovateľa alebo zmiešané streamy.

Streamovanie v štýle Gemini a Vertex

Gemini podporuje streamovanie kúskov na zníženie vnímanej latencie. V súpravách SDK v štýle Vertex môže streamovanie odhaliť asynchrónny stream aj agregovaný objekt odpovede. Brána by mala zachovať túto agregovanú cestu, keď je k dispozícii.

const streamingResult = wait model.generateContentStream(request);
for wait (const chunk of streamingResult.stream) {
  forwardChunk(kus);
  countDeliveredBytesOrText(kus);
}
const agregované = wait streamingResult.response;
setttleFromAggregatedUsage(agregated);

Odporúčanie: vyhnite sa vytváraniu celého účtovníctva z viditeľných častí, ak súprava SDK poskytuje úplný záznam odpovede. Kusy sú pre latenciu. Konečný objekt je často lepší pre fakturáciu a analýzu.

Spravujte odpojenia klienta ako prvotriedne účtovné udalosti

Odpojením klientov mnoho brán prichádza o peniaze alebo predražuje zákazníkov. Karta prehliadača sa zatvorí, mobilná sieť klesne alebo aplikácia zruší požiadavku. Brána si všimne zatvorený downstream soket, ale poskytovateľ upstream môže stále generovať.

Brána by mala explicitne zvoliť pravidlá:

• Okamžité zrušenie upstreamu: znižuje plytvanie generovaním a náklady poskytovateľa, ale môže narušiť pracovné postupy, kde backend stále potrebuje výsledok po odpojení používateľského rozhrania.
• Pokračovať v upstreame na pozadí: môže zachovať prácu pre spotrebiteľov na strane servera, ale používateľ nemusí vidieť všetky vygenerované a účtované tokeny.
• Správanie závislé od trasy: zrušte pre interaktívny rozhovor, pokračujte v pracovných postupoch podobných úlohám a zviditeľnite nastavenie pre nájomníkov.

Praktickým predvoleným nastavením pre interaktívne streamovanie je zrušiť upstream, keď sa následný klient odpojí, a potom označiť riadok účtovnej knihy ako client_aborted. Ak počas zrušenia dôjde ku konečnému použitiu, vyrovnajte sa z tohto autoritatívneho použitia. Ak nie, označte riadok odhadovaný alebo čakajúce na vyrovnanie namiesto toho, aby ste predstierali, že je presný.

downstream.on("close", async () => {
  if (!providerCompleted) {
    ledger.markClientAborted(requestId);
    wait upstream.abort().catch(() => {
      ledger.emit("upstream_cancel_failed", requestId);
    });
  }
});

Odporúčanie: odhaľte transparentné fakturačné štítky, ako sú konečné, poskytovateľ_odsúhlasené, odhadované, upustené alebo čakajúce na vyrovnanie. Je to lepšie obhájiteľné, ako zobrazovať každý streamovaný hovor ako okamžite presný.

Presadzovanie kvóty počas streamu

Presná fakturácia zvyčajne závisí od využitia konečného poskytovateľa, ale presadzovanie kvót nemôže vždy počkať až do konca. Nájomcovi s pevným rozpočtom by nemalo byť umožnené streamovať donekonečna, pretože presné využitie nie je dostupné počas trvania.

Použite dva mechanizmy súčasne:

1. Predletová rezervácia: rezervujte si odhadované maximum na základe modelu, požadovaných maximálnych tokenov, pravidiel nájomcu a aktuálneho zostatku.
2. Kontrola tlaku streamovania: odhadne dodaný výstup počas streamu a zastaví sa, ak požiadavka prekročí nakonfigurovanú bezpečnostnú hranicu.

Toto je kontrolný mechanizmus, nie konečný účet. Poskytovatelia môžu počítať tokeny uložené vo vyrovnávacej pamäti, tokeny uvažovania, multimodálne tokeny alebo skryté tokeny odlišne od odhadu brány.

Výmena: odhady v reálnom čase pomáhajú presadzovať rozpočty, ale môžu sa líšiť od tokenov účtovaných poskytovateľom. Pri konečnom zúčtovaní by sa malo použiť autoritatívne využitie poskytovateľa, ak je k dispozícii, a zosúladenie by malo odhady upraviť neskôr.

Udalosti pozorovateľnosti, ktoré zachytávajú chyby v účtovníctve

Zlyhania fakturácie pri streamovaní sa ľahšie ladia, keď brána vysiela cielené udalosti namiesto iba všeobecných protokolov požiadaviek. Pridajte udalosti ako:

• final_usage_missing: stream sa skončil bez autoritatívneho použitia.
• cumulative_usage_regressed: kumulatívny počet tokenov sa posunul dozadu.
• stream_ended_without_stop_event: nebola pozorovaná žiadna normálna značka zastavenia poskytovateľa.
• aborted_after_provider_completion: poskytovateľ dokončil, ale následný klient sa zavrel skôr, ako brána dokončila preposielanie.
• settled_from_estimate: účtovná kniha nájomníkov použila odhad, pretože konečné využitie nebolo k dispozícii.
• reconciliation_adjusted_usage: hlásenie poskytovateľa neskôr zmenilo riadok.

Skutočnosť: Sémantické konvencie OpenTelemetry GenAI odporúčajú používať informácie o používaní vrátené poskytovateľom pre odpovede na streamovanie, ak sú k dispozícii, a varujú pred nahlasovaním metrík používania, ak počet tokenov nemožno získať efektívne alebo presne.

Pre analýzu používania AI to znamená, že informačné panely by mali podporovať úrovne spoľahlivosti. Tabuľka, ktorá kombinuje konečné, odhadované a zosúladené hodnoty bez štítkov, môže vyzerať čisto, no môže zavádzať finančné a podporné tímy.

Testy zhody pre účtovníctvo streamovania

Nespoliehajte sa na manuálne testovanie s výzvou na rozhovor so šťastnou cestou. Každý adaptér poskytovateľa by mal mať testy zhody pre prípady, ktoré porušujú účtovné knihy:

• Normálny stream: príde konečné použitie, pozorovaná udalosť zastavenia, účtovná kniha sa ustáli ako konečná.
• Tool-call stream: delta volaní nástroja sú preposielané, využitie je zachytené, štruktúrované metadáta nepoškodzujú počítanie tokenov.
• Bezpečnostné zastavenie alebo zastavenie odmietnutia: poskytovateľ sa predčasne zastaví, používanie sa stále správne ustáli.
• Nútené odpojenie klienta: downstream sa po čiastočnom výstupe zatvorí; upstream je zrušený alebo bude pokračovať podľa pravidiel.
• Upstream 5xx po čiastočnom výstupe: brána zaznamená čiastočné doručenie a neoznačí požiadavku ako úspešnú.
• Časový limit brány pred konečným použitím: riadok sa stane odhadovaným alebo čaká na vyrovnanie.
• Chýbajúca posledná udalosť: adaptér vysiela final_usage_missing a vyhýba sa presným fakturačným štítkom.

Tieto testy by mali potvrdiť prechody stavov, polia účtovnej knihy, emitované udalosti pozorovateľnosti a následné správanie. Kompatibilita toku po bajtoch nestačí; účtovné vedľajšie účinky sú súčasťou zmluvy.

Praktický kontrolný zoznam implementácie

• Pred odoslaním upstream požiadavky vytvorte riadok knihy použitia.
• Uložte identifikátory nájomníka, kľúča, používateľa, modelu, smerovania, poskytovateľa a požiadavky v čase vyžiadania.
• Ak je to podporované, povoľte hlásenie konečného využitia poskytovateľa, ako napríklad stream_options.include_usage kompatibilné s OpenAI.
• V prípade kumulatívnych poskytovateľov uložte namiesto sčítania udalostí poslednú hodnotu využitia.
• Zachovať agregované objekty odpovedí, keď ich poskytujú súpravy SDK.
• Sledujte dodaný výstup oddelene od spotreby účtovanej poskytovateľom.
• Pri odpojení zrušte upstream podľa pravidiel smerovania a označte client_aborted.
• Používajte transparentné stavy fakturácie: konečná, odhadovaná, čakajúca na vyrovnanie, odsúhlasená poskytovateľom alebo odložená.
• Vysielajte udalosti pozorovateľnosti špecifické pre účtovníctvo.
• Neskôr sa zosúlaďte s prehľadmi o používaní poskytovateľa alebo o nákladoch, keď budú k dispozícii, pričom zachováte priradenie nájomníka v čase vyžiadania.

Čo zobraziť nájomníkom

Nájomníci nepotrebujú každú internú udalosť, ale potrebujú čestné označenia. Užitočná tabuľka používania môže zobrazovať:

• Stav: konečný, odhadovaný alebo odsúhlasený.
• Výsledok žiadosti: dokončené, klient prerušený, chyba poskytovateľa alebo časový limit brány.
• Doručený výstup: približný text alebo bajty odoslané klientovi.
• Fakturované tokeny: využitie normalizované poskytovateľom, ktoré sa používa na úhradu nákladov.
• Úprava: akékoľvek neskoršie delta vyrovnania.

Tento dizajn znižuje nejednoznačnosť podpory. Ak používateľ videl iba časť odpovede, na informačnom paneli sa môže vysvetliť, či už poskytovateľ dokončil, či bola brána zrušená upstream a či je poplatok konečný alebo odhadovaný.

Odporúčania verzus predpovede

Odporúčania: spracovávajte streamované požiadavky ako stavové automaty, počkajte na autoritatívne konečné použitie pred presným vyrovnaním, oddeľte dodaný výstup od fakturovaného použitia a označte odhadované riadky čestne. Adaptéry poskytovateľa by mali skôr zakódovať sémantiku používania špecifickú pre poskytovateľa, než zlúčiť každý stream do všeobecného bajtového proxy.

Predpoveď: Účtovanie streamovania bude dôležitejšie, pretože modely odhaľujú viac skrytej práce: tokeny uvažovania, zľavy tokenov uložených vo vyrovnávacej pamäti, multimodálne spracovanie, sledovanie používania nástrojov a bezpečnostné zastávky. Brány, ktoré už oddeľujú používanie účtované poskytovateľom od výstupu viditeľného pre klienta, sa prispôsobia ľahšie ako brány, ktoré počítajú iba streamovaný text.

Uplatniteľný záver

Ak vaša brána podporuje streamovanie, auditujte jednu cestu ešte dnes: po niekoľkých prvých kúskoch vynútiť odpojenie klienta a skontrolovať riadok účtovnej knihy. Ak sa pri presne vyzerajúcom počte tokenov uvádza „úspech“, vaša analytika pravdepodobne klame.

Opravou nie je opustiť streamovanie. Zachovajte si rýchly používateľský zážitok, ale dokončenie streamu, zrušenie, chyby poskytovateľa, chýbajúce konečné použitie a zosúladenie urobte explicitnými účtovnými stavmi. To poskytuje produktovým tímom pohotový výstup, finančným tímom obhájiteľné náklady a tímom podpory dostatok dôkazov na vysvetlenie čiastkových odpovedí bez hádania.

Súvisiace čítanie

• spájanie trasovaní, účtovných kníh tokenov a analýzy bezpečného používania
• vytvorenie zmluvy o kompatibilite brány kompatibilnej s OpenAI