Отчитане на поточно токен в AI API Gateway: окончателно използване, анулиране и частични отговори

Отговорите за поточно предаване на LLM са лесни за прокси и трудни за правилно таксуване. Ако AI API шлюз препраща изпратени от сървъра събития към клиента, но третира първите части като запис за използване, анализите на клиента ще се променят. Дрейфът обикновено се появява при спорове като: „потребителят видя само половината от отговора“, „доставчикът е таксувал повече, отколкото показва таблото ни за управление“, „квотата е освободена твърде рано“ или „таймаут създаде токени, но няма ред за фактура.“

Основният проблем е, че поточно предаваните повиквания не са едно събитие. Те са последователност: приета заявка, отворен поток нагоре, доставени байтове, докладвано крайно използване, доставчик спрян, клиент прекъснат, времето за изчакване на шлюза изтече и таксуването е уредено. Един надежден шлюз трябва да моделира изрично тези състояния, вместо да приема, че завършен HTTP отговор е единственият успешен път.

Режимът на повреда: стриймингът скрива счетоводната граница

Завършванията без поточно предаване обикновено връщат един обект на отговор с метаданни за използването. Шлюзът може да нормализира това използване, да напише ред в книга, да актуализира квотата и да излъчва анализи с едно преминаване.

Поточното предаване променя границата. Потребителското изживяване е постепенно, но истината за таксуването може да стигне накрая, в конкретно за доставчика крайно събитие, в кумулативна делта, чрез обобщен SDK отговор или по-късно чрез API за отчитане на доставчика. Ако клиентът прекъсне връзката преди последното събитие на използване, шлюзът може да е доставил само част от отговора, докато доставчикът все още е генерирал и таксувал още токени.

Факт: OpenAI документира, че стрийминг обаждащите се, които искат данни за използването, трябва да зададат stream_options с include_usage. OpenAI също предоставя крайни точки за използване и разходи на ниво организация, като същевременно отбелязва, че използването и разходите не винаги могат да се съгласуват перфектно за финансови цели.

Факт: Anthropic поточно предаване използва изпратени от сървъра събития като message_start, content_block_delta, message_delta и message_stop. Неговата message_delta информация за използване е кумулативна, така че шлюзът не трябва да добавя всяка делта за използване заедно.

Факт: Gemini и приложните програмни интерфейси (API) за поточно предаване в стил Vertex могат да разкрият инкрементални парчета, докато SDK могат също да предоставят обект на обобщен отговор. За шлюзовете този обобщен път може да бъде по-добър източник за завършена употреба, отколкото само видимите части.

Използване на поточна машина, а не булев флаг за успех

Поточно предаваната заявка трябва да има траен запис на използване, преди да започне повикването нагоре. Този запис трябва да се движи през изрични състояния. Практически минимум е:

• accepted: шлюзът удостовери ключа, приписа наемателя и създаде отворен ред в книга.
• first_byte_sent: поне едно изходно събитие достигна клиента надолу по веригата.
• provider_completed: доставчикът нагоре по веригата излъчи нормален стоп сигнал или завършен обект за отговор.
• client_aborted: сокетът надолу по веригата се затвори преди нормалното завършване на шлюза.
• provider_error: доставчикът нагоре по веригата върна грешка след началото на потока или преди да пристигне окончателното използване.
• gateway_timeout: шлюзът наложи своя бюджет за забавяне и прекрати заявката.
• settled: шлюзът преобразува използването в разходи на наемател и потребление на квота.
• reconciled: по-късните данни за използването или разходите на доставчика потвърждават или коригират реда.

Този модел предотвратява често срещана грешка в анализа: маркиране на всеки поток, който е произвел текст, като „успешен и точен“. Потокът може да бъде полезен за потребителя, непълен от доставчика, приблизителен за фактуриране и в същото време чакащ съгласуване.

Препоръчителни полета за счетоводна книга

Поддържайте реда за време на заявка малък, но ясен:

{
  "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
}

Важното разделяне е output_tokens_billed срещу output_tokens_delivered_estimate. Потребителите се интересуват какво е достигнало тяхното приложение. Финансите се интересуват какво е таксувал доставчикът. Тези числа могат да се различават след прекъсване на връзката, потоци от извикване на инструменти, скрити токени за разсъждение, кеширани токени, спирания за безопасност или изтичане на времето за изчакване на шлюза.

Специфични за доставчика правила за улавяне

Неутрален по отношение на доставчик OpenAI-съвместим API е полезен за разработчиците на приложения, но адаптерът на шлюза все още се нуждае от специфични за доставчика правила за отчитане.

OpenAI-съвместим стрийминг

За OpenAI маршрути изложете опция за шлюз, която позволява отчитане на използването нагоре, където се поддържа. Често срещан модел е да се приеме стандартно ниво на шлюз като:

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

Ако повикващият надолу по веригата го пропусне, шлюзът може да реши дали да го инжектира за маршрути, където това е съвместимо. Документирайте това поведение, тъй като някои клиенти очакват точна кабелна съвместимост и някои модели или нагоре по веригата може да не поддържат крайната употреба по същия начин.

