AI API Ağ Geçidinde Akış Token Muhasebesi: Nihai Kullanım, İptaller ve Kısmi Yanıtlar

LLM yanıtlarını akış halinde temsil etmek kolaydır, ancak doğru şekilde faturalandırmak zordur. AI API ağ geçidi, sunucu tarafından gönderilen etkinlikleri istemciye iletir ancak ilk parçaları kullanım kaydı olarak ele alırsa kiracı analitiği sapar. Bu sapma genellikle şu gibi anlaşmazlıklarda ortaya çıkar: "Kullanıcı yanıtın yalnızca yarısını gördü", "Sağlayıcı kontrol panelimizde gösterilenden daha fazla fatura çıkardı", "Kota çok erken serbest bırakıldı" veya "Token üretimi sırasında zaman aşımı oluştu ancak fatura satırı yok."

Asıl sorun, akışlı çağrıların tek bir etkinlik olmamasıdır. Bunlar bir sıralamadır: istek kabul edildi, yukarı akış açıldı, baytlar teslim edildi, son kullanım rapor edildi, sağlayıcı durduruldu, istemci bağlantısı kesildi, ağ geçidi zaman aşımına uğradı ve faturalandırma yapıldı. Güvenilir bir ağ geçidi, tamamlanmış bir HTTP yanıtının tek başarılı yol olduğunu varsaymak yerine, bu durumları açıkça modellemelidir.

Başarısızlık modu: akış, hesaplama sınırını gizler

Akışsız tamamlamalar genellikle kullanım meta verilerini içeren bir yanıt nesnesi döndürür. Bir ağ geçidi tek geçişte bu kullanımı normalleştirebilir, bir genel muhasebe satırı yazabilir, kotayı güncelleyebilir ve analizleri yayınlayabilir.

Akış, sınırı değiştirir. Kullanıcı deneyimi artımlıdır, ancak faturalandırma gerçeği, sağlayıcıya özel bir son etkinlikte, kümülatif bir delta halinde, toplu bir SDK yanıtı aracılığıyla veya daha sonra sağlayıcı raporlama API'leri aracılığıyla en sona ulaşabilir. İstemcinin bağlantısı son kullanım olayından önce kesilirse, sağlayıcı hâlâ daha fazla jeton oluşturup faturalandırırken ağ geçidi yanıtın yalnızca bir kısmını iletmiş olabilir.

Gerçek: OpenAI, kullanım verilerini isteyen akışlı arayanların stream_options'ı include_usage ile ayarlaması gerektiğini belgeliyor. OpenAI aynı zamanda kuruluş düzeyinde kullanım ve maliyet uç noktaları da sağlarken, kullanım ve maliyetlerin mali amaçlar açısından her zaman mükemmel şekilde uyum sağlayamayabileceğini belirtiyor.

Gerçek: Anthropic akış, message_start, content_block_delta, message_delta ve message_stop gibi sunucu tarafından gönderilen etkinlikleri kullanır. message_delta kullanım bilgileri kümülatif olduğundan ağ geçidinin her kullanım deltasını birbirine eklememesi gerekir.

Fact: Gemini ve Vertex tarzı akış API'leri artımlı parçaları açığa çıkarabilirken, SDK'lar da toplu bir yanıt nesnesi sağlayabilir. Ağ geçitleri için bu birleştirilmiş yol, tamamlanmış kullanım açısından tek başına görünür parçalardan daha iyi bir kaynak olabilir.

Boole başarı bayrağını değil, akış durumu makinesini kullanın

Akışlı bir isteğin, yukarı akış çağrısı başlamadan önce dayanıklı bir kullanım kaydı olmalıdır. Bu kayıt açık durumlardan geçmelidir. Pratik minimum değer:

