Token könyvelés streamelése AI API-átjáróban: végső használat, törlések és részleges válaszok

A streaming LLM-válaszokat könnyű proxyzni, és nehéz helyesen számlázni. Ha egy AI API-átjáró továbbítja a szerver által küldött eseményeket az ügyfélnek, de az első darabokat használati rekordként kezeli, a bérlői elemzések eltolódnak. Az elsodródás általában olyan vitákban jelentkezik, mint például: „a felhasználó csak a válasz felét látta”, „a szolgáltató többet számlázott, mint amennyit az irányítópulton mutat”, „a kvóta túl korán lett felszabadítva” vagy „az időtúllépés tokeneket hozott létre, de nincs számlasor”.

Az alapvető probléma az, hogy a streamelt hívások nem egy eseményt jelentenek. Ezek egy sorozat: kérés elfogadva, upstream adatfolyam megnyitása, bájtok kézbesítése, végső felhasználás jelentése, szolgáltató leállítása, ügyfél lekapcsolva, az átjáró időtúllépése és a számlázás rendezve. Egy megbízható átjárónak kifejezetten modelleznie kell ezeket az állapotokat ahelyett, hogy azt feltételezné, hogy a befejezett HTTP-válasz az egyetlen sikeres útvonal.

A hibamód: a streaming elrejti a könyvelési határt

A nem adatfolyamos befejezések általában egy válaszobjektumot adnak vissza használati metaadatokkal. Egy átjáró egy lépésben normalizálhatja a használatot, írhat egy főkönyvi sort, frissítheti a kvótát, és elemzéseket bocsáthat ki.

A streamelés megváltoztatja a határt. A felhasználói élmény növekményes, de a számlázási igazság megérkezhet a végén, egy szolgáltató-specifikus végső eseményben, egy kumulatív deltában, egy összesített SDK-válaszon keresztül, vagy később a szolgáltatói jelentéskészítő API-kon keresztül. Ha az ügyfél a végső használati esemény előtt megszakad, előfordulhat, hogy az átjáró csak a válasz egy részét kézbesítette, miközben a szolgáltató még további tokeneket generált és számlázott.

Tény: Az OpenAI dokumentumok azt mutatják, hogy a streaming hívóknak, akik használati adatokat szeretnének, be kell állítaniuk a stream_options paramétert az include_usage paraméterrel. Az OpenAI szervezeti szintű használati és költségvégpontokat is biztosít, ugyanakkor megjegyzi, hogy a felhasználás és a költségek nem mindig egyeztethetők össze tökéletesen pénzügyi célokra.

Tény: Az antropikus streamelés szerver által küldött eseményeket használ, például message_start, content_block_delta, message_delta és message_stop. A message_delta használati információi kumulatívak, így egy átjáró nem adhatja össze az egyes használati delta-értékeket.

Tény: A Gemini és Vertex stílusú streaming API-k növekményes darabokat jeleníthetnek meg, míg az SDK-k összesített válaszobjektumot is biztosíthatnak. Átjárók esetében ez az összesített útvonal jobb forrás lehet a teljes használathoz, mint a látható darabok önmagukban.

Használjon adatfolyam állapotú gépet, ne logikai sikerjelzőt

A streamelt kérésnek tartós használati rekorddal kell rendelkeznie az upstream hívás megkezdése előtt. Ennek a rekordnak explicit állapotokon kell haladnia. Gyakorlati minimum:

• elfogadva: az átjáró hitelesítette a kulcsot, hozzárendelte a bérlőt, és nyitott főkönyvi sort hozott létre.
• first_byte_sent: legalább egy kimeneti esemény elérte a downstream klienst.
• provider_completed: az upstream szolgáltató normál leállítási jelet bocsátott ki, vagy befejezett válaszobjektumot.
• client_aborted: a downstream socket az átjáró normál befejezése előtt bezárult.
• provider_error: az upstream szolgáltató hibát adott vissza az adatfolyam megkezdése után vagy a végső használat megérkezése előtt.
• gateway_timeout: az átjáró kényszerítette a késleltetési költségkeretét, és befejezte a kérést.
• kiegyenlített: az átjáró a használatot bérlői költséggé és kvótafelhasználássá alakította át.
• egyeztetve: a későbbi szolgáltatói használati vagy költségadatok megerősítették vagy módosították a sort.

