Transmiterea în flux a contabilității jetoane într-un gateway AI API: utilizare finală, anulări și răspunsuri parțiale

Răspunsurile în flux LLM sunt ușor de proxy și greu de facturat corect. Dacă o gateway API AI redirecționează către client evenimentele trimise de server, dar tratează primele bucăți ca pe înregistrarea utilizării, analiza locatarului va fi în derivă. Derivea apare de obicei în dispute precum: „utilizatorul a văzut doar jumătate din răspuns”, „furnizorul a facturat mai mult decât arată tabloul de bord”, „cota a fost eliberată prea devreme” sau „un timeout a produs jetoane, dar nicio linie de factură.”

Problema rădăcină este că apelurile transmise în flux nu sunt un singur eveniment. Acestea sunt o secvență: cerere acceptată, flux în amonte deschis, octeți livrați, utilizare finală raportată, furnizor oprit, client deconectat, gateway expirat și facturare stabilită. Un gateway de încredere ar trebui să modeleze acele stări în mod explicit, în loc să presupună că un răspuns HTTP finalizat este singura cale de succes.

Modul de eșec: streaming ascunde limita contabilă

Finalizările care nu sunt transmise în flux returnează de obicei un obiect de răspuns cu metadate de utilizare. Un gateway poate normaliza acea utilizare, poate scrie un rând de registru, poate actualiza cota și poate emite analize într-o singură trecere.

Transmiterea în flux schimbă limita. Experiența utilizatorului este incrementală, dar adevărul de facturare poate ajunge la sfârșit, într-un eveniment final specific furnizorului, într-o deltă cumulativă, printr-un răspuns SDK agregat sau mai târziu prin intermediul API-urilor de raportare a furnizorului. Dacă clientul se deconectează înainte de evenimentul final de utilizare, este posibil ca gateway-ul să fi livrat doar o parte a răspunsului, în timp ce furnizorul încă a generat și facturat mai multe jetoane.

Realitate: OpenAI documentează că apelanții în flux care doresc date de utilizare ar trebui să seteze stream_options cu include_usage. OpenAI oferă, de asemenea, terminale de utilizare și costuri la nivel de organizație, menționând în același timp că utilizarea și costurile pot să nu se împace întotdeauna perfect în scopuri financiare.

Realitate: Streamingul antropic utilizează evenimente trimise de server, cum ar fi message_start, content_block_delta, message_delta și message_stop. Informațiile sale de utilizare message_delta sunt cumulative, așa că un gateway nu trebuie să adauge fiecare delta de utilizare împreună.

Realitate: API-urile de streaming în stil Gemini și Vertex pot expune fragmente incrementale, în timp ce SDK-urile pot oferi și un obiect de răspuns agregat. Pentru gateway-uri, acea cale agregată poate fi o sursă mai bună pentru o utilizare completă decât numai bucățile vizibile.

Utilizați o mașină de stare a fluxului, nu un semnal boolean de succes

O solicitare transmisă în flux ar trebui să aibă o înregistrare durabilă de utilizare înainte de a începe apelul în amonte. Acea înregistrare ar trebui să treacă prin stări explicite. Un minim practic este:

• acceptat: gateway-ul a autentificat cheia, a atribuit chiriașului și a creat un rând deschis în registru.
• first_byte_sent: cel puțin un eveniment de ieșire a ajuns la clientul din aval.
• provider_completed: furnizorul din amonte a emis un semnal de oprire normal sau un obiect de răspuns finalizat.
• client_aborted: socket-ul din aval s-a închis înainte de finalizarea normală a gateway-ului.
• provider_error: furnizorul din amonte a returnat o eroare după începerea fluxului sau înainte de sosirea utilizării finale.
• gateway_timeout: gateway-ul și-a aplicat bugetul de latență și a încheiat solicitarea.
• rezolvat: gateway-ul a convertit utilizarea în costul locatarului și consumul de cotă.
• reconciliat: utilizarea ulterioară a furnizorului sau datele de cost confirmate sau ajustate rândul.

Acest model previne o eroare obișnuită de analiză: marcarea fiecărui flux care a produs text ca „reușit și exact”. Un flux poate fi util utilizatorului, incomplet de la furnizor, estimat pentru facturare și în așteptarea reconcilierii în același timp.

Câmpuri registru recomandate

Păstrați rândul din timpul solicitării mic, dar explicit:

{
  "request_id": "gw_req_...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "furnizor": "openai|antropic|gemeni|...",
  „provider_request_id”: nul,
  "model": "furnizor-model-id",
  "state": "acceptat",
  „stream”: adevărat,
  „input_tokens”: nul,
  „output_tokens_billed”: nul,
  „output_tokens_delivered_estimate”: 0,
  „provider_usage_source”: nul,
  "billing_status": "pending_reconciliation",
  „client_abort_at”: nul,
  „provider_completed_at”: nul,
  „settled_at”: nul,
  "error_class": nul
}

Separarea importantă este output_tokens_billed față de output_tokens_delivered_estimate. Utilizatorilor le pasă ce a ajuns la aplicația lor. Finanțelor îi pasă ce a facturat furnizorul. Aceste numere pot diferi după deconectări, fluxuri de apeluri de instrumente, jetoane de raționament ascunse, jetoane stocate în cache, opriri de siguranță sau expirări ale gateway-ului.

Reguli de captare specifice furnizorului

O API compatibilă cu OpenAI neutră pentru furnizor este utilă pentru dezvoltatorii de aplicații, dar adaptorul de gateway are încă nevoie de reguli de contabilitate specifice furnizorului.

Streaming compatibil cu OpenAI

Pentru rutele OpenAI, expuneți o opțiune de gateway care permite raportarea utilizării în amonte acolo unde este acceptată. Un model obișnuit este de a accepta o valoare implicită la nivel de gateway, cum ar fi:

{
  „stream”: adevărat,
  „stream_options”: {
    „include_usage”: adevărat
  }
}

Dacă apelantul din aval îl omite, gateway-ul poate decide dacă îl injectează pentru rutele în care acest lucru este compatibil. Documentați acest comportament, deoarece unii clienți se așteaptă la compatibilitate exactă a cablurilor și este posibil ca unele modele sau versiuni în amonte să nu accepte utilizarea finală în același mod.

Recomandare: nu decontați costul locatarului din primele părți. Păstrați deschis rândul registrului până când evenimentul final de utilizare este capturat, răspunsul furnizorului se încheie fără utilizare sau fluxul intră într-o cale de eroare sau de anulare.

Streaming antropic

Folosirea cumulativă a lui Anthropic necesită o regulă diferită. Dacă un gateway vede trei evenimente message_delta cu un număr de jetoane de ieșire de 10, 25 și 40, numărul de ieșire este 40, nu 75.

let latestUsage = null;
pentru așteptare (const event of anthropicStream) {
  if (event.type === „message_delta” && event.usage) {
    if (latestUsage && event.usage.output_tokens < latestUsage.output_tokens) {
      emit("utilizare_cumulativă_regresată", requestId);
    }
    latestUsage = eveniment.utilizare;
  }
  forwardToClient(eveniment);
}
settleFromLatestCumulativeUsage(latestUsage);

Recomandare: înregistrați cea mai recentă valoare de utilizare cumulată și emiteți un eveniment de observabilitate dacă regresează. O regresie poate indica erori ale analizorului, evenimente duplicate, modificări ale furnizorului sau fluxuri mixte.

Streaming în stil Gemeni și Vertex

Gemini acceptă bucăți de streaming pentru a reduce latența percepută. În SDK-urile în stil Vertex, fluxul poate expune atât un flux asincron, cât și un obiect de răspuns agregat. Un gateway ar trebui să păstreze acea cale agregată atunci când este disponibilă.

const streamingResult = await model.generateContentStream(request);
pentru așteptare (porțiune constantă din streamingResult.stream) {
  înainteChunk(bucătură);
  countDeliveredBytesOrText(bucătură);
}
const aggregated = await streamingResult.response;
settleFromAggregatedUsage(agregat);

Recomandare: evitați să construiți toată contabilitatea din bucăți vizibile dacă SDK-ul oferă o înregistrare completă a răspunsurilor. Bucățile sunt pentru latență. Obiectul final este adesea mai bun pentru facturare și analiză.

Tratați deconectările clienților ca evenimente contabile de primă clasă

Deconectarea clienților este locul în care multe gateway-uri pierd bani sau supraîncărcă clienții. O filă de browser se închide, o rețea mobilă se retrage sau o aplicație anulează o solicitare. Gateway-ul observă că priza din aval este închisă, dar furnizorul din amonte poate genera în continuare.

Poarta de acces ar trebui să facă o alegere explicită de politică:

• Anulați imediat în amonte: reduce pierderea generației și costul furnizorului, dar poate întrerupe fluxurile de lucru în care backend-ul încă mai are nevoie de rezultat după deconectarea interfeței de utilizare.
• Continuați în amonte în fundal: poate păstra munca pentru consumatorii de pe server, dar este posibil ca utilizatorul să nu vadă toate indicativele generate și facturate.
• Comportament dependent de rută: anulați pentru chat interactiv, continuați pentru fluxuri de lucru asemănătoare unui job și faceți setarea vizibilă pentru chiriași.

