Çok Kiracılı Bir Ağ Geçidinde Anthropic API Sürümleri ve Beta Başlıklarını Yönetin

Anthropic uyumlu bir API ağ geçidi, anthropic-version ve anthropic-beta'i sıradan geçiş başlıkları olarak değerlendirmemelidir. Doğrulama kurallarını, yanıt bloklarını, akış olaylarını, kullanılabilirliği, fiyatlandırmayı ve önbellek hesaplamasını değiştirebilecek protokol davranışını ve deneysel yetenekleri seçerler.

Uygulamadaki sorun, bir kiracının istek üstbilgilerinin platform politikasını atlamasına izin vermeden yerel Claude davranışını korumaktır. Çözüm, protokol kabulünü birinci sınıf bir ağ geçidi kararı haline getirmektir: arayanın kimliğini doğrulamak, sürüm politikasını çözümlemek, istenen beta özelliklerini doğrulamak, uyumlu bir rota seçmek ve yukarı yönde gönderilenleri tam olarak kaydetmek.

Politika sınırını tanımlayın

Gerçek: Doğrudan Claude API istekleri bir anthropic-version başlığı gerektirir, ancak resmi SDK'lar normalde bunu sağlar. Anthropic beta özellikleri, anthropic-beta veya SDK'ye özgü bir beta parametresi aracılığıyla istenir.

Öneri: Her iki değeri de güvenilir yönlendirme talimatları olarak değil, istenen yetenekler olarak yorumlayın. İstemci bir sürüm veya beta isteyebilir ancak ağ geçidi, bu kombinasyonun kiracı, API anahtarı, model, bölge ve yukarı akış kimlik bilgileri için desteklenip desteklenmediğine karar verir.

Onaylanmamış bir beta sürümünü sessizce kaldırma. Bu, açık bir isteği farklı anlamlara sahip başarılı bir çağrıya dönüştürebilir. Gönderimden önce, yukarı akış kimlik bilgilerini veya dahili rota ayrıntılarını açığa çıkarmadan desteklenmeyen özelliği tanımlayan kararlı bir ağ geçidi hatasıyla bunu reddedin.

{
  "type": "gateway_policy_error",
  "code": "beta_not_allowed",
  "message": "The requested Anthropic beta is not enabled for this API key.",
  "details": {
    "beta": "example-beta-2026-01-01",
    "policy_id": "claude-production"
  }
}

Kabul hataları için 4xx yanıtı döndürün ve ağ geçidi veya yukarı akış hataları için 5xx yanıtlarını ayırın. Anthropic kendi hata biçimini değiştirse bile hata şemasını sabit tutun.

Bir sürüm ve yetenek kaydı oluşturun

Tarih şeklindeki sürüm dizesinin sözdizimsel olarak doğrulanması kolaydır ancak yalnızca sözdiziminden yönetilmesi imkansızdır. Ağ geçidinin, gerçekte test ettiği sürümleri ve beta özellikleri içeren bir kayıt defterine ihtiyacı vardır.

Sürüm kayıtları

Her sürüm kaydı şunları içermelidir:

• Kanonik sürüm tanımlayıcısı ve yaşam döngüsü durumu: test ediliyor, kullanılabilir, varsayılan, kullanımdan kaldırıldı veya engellendi.
• Desteklenen istek alanları, içerik blokları, durma nedenleri, kullanım alanları ve bilinen akış etkinlikleri.
• Uyumlu modeller, yukarı akış platformları, bölgeler ve kimlik bilgisi havuzları.
• Sözleşme-fikstür sonuçları ve en son başarılı testin tarihi.
• Fiyatlandırma-katalog uyumluluğu ve bilinen tüm önbellek muhasebesi sonuçları.
• Evlat edinme kısıtlamaları, kullanımdan kaldırma tarihleri ve değiştirme kılavuzu.

Beta kayıtları

Beta özelliklerinin, kullanılabilirliği ve operasyonel riskleri temel API sürümden farklı olabileceğinden ayrı kayıtlara ihtiyacı vardır. Standart beta adını, uyumlu sürümleri ve modelleri, izin verilen bölgeleri, gerekli istek alanlarını, olası yanıt bloklarını, akış etkinliklerini, fiyatlandırma işlemini, hız sınırı sınıfını ve kullanıma sunma durumunu kaydedin.