Ez a modell megakadályozza az általános elemzési hibát: minden szöveget létrehozó adatfolyamot „sikeresnek és pontosnak” jelöl meg. Egy adatfolyam hasznos lehet a felhasználó számára, hiányos a szolgáltatótól, becsült számlázásra számíthat, és egyidejűleg egyeztetésre vár.

Ajánlott főkönyvi mezők

A kérés ideje sor legyen kicsi, de egyértelmű:

{
  "request_id": "gw_req_...",
  "bérlő_azonosítója": "bérlő_123",
  "api_key_id": "key_456",
  "szolgáltató": "openai|anthropic|gemini|...",
  "provider_request_id": null,
  "modell": "szolgáltató-modell-azonosító",
  "state": "elfogadva",
  "folyam": igaz,
  "input_tokens": null,
  "output_tokens_billed": null,
  "output_tokens_delivered_estimate": 0,
  "provider_usage_source": null,
  "billing_status": "pending_conciliation",
  "client_abort_at": null,
  "provider_completed_at": null,
  "setled_at": null,
  "error_class": null
}

A fontos elválasztás az output_tokens_billed és az output_tokens_delivered_estimate. A felhasználókat érdekli, hogy mi jutott el az alkalmazásukhoz. A pénzügyeket érdekli, hogy a szolgáltató mit számlázott. Ezek a számok eltérhetnek a kapcsolat megszakítása, az eszközhívási adatfolyamok, a rejtett érvelési tokenek, a gyorsítótárazott tokenek, a biztonsági leállások vagy az átjáró időtúllépései után.

Szolgáltatóspecifikus rögzítési szabályok

A szolgáltató-semleges OpenAI-kompatibilis API hasznos az alkalmazásfejlesztők számára, de az átjáróadapternek továbbra is szolgáltató-specifikus elszámolási szabályokra van szüksége.

OpenAI-kompatibilis streamelés

OpenAI útvonalak esetén tegyen közzé egy átjáró-beállítást, amely lehetővé teszi az upstream használati jelentéseket, ahol ez támogatott. Gyakori példa az átjárószintű alapértelmezett beállítások elfogadása, például:

{
  "folyam": igaz,
  "stream_options": {
    "include_usage": igaz
  }
}

Ha a későbbi hívó kihagyja, az átjáró eldöntheti, hogy beadja-e az olyan útvonalakra, ahol ez kompatibilis. Dokumentálja ezt a viselkedést, mert egyes kliensek pontos vezeték-kompatibilitást várnak el, és előfordulhat, hogy egyes modellek vagy upstream modellek nem támogatják ugyanúgy a végső felhasználást.

Javaslat: ne rendezze a bérlői költségeket korai részekből. Tartsa nyitva a főkönyvi sort mindaddig, amíg a végső használati eseményt rögzítik, a szolgáltatói válasz használat nélkül le nem fejeződik, vagy az adatfolyam hibába vagy törlési útvonalba nem lép.

Antropikus közvetítés

Az Anthropic kumulatív használatához más szabályra van szükség. Ha egy átjáró három message_delta eseményt lát 10, 25 és 40 kimeneti tokenekkel, akkor a kimeneti szám 40, nem pedig 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("kumulatív_használat_visszafejlődött", requestId);
    }
    latestUsage = event.usage;
  }
  forwardToClient(esemény);
}
setttleFromLatestCumulativeUsage(latestUsage);

Javaslat: Rögzítse a legutóbbi összesített használati értéket, és adjon ki megfigyelhetőségi eseményt, ha az visszafejlődik. A regresszió az elemző hibáit, az ismétlődő eseményeket, a szolgáltató változásait vagy a vegyes adatfolyamokat jelezheti.

