Streamingtoken-accounting in een AI API-gateway: eindgebruik, annuleringen en gedeeltelijke reacties

Aanbeveling: registreer de laatste cumulatieve gebruikswaarde en verzend een waarneembaarheidsgebeurtenis als deze achteruitgaat. Een regressie kan wijzen op parserbugs, dubbele gebeurtenissen, wijzigingen in de provider of gemengde streams.

Streaming in Gemini- en Vertex-stijl

Gemini ondersteunt streaming-brokken om de waargenomen latentie te verminderen. In SDK's in Vertex-stijl kan streaming zowel een asynchrone stroom als een geaggregeerd antwoordobject blootleggen. Een gateway moet dat geaggregeerde pad behouden, indien beschikbaar.

const streamingResult = wachten op model.generateContentStream(request);
voor wachten (const deel van streamingResult.stream) {
  forwardChunk(stuk);
  countDeliveredBytesOrText(chunk);
}
const geaggregeerd = wacht op streamingResult.response;
nederzettingFromAggregatedUsage(geaggregeerd);

Aanbeveling: vermijd het opbouwen van alle boekhouding uit zichtbare delen als de SDK een voltooid antwoordrecord geeft. Chunks zijn voor latentie. Het uiteindelijke doel is vaak beter voor facturering en analyse.

Behandel verbroken verbindingen van klanten als eersteklas boekhoudkundige gebeurtenissen

Clientverbroken verbindingen zijn de reden dat veel gateways geld verliezen of klanten te veel in rekening brengen. Een browsertabblad wordt gesloten, een mobiel netwerk valt weg of een applicatie annuleert een verzoek. De gateway merkt dat de downstream-socket gesloten is, maar de upstream-provider genereert mogelijk nog steeds.

De gateway moet een expliciete beleidskeuze maken:

• Upstream onmiddellijk opzeggen: vermindert verspilling van opwekking en providerkosten, maar kan workflows verbreken waarbij de backend nog steeds het resultaat nodig heeft nadat de gebruikersinterface is verbroken.
• Upstream doorgaan op de achtergrond: kan werk behouden voor consumenten aan de serverzijde, maar de gebruiker ziet mogelijk niet alle gegenereerde en gefactureerde tokens.
• Routeafhankelijk gedrag: annuleer voor interactieve chat, ga door voor taakachtige workflows en maak de instelling zichtbaar voor huurders.

Een praktische standaard voor interactieve streaming is om upstream te annuleren wanneer de downstream-client de verbinding verbreekt, en vervolgens de grootboekrij te markeren als client_aborted. Als het definitieve gebruik tijdens de annulering binnenkomt, reken dan af met dat gezaghebbende gebruik. Als dit niet het geval is, markeert u de rij geschat of pending_reconciliation in plaats van te doen alsof deze exact is.

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

Aanbeveling: maak transparante factureringslabels zichtbaar, zoals definitief, provider_reconciled, geschat, vrijgesteld of pending_reconciliation. Dit is beter verdedigbaar dan het weergeven van elk gestreamd gesprek als onmiddellijk exact.

Quotahandhaving tijdens een stream

Nauwkeurige facturering is meestal afhankelijk van het uiteindelijke gebruik van de provider, maar het afdwingen van quota kan niet altijd tot het einde wachten. Een huurder met een vast budget mag niet voor onbepaalde tijd streamen, omdat het exacte gebruik halverwege de vlucht niet beschikbaar is.

Gebruik twee mechanismen samen:

1. Preflight-reservering: reserveer een geschat maximum op basis van model, aangevraagde maximale tokens, tenantbeleid en huidig saldo.
2. Streamingdrukcontroles: schat de geleverde output tijdens de stream en stop als het verzoek een geconfigureerde veiligheidsgrens overschrijdt.

Dit is een controlemechanisme, niet de eindafrekening. Providers kunnen tokens in het cachegeheugen, redeneringstokens, multimodale tokens of verborgen tokens anders tellen dan de schatter van een gateway.

Trade-off: realtime schattingen helpen bij het handhaven van budgetten, maar ze kunnen afwijken van door de provider gefactureerde tokens. Bij de eindafrekening moet gebruik worden gemaakt van gezaghebbend gebruik van de provider, indien beschikbaar, en bij afstemming moeten de schattingen later worden aangepast.

Waarneembaarheidsgebeurtenissen die boekhoudfouten opsporen

Fouten bij het streamen van facturering zijn gemakkelijker op te sporen wanneer de gateway gerichte gebeurtenissen uitzendt in plaats van alleen generieke verzoeklogboeken. Voeg evenementen toe zoals:

• final_usage_missing: stream beëindigd zonder gezaghebbend gebruik.
• cumulative_usage_regressed: cumulatieve tokentelling achteruit verplaatst.
• stream_ended_without_stop_event: er is geen normale stopmarkering voor de provider waargenomen.
• aborted_after_provider_completion: de provider is voltooid, maar de downstream-client is gesloten voordat de gateway klaar was met doorsturen.
• settled_from_ estimate: huurdersgrootboek gebruikte een schatting omdat het uiteindelijke gebruik niet beschikbaar was.
• reconciliation_adjusted_usage: providerrapportage heeft de rij later gewijzigd.

Feit: de semantische conventies van OpenTelemetry GenAI raden aan om door de provider geretourneerde gebruiksinformatie te gebruiken voor het streamen van reacties indien beschikbaar, en waarschuwen voor het rapporteren van gebruiksstatistieken als het aantal tokens niet efficiënt of nauwkeurig kan worden verkregen.

