Účtování tokenů streamování v bráně AI API: konečné použití, zrušení a částečné odezvy

Streamování odpovědí LLM lze snadno použít jako proxy a je obtížné správně fakturovat. Pokud brána AI API předává události odeslané serverem klientovi, ale s prvními částmi zachází jako se záznamem využití, analytika tenanta se posune. Posun se obvykle objevuje ve sporech, jako například: „uživatel viděl jen polovinu odpovědi“, „poskytovatel účtoval více, než ukazuje náš řídicí panel“, „kvóta byla uvolněna příliš brzy“ nebo „vypršel časový limit pro vytvoření tokenů, ale žádný řádek faktury.“

Základním problémem je, že streamované hovory nejsou jedna událost. Jedná se o sekvenci: požadavek přijat, upstream stream otevřen, bajty doručeny, nahlášeno konečné využití, poskytovatel zastaven, klient odpojen, vypršel časový limit brány a vyúčtováno. Spolehlivá brána by měla tyto stavy modelovat explicitně, místo aby předpokládala, že dokončená odpověď HTTP je jedinou úspěšnou cestou.

Režim selhání: streamování skrývá hranici účtování

Nestreamovaná dokončení obvykle vracejí jeden objekt odpovědi s metadaty využití. Brána může toto využití normalizovat, zapisovat řádek hlavní knihy, aktualizovat kvótu a vydávat analýzy v jednom průchodu.

Streamování mění hranice. Uživatelský dojem je přírůstkový, ale pravdivost fakturace se může objevit na konci, v konečné události specifické pro poskytovatele, v kumulativním rozdílu, prostřednictvím agregované odpovědi SDK nebo později prostřednictvím rozhraní API pro vytváření přehledů poskytovatelů. Pokud se klient odpojí před událostí konečného použití, brána možná doručila pouze část odpovědi, zatímco poskytovatel stále generoval a účtoval další tokeny.

Fakt: OpenAI dokumentuje, že streamující volající, kteří chtějí údaje o využití, by měli nastavit stream_options na include_usage. OpenAI také poskytuje koncové body využití a nákladů na úrovni organizace, přičemž je třeba poznamenat, že využití a náklady nemusí vždy dokonale odpovídat finančním účelům.

Fakt: Antropické streamování využívá události odeslané serverem, jako jsou message_start, content_block_delta, message_delta a message_stop. Informace o využití message_delta jsou kumulativní, takže brána nesmí sčítat každý rozdíl využití dohromady.

Fakt: Rozhraní API pro streamování ve stylu Gemini a Vertex mohou odhalit přírůstkové části, zatímco sady SDK mohou také poskytovat agregovaný objekt odezvy. Pro brány může být tato agregovaná cesta lepším zdrojem pro dokončené použití než samotné viditelné části.

Používejte stavový stroj proudu, nikoli booleovský příznak úspěchu

Streamovaný požadavek by měl mít trvalý záznam o využití před zahájením upstreamového volání. Tento záznam by se měl pohybovat přes explicitní stavy. Praktické minimum je:

• přijato: brána ověřila klíč, přiřadila tenanta a vytvořila otevřený řádek hlavní knihy.
• first_byte_sent: nejméně jedna výstupní událost dosáhla navazujícího klienta.
• provider_completed: poskytovatel upstream vyslal normální signál zastavení nebo dokončený objekt odpovědi.
• client_aborted: downstream soket byl uzavřen před dokončením normální brány.
• provider_error: poskytovatel upstream vrátil chybu po zahájení streamu nebo před konečným využitím.
• gateway_timeout: brána vynutila svůj rozpočet na latenci a ukončila požadavek.
• vypořádáno: brána převedla využití na náklady nájemce a spotřebu kvóty.
• odsouhlaseno: pozdější údaje o využití poskytovatele nebo o nákladech řádek potvrdily nebo upravily.

Tento model zabraňuje běžné chybě analýzy: označení každého streamu, který vytvořil text, jako „úspěšný a přesný“. Stream může být pro uživatele užitečný, od poskytovatele neúplný, odhadovaný pro fakturaci a zároveň čekající na odsouhlasení.

Doporučená pole hlavní knihy

Řádek doby požadavku ponechte malý, ale explicitní:

{
  "request_id": "gw_req_...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "poskytovatel": "openai|antropický|gemini|...",
  "provider_request_id": null,
  "model": "id-model-poskytovatele",
  "state": "přijato",
  "stream": pravda,
  "input_tokens": null,
  "output_tokens_billed": null,
  "output_tokens_delivered_estimate": 0,
  "provider_usage_source": null,
  "billing_status": "čekající_odsouhlasení",
  "client_abort_at": null,
  "provider_completed_at": null,
  "settled_at": null,
  "error_class": null
}

Důležité oddělení je output_tokens_billed a output_tokens_delivered_estimate. Uživatelé se starají o to, co dosáhlo jejich aplikace. Finance zajímá, co poskytovatel fakturoval. Tato čísla se mohou lišit po odpojení, streamech volání nástrojů, skrytých tokenech uvažování, tokenech uložených v mezipaměti, bezpečnostních zastaveních nebo vypršení časového limitu brány.

Pravidla zachycení specifická pro poskytovatele

Neutrální vůči poskytovateli API kompatibilní s OpenAI je užitečné pro vývojáře aplikací, ale adaptér brány stále potřebuje účetní pravidla specifická pro poskytovatele.

Streamování kompatibilní s OpenAI

U tras OpenAI vystavte možnost brány, která umožňuje hlášení o využití, pokud je podporováno. Běžným vzorem je přijmout výchozí nastavení na úrovni brány, například:

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

Pokud jej následný volající vynechá, brána se může rozhodnout, zda jej vloží do tras, kde je to kompatibilní. Toto chování zdokumentujte, protože někteří klienti očekávají přesnou kabelovou kompatibilitu a některé modely nebo upstreamy nemusí podporovat konečné použití stejným způsobem.

Doporučení: neřešte náklady nájemce z prvních částí. Řádek hlavní knihy ponechte otevřený, dokud nebude zachycena událost konečného využití, neskončí odpověď poskytovatele bez využití nebo dokud stream nevstoupí do cesty chyby nebo zrušení.

Antropické streamování

Komulativní využití Anthropicu vyžaduje jiné pravidlo. Pokud brána vidí tři události message_delta s počty výstupních tokenů 10, 25 a 40, výstupní počet je 40, nikoli 75.

let lastUsage = null;
for wait (konst. událost anthropicStream) {
  if (event.type === "message_delta" && event.usage) {
    if (latestUsage && event.usage.output_tokens < nejnovějšíUsage.output_tokens) {
      emit("kumulativní_usage_regressed", requestId);
    }
    nejnovějšíUsage = event.usage;
  }
  forwardToClient(událost);
}
settleFromLatestCumulativeUsage(latestUsage);

Doporučení: zaznamenejte poslední kumulativní hodnotu využití a v případě, že dojde k jejímu návratu, vygenerujte událost pozorovatelnosti. Regrese může indikovat chyby analyzátoru, duplicitní události, změny poskytovatele nebo smíšené streamy.

Streamování ve stylu Gemini a Vertex

Gemini podporuje streaming chunks ke snížení vnímané latence. V sadách SDK ve stylu Vertex může streamování odhalit jak asynchronní stream, tak agregovaný objekt odpovědi. Brána by měla zachovat tuto agregovanou cestu, pokud je k dispozici.

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

Doporučení: Vyhněte se vytváření veškerého účetnictví z viditelných částí, pokud sada SDK poskytuje úplný záznam odpovědi. Kousky jsou pro latenci. Konečný objekt je často lepší pro fakturaci a analýzu.

Zpracovávejte odpojení klienta jako prvotřídní účetní události

Odpojení klientů je místo, kde mnoho bran přichází o peníze nebo předražuje zákazníky. Karta prohlížeče se zavře, mobilní síť přestane fungovat nebo aplikace zruší požadavek. Brána si všimne uzavření downstream soketu, ale poskytovatel upstream může stále generovat.

Brána by měla explicitně zvolit zásady:

• Okamžité zrušení upstreamu: snižuje plýtvání generováním a náklady poskytovatele, ale může narušit pracovní postupy, kde backend stále potřebuje výsledek po odpojení uživatelského rozhraní.
• Pokračovat proti proudu na pozadí: může zachovat práci pro spotřebitele na straně serveru, ale uživatel nemusí vidět všechny vygenerované a účtované tokeny.
• Chování závislé na trase: zrušte pro interaktivní chat, pokračujte v pracovních postupech podobných úlohám a zpřístupněte nastavení nájemcům.