• accepted: Ağ geçidi anahtarın kimliğini doğruladı, kiracıyı ilişkilendirdi ve açık bir genel muhasebe satırı oluşturdu.
• first_byte_sent: en az bir çıkış etkinliği alt istemciye ulaştı.
• provider_completed: yukarı akış sağlayıcısı normal bir durdurma sinyali gönderdi veya yanıt nesnesini tamamladı.
• client_aborted: aşağı akış soketi normal ağ geçidi tamamlanmadan önce kapatıldı.
• provider_error: yukarı akış sağlayıcısı, akış başladıktan sonra veya son kullanım gelmeden önce bir hata döndürdü.
• gateway_timeout: Ağ geçidi gecikme bütçesini uyguladı ve isteği sonlandırdı.
• settled: ağ geçidi, kullanımı kiracı maliyetine ve kota tüketimine dönüştürdü.
• reconciled: daha sonraki sağlayıcı kullanımı veya maliyet verileri doğrulandı veya satır düzenlendi.

Bu model yaygın bir analiz hatasını önler: Metin üreten her akışın "başarılı ve kesin" olarak işaretlenmesi. Bir akış kullanıcı için yararlı olabilir, sağlayıcı tarafından tamamlanmayabilir, faturalandırma için tahmin edilebilir ve aynı zamanda mutabakat da beklenebilir.

Önerilen defter alanları

İstek zamanı satırını küçük ama açık tutun:

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

Önemli ayrım output_tokens_billed ve output_tokens_delivered_estimate'dir. Kullanıcılar uygulamalarına neyin ulaştığını önemsiyorlar. Finans, sağlayıcının ne faturalandırdığıyla ilgilenir. Bu sayılar; bağlantı kesintileri, araç çağrısı akışları, gizli akıl yürütme belirteçleri, önbelleğe alınmış belirteçler, güvenlik durdurmaları veya ağ geçidi zaman aşımlarından sonra farklılık gösterebilir.

Sağlayıcıya özel yakalama kuralları

Sağlayıcıdan bağımsız OpenAI-uyumlu API, uygulama geliştiricileri için kullanışlıdır, ancak ağ geçidi bağdaştırıcısının yine de sağlayıcıya özel muhasebe kurallarına ihtiyacı vardır.

OpenAI-uyumlu akış

OpenAI rota için, desteklendiğinde yukarı akış kullanım raporlamasına olanak tanıyan bir ağ geçidi seçeneğini kullanıma çıkarın. Yaygın bir model, aşağıdaki gibi ağ geçidi düzeyinde bir varsayılanı kabul etmektir:

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

Aşağı yönlü arayan kişi bunu atlarsa ağ geçidi, bunun uyumlu olduğu rotalara bunu ekleyip eklemeyeceğine karar verebilir. Bazı istemciler tam kablo uyumluluğu beklediğinden ve bazı modeller veya yukarı akışlar son kullanımı aynı şekilde desteklemeyebileceğinden bu davranışı belgeleyin.

Öneri: kiracı maliyetini erken parçalardan karşılamayın. Son kullanım olayı yakalanana, sağlayıcının yanıtı kullanım olmadan sona erene veya akış bir hata ya da iptal yoluna girene kadar genel muhasebe satırını açık tutun.

Anthropic akış

Anthropic'nın kümülatif kullanımı farklı bir kural gerektirir. Bir ağ geçidi, çıkış jetonu sayısı 10, 25 ve 40 olan üç message_delta olayı görürse, çıkış sayısı 75 değil 40 olur.

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);

Öneri: En son kümülatif kullanım değerini kaydedin ve gerilemesi durumunda bir gözlemlenebilirlik olayı yayınlayın. Bir regresyon, ayrıştırıcı hatalarını, yinelenen etkinlikleri, sağlayıcı değişikliklerini veya karışık akışları gösterebilir.

Gemini ve Vertex tarzı akış

Gemini, algılanan gecikmeyi azaltmak için akış parçalarını destekler. Vertex tarzı SDK'larda akış, hem eşzamansız akışı hem de toplanmış yanıt nesnesini ortaya çıkarabilir. Ağ geçidi, mevcut olduğunda bu toplu yolu korumalıdır.