Bunu uygulama koşulları yerine veri olarak modelleyin. Bir politika değerlendiricisi daha sonra somut bir soruyu yanıtlayabilir: "K anahtarı, R yolunda beta seti B ile V versiyonunu kullanabilir mi?" Aynı katalog, her bağdaştırıcıyı kendi kiracı kurallarını uygulamaya zorlamadan ekipler için çok modelli API ağ geçidini destekleyebilir.

Her kiracıya açık bir sürüm politikası verin

Üç politika modunu destekleyin:

1. Sabitlendi: Kiracı veya anahtarın tam bir sürüm kullanması gerekir. Eksik veya farklı değerleri reddet.
2. Ağ geçidi akımı: Eksik bir başlık, ağ geçidinin test edilen varsayılanına çözümlenir. Açık bir istemci değeri hâlâ doğrulanıyor.
3. Onaylanan aralık: Müşteri, test edilen sürümlerden oluşan sınırlı bir izin verilenler listesinden seçim yapabilir.

"Aralığı" iki uç nokta arasındaki her tarih olarak yorumlamaktan kaçının. Anthropic sürümleri, sürekli bir anlamsal sürüm dizisi değil, tanımlayıcılardır. Kabul edilen değerlerin açık bir kümesini saklayın.

Bir yukarı akış rotası seçmeden önce geçerli sürümü çözümleyin:

requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)

İstenen ve etkili değerleri ayrı tutun. Bir politika bir varsayılanı sağladığında bunlar farklılık gösterebilir ancak bir denetim kaydının bu değişikliği görünür hale getirmesi gerekir.

Beta başlıklarını yapısal olarak ayrıştırın

Alt dize eşleşmesi veya ham dize eşitliği içeren beta özelliklerine yetki vermeyin. Başlığı API tarafından kabul edilen sözdizimine göre ayrıştırın, hatalı biçimlendirilmiş veya yinelenen girişleri uygun şekilde reddedin ve standart özellik tanımlayıcılarını karşılaştırın.

Kanonik sıralama, politika önbellek anahtarları ve telemetri boyutları için kullanışlıdır:

requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a  // serialized in accepted upstream syntax

Hata ayıklama için yeterli miktarda istek meta verisini koruyun, ancak normalleştirilmiş tanımlayıcılar yeterli olduğunda ham başlıkları süresiz olarak saklamayın. Başlık günlükleri gereksiz istemci meta verileri içerebilir ve bunların depolanması, saklama ve erişim kontrollerinin kapsamını artırır.

Beta yetkilendirmesi kiracı kapsamlı ve tercihen anahtar kapsamlı olmalıdır. Bir geliştirme anahtarı, üretim iş yüklerine otomatik olarak verilmeden deneysel bir yetenek alabilir. İzin verilenler listelerinde yapılan değişiklikler, aktör, neden, önceki durum, yeni durum ve geçerlilik süresini içeren kontrol düzlemi denetim etkinlikleri oluşturmalıdır.

Yönlendirmeden ayrı giriş

Bir istek yalnızca model adı mevcut olduğu için yönlendirilemez. Rota uygunluğu, protokol ve altyapı özelliklerinin kesişimidir:

eligible(route) =
  route.platform supports effective_version
  AND route.model supports every admitted_beta
  AND route.region permits every admitted_beta
  AND route.credentials are entitled to those capabilities
  AND route.pricing_catalog can account for the result

Hiçbir rota tam grubu karşılamıyorsa, isteği göndermeden önce başarısız olun. Bir rotayı uygun hale getirmek için beta özelliklerini bırakmayın. Kiracı politikası bu davranışı açıkça tanımlamadığı sürece otomatik olarak başka bir sürümü değiştirmeyin.

Bu ayrım, kimlik bilgilerini bir havuzda toplayan, müşteri tarafından sağlanan anahtarları destekleyen veya bölgeler arasında çalışan ağ geçitlerinde önemlidir. Aynı modele giden iki yol, farklı özellik erişimine, ikamet kısıtlamalarına veya hız sınırlarına sahip olabilir.

Yerel yanıt semantiğini koru