O prestabilită practică pentru streaming interactiv este anularea în amonte atunci când clientul din aval se deconectează, apoi marcați rândul registrului ca client_aborted. Dacă folosirea finală ajunge în timpul anulării, achitați din acea utilizare autorizată. Dacă nu, marcați rândul estimated sau pending_reconciliation în loc să pretindeți că este exact.

downstream.on(„close”, async () => {
  dacă (!providerCompleted) {
    ledger.markClientAborted(requestId);
    așteaptă în amonte.abort().catch(() => {
      ledger.emit("upstream_cancel_failed", requestId);
    });
  }
});

Recomandare: expuneți etichete transparente de facturare, cum ar fi final, provider_reconciled, estimated, waived sau pending_reconciliation. Acest lucru este mai susceptibil de a arăta fiecare apel transmis în flux ca fiind imediat exact.

Aplicarea cotelor în timpul unui flux

Facturarea precisă depinde de obicei de utilizarea finală a furnizorului, dar aplicarea cotelor nu poate aștepta întotdeauna până la sfârșit. Un chiriaș cu un buget greu nu ar trebui să aibă voie să transmită în flux la nesfârșit, deoarece utilizarea exactă nu este disponibilă în timpul zborului.

Utilizați împreună două mecanisme:

1. Rezervare preflight: rezervați un maxim estimat pe baza modelului, a indicativelor maxime solicitate, a politicii locatarilor și a soldului actual.
2. Verificări ale presiunii în flux: estimați rezultatul livrat în timpul fluxului și opriți dacă solicitarea depășește o limită de siguranță configurată.

Acesta este un mecanism de control, nu factura finală. Furnizorii pot număra jetoane stocate în cache, jetoane de raționament, jetoane multimodale sau jetoane ascunse în mod diferit față de estimatorul unui gateway.

Compartiment: estimările în timp real ajută la aplicarea bugetelor, dar ele pot diferi de tokenurile facturate de furnizor. Decontarea finală ar trebui să utilizeze utilizarea autorizată a furnizorului atunci când este disponibilă, iar reconcilierea ar trebui să ajusteze estimările mai târziu.

Evenimente de observabilitate care detectează erori contabile

Eșecurile de facturare în flux sunt mai ușor de depanat atunci când gateway-ul emite evenimente vizate în loc de doar jurnalele de solicitări generice. Adăugați evenimente precum:

• final_usage_missing: fluxul s-a încheiat fără utilizare autorizată.
• cumulative_usage_regressed: numărul cumulativ de jetoane a fost mutat înapoi.
• stream_ended_without_stop_event: nu a fost observat niciun marcator normal de oprire a furnizorului.
• aborted_after_provider_completion: furnizorul a finalizat, dar clientul din aval sa închis înainte ca gateway-ul să termine redirecționarea.
• settled_from_estimate: registrul locatarului a folosit o estimare deoarece utilizarea finală nu a fost disponibilă.
• reconciliation_adjusted_usage: raportarea furnizorului a schimbat ulterior rândul.

Realitate: convențiile semantice OpenTelemetry GenAI recomandă utilizarea informațiilor de utilizare returnate de furnizor pentru răspunsurile transmise în flux, atunci când sunt disponibile, și avertizează împotriva raportării valorilor de utilizare în cazul în care numărul de simboluri nu poate fi obținut în mod eficient sau precis.

Pentru analitica utilizării AI, aceasta înseamnă că tablourile de bord ar trebui să accepte niveluri de încredere. Un grafic care combină valorile finale, estimate și reconciliate fără etichete poate părea curat, dar poate induce în eroare echipele de finanțare și asistență.

Teste de conformitate pentru contabilitatea în flux

Nu vă bazați pe testarea manuală cu o solicitare de chat cu calea fericită. Fiecare adaptor de furnizor ar trebui să aibă teste de conformitate pentru cazurile care încalcă registrele:

• Flux normal: sosește utilizarea finală, evenimentul de oprire a fost observat, registrul se stabilește ca final.
• Flux de apeluri de instrumente: deltele apelurilor de instrumente sunt redirecționate, utilizarea este capturată, metadatele structurate nu corupă numărarea simbolurilor.
• Oprire de siguranță sau refuz: furnizorul se oprește mai devreme, utilizarea încă se stabilește corect.
• Deconectarea forțată a clientului: în aval se închide după o ieșire parțială; în amonte este anulat sau continuat conform politicii.
• Amonte 5xx după ieșire parțială: gateway-ul înregistrează livrarea parțială și nu marchează solicitarea ca fiind un succes complet.
• Timpul expirat pentru gateway înainte de utilizarea finală: rândul devine estimat sau în așteptarea reconcilierii.
• Eveniment final lipsă: adaptorul emite final_usage_missing și evită etichetele exacte de facturare.

Aceste teste ar trebui să afirme tranzițiile de stare, câmpurile registrului, evenimentele de observabilitate emise și comportamentul în aval. Compatibilitatea fluxului octet pentru octet nu este suficientă; efectele secundare contabile fac parte din contract.

Lista de verificare practică a implementării

• Creați rândul registrului de utilizare înainte de a trimite solicitarea în amonte.
• Păstrați locatari, cheie, utilizator, model, rută, furnizor și identificatori de solicitare la momentul solicitării.
• Activați raportarea utilizării finale a furnizorului acolo unde este acceptată, cum ar fi stream_options.include_usage compatibil cu OpenAI.
• Pentru furnizorii cumulați, stocați cea mai recentă valoare de utilizare în loc să însumați evenimentele.
• Păstrați obiectele de răspuns agregate atunci când SDK-urile le furnizează.
• Urmăriți rezultatul livrat separat de utilizarea facturată de furnizor.
• La deconectare, anulați în amonte conform politicii de rută și marcați client_aborted.
• Utilizați stări transparente de facturare: finală, estimată, în așteptarea reconcilierii, reconciliată de furnizor sau renunțată.
• Emite evenimente de observabilitate specifice contabilității.
• Reconciliați mai târziu cu rapoartele privind utilizarea furnizorului sau costurile, atunci când sunt disponibile, păstrând în același timp atribuirea chiriașului la momentul solicitării.

Ce să le arătăți chiriașilor

Chiriașii nu au nevoie de fiecare eveniment intern, dar au nevoie de etichete sincere. Un tabel util de utilizare poate afișa:

• Stare: finală, estimată sau reconciliată.
• Rezultatul solicitării: finalizată, client anulat, eroare de furnizor sau expirare a gateway-ului.
• Ieșire livrată: text aproximativ sau octeți trimiși către client.
• Jetoane facturate: utilizare normalizată de furnizor folosită pentru cost.
• Ajustare: orice deltă de reconciliere ulterioară.

Acest design reduce ambiguitatea suportului. Dacă un utilizator a văzut doar o parte a unui răspuns, tabloul de bord poate explica dacă furnizorul a finalizat deja, dacă gateway-ul a fost anulat în amonte și dacă taxa este finală sau estimată.

Recomandări versus predicții

Recomandări: tratați cererile transmise în flux ca mașini de stat, așteptați utilizarea finală autorizată înainte de decontarea exactă, separați rezultatul livrat de utilizarea facturată și etichetați cu onestitate rândurile estimate. Adaptoarele de furnizor ar trebui să codifice semantica de utilizare specifică furnizorului, mai degrabă decât să aplatizeze fiecare flux într-un proxy generic de octeți.

Predicție: contabilitatea în flux va deveni mai importantă pe măsură ce modelele expun mai multe lucrări ascunse: jetoane de raționament, reduceri de jetoane stocate în cache, procesare multimodală, urme de utilizare a instrumentelor și opriri de siguranță. Gateway-urile care separă deja utilizarea facturată de furnizor de rezultatul vizibil de client se vor adapta mai ușor decât gateway-urile care contorizează doar textul transmis în flux.

Concluzie acționabilă

Dacă gateway-ul dvs. acceptă streaming, auditați o singură cale astăzi: forțați deconectarea unui client după primele câteva bucăți și inspectați rândul registrului. Dacă scrie „succes” cu un număr de simboluri exacte, probabil că statisticile dvs. mint.

Remedierea este să nu abandonați fluxul. Păstrați experiența rapidă a utilizatorului, dar faceți ca finalizarea fluxului, anularea, erorile furnizorului, lipsa utilizării finale și reconcilierea stărilor contabile explicite. Acest lucru oferă echipelor de produse rezultate receptive, costuri susținute echipelor financiare și echipelor de asistență suficiente dovezi pentru a explica răspunsurile parțiale fără a ghici.

Lectură similară

• uniunea urmelor, registrelor de jetoane și analizelor de utilizare în siguranță
• constructia unui contract de compatibilitate gateway compatibil OpenAI