const streamingResult = await model.generateContentStream(request);

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

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

Öneri: SDK tamamlanmış bir yanıt kaydı veriyorsa tüm muhasebeyi görünür parçalardan oluşturmaktan kaçının. Parçalar gecikme içindir. Nihai nesne genellikle faturalandırma ve analiz açısından daha iyidir.

Müşteri bağlantı kesintilerini birinci sınıf muhasebe etkinlikleri olarak ele alın

Müşteri bağlantılarının kesilmesi, birçok ağ geçidinin para kaybetmesine veya müşterilerden fazla ücret almasına neden olur. Bir tarayıcı sekmesi kapanır, bir mobil ağ kesilir veya bir uygulama bir isteği iptal eder. Ağ geçidi, aşağı akış soketinin kapalı olduğunu fark eder ancak yukarı akış sağlayıcısı hâlâ üretim yapıyor olabilir.

Ağ geçidi açık bir politika seçimi yapmalıdır:

• Yukarı akışı hemen iptal edin: boşa giden üretim ve sağlayıcı maliyetini azaltır, ancak kullanıcı arayüzünün bağlantısı kesildikten sonra arka ucun sonuca hâlâ ihtiyaç duyması durumunda iş akışlarını bozabilir.
• Arka planda yukarı akışa devam et:, sunucu tarafı tüketicilerinin çalışmasını koruyabilir, ancak kullanıcı, oluşturulan ve faturalandırılan tüm jetonları göremeyebilir.
• Rotaya bağlı davranış: Etkileşimli sohbet için iptal edin, iş benzeri iş akışları için devam edin ve ayarı kiracılar için görünür hale getirin.

Etkileşimli akış için pratik bir varsayılan, aşağı akış istemcisinin bağlantısı kesildiğinde yukarı akışı iptal etmek ve ardından genel muhasebe satırını client_aborted olarak işaretlemektir. İptal sırasında son kullanım gerçekleşirse, bu yetkili kullanımdan vazgeçin. Değilse, tammış gibi davranmak yerine estimated veya pending_reconciliation satırını işaretleyin.

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

Öneri: final, provider_reconciled, estimated, waived veya pending_reconciliation gibi şeffaf faturalandırma etiketlerini gösterin. Bu, aktarılan her çağrıyı anında tam olarak göstermekten daha savunulabilir bir yöntemdir.

Akış sırasında kota uygulaması

Doğru faturalandırma genellikle nihai sağlayıcı kullanımına bağlıdır, ancak kota uygulaması her zaman sonuna kadar bekleyemez. Kesin kullanım uçuş sırasında mevcut olmadığından, bütçesi zor bir kiracının süresiz olarak yayın yapmasına izin verilmemelidir.

İki mekanizmayı bir arada kullanın:

1. Ön kontrol rezervasyonu: modele, talep edilen maksimum jetonlara, kiracı politikasına ve mevcut bakiyeye göre tahmini bir maksimum rezervasyon yapın.
2. Akış basıncı kontrolleri: akış sırasında teslim edilen çıktıyı tahmin edin ve istek, yapılandırılmış bir güvenlik sınırını aşarsa durun.

Bu bir kontrol mekanizmasıdır, nihai fatura değil. Sağlayıcılar önbelleğe alınmış belirteçleri, akıl yürütme belirteçlerini, çok modlu belirteçleri veya gizli belirteçleri ağ geçidinin tahmincisinden farklı şekilde sayabilir.

Ödünleşme: Gerçek zamanlı tahminler bütçelerin uygulanmasına yardımcı olur, ancak bunlar sağlayıcı tarafından faturalandırılan jetonlardan farklılık gösterebilir. Nihai uzlaşmada, mümkün olduğunda yetkili sağlayıcı kullanımı kullanılmalı ve mutabakat, tahminleri daha sonra ayarlamalıdır.

Muhasebe hatalarını yakalayan gözlemlenebilirlik etkinlikleri