Препоръка: не уреждайте разходите на наемателя от ранни части. Дръжте реда на книгата отворен, докато последното събитие за използване не бъде уловено, отговорът на доставчика приключи без използване или потокът влезе в път за грешка или анулиране.

Anthropic стрийминг

Anthropic изисква различно правило. Ако шлюз види три message_delta събития с брой изходни токени 10, 25 и 40, изходният брой е 40, а не 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);

Препоръка: запишете най-новата кумулативна стойност на употреба и излъчете събитие за наблюдение, ако регресира. Регресията може да показва грешки в анализатора, дублирани събития, промени в доставчика или смесени потоци.

Gemini и поточно предаване в стил Vertex

Gemini поддържа поточно предаване на части за намаляване на възприеманото забавяне. В SDK в стил Vertex стриймингът може да изложи както асинхронен поток, така и обект на агрегиран отговор. Шлюзът трябва да запази този обобщен път, когато е наличен.

const streamingResult = await model.generateContentStream(request);

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

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

Препоръка: избягвайте изграждането на всички отчети от видими части, ако SDK дава завършен запис на отговор. Частите са за латентност. Крайният обект често е по-добър за таксуване и анализи.

Обработвайте прекъсванията на връзката на клиента като първокласни счетоводни събития

Прекъсването на връзката на клиентите е мястото, където много шлюзове губят пари или надценяват клиентите. Раздел на браузъра се затваря, мобилна мрежа прекъсва или приложение отменя заявка. Шлюзът забелязва, че сокетът надолу по веригата е затворен, но доставчикът нагоре може все още да генерира.

Шлюзът трябва да направи ясен избор на политика:

• Анулиране нагоре по веригата незабавно: намалява загубата на генериране и разходите на доставчика, но може да наруши работните потоци, когато задната част все още се нуждае от резултата след прекъсване на връзката с потребителския интерфейс.
• Продължаване нагоре във фонов режим: може да запази работата за потребителите от страна на сървъра, но потребителят може да не види всички генерирани и таксувани токени.
• Поведение, зависимо от маршрута: анулирайте за интерактивен чат, продължете за работни процеси, подобни на работа, и направете настройката видима за наемателите.

Практически стандарт по подразбиране за интерактивно поточно предаване е да се отмени нагоре по веригата, когато клиентът надолу по веригата прекъсне връзката, след което да се маркира редът на книгата като client_aborted. Ако окончателното използване пристигне по време на анулирането, уредете се от това авторитетно използване. Ако не, маркирайте реда estimated или pending_reconciliation, вместо да се преструвате, че е точен.

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

Препоръка: изложете прозрачни етикети за таксуване като final, provider_reconciled, estimated, waived или pending_reconciliation. Това е по-защитимо от показването на всяко поточно обаждане като незабавно точно.

Налагане на квота по време на поток

Точното таксуване обикновено зависи от крайното използване на доставчика, но прилагането на квотата не винаги може да чака до края. На наемател с ограничен бюджет не трябва да се позволява да предава поточно безкрайно дълго време, защото точното използване не е налично по време на полета.

Използвайте два механизма заедно:

1. Резервация преди полет: резервирайте прогнозен максимум въз основа на модела, заявените максимални токени, политиката на клиента и текущия баланс.
2. Проверки на налягането при поточно предаване: оценява доставения изход по време на потока и спира, ако заявката пресече конфигурирана безопасна граница.

Това е контролен механизъм, а не окончателната сметка. Доставчиците могат да отчитат кеширани токени, логически токени, мултимодални токени или скрити токени по различен начин от оценителя на шлюза.

Компромис: прогнозите в реално време спомагат за налагането на бюджети, но могат да се различават от токените, таксувани от доставчика. Окончателното уреждане трябва да използва използването на авторитетен доставчик, когато е налично, а съгласуването трябва да коригира прогнозите по-късно.

Събития за наблюдение, които улавят счетоводни грешки

Неуспешните плащания при поточно предаване са по-лесни за отстраняване на грешки, когато шлюзът излъчва целеви събития вместо само регистрационни файлове с общи заявки. Добавете събития като:

• final_usage_missing: потокът приключи без пълномощно използване.
• cumulative_usage_regressed: кумулативният брой токени се премести назад.
• stream_ended_without_stop_event: не е наблюдаван нормален маркер за спиране на доставчик.
• aborted_after_provider_completion: доставчикът завърши, но клиентът надолу по веригата се затвори, преди шлюзът да завърши препращането.
• settled_from_estimate: книгата на наемателите използва приблизителна оценка, тъй като окончателното използване не беше налично.
• reconciliation_adjusted_usage: докладването на доставчика по-късно промени реда.

Факт: Семантичните конвенции на OpenTelemetry GenAI препоръчват използването на върната от доставчика информация за употреба за поточно предаване на отговори, когато е налице, и предупреждават да не се докладват показатели за употреба, ако броят на токените не може да бъде получен ефективно или точно.