Gerçek: Anthropic Mesaj yanıtları, araç kullanımı, belirteç sınırları, bağlam penceresi sınırları, duraklatılmış dönüşler ve retler gibi nedenlerle sona erebilir. Akış yanıtları, sunucu tarafından gönderilen adlandırılmış etkinlikleri kullanır ve Anthropic'in uyumluluk kılavuzu, istemcilerin yeni etkinlik türlerini tolere etmesini gerektirir.

Öneri: Tüm başarılı terminal durumlarını "tamamlandı" olarak daraltmayın. Yerel yanıtta ve ağ geçidi telemetrisinde yukarı akış durdurma nedenini koruyun. Uygulamaların bir aracı çalıştırması, duraklatılmış bir dönüşe devam etmesi, bağlamı azaltması veya bir ret durumunu ortaya çıkarması gerekebilir.

Akış proxy'si, ileriye dönük uyumluluğu korurken muhasebe ve yaşam döngüsü yönetimi için gereken etkinlikleri tanımalıdır:

• Kiracı politikası yerel geçişe izin verdiğinde bilinmeyen etkinlik türlerini ilet.
• Sınırlı teşhis meta verilerindeki ham etkinlik adını ve sıra konumunu koruyun.
• Tanıdık olmayan bir ekleme etkinliğinde akışı kapatan kapsamlı bir numaralandırma kullanmayın.
• Yukarı akış hatası olayını aktarım bağlantısının kesilmesi ve istemci iptalinden ayırın.
• Kullanımı yalnızca yetkili alanlardan sonlandırın; Nihai kullanım mevcut olmadığında tamamlanmamış akışları geçici olarak işaretleyin.

Ağ geçidi ayrıca OpenAI şeklinde bir uç nokta ortaya çıkarıyorsa, bu bağdaştırıcıyı yerel Mesajlar yolundan ayrı tutun. Anthropic'in OpenAI uyumluluk katmanı belgelenmiş alan ve özellik sınırlamalarına sahiptir. Ortak bir dahili zarf, yönlendirmeye yardımcı olabilir ancak içerik bloğu sırasını, önbellek kontrollerini, düşünme imzalarını, araç durumunu veya sağlayıcıya özgü durdurma nedenlerini göz ardı etmemelidir.

Muhasebeyi sürüme duyarlı hale getirin

Gerçek: İstem önbellek kullanımı, sıradan giriş jetonlarını, önbellek oluşturma giriş jetonlarını ve önbellek okuma giriş jetonlarını ayırır. Toplam girdi tüketimi geçerli tüm kategorileri hesaba katmalıdır.

Bir sürüm veya beta değişikliği, önbellek uygunluğunu, içerik gösterimini veya döndürülen kullanım alanlarını değiştirebilir. Bu nedenle her kullanım etkinliği şunları içermelidir:

• İstenen ve geçerli API sürüm.
• İstenen ve kabul edilen beta setleri.
• Kiracı, API anahtar, politika, rota, model, bölge ve yukarı akış istek kimliği.
• Durum, durdurma nedeni, akışın tamamlanma durumu ve hata ilişkilendirmesi.
• Giriş, çıkış, önbellek oluşturma ve önbellek okuma jetonu kategorileri.
• Fiyatlandırma kataloğu sürümü ve geçici veya kesinleşmiş maliyet durumu.

Bu boyutlar, birleşik AI API faturalandırmanın benzer isteklerin neden farklı maliyetler ürettiğini açıklamasına olanak tanır. Sağlayıcı farklı ücretlere sahip kategoriler sunduğunda tek bir birleşik jeton sayımı üzerinden faturalandırma yapmaktan kaçının.

Bir sürümü veya betayı etkinleştirmeden önce test edin

Sıradan metin, akış metni, araç çağrıları, yapılandırılmış çıktı, retler, belirtecin kesilmesi, bağlam penceresi tükenmesi, duraklatılmış dönüşler, istem önbelleğe alma, hatalı biçimlendirilmiş istekler, hız sınırları ve orta akış hataları için sözleşme fikstürleri oluşturun.

Her fikstür için HTTP'den fazla durumu karşılaştırın. İçerik bloğu türünü ve sırasını, durma nedenini, araç tanımlayıcılarını ve bağımsız değişkenlerini, olay sırasını, kullanım alanı varlığını, önbellek kategorilerini ve hata şeklini yakalayın. Kesin düzyazı çıktısı yerine onaylanmış yapısal beklentileri saklayın.