Gemini és Vertex stílusú streaming

A Gemini támogatja a streaming-darabokat az észlelt késleltetés csökkentése érdekében. A Vertex-stílusú SDK-kban a streaming egy aszinkron adatfolyamot és egy összesített válaszobjektumot is megjeleníthet. Az átjárónak meg kell őriznie ezt az összesített elérési utat, ha elérhető.

const streamingResult = várakozás model.generateContentStream(request);
for await (const chunk of streamingResult.stream) {
  előreChunk(darab);
  countDeliveredBytesOrText(chunk);
}
const aggregated = várja a streamingResult.response-t;
setttleFromAggregatedUsage(aggregated);

Javaslat: ha az SDK kitöltött válaszrekordot ad, ne állítsa össze az összes elszámolást látható darabokból. A darabok a késleltetést szolgálják. A végső objektum gyakran jobb a számlázáshoz és az elemzéshez.

Az ügyfél-lekapcsolások első osztályú könyvelési eseményként kezelése

Az ügyfélkapcsolat megszakítása az a hely, ahol sok átjáró pénzt veszít, vagy túlterheli az ügyfeleket. Egy böngészőlap bezárul, a mobilhálózat leáll, vagy egy alkalmazás visszavon egy kérést. Az átjáró észreveszi, hogy a downstream socket zárva van, de a felfelé irányuló szolgáltató továbbra is generál.

Az átjárónak konkrét irányelvet kell választania:

• Azonnali lemondás: csökkenti az elpazarolt előállítási és szolgáltatói költségeket, de megszakíthatja azokat a munkafolyamatokat, ahol a háttérrendszernek a felhasználói felület leválasztása után is szüksége van az eredményre.
• Folytatás felfelé a háttérben: megőrizheti a szerveroldali fogyasztók munkáját, de előfordulhat, hogy a felhasználó nem látja az összes generált és számlázott tokent.
• Útvonalfüggő viselkedés: mégse az interaktív csevegés esetén, folytassa a munkafolyamatokhoz hasonló munkát, és tegye láthatóvá a beállítást a bérlők számára.

Az interaktív streamelés gyakorlati alapértelmezése az upstream szolgáltatás törlése, amikor a downstream kliens megszakad, majd a főkönyvi sort client_aborted-ként jelöli meg. Ha a végső felhasználás a lemondás során érkezik meg, akkor a mérvadó felhasználásból számoljon el. Ha nem, jelölje be a becsült vagy a pending_conciliation sort ahelyett, hogy pontosnak tenné.

downstream.on("close", async () => {
  if (!providerCompleted) {
    főkönyv.markClientAborted(requestId);
    várjon upstream.abort().catch(() => {
      főkönyv.emit("upstream_cancel_failed", requestId);
    });
  }
});

Javaslat: tegye közzé az átlátható számlázási címkéket, például a final, a provider_reconciled, a becsült, a elhagyott vagy a pending_conciliation. Ez jobban védhető, mintha minden streamelt hívást azonnal pontosnak mutatnánk.

A kvóta betartatása adatfolyam közben

A pontos számlázás általában a végső szolgáltató használatától függ, de a kvóta betartatása nem mindig várhat a végére. A kemény költségvetésű bérlőnek nem szabad megengedni, hogy a végtelenségig streameljen, mert a pontos használat nem érhető el menet közben.

Használjon együtt két mechanizmust:

1. Futtatás előtti foglalás: foglaljon le egy becsült maximumot a modell, a kért maximális tokenek, a bérlői szabályzat és az aktuális egyenleg alapján.
2. Streamelési nyomásellenőrzések: az adatfolyam során leadott kimenet becslése, és leállítás, ha a kérés átlép egy konfigurált biztonsági határt.

Ez egy ellenőrzési mechanizmus, nem a végső számla. A szolgáltatók a gyorsítótárazott tokeneket, az érvelési tokeneket, a multimodális tokeneket vagy a rejtett tokeneket az átjáró becslésétől eltérően számolhatják.

