Úč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řeposílá 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ě namísto toho, 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 se z finančních důvodů nemusí vždy dokonale shodovat.

Fakt: Anthropic 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: Gemini a rozhraní API pro streamování ve stylu Vertex mohou odhalit přírůstkové části, zatímco sady SDK mohou také poskytovat agregovaný objekt odpovědi. 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 streamu, 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 hovoru. Tento záznam by se měl pohybovat přes explicitní stavy. Praktické minimum je:

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

Tento model zabraňuje běžné analytické chybě: označuje každý stream, 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",
  "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é oddělení je output_tokens_billed versus 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í poskytovatel OpenAI-kompatibilní API je užitečný pro vývojáře aplikací, ale adaptér brány stále potřebuje účetní pravidla specifická pro poskytovatele.

OpenAI-kompatibilní streamování

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": true,
  "stream_options": {
    "include_usage": true
  }
}

Pokud ji volající po proudu vynechá, brána se může rozhodnout, zda ji 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í.

Anthropic streaming

Anthropic 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 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);

Doporučení: zaznamenejte nejnovější kumulativní hodnotu využití a vygenerujte událost pozorovatelnosti, pokud dojde k její regresi. Regrese může naznačovat chyby analyzátoru, duplicitní události, změny poskytovatele nebo smíšené streamy.

Gemini a streamování ve stylu Vertex

Gemini podporuje streamování bloků 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, je-li k dispozici.

const streamingResult = await model.generateContentStream(request);

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

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

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

Zvládejte 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 upstream poskytovatel může stále generovat.

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

• Okamžité zrušení upstreamu: snižuje zbytečné náklady na generování a 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šit pro interaktivní chat, pokračovat v pracovních postupech podobných úlohám a zpřístupnit 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 estimated nebo pending_reconciliation a nepředstírejte, že je přesný.

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

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

Vynucování kvót během streamování

Přesná fakturace 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 letu k dispozici.

Používejte dva mechanismy společně:

1. Předletová rezervace: rezervujte si 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.

Trade-off: 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, pokud je 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á normální značka zastavení poskytovatele.
• aborted_after_provider_completion: poskytovatel dokončen, ale následný klient se zavřel dříve, než brána dokončila přeposílání.
• settled_from_estimate: Kniha nájemců použila odhad, protože konečné využití nebylo k dispozici.
• reconciliation_adjusted_usage: hlášení poskytovatele později řádek změnilo.

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

Pro analytiku využití AI to znamená, že řídicí panely by měly podporovat úrovně spolehlivosti. Graf, který kombinuje 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 na ruční testování pomocí výzvy k chatu šťastnou cestou. 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 využití, pozorována událost stop, účetní kniha se ustálí jako final.
• Tool-call stream: Rozdíly volání nástroje jsou přesměrovány, využití je zachyceno, strukturovaná metadata nepoškodí počítání tokenů.
• Bezpečnost nebo odmítnutí: Poskytovatel se předčasně zastaví, využití se stále správně ustálí.
• Nucené odpojení klienta: po částečném výstupu se zavře po proudu; upstream je zrušen nebo bude pokračovat v souladu se zásadami.
• 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í poslední událost: adaptér vydává 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ší účinky jsou součástí smlouvy.

Kontrolní seznam praktické implementace

• Před odesláním upstreamové žádosti vytvořte řádek knihy použití.
• Ukládat identifikátory nájemce, klíče, uživatele, modelu, trasy, poskytovatele a požadavku v době požadavku.
• Povolit hlášení o konečném využití poskytovatele tam, kde je to podporováno, například OpenAI-kompatibilní stream_options.include_usage.
• U kumulativních poskytovatelů místo sčítání událostí ukládejte 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í.
• Soulad později s přehledy využití poskytovatele nebo nákladů, až budou k dispozici, při zachování atribuce tenanta v době požadavku.

Co ukázat nájemcům

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

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

Tento design 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 proti proudu zrušena a zda je poplatek konečný nebo odhadovaný.

Doporučení versus předpovědi

Doporučení: zacházet se streamovanými požadavky jako se stavovými stroji, před přesným vyúčtováním čekat na autoritativní konečné použití, oddělovat dodaný výstup od fakturovaného použití a poctivě označovat odhadované řádky. Adaptéry poskytovatelů 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.

Prediction: Úč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ů v mezipaměti, multimodální zpracování, sledování používání 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í týmy obhajitelné náklady a týmům podpory dostatek důkazů k vysvětlení částečných odpovědí bez dohadování.

Související čtení

• navrhování účetní knihy za každým voláním modelu
• spojení trasování led, bezpečné použití a token analytics
• vytvoření OpenAIkompatibilní smlouvy o kompatibilitě brány