Gölge istekleri yalnızca yinelenen yürütmenin güvenli olduğu durumlarda kullanın. Araçlar, harici yan etkiler, hassas veriler veya malzeme maliyeti içeren talepler uygun olmayabilir. Bu iş yükleri için, dezenfekte edilmiş donanımları kontrollü bir ortamda yeniden oynatın.

Tahmin: Yeni sürümler ve beta özellikler, yanıt çeşitleri ve etkinlikleri eklemeye devam edecek. Yetenek kayıtları ve eklemeli ayrıştırma etrafında tasarlanan bir ağ geçidi, sabit numaralandırmalar ve genel varsayılanlar etrafında oluşturulan bir ağ geçidine göre genellikle bu değişiklikleri daha az acil durum çalışmasıyla absorbe eder.

Yetenekleri güvenli bir şekilde kullanıma alın ve kullanımdan kaldırın

Test etme, dahili, katılım, canary, kullanılabilir, kullanımdan kaldırılmış ve engellenmiş durumlarla bir yeteneği tanıtın. Canarying sırasında durum dağılımlarını, durma nedenlerini, içerik engelleme sıralarını, araç davranışını, kullanım alanlarını, gecikmeyi ve önbellek sonuçlarını karşılaştırın. Trafik başlamadan önce geri alma eşiklerini tanımlayın.

Emeklilik aşamalı olarak gerçekleşmelidir:

1. Mevcut atamalar devam ederken yeni kiracının benimsenmesini engelleyin.
2. Etkilenen kiracıları, anahtarları, modelleri ve son istek kalıplarını tanımlayın.
3. Değiştirme için bir uyumluluk raporu veya test uç noktası sağlayın.
4. Kabul edilen istekler konusunda uyarıda bulunun ve kesin bir kesinti yayınlayın.
5. Sahipler ve son kullanma tarihleriyle birlikte açık istisnalar gerektir.
6. Yeteneği engelleyin ve geçmiş denetim ve faturalandırmanın yorumlanması için kayıt defteri kaydını saklayın.

Sabitleme tekrarlanabilirliği artırır ancak test matrisini genişletir. Ağ geçidi çapında bir sürüm, operasyonel değişkenleri azaltır ancak ilgisiz kiracıları tek bir geçiş zamanlamasına bağlar. Geniş beta geçişi, özelliklere erişimi hızlandırır ancak maliyet, ikamet ve destek garantilerini zayıflatır. Çok kiracılı bir hizmet için, kiracı başına açık politika genellikle savunulabilir orta yoldur.

Uygulama kontrol listesi

• Her kiracı veya API anahtarı için bir sürüm politikası gerektir.
• Test edilmiş sürüm ve beta yetenek kayıtlarını tutun.
• Kötü biçimlendirilmiş, bilinmeyen veya yetkisiz özellikleri göndermeden önce reddedin.
• Rotaları yalnızca protokol isteğinin tamamını çözümledikten sonra seçin.
• Yerel içerik bloklarını, durma nedenlerini, kullanım alanlarını ve akışları koruyun.
• Ek akış etkinliklerini güvenli bir şekilde iletin ve etkinlik adlarını koruyun.
• Kullanım ve denetim etkinlikleriyle ilgili istenen ve etkili protokol değerlerini kaydedin.
• Varsayılanları değiştirmeden önce sözleşme fikstürlerini ve kontrollü kanaryaları çalıştırın.
• Sessiz yeniden yazma işlemleri yerine, ölçülü benimseme kontrolleri aracılığıyla eski yetenekleri kullanımdan kaldırın.

Temel tasarım kararı basittir: Sürüm ve beta başlıkları politika girdileridir. Ağ geçidi bunları yetenek olarak kabul ettiğinde, yönlendirdiğinde, test ettiğinde ve ölçtüğünde, yerel API uyumluluğu, deneysel davranışın sıradan HTTP meta veri olduğunu iddia etmeden yönetilebilir hale gelir.

İlgili okuma

• son kullanım, iptaller ve kısmi akış yanıtlarının muhasebeleştirilmesi