Praktickým výchozím nastavením pro interaktivní streamování je zrušit upstream, když se následný klient odpojí, a poté označit řádek hlavní knihy jako client_aborted. Pokud během zrušení dojde ke konečnému použití, vyrovnejte se z tohoto autoritativního použití. Pokud ne, označte řádek odhadovaný nebo čekající_srovnání místo toho, abyste předstírali, že je přesný.

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

Doporučení: odhalte transparentní fakturační štítky, jako je final, provider_reconciled, estimated, waived nebo pending_reconciliation. To je obhajitelnější než zobrazovat každý streamovaný hovor jako okamžitě přesný.

Vynucení kvóty během streamování

Přesné účtování obvykle závisí na využití konečným poskytovatelem, ale vynucování kvót nemůže vždy počkat až do konce. Nájemci s pevným rozpočtem by nemělo být povoleno streamovat donekonečna, protože přesné využití není v průběhu provozu k dispozici.

Používejte společně dva mechanismy:

1. Předletová rezervace: rezervujte odhadované maximum na základě modelu, požadovaných maximálních tokenů, zásad pro nájemce a aktuálního zůstatku.
2. Kontrola tlaku streamování: odhadne dodaný výstup během streamování a zastaví se, pokud požadavek překročí nakonfigurovanou bezpečnostní hranici.

Toto je kontrolní mechanismus, nikoli konečný účet. Poskytovatelé mohou počítat tokeny uložené v mezipaměti, tokeny uvažování, multimodální tokeny nebo skryté tokeny jinak než odhadce brány.

Výměna: Odhady v reálném čase pomáhají prosazovat rozpočty, ale mohou se lišit od tokenů účtovaných poskytovatelem. Konečné vypořádání by mělo využívat autoritativní využití poskytovatele, je-li k dispozici, a odsouhlasení by mělo odhady upravit později.

Události pozorovatelnosti, které zachycují chyby v účetnictví

Chyby fakturace při streamování se snáze ladí, když brána generuje cílené události namísto pouze obecných protokolů požadavků. Přidejte události jako:

• final_usage_missing: stream skončil bez autoritativního použití.
• cumulative_usage_regressed: kumulativní počet tokenů se posunul zpět.
• stream_ended_without_stop_event: nebyla pozorována žádná běžná značka zastavení poskytovatele.
• aborted_after_provider_completion: Poskytovatel dokončil, ale následný klient se zavřel dříve, než brána dokončila předávání.
• settled_from_estimate: účetní kniha nájemců použila odhad, protože konečné využití nebylo k dispozici.
• reconciliation_adjusted_usage: hlášení poskytovatele později změnilo řádek.

Fakt: Sémantické konvence OpenTelemetry GenAI doporučují používat informace o využití vrácené poskytovatelem pro odpovědi streamování, pokud jsou k dispozici, a varují před hlášením metrik využití, pokud nelze efektivně nebo přesně získat počty tokenů.

Pro analýzu využití AI to znamená, že řídicí panely by měly podporovat úrovně spolehlivosti. Graf, který míchá konečné, odhadované a odsouhlasené hodnoty bez štítků, může vypadat čistě, ale finanční a podpůrné týmy může být zavádějící.

Test shody pro účtování streamování

Nespoléhejte se na ruční testování pomocí výzvy k chatu. Každý adaptér poskytovatele by měl mít testy shody pro případy, které porušují účetní knihy:

• Normální stream: dojde ke konečnému použití, pozorována událost stop, účetní kniha se ustálí jako konečná.
• Tool-call stream: Delta volání nástroje jsou přesměrovány, využití je zachyceno, strukturovaná metadata nepoškodí počítání tokenů.
• Bezpečnostní nebo odmítnutí: Poskytovatel se předčasně zastaví, využití se stále ustálí správně.
• Nucené odpojení klienta: downstream se po částečném výstupu zavře; upstream je zrušen nebo bude pokračovat podle zásad.
• Upstream 5xx po částečném výstupu: brána zaznamená částečné doručení a neoznačí požadavek jako čistý úspěšný.
• Časový limit brány před konečným použitím: řádek se stane odhadovaným nebo čeká na odsouhlasení.
• Chybějící závěrečná událost: adaptér generuje final_usage_missing a vyhýbá se přesným fakturačním štítkům.

Tyto testy by měly potvrdit přechody stavů, pole hlavní knihy, emitované události pozorovatelnosti a následné chování. Kompatibilita toku po bajtech nestačí; účetní vedlejší efekty jsou součástí smlouvy.

Kontrolní seznam praktické implementace

• Před odesláním upstreamové žádosti vytvořte řádek knihy použití.
• Uložte identifikátory nájemce, klíče, uživatele, modelu, trasy, poskytovatele a požadavku v okamžiku požadavku.
• Povolte hlášení konečného využití poskytovatele tam, kde je to podporováno, například stream_options.include_usage kompatibilní s OpenAI.
• U kumulativních poskytovatelů ukládejte místo sčítání událostí poslední hodnotu využití.
• Zachovat agregované objekty odpovědí, když je poskytují sady SDK.
• Sledujte dodaný výstup odděleně od využití účtovaného poskytovatelem.
• Při odpojení zrušte upstream podle zásad směrování a označte client_aborted.
• Používejte transparentní stavy fakturace: konečná, odhadovaná, čekající na odsouhlasení, odsouhlaseno poskytovatelem nebo prominuto.
• Vysílat události pozorovatelnosti specifické pro účetnictví.
• Později proveďte soulad s přehledy využití poskytovatele nebo nákladů, až budou k dispozici, a zachováte atribuci tenanta v době požadavku.

Co zobrazit nájemcům

Nájemci nepotřebují každou interní událost, ale potřebují poctivé štítky. Užitečná tabulka použití může ukazovat:

• Stav: konečný, odhadovaný nebo odsouhlasený.
• Výsledek požadavku: dokončeno, klient byl přerušen, došlo k chybě poskytovatele nebo vypršel časový limit brány.
• Doručený výstup: přibližný text nebo bajty odeslané klientovi.
• Fakturované tokeny: využití normalizované poskytovatelem použité pro náklady.
• Úprava: jakákoli pozdější delta odsouhlasení.

Tento návrh snižuje nejednoznačnost podpory. Pokud uživatel viděl pouze část odpovědi, může řídicí panel vysvětlit, zda poskytovatel již dokončil, zda byla brána zrušena upstream a zda je poplatek konečný nebo odhadovaný.

Doporučení versus předpovědi

Doporučení: zacházejte se streamovanými požadavky jako se stavovými stroji, před přesným vyúčtováním počkejte na autoritativní konečné použití, oddělte dodaný výstup od fakturovaného použití a poctivě označte odhadované řádky. Adaptéry poskytovatele by měly spíše kódovat sémantiku využití specifickou pro poskytovatele, než sloučit každý stream do obecného bajtového proxy.

Predpověď: účtování streamování bude stále důležitější, protože modely odhalují více skryté práce: tokeny uvažování, slevy tokenů uložených v mezipaměti, multimodální zpracování, sledování použití nástrojů a bezpečnostní zastávky. Brány, které již oddělují využití účtované poskytovatelem od výstupu viditelného pro klienty, se přizpůsobí snadněji než brány, které počítají pouze streamovaný text.

Akční závěr

Pokud vaše brána podporuje streamování, auditujte jednu cestu ještě dnes: vynuťte odpojení klienta po prvních několika blocích a zkontrolujte řádek hlavní knihy. Pokud to říká „úspěch“ s přesně vypadajícím počtem tokenů, vaše analytika pravděpodobně lže.

Oprava není opustit streamování. Zachovejte rychlé uživatelské prostředí, ale dokončete streamování, rušení, chyby poskytovatele, chybějící konečné využití a odsouhlasení explicitních účetních stavů. To poskytuje produktovým týmům pohotový výstup, finančním týmům obhajitelné náklady a týmům podpory dostatek důkazů pro vysvětlení dílčích odpovědí bez dohadování.

Související informace

• spojování trasování, účetní knihy tokenů a analýzy bezpečného použití
• vytvoření smlouvy o kompatibilitě brány kompatibilní s OpenAI