Transmissió de la comptabilitat de testimonis en una passarel·la de l'API AI: ús final, cancel·lacions i respostes parcials

Les respostes de LLM en temps real són fàcils de representar i són difícils de facturar correctament. Si una gateway d'API AI reenvia els esdeveniments enviats pel servidor al client, però tracta els primers fragments com el registre d'ús, l'anàlisi dels inquilins es desviarà. La deriva sol aparèixer en disputes com ara: "l'usuari només va veure la meitat de la resposta", "el proveïdor va facturar més del que mostra el nostre tauler", "la quota es va alliberar massa aviat" o "un temps d'espera va produir fitxes però no hi ha cap línia de factura".

El problema d'arrel és que les trucades en streaming no són un esdeveniment. Són una seqüència: sol·licitud acceptada, flux amunt obert, bytes lliurats, ús final informat, proveïdor aturat, client desconnectat, passarel·la esgotada i facturació liquidada. Una passarel·la fiable hauria de modelar aquests estats de manera explícita en lloc de suposar que una resposta HTTP completa és l'únic camí d'èxit.

El mode d'error: la transmissió en temps real amaga el límit de la comptabilitat

Les finalitzacions no reproduïdes normalment retornen un objecte de resposta amb metadades d'ús. Una passarel·la pot normalitzar aquest ús, escriure una fila del llibre major, actualitzar la quota i emetre analítiques en una sola passada.

La reproducció en temps real canvia el límit. L'experiència de l'usuari és incremental, però la veritat de la facturació pot arribar al final, en un esdeveniment final específic del proveïdor, en un delta acumulat, mitjançant una resposta SDK agregada o més tard mitjançant API d'informes del proveïdor. Si el client es desconnecta abans de l'esdeveniment d'ús final, és possible que la passarel·la només hagi lliurat una part de la resposta mentre el proveïdor encara generava i facturava més fitxes.

Fet: OpenAI documenta que les persones que fan una trucada en temps real que volen dades d'ús haurien d'establir stream_options amb include_usage. OpenAI també proporciona punts finals d'ús i costos a nivell d'organització, tot i que assenyala que l'ús i els costos poden no sempre conciliar-se perfectament amb finalitats financeres.

Fet: la transmissió antròpica utilitza esdeveniments enviats pel servidor com ara message_start, content_block_delta, message_delta i message_stop. La seva informació d'ús message_delta és acumulativa, de manera que una passarel·la no ha d'afegir cada delta d'ús.

Fet: les API de reproducció d'estil Gemini i Vertex poden exposar fragments incrementals, mentre que els SDK també poden proporcionar un objecte de resposta agregada. Per a les passarel·les, aquest camí agregat pot ser una millor font per a l'ús completat que només els fragments visibles.

Utilitzeu una màquina d'estat de flux, no un senyal d'èxit booleà

Una sol·licitud transmesa ha de tenir un registre d'ús durador abans que comenci la trucada amunt. Aquest registre hauria de passar per estats explícits. Un mínim pràctic és:

• acceptat: la passarel·la ha autenticat la clau, ha atribuït l'inquilí i ha creat una fila del llibre major oberta.
• first_byte_sent: almenys un esdeveniment de sortida ha arribat al client avall.
• provider_completed: el proveïdor aigües amunt va emetre un senyal d'aturada normal o un objecte de resposta completat.
• client_aborted: el sòcol aigües avall es va tancar abans de la finalització normal de la passarel·la.
• provider_error: el proveïdor amunt ha retornat un error després de començar el flux o abans que arribés l'ús final.
• gateway_timeout: la passarel·la ha aplicat el seu pressupost de latència i ha finalitzat la sol·licitud.
• resolut: la passarel·la va convertir l'ús en cost de l'arrendatari i en consum de quota.
• conciliat: ús posterior del proveïdor o dades de cost confirmades o ajustades a la fila.

Aquest model evita un error d'anàlisi comú: marcar tots els fluxos que han produït text com a "èxit i exacte". Un flux pot ser útil per a l'usuari, incomplet del proveïdor, estimat per a la facturació i pendent de conciliació alhora.

Camps del llibre major recomanats

Mantingueu la fila del temps de sol·licitud petita però explícita:

{
  "request_id": "gw_req_...",
  "tenant_id": "arrendatari_123",
  "api_key_id": "key_456",
  "proveïdor": "openai|anthropic|gemini|...",
  "provider_request_id": nul,
  "model": "id-model-proveïdor",
  "state": "acceptat",
  "stream": cert,
  "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,
  "classe_error": nul
}