Kiváltás: A valós idejű becslések segítik a költségkeretek érvényesítését, de eltérhetnek a szolgáltató által számlázott tokenektől. A végső elszámolásnál a mérvadó szolgáltatói felhasználást kell alkalmazni, ha lehetséges, az egyeztetésnek pedig később módosítania kell a becsléseket.

A könyvelési hibákat észlelő megfigyelési események

A streamelési számlázási hibák könnyebben háríthatók el, ha az átjáró célzott eseményeket bocsát ki az általános kérésnaplók helyett. Adjon hozzá eseményeket, például:

• final_usage_missing: az adatfolyam hiteles használat nélkül fejeződött be.
• cumulative_usage_regressed: az összesített tokenszám visszafelé került.
• stream_ended_without_stop_event: nem figyeltek meg normál szolgáltatói leállásjelzőt.
• aborted_after_provider_completion: a szolgáltató befejezte, de a downstream kliens bezárt, mielőtt az átjáró befejezte a továbbítást.
• settled_from_estimate: a bérlői főkönyv becslést használt, mert a végső felhasználás nem volt elérhető.
• reconciliation_adjusted_usage: a szolgáltató jelentése később módosította a sort.

Tény: Az OpenTelemetry GenAI szemantikai konvenciói azt javasolják, hogy a szolgáltatók által visszaküldött használati információkat használja a streamelési válaszokhoz, ha rendelkezésre áll, és figyelmeztet a használati mutatók jelentésére, ha a tokenszámok nem szerezhetők be hatékonyan vagy pontosan.

Az AI-használati elemzések esetében ez azt jelenti, hogy az irányítópultoknak támogatniuk kell a megbízhatósági szinteket. A végső, becsült és egyeztetett értékeket címkék nélkül keverő diagram tisztanak tűnhet, de félrevezetheti a pénzügyi és támogató csapatokat.

Megfelelőségi tesztek a streaming elszámoláshoz

Ne hagyatkozzon a kézi tesztelésre egy boldog út csevegési üzenettel. Minden szolgáltatói adapternek rendelkeznie kell megfelelőségi tesztekkel a főkönyveket megszakító esetekre:

• Normál adatfolyam: a végső használat megérkezik, leállási esemény megfigyelhető, a főkönyv végsőként rendeződik.
• Eszközhívás adatfolyam: az eszközhívás-delták továbbításra kerülnek, a használat rögzítésre kerül, a strukturált metaadatok nem rontják a tokenszámlálást.
• Biztonsági vagy elutasítási leállás: a szolgáltató korán leáll, a használat továbbra is megfelelően rendeződik.
• Kényszerített kliens leválasztás: a downstream bezár a részleges kimenet után; upstream törlik vagy folytatódik a szabályzatnak megfelelően.
• Upstream 5xx részleges kimenet után: az átjáró rögzíti a részleges kézbesítést, és nem jelöli meg a kérést sikeresnek.
• Az átjáró időtúllépése a végső használat előtt: a sor becsült lesz, vagy egyeztetésre vár.
• Hiányzó végső esemény: az adapter final_usage_missing üzenetet bocsát ki, és elkerüli a pontos számlázási címkéket.

Ezeknek a teszteknek az állapotátmeneteket, a főkönyvi mezőket, a kibocsátott megfigyelési eseményeket és a lefelé irányuló viselkedést kell érvényesíteniük. A byte-on-byte adatfolyam-kompatibilitás nem elegendő; a könyvelési mellékhatások a szerződés részét képezik.

Gyakorlati megvalósítási ellenőrzőlista