Ağ geçidi yalnızca genel istek günlükleri yerine hedeflenen etkinlikleri yayınladığında akış faturalandırma hatalarında hata ayıklamak daha kolaydır. Şunun gibi etkinlikler ekleyin:

• final_usage_missing: yayın, yetkili kullanım olmadan sonlandırıldı.
• cumulative_usage_regressed: kümülatif jeton sayısı geriye doğru taşındı.
• stream_ended_without_stop_event: normal bir sağlayıcı durdurma işareti gözlemlenmedi.
• aborted_after_provider_completion: sağlayıcı işlemi tamamladı ancak ağ geçidi yönlendirmeyi tamamlamadan alt istemci kapandı.
• settled_from_estimate: kiracı defteri, nihai kullanım mevcut olmadığından bir tahmin kullandı.
• reconciliation_adjusted_usage: sağlayıcı raporlaması daha sonra satırı değiştirdi.

Gerçek: OpenTelemetry GenAI anlam kuralları, mümkün olduğunda akış yanıtları için sağlayıcı tarafından döndürülen kullanım bilgilerinin kullanılmasını önerir ve belirteç sayımlarının verimli veya doğru bir şekilde elde edilememesi durumunda kullanım ölçümlerinin raporlanmasına karşı uyarıda bulunur.

Yapay zeka kullanım analizi için bu, kontrol panellerinin güven düzeylerini desteklemesi gerektiği anlamına gelir. Nihai, tahmini ve mutabakata varılan değerleri etiketler olmadan birleştiren bir grafik temiz görünebilir ancak finans ve destek ekiplerini yanıltıcı olabilir.

Akış muhasebesi için uygunluk testleri

Mutlu yol sohbet istemiyle manuel teste güvenmeyin. Her sağlayıcı bağdaştırıcısının, defterleri bozan durumlara yönelik uyumluluk testleri olmalıdır:

• Normal akış: son kullanım geldi, durdurma olayı gözlemlendi, defter final.
olarak belirlendi
• Araç çağrısı akışı: araç çağrısı deltaları iletilir, kullanım yakalanır, yapılandırılmış meta veriler belirteç sayımını bozmaz.
• Güvenlik veya ret durdurma: sağlayıcı erken durur, kullanım hâlâ doğru şekilde sabitlenir.
• Zorunlu istemci bağlantısının kesilmesi: kısmi çıktıdan sonra aşağı akış kapanır; politikaya göre yukarı akış iptal edildi veya devam ettirildi.
• Kısmi çıktıdan sonra yukarı akış 5xx: ağ geçidi kısmi teslimatı kaydeder ve isteği temiz bir başarı olarak işaretlemez.
• Son kullanımdan önce ağ geçidi zaman aşımı: satır tahmini veya bekleyen mutabakat haline gelir.
• Eksik son etkinlik: bağdaştırıcısı final_usage_missing yayınlıyor ve tam faturalandırma etiketlerinden kaçınıyor.

Bu testler, durum geçişlerini, defter alanlarını, yayılan gözlemlenebilirlik olaylarını ve aşağı yöndeki davranışları doğrulamalıdır. Bayt bayt akışı uyumluluğu yeterli değildir; muhasebe yan etkileri sözleşmenin bir parçasıdır.

Pratik uygulama kontrol listesi

• Yukarı yöndeki isteği göndermeden önce kullanım defteri satırını oluşturun.
• İstek zamanında kiracı, anahtar, kullanıcı, model, rota, sağlayıcı ve istek tanımlayıcılarını depolayın.
• Desteklendiği yerlerde, OpenAI-uyumlu stream_options.include_usage gibi sağlayıcının son kullanım raporlamasını etkinleştirin.
• Kümülatif sağlayıcılar için etkinlikleri toplamak yerine en son kullanım değerini saklayın.
• Toplanmış yanıt nesnelerini, SDK'lar sağladığında koruyun.
• Teslim edilen çıktıyı, sağlayıcı tarafından faturalandırılan kullanımdan ayrı olarak izleyin.
• Bağlantı kesildiğinde, rota politikasına göre yukarı akışı iptal edin ve client_aborted.# olarak işaretleyin.
• Şeffaf faturalandırma durumlarını kullanın: nihai, tahmini, mutabakat bekleniyor, sağlayıcı mutabakatı sağlandı veya feragat edildi.
• Hesaplamaya özgü gözlemlenebilirlik etkinlikleri yayınlayın.
• İstek zamanındaki kiracı ilişkilendirmesini korurken, daha sonra sağlayıcı kullanımı veya mevcut olduğunda maliyet raporları ile mutabakat sağlayın.