Voor AI-gebruiksanalyses betekent dit dat dashboards de betrouwbaarheidsniveaus moeten ondersteunen. Een diagram waarin definitieve, geschatte en afgestemde waarden zonder labels worden gecombineerd, ziet er misschien netjes uit, maar kan financiële en ondersteuningsteams misleiden.

Conformiteitstests voor streaming accounting

Vertrouw niet op handmatig testen met een vrolijke chatprompt. Elke provideradapter moet conformiteitstests ondergaan voor de gevallen waarin grootboeken kapot gaan:

• Normale stroom: het uiteindelijke gebruik arriveert, de stopgebeurtenis wordt waargenomen, het grootboek wordt afgehandeld als definitief.
• Tool-call-stream: tool-call-delta's worden doorgestuurd, gebruik wordt vastgelegd, gestructureerde metagegevens verstoren het aantal tokens niet.
• Veiligheids- of weigeringsstop: aanbieder stopt vroegtijdig, gebruik wordt nog steeds correct afgehandeld.
• Geforceerd ontkoppelen van client: stroomafwaarts wordt gesloten na gedeeltelijke uitvoer; upstream wordt geannuleerd of voortgezet volgens het beleid.
• Upstream 5xx na gedeeltelijke uitvoer: gateway registreert gedeeltelijke levering en markeert het verzoek niet als volledig succes.
• Gatewaytime-out vóór definitief gebruik: rij wordt geschat of is in afwachting van afstemming.
• Ontbrekende laatste gebeurtenis: adapter zendt final_usage_missing uit en vermijdt exacte factuurlabels.

Deze tests moeten statusovergangen, grootboekvelden, uitgezonden waarneembaarheidsgebeurtenissen en stroomafwaarts gedrag bevestigen. Byte-voor-byte stream-compatibiliteit is niet voldoende; de boekhoudkundige neveneffecten maken deel uit van het contract.

Praktische implementatiechecklist

• Maak de gebruiksgrootboekrij voordat u het upstream-verzoek verzendt.
• Sla huurder-, sleutel-, gebruiker-, model-, route-, provider- en verzoek-ID's op op het moment van de aanvraag.
• Schakel rapportage van het eindgebruik van de provider in waar dit wordt ondersteund, zoals OpenAI-compatibele stream_options.include_usage.
• Voor cumulatieve providers slaat u de laatste gebruikswaarde op in plaats van gebeurtenissen op te tellen.
• Bewaar de verzamelde antwoordobjecten wanneer SDK's deze leveren.
• Volg de geleverde output afzonderlijk van het door de provider gefactureerde gebruik.
• Bij het verbreken van de verbinding annuleert u upstream volgens het routebeleid en markeert u client_aborted.
• Gebruik transparante factureringsstatussen: definitief, geschat, afstemming in behandeling, afstemming met provider of kwijtschelding.
• Accountingspecifieke waarneembaarheidsgebeurtenissen uitzenden.
• Vergelijk later het gebruik van de provider of de kostenrapporten, indien beschikbaar, terwijl de toewijzing van de tenant op de aanvraagtijd behouden blijft.

Wat huurders moeten laten zien

Huurders hebben niet elk intern evenement nodig, maar wel eerlijke labels. Een nuttige gebruikstabel zou het volgende kunnen tonen:

• Status: definitief, geschat of afgestemd.
• Verzoekresultaat: voltooid, client afgebroken, providerfout of gateway-time-out.
• Geleverde uitvoer: geschatte tekst of bytes verzonden naar de client.
• Gefactureerde tokens: door de provider genormaliseerd gebruik gebruikt voor de kosten.
• Aanpassing: eventuele latere afstemmingsdelta.

Dit ontwerp vermindert de dubbelzinnigheid van de ondersteuning. Als een gebruiker slechts een deel van een reactie heeft gezien, kan het dashboard uitleggen of de provider al heeft voltooid, of de gateway upstream heeft geannuleerd en of de kosten definitief of geschat zijn.

Aanbevelingen versus voorspellingen

Aanbevelingen: behandel gestreamde verzoeken als statusmachines, wacht op gezaghebbend eindgebruik voordat de exacte afhandeling plaatsvindt, scheid geleverde uitvoer van gefactureerd gebruik en label geschatte rijen eerlijk. Provideradapters moeten providerspecifieke gebruikssemantiek coderen in plaats van elke stream af te vlakken in een generieke byteproxy.

Voorspelling: streaming-accounting zal belangrijker worden naarmate modellen meer verborgen werk blootleggen: redeneringstokens, kortingen op cache-tokens, multimodale verwerking, sporen van toolgebruik en veiligheidsstops. Gateways die het door de provider gefactureerde gebruik al scheiden van de voor de klant zichtbare uitvoer, zullen zich gemakkelijker aanpassen dan gateways die alleen gestreamde tekst tellen.

Bruikbare conclusie

Als uw gateway streaming ondersteunt, controleer dan vandaag nog één pad: forceer de verbinding van een client na de eerste paar chunks en inspecteer de grootboekrij. Als er ‘succes’ staat met exact uitziende tokenaantallen, liegen uw analyses waarschijnlijk.

De oplossing is om het streamen niet te staken. Behoud de snelle gebruikerservaring, maar maak de voltooiing van streams, annuleringen, providerfouten, ontbrekend eindgebruik en afstemming expliciete boekhoudkundige statussen. Dat geeft productteams responsieve output, financiële teams verdedigbare kosten en ondersteuningsteams voldoende bewijs om gedeeltelijke reacties te verklaren zonder te raden.

Gerelateerde informatie

• het ontwerpen van het factureringsgrootboek achter elke modelaanroep
• het samenvoegen van sporen, token-grootboeken en veilige gebruiksanalyses
• het bouwen van een OpenAI-compatibel gateway-compatibiliteitscontract