• A felfelé irányuló kérelem elküldése előtt hozza létre a használati főkönyvi sort.
• A kérés időpontjában tárolja a bérlő, kulcs, felhasználó, modell, útvonal, szolgáltató és kérés azonosítóit.
• Ahol támogatott, engedélyezze a szolgáltató végső használati jelentését, például OpenAI-kompatibilis stream_options.include_usage.
• Az összesített szolgáltatók esetében az események összegzése helyett a legfrissebb használati értéket tárolja.
• Megőrzi az összesített válaszobjektumokat, ha az SDK-k biztosítják őket.
• A szállított kimenet nyomon követése a szolgáltató által számlázott használattól elkülönítve.
• Kapcsolatbontáskor törölje az upstream szolgáltatást az útvonalszabályzatnak megfelelően, és jelölje be a client_aborted lehetőséget.
• Használjon átlátható számlázási állapotokat: végleges, becsült, egyeztetésre váró, szolgáltató egyeztetve vagy lemondva.
• Számvitel-specifikus megfigyelési eseményeket bocsát ki.
• Később egyeztetheti a szolgáltatói használati vagy költségjelentésekkel, ha rendelkezésre állnak, miközben megőrzi a kérésidő-bérlői hozzárendelést.

Mit kell megjeleníteni a bérlőknek

A bérlőknek nincs szükségük minden belső eseményre, de őszinte címkékre igen. Egy hasznos használati táblázat a következőket jelenítheti meg:

• Állapot: végleges, becsült vagy egyeztetett.
• Kérés eredménye: befejezve, az ügyfél megszakadt, szolgáltatói hiba vagy az átjáró időtúllépése.
• Kézbesített kimenet: az ügyfélnek küldött hozzávetőleges szöveg vagy bájtok.
• Számlázott tokenek: a szolgáltató által normalizált használat a költségekhez.
• Korrekció: bármely későbbi egyeztetési delta.

Ez a kialakítás csökkenti a támogatás kétértelműségét. Ha a felhasználó a válasznak csak egy részét látta, az irányítópult meg tudja magyarázni, hogy a szolgáltató befejezte-e már, hogy az átjárót törölték-e, és hogy a terhelés végleges vagy becsült.

Ajánlások versus előrejelzések

Javaslatok: kezelje a streamelt kéréseket állapotgépként, várja meg a mérvadó végső felhasználást a pontos elszámolás előtt, válassza el a kézbesített kimenetet a számlázott használattól, és becsülje fel a becsült sorokat őszintén. A szolgáltatói adaptereknek szolgáltató-specifikus használati szemantikát kell kódolniuk, ahelyett, hogy minden adatfolyamot egy általános bájtproxyba lapítanának.

Előrejelzés: A streamelési elszámolás egyre fontosabb lesz, mivel a modellek több rejtett munkát tesznek közzé: érvelési tokenek, gyorsítótárazott token kedvezmények, multimodális feldolgozás, szerszámhasználati nyomok és biztonsági leállítások. Azok az átjárók, amelyek már elválasztják a szolgáltató által számlázott használatot az ügyfél által látható kimenettől, könnyebben alkalmazkodnak, mint azok az átjárók, amelyek csak a streamelt szöveget számolják.

Intézhető következtetés

Ha az átjárója támogatja az adatfolyamot, ellenőrizze az egyik útvonalat még ma: kényszerítse az ügyfél leválasztását az első néhány darab után, és ellenőrizze a főkönyvi sort. Ha azt írja ki, hogy „siker” pontosnak látszó tokenszámmal, akkor az elemzése valószínűleg hazudik.

A megoldás az, hogy nem hagyjuk fel a streamelést. Tartsa meg a gyors felhasználói élményt, de tegye explicit elszámolási állapotba a streamelés befejezését, törlését, szolgáltatói hibáit, hiányzó végső felhasználást és egyeztetést. Ez a termékcsapatok számára reagáló teljesítményt, a finanszírozó csapatoknak védhető költségeket, a támogató csapatoknak pedig elegendő bizonyítékot biztosít a részleges válaszok találgatások nélküli magyarázatához.

Kapcsolódó olvasmány

• a modell hátterében hívja a
• csatlakozási nyomokat, token főkönyveket és biztonságos használat elemzését
OpenAI-kompatibilis átjáró kompatibilitási szerződés készítése