Kiracılara ne gösterilecek?

Kiracıların her dahili etkinliğe ihtiyacı yoktur ancak dürüst etiketlere ihtiyaçları vardır. Faydalı bir kullanım tablosu şunları gösterebilir:

• Durum: nihai, tahmini veya mutabakata varıldı.
• İstek sonucu: tamamlandı, istemci iptal edildi, sağlayıcı hatası veya ağ geçidi zaman aşımı.
• Teslim edilen çıktı: istemciye gönderilen yaklaşık metin veya bayt miktarı.
• Faturalandırılmış jetonlar: maliyet için kullanılan, sağlayıcı tarafından normalleştirilmiş kullanım.
• Ayarlama: daha sonraki herhangi bir mutabakat deltası.

Bu tasarım desteğin belirsizliğini azaltır. Kullanıcı yanıtın yalnızca bir kısmını gördüyse kontrol paneli, sağlayıcının zaten tamamlayıp tamamlamadığını, ağ geçidinin yukarı yönde iptal edip etmediğini ve ücretin nihai mi yoksa tahmini mi olduğunu açıklayabilir.

Öneriler ve tahminler

Öneriler: Akışlı istekleri durum makineleri olarak ele alın, kesin ödemeden önce yetkili son kullanımı bekleyin, teslim edilen çıktıyı faturalanan kullanımdan ayırın ve tahmini satırları dürüst bir şekilde etiketleyin. Sağlayıcı bağdaştırıcıları, her akışı genel bayt proxy'sine dönüştürmek yerine sağlayıcıya özel kullanım semantiğini kodlamalıdır.

Tahmin: Modeller daha fazla gizli çalışmayı ortaya çıkardıkça akış muhasebesi daha önemli hale gelecektir: akıl yürütme belirteçleri, önbelleğe alınmış belirteç indirimleri, çok modlu işleme, araç kullanım izleri ve güvenlik durakları. Zaten sağlayıcı tarafından faturalanan kullanımı müşterinin görebildiği çıktıdan ayıran ağ geçitleri, yalnızca akış halindeki metni sayan ağ geçitlerine göre daha kolay uyum sağlayacaktır.

Harekete geçirilebilir sonuç

Ağ geçidiniz akışı destekliyorsa bugün bir yolu denetleyin: ilk birkaç parçadan sonra istemcinin bağlantısını kesmeye zorlayın ve genel muhasebe satırını inceleyin. Tam olarak görünen jeton sayılarında "başarı" yazıyorsa, analizleriniz muhtemelen yalan söylüyordur.

Çözüm akışı bırakmamaktır. Hızlı kullanıcı deneyimini koruyun ancak akışın tamamlanması, iptal edilmesi, sağlayıcı hataları, eksik son kullanım ve mutabakatın açık muhasebe durumlarını yapın. Bu, ürün ekiplerine duyarlı çıktılar, finans ekiplerine savunulabilir maliyetler sağlar ve destek ekiplerine kısmi yanıtları tahmin etmeden açıklamaya yetecek kadar kanıt sağlar.

İlgili okumalar

• her model çağrısının arkasında fatura defterini tasarlama
• izleri, jeton defterlerini birleştirme ve güvenli kullanım analiz
• OpenAI uyumlu bir ağ geçidi uyumluluk sözleşmesi oluşturma