La separació important és output_tokens_billed versus output_tokens_delivered_estimate. Els usuaris els importa què ha arribat a la seva aplicació. A les finances li importa el que va facturar el proveïdor. Aquests números poden variar després de les desconnexions, els fluxos de trucades d'eines, els testimonis de raonament ocults, els testimonis en memòria cau, les parades de seguretat o els temps d'espera de la passarel·la.

Regles de captura específiques del proveïdor

Una API compatible amb OpenAI neutral per al proveïdor és útil per als desenvolupadors d'aplicacions, però l'adaptador de passarel·la encara necessita regles de comptabilitat específiques del proveïdor.

Transmissió en temps real compatible amb OpenAI

Per a les rutes d'OpenAI, exposa una opció de passarel·la que permeti els informes d'ús amunt quan sigui compatible. Un patró comú és acceptar un valor predeterminat a nivell de passarel·la com ara:

{
  "stream": cert,
  "stream_options": {
    "include_usage": cert
  }
}

Si la persona que truca aigües avall l'omet, la passarel·la pot decidir si l'injecta per a rutes on fer-ho sigui compatible. Documenteu aquest comportament perquè alguns clients esperen una compatibilitat exacta de cables i alguns models o aigües amunt poden no admetre l'ús final de la mateixa manera.

Recomanació: no pagueu el cost de l'arrendatari des de les primeres parts. Manteniu oberta la fila del llibre major fins que es capture l'esdeveniment d'ús final, la resposta del proveïdor acabi sense utilitzar-la o el flux introdueix un error o un camí de cancel·lació.

Transmissió antròpica

L'ús acumulat d'Anthropic requereix una regla diferent. Si una passarel·la veu tres esdeveniments message_delta amb un nombre de testimonis de sortida de 10, 25 i 40, el nombre de sortida és 40, no 75.

let latestUsage = null;
per await (esdeveniment constant de anthropicStream) {
  if (event.type === "message_delta" && event.usage) {
    if (latestUsage && event.usage.output_tokens < latestUsage.output_tokens) {
      emit("ús_acumulatiu_regressat", requestId);
    }
    latestUsage = event.usage;
  }
  forwardToClient(esdeveniment);
}
settleFromLatestCumulativeUsage(latestUsage);

Recomanació: enregistreu l'últim valor d'ús acumulat i emeteu un esdeveniment d'observabilitat si retrocedeix. Una regressió pot indicar errors d'analitzador, esdeveniments duplicats, canvis de proveïdor o fluxos mixts.

Transmissió en directe a l'estil Gemini i Vertex

Gemini admet fragments de transmissió per reduir la latència percebuda. Als SDK d'estil Vertex, la transmissió pot exposar tant un flux asíncron com un objecte de resposta agregada. Una passarel·la hauria de conservar aquesta ruta agregada quan estigui disponible.

const streamingResult = espere model.generateContentStream(request);
per esperar (const tros de streamingResult.stream) {
  forwardChunk(tros);
  countDeliveredBytesOrText(tros);
}
const aggregated = esperar streamingResult.response;
settleFromAggregatedUsage(agregat);

Recomanació: eviteu crear tota la comptabilitat a partir de fragments visibles si l'SDK dóna un registre de resposta completa. Els trossos són per a la latència. L'objecte final sovint és millor per a la facturació i l'anàlisi.

Gestiona les desconnexions del client com a esdeveniments comptables de primer nivell

Les desconnexions dels clients són on moltes passarel·les perden diners o cobren de més als clients. Es tanca una pestanya del navegador, una xarxa mòbil baixa o una aplicació cancel·la una sol·licitud. La passarel·la nota que el sòcol avall està tancat, però és possible que el proveïdor amunt encara estigui generant.

La passarel·la hauria de triar una política explícita:

• Cancel·la aigües amunt immediatament: redueix la generació malgastada i el cost del proveïdor, però pot trencar els fluxos de treball on el backend encara necessita el resultat després que la IU es desconnecti.
• Continua amunt en segon pla: pot conservar el treball dels consumidors del servidor, però és possible que l'usuari no vegi tots els testimonis generats i facturats.
• Comportament depenent de la ruta: cancel·leu el xat interactiu, continueu amb fluxos de treball semblants a una feina i feu que la configuració sigui visible per als inquilins.

Una predeterminada pràctica per a la transmissió interactiva és cancel·lar aigües amunt quan el client aigües avall es desconnecta i després marcar la fila del llibre major com a client_aborted. Si l'ús final arriba durant la cancel·lació, resol a partir d'aquest ús autoritzat. Si no, marqueu la fila estimated o pending_reconciliation en lloc de fingir que és exacta.

downstream.on("tancar", asincrònic () => {
  si (!providerCompleted) {
    ledger.markClientAborted(requestId);
    espereu amunt.abort().catch(() => {
      ledger.emit("downstream_cancel_failed", requestId);
    });
  }
});

Recomanació: exposa etiquetes de facturació transparents com ara final, provider_reconciled, estimated, waived o pending_reconciliation. Això és més defensable que mostrar totes les trucades retransmeses com a exactes immediatament.

Aplicació de quotes durant un flux

La facturació precisa normalment depèn de l'ús final del proveïdor, però l'aplicació de les quotes no sempre pot esperar fins al final. No s'ha de permetre que un inquilí amb un pressupost limitat pugui reproduir en temps real indefinidament perquè l'ús exacte no està disponible a la meitat del vol.

Utilitzeu dos mecanismes junts:

1. Reserva prèvia al vol: reserva un màxim estimat en funció del model, les fitxes màximes sol·licitades, la política d'inquilí i el saldo actual.
2. Comprovacions de pressió de transmissió: estimeu la sortida lliurada durant la transmissió i atureu-la si la sol·licitud traspassa un límit de seguretat configurat.

Aquest és un mecanisme de control, no la factura final. Els proveïdors poden comptar fitxes emmagatzemades a la memòria cau, fitxes de raonament, fitxes multimodals o fitxes ocultes de manera diferent a l'estimador d'una passarel·la.

Compartiment: les estimacions en temps real ajuden a fer complir els pressupostos, però poden diferir dels testimonis facturats pel proveïdor. La liquidació final hauria d'utilitzar l'ús autoritzat del proveïdor quan estigui disponible, i la conciliació hauria d'ajustar les estimacions més endavant.

Esdeveniments d'observabilitat que detecten errors de comptabilitat

Els errors de facturació en temps real són més fàcils de depurar quan la passarel·la emet esdeveniments orientats en comptes de només registres de sol·licituds genèrics. Afegeix esdeveniments com ara:

• final_usage_missing: el flux s'ha acabat sense ús autoritzat.
• cumulative_usage_regressed: el recompte acumulat de testimonis s'ha mogut cap enrere.
• stream_ended_without_stop_event: no s'ha observat cap marcador normal d'aturada del proveïdor.
• aborted_after_provider_completion: el proveïdor ha completat, però el client aigües avall es va tancar abans que la passarel·la acabés de reenviar.
• settled_from_estimate: el registre de l'arrendatari va utilitzar una estimació perquè l'ús final no estava disponible.
• reconciliation_adjusted_usage: els informes del proveïdor van canviar més tard la fila.

Fet: les convencions semàntiques d'OpenTelemetry GenAI recomanen utilitzar la informació d'ús retornada pel proveïdor per a les respostes en temps real quan estigui disponible, i adverteixen que no s'informen les mètriques d'ús si els recomptes de testimonis no es poden obtenir de manera eficient o precisa.

Per a l'analítica de l'ús de la IA, això vol dir que els taulers de control haurien d'admetre nivells de confiança. Un gràfic que barreja valors finals, estimats i conciliats sense etiquetes pot semblar net, però enganyar els equips financers i de suport.

Proves de conformitat per a la comptabilitat en temps real

No confieu en proves manuals amb un missatge de xat de camí feliç. Cada adaptador de proveïdor ha de tenir proves de conformitat per als casos que trenquen els llibres majors:

• Full d'activitat normal: arriba l'ús final, s'observa un esdeveniment d'aturada, el llibre major es liquida com a final.
• Seqüència de trucades d'eines: es reenvien els delta de trucades d'eines, es captura l'ús, les metadades estructurades no corrompeixen el recompte de testimonis.
• Atura de seguretat o denegació: el proveïdor s'atura abans d'hora, l'ús encara s'estableix correctament.
• Desconnexió forçada del client: aigües avall es tanca després d'una sortida parcial; aigües amunt es cancel·la o es continua segons la política.
• Amunt 5xx després de la sortida parcial: la passarel·la registra l'entrega parcial i no marca la sol·licitud com a èxit neta.
• Temps d'espera de la passarel·la abans de l'ús final: la fila esdevé estimada o pendent de conciliació.
• S'ha perdut l'esdeveniment final: l'adaptador emet final_usage_missing i evita les etiquetes de facturació exactes.

Aquestes proves haurien d'afirmar les transicions d'estat, els camps de registre, els esdeveniments d'observabilitat emesos i el comportament aigües avall. La compatibilitat de flux byte per byte no és suficient; els efectes secundaris comptables formen part del contracte.

Llista de comprovació pràctica d'implementació

• Creeu la fila del registre d'ús abans d'enviar la sol·licitud amunt.
• Botiga els identificadors d'inquilí, clau, usuari, model, ruta, proveïdor i sol·licitud en el moment de la sol·licitud.
• Activeu els informes d'ús final del proveïdor quan siguin compatibles, com ara stream_options.include_usage compatible amb OpenAI.
• Per als proveïdors acumulatius, emmagatzemeu el valor d'ús més recent en lloc de sumar els esdeveniments.
• Conserva els objectes de resposta agregats quan els SDK els proporcionen.
• Feu un seguiment de la sortida lliurada per separat de l'ús facturat pel proveïdor.
• En desconnectar, cancel·leu aigües amunt segons la política de ruta i marqueu client_aborted.
• Utilitzeu estats de facturació transparents: final, estimat, pendent de conciliació, conciliació del proveïdor o renúncia.
• Emet esdeveniments d'observabilitat específics de la comptabilitat.
• Reconciliar més tard amb l'ús del proveïdor o els informes de costos quan estiguin disponibles, tot conservant l'atribució de l'inquilí en el moment de la sol·licitud.

Què mostrar als llogaters

Els llogaters no necessiten tots els esdeveniments interns, però sí que necessiten etiquetes honestes. Una taula d'ús útil pot mostrar:

• Estat: final, estimat o conciliat.
• Resultat de la sol·licitud: completat, avortat del client, error del proveïdor o temps d'espera de la passarel·la.
• Sortida lliurada: text o bytes aproximats enviats al client.
• Títols facturats: ús normalitzat pel proveïdor utilitzat per al cost.
• Ajust: qualsevol delta de conciliació posterior.

Aquest disseny redueix l'ambigüitat del suport. Si un usuari només ha vist una part d'una resposta, el tauler pot explicar si el proveïdor ja l'ha completat, si la passarel·la s'ha cancel·lat aigües amunt i si el càrrec és definitiu o estimat.

Recomanacions versus prediccions

Recomanacions: tracteu les sol·licituds transmeses com a màquines d'estat, espereu l'ús final autoritzat abans de la liquidació exacta, separeu la sortida lliurada de l'ús facturat i etiqueteu les files estimades amb honestedat. Els adaptadors del proveïdor haurien de codificar la semàntica d'ús específica del proveïdor en lloc d'aplanar cada flux en un servidor intermediari de bytes genèric.

Predicció: la comptabilitat en temps real serà més important a mesura que els models exposin més treballs amagats: fitxes de raonament, descomptes de testimonis en memòria cau, processament multimodal, rastres d'ús d'eines i parades de seguretat. Les passarel·les que ja separen l'ús facturat pel proveïdor de la sortida visible pel client s'adaptaran més fàcilment que les passarel·les que només compten el text transmès.

Conclusió accionable

Si la vostra passarel·la admet la transmissió en temps real, auditeu un camí avui: forçau la desconnexió d'un client després dels primers trossos i inspeccioneu la fila del llibre major. Si diu "èxit" amb un recompte de testimonis d'aspecte exacte, probablement les vostres analítiques mentiran.

La solució és no abandonar la reproducció en temps real. Mantingueu l'experiència de l'usuari ràpida, però feu que la finalització de la reproducció, la cancel·lació, els errors del proveïdor, l'ús final perdut i la conciliació explícita els estats de comptabilitat. Això ofereix als equips de producte una sortida sensible, costos defensables als equips financers i als equips de suport suficients evidències per explicar respostes parcials sense endevinar-les.

Lectura relacionada

• unir traces, registres de testimonis i analítiques d'ús segur
• creació d'un contracte de compatibilitat de passarel·la compatible amb OpenAI