За анализа на използването на AI това означава, че таблата за управление трябва да поддържат нива на сигурност. Диаграма, която смесва окончателни, прогнозни и съгласувани стойности без етикети, може да изглежда чиста, но да подведе екипите за финанси и поддръжка.

Тестове за съответствие за поточно отчитане

Не разчитайте на ръчно тестване с подкана за чат за щастлив път. Всеки адаптер на доставчик трябва да има тестове за съответствие за случаите, които нарушават регистрите:

• Нормален поток: пристига окончателно използване, наблюдава се събитие за спиране, счетоводната книга се установява като final.
• Поток на извикване на инструмент: делтите на извикване на инструмент се препращат, използването се улавя, структурираните метаданни не повреждат броенето на токени.
• Спиране за безопасност или отказ: доставчикът спира рано, използването все още се урежда правилно.
• Принудително прекъсване на връзката на клиента: надолу по веригата се затваря след частичен изход; нагоре по веригата се отменя или продължава съгласно правилата.
• Нагоре по веригата 5xx след частичен изход: шлюзът записва частично доставяне и не маркира заявката като чист успех.
• Време за изчакване на шлюза преди окончателно използване: редът става приблизителен или очаква съгласуване.
• Липсващо последно събитие: адаптерът излъчва final_usage_missing и избягва точните етикети за фактуриране.

Тези тестове трябва да потвърждават преходи на състояния, полета в счетоводна книга, излъчени събития за наблюдение и поведение надолу по веригата. Съвместимостта на потока байт за байт не е достатъчна; страничните счетоводни ефекти са част от договора.

Контролен списък за практическо внедряване

• Създайте реда на книгата за използване, преди да изпратите заявката нагоре по веригата.
• Идентификатори на наемател, ключ, потребител, модел, маршрут, доставчик и заявка в момента на заявка.
• Активирайте крайното отчитане на употребата на доставчика, където се поддържа, като например OpenAI-съвместим stream_options.include_usage.
• За кумулативни доставчици, съхранявайте най-новата стойност на използване вместо сумиране на събития.
• Запазване на обобщени обекти за отговор, когато SDK ги предоставя.
• Проследявайте доставения резултат отделно от таксуваното от доставчика използване.
• При прекъсване на връзката, анулирайте нагоре по течението според правилата за маршрута и маркирайте client_aborted.
• Използвайте прозрачни състояния на фактуриране: окончателно, прогнозно, предстоящо съгласуване, съгласувано с доставчика или отказано.
• Излъчване на събития за наблюдение, специфични за счетоводството.
• Сравнявайте по-късно с отчетите за използване или разходи на доставчика, когато са налични, като същевременно запазвате приписването на наемателя по време на заявка.

Какво да покажа на наемателите

Наемателите не се нуждаят от всяко вътрешно събитие, но имат нужда от честни етикети. Полезна таблица за използване може да показва:

• Състояние: окончателно, прогнозно или съгласувано.
• Резултат от заявката: завършена, клиент прекъснат, грешка на доставчика или изчакване на шлюза.
• Доставен изход: приблизителен текст или байтове, изпратени до клиента.
• Таксувани токени: нормализирано от доставчика използване, използвано за разходите.
• Коригиране: всяка по-късна делта за съгласуване.

Този дизайн намалява двусмислието на поддръжката. Ако потребителят е видял само част от отговор, таблото за управление може да обясни дали доставчикът вече е завършил, дали шлюзът е отменен нагоре по веригата и дали таксуването е окончателно или прогнозно.

Препоръки срещу прогнози

Препоръки: третирайте поточно предаваните заявки като държавни машини, изчакайте окончателното използване преди точното уреждане, отделете доставения изход от таксуваното използване и маркирайте честно прогнозните редове. Адаптерите на доставчика трябва да кодират специфична за доставчика семантика на използване, вместо да изравняват всеки поток в общ байт прокси.

Прогноза: отчитането на поточното предаване ще стане по-важно, тъй като моделите разкриват повече скрита работа: логически токени, отстъпки за кеширани токени, мултимодална обработка, следи за използване на инструменти и спирания за безопасност. Шлюзовете, които вече отделят таксуваното от доставчика използване от видимия за клиента изход, ще се адаптират по-лесно от шлюзовете, които отчитат само поточно предаван текст.

Приложимо заключение

Ако вашият шлюз поддържа поточно предаване, одитирайте един път днес: принудително прекъснете връзката на клиент след първите няколко части и проверете реда на книгата. Ако пише „успех“ с точен брой токени, вашите анализи вероятно лъжат.

Решението не е да се откажете от стрийминг. Запазете бързото потребителско изживяване, но направете изрични счетоводни състояния за завършване на потока, анулиране, грешки на доставчика, липсващо крайно използване и съгласуване. Това дава на продуктовите екипи отзивчив изход, на финансовите екипи защитими разходи и на екипите за поддръжка достатъчно доказателства, за да обяснят частичните отговори, без да гадаят.

Свързано четене

• проектиране на счетоводната книга зад всяко извикване на модел
• съединяване на следи, токен регистри и безопасно анализ на използването
• изграждане на OpenAI-съвместим договор за съвместимост на шлюза