Отчитане на поточно токен в 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 е кумулативна, така че шлюзът не трябва да добавя всяка делта на използване заедно.

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

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

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

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

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

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

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

<предварителен код>{ "request_id": "gw_req_...", "tenant_id": "tenant_123", "api_key_id": "ключ_456", "доставчик": "отворен|антропичен|близнаци|...", "provider_request_id": нула, "модел": "идентификатор на модел-доставчик", "състояние": "прието", "поток": вярно, "input_tokens": нула, "output_tokens_billed": нула, "output_tokens_delivered_estimate": 0, "provider_usage_source": нула, "billing_status": "чакащо_съпоставяне", "client_abort_at": нула, "provider_completed_at": нула, "settled_at": нула, "грешка_клас": нула }

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

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

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

Поточно предаване, съвместимо с OpenAI

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

<предварителен код>{ "поток": вярно, "stream_options": { "include_usage": вярно } }

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

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

Антропичен стрийминг

Кумулативната употреба на Anthropic изисква различно правило. Ако шлюз види три събития message_delta с брой изходни токени 10, 25 и 40, изходният брой е 40, а не 75.

let latestUsage = null;
за чакане (константно събитие на 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(събитие);
}
settleFromLatestCumulativeUsage(latestUsage);

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

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

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

const streamingResult = изчакайте model.generateContentStream(request);
за изчакване (константна част от streamingResult.stream) {
  напредЧунк(парче);
  countDeliveredBytesOrText(chunk);
}
const aggregated = await streamingResult.response;
settleFromAggregatedUsage(обобщено);

Препоръка: избягвайте изграждането на всички отчети от видими части, ако 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 това означава, че таблата за управление трябва да поддържат нива на сигурност. Диаграма, която смесва окончателни, прогнозни и съгласувани стойности без етикети, може да изглежда чиста, но да подведе екипите за финанси и поддръжка.

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

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

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

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

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

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

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

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

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

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

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

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

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

Изпълнимо заключение

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

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

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

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