Úč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ú. Posun sa zvyčajne objavuje v sporoch, ako napríklad: „používateľ videl iba polovicu odpovede“, „poskytovateľ fakturoval viac, ako ukazuje náš informačný panel“, „kvóta bola uvoľnená príliš skoro“ alebo „vypršanie časového limitu vyprodukovalo tokeny, ale žiaden riadok na faktúre.“

Základný problém je v tom, že streamované hovory nie sú jedna udalosť. 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 účtovníctva

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 SDK alebo neskôr prostredníctvom rozhraní API na vytváranie prehľadov poskytovateľa. Ak sa klient odpojí pred udalosťou posledného použitia, brána mohla doručiť iba časť odpovede, zatiaľ čo poskytovateľ stále generoval a fakturoval ď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: Anthropic streamovanie používa udalosti odoslané serverom, ako napríklad message_start, content_block_delta, message_delta a message_stop. Jej message_delta informácie o používaní sú kumulatívne, takže brána nesmie sčítavať všetky rozdiely využitia.

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

Použite stroj stavu streamu, 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:

• accepted: brána overila kľúč, priradila nájomníka 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 signál zastavenia 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 na latenciu a ukončila požiadavku.
• settled: brána previedla využitie na náklady nájomníka a spotrebu kvóty.
• reconciled: neskoršie údaje o využití poskytovateľa alebo 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 účtovnej knihy

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

{
  "request_id": "gw_req_...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "provider": "openai|anthropic|gemini|...",
  "provider_request_id": null,
  "model": "provider-model-id",
  "state": "accepted",
  "stream": true,
  "input_tokens": null,
  "output_tokens_billed": null,
  "output_tokens_delivered_estimate": 0,
  "provider_usage_source": null,
  "billing_status": "pending_reconciliation",
  "client_abort_at": null,
  "provider_completed_at": null,
  "settled_at": null,
  "error_class": null
}

Dôležité oddelenie je output_tokens_billed verzus 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ástroja, 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álny poskytovateľ OpenAI-kompatibilný API je užitočný pre vývojárov aplikácií, ale adaptér brány stále potrebuje účtovné pravidlá špecifické pre poskytovateľa.

OpenAI-kompatibilný streaming

Pre trasy OpenAI zobrazte 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, napríklad:

{
  "stream": true,
  "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 stream nezaznamená chybu alebo cestu zrušenia.

Anthropic streaming

Anthropic 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.

let latestUsage = null;

for await (const event of anthropicStream) {
  if (event.type === "message_delta" && event.usage) {
    if (latestUsage && event.usage.output_tokens < latestUsage.output_tokens) {
      emit("cumulative_usage_regressed", requestId);
    }
    latestUsage = event.usage;
  }

  forwardToClient(event);
}

settleFromLatestCumulativeUsage(latestUsage);

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

Gemini a streamovanie v štýle Vertex

Gemini podporuje streamovanie častí 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 = await model.generateContentStream(request);

for await (const chunk of streamingResult.stream) {
  forwardChunk(chunk);
  countDeliveredBytesOrText(chunk);
}

const aggregated = await streamingResult.response;
settleFromAggregatedUsage(aggregated);

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

Spracovanie odpojení klienta ako prvotriedne účtovné udalosti

Odpojenia klientov sú miestom, kde mnohé brány prichádzajú o peniaze alebo predražujú 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 premárnené generovanie 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ť proti prúdu 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 estimated alebo pending_reconciliation a nepredstierajte, že je presný.

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

Odporúčanie: odhaľte transparentné fakturačné štítky, ako napríklad final, provider_reconciled, estimated, waived alebo pending_reconciliation. 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ájomníkovi 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 spolu dva mechanizmy:

1. Predletová rezervácia: rezervujte si odhadované maximum na základe modelu, požadovaných maximálnych tokenov, pravidiel nájomníka 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.

Trade-off: 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ť overené používanie 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 dajú ľahšie ladiť, keď brána vydáva 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 posunutý 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 zatvoril 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 riadok zmenilo.

Fakt: 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 analytiku 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, ale 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 čet šť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 final.
• Tool-call stream: delta volaní nástroja sa preposielajú, využitie sa zaznamenáva, štruktúrované metadáta nepoškodzujú počítanie tokenov.
• Bezpečnostné zastavenie alebo odmietnutie: Poskytovateľ sa predčasne zastaví, používanie sa stále správne ustáli.
• Nútené odpojenie klienta: následné zatvorenie po čiastočnom výstupe; upstream je zrušený alebo pokračovať v súlade s pravidlami.
• 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ýba posledná udalosť: adaptér vydáva 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.

Kontrolný zoznam na praktickú implementáciu

• Pred odoslaním upstream požiadavky vytvorte riadok knihy použitia.
• Uložiť identifikátory nájomníka, kľúča, používateľa, modelu, trasy, poskytovateľa a požiadavky v čase vyžiadania.
• Ak je to podporované, povoliť hlásenie konečného využitia poskytovateľa, napríklad OpenAI-kompatibilný stream_options.include_usage.
• 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 trasy a označte client_aborted.
• Používajte transparentné stavy fakturácie: konečný, odhadovaný, čakajúci na vyrovnanie, odsúhlasený poskytovateľom alebo zrieknutý.
• Vysielať 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 ukázať 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 použité na náklady.
• Úprava: akákoľvek neskoršia delta vyrovnania.

Tento dizajn znižuje nejednoznačnosť podpory. Ak sa používateľovi zobrazila 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: zaobchádzajte so streamovanými požiadavkami ako so stavovými strojmi, 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čujte 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.

Prediction: Úč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 jednoduchš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: vynútiť odpojenie klienta po niekoľkých prvých kúskoch 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 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 čiastočných odpovedí bez hádania.

Súvisiace čítanie

• navrhovanie účtovnej knihy za každým modelovým hovorom
• spojenie stôp ledgerov, bezpečného používania a tokenov analytics
• vytvorenie OpenAIkompatibilnej zmluvy o kompatibilite brány