Çok Modelli API Ağ Geçidi için Kiracı Farkındalıklı /v1/models Kataloğu Oluşturun

Bir ağ geçidi GET /v1/models'den bağlı her sağlayıcının bildiği her modeli döndürmemelidir. Kimliği doğrulanmış API anahtarının yetkili olduğu ve operasyonel olarak çağırabildiği modelleri döndürmelidir.

Bu ayrım, bir API anahtarın birden fazla LLM sağlayıcısına erişim sağlaması durumunda önemlidir. Yukarı akış kataloglarının ham bir birleşimi, ekip politikası tarafından yasaklanan, kiracının planı kapsamında kullanılamayan, sağlıklı bir kimlik bilgisi eksik, istenen API ile uyumsuz veya gerekli bölgede dağıtılmayan modelleri içerebilir. Bu girişler, keşfin engellemesi gereken bozuk model seçicilere ve çalışma zamanı hatalarına neden olur.

Pratik sözleşme daha güçlüdür: Reklamı yapılan her model, gerçek bir istek için geçerli olan kabul kontrollerinin aynısını geçmelidir.

"Kullanılabilir"in ne anlama geldiğini tanımlayın

Sağlayıcının varlığı yalnızca bir girdidir. Bir model, yalnızca gerekli tüm koşullar doğru olduğunda anahtarın varsayılan kataloğunda görünmelidir:

• Ağ geçidinin, model için yapılandırılmış bir genel ürünü var.
• Kiracı, ekip ve API anahtarı bu ürüne hak kazanır.
• Geçerli ticari plan bunun kullanımına izin vermektedir.
• Politika modele, sağlayıcıya, bölgeye ve veri işleme moduna izin verir.
• En az bir uyumlu yukarı akış dağıtımı veya rota mevcut.
• Bu rota için kullanılabilir bir sağlayıcı kimlik bilgisi mevcut.
• Rota, katalogda reklamı yapılan en az bir API yüzeyi destekliyor.
• Rota, ağ geçidinin sağlık politikası kapsamında operasyonel olarak hazır.

Ayarlanmış işlem olarak ifade edilir:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

Bu bir öneridir, OpenAI şemasıyla ilgili bir iddia değil. Standart şema, ağ geçidine özgü bu kontrollerin tümünü tanımlamaz. Ağ geçidinin kontrol düzlemine ve katalog derleyicisine aittirler.

Sağlayıcı keşfini proxy olmadan normalleştirin

Gerçek: sağlayıcı keşif API'leri farklı kavramları ortaya çıkarır. OpenAI'nin model listesi tanımlayıcıları ve temel meta verileri sağlar, ancak her API yüzeyi için tam bir yetenek matrisi sağlamaz. Anthropic yaşam döngüsü durumlarını ayırt eder ve bir model veya takma ad alındığında daha zengin yetenek bilgileri döndürebilir. Gemini belirteç sınırları ve desteklenen oluşturma yöntemleri gibi alanları ortaya çıkarır. Microsoft Foundry, model alanında bir dağıtım adı gerektirebilir ve bir dağıtım, temel model mevcut olsa bile belirli bir API ile uyumsuz olabilir.

Sonuç olarak, sağlayıcı yanıtlarını doğrudan iletmek dayanıklı bir tasarım değildir. Her sağlayıcı API'yı mutabakat kaynağı olarak değerlendirin. Gözlemlerini dahili bir kayda dönüştürün ve ardından bunları ağ geçidi yapılandırması ve kiracı politikasıyla birleştirin.

Kurallı katalog kaydı kullanın

Faydalı bir dahili kayıt, kamu sözleşmesini yukarı yönlü uygulamadan ayırır:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

target_id'ı, kimlik bilgisi referanslarını veya dahili yönlendirme durumunu standart genel uç nokta aracılığıyla ifşa etmeyin. Bu alanlar kontrol düzlemi verileridir. Bunları, giriş yönlendirmesi, destek araçları ve kullanım ilişkilendirmesi için hazır bulundurun.

Ayrı kimlikler, takma adlar ve dağıtımlar

Genel model kimliği bir müşteri sözleşmesidir. Sağlayıcı model kimliği, yukarı yöndeki bir model ailesini veya sürümünü tanımlar. Dağıtım adı, operatör tarafından oluşturulan bir hizmet kaynağını tanımlar. Bunlar birbirinin yerine kullanılamaz.

Yönlendirmeden önce genel takma adı, değişmez bir katalog revizyonuna çözümleyin. Kullanım olayına hem istenen kimliği hem de çözümlenen hedefi kaydedin. Takma ad daha sonra değişirse destek personeli daha önceki bir çağrıyı hangi dağıtımın gerçekleştirdiğini yine de yeniden yapılandırabilir.

Kimliği doğrulanmış anahtar için kataloğu derleyin

Katalog derleyicisi yalnızca kiracı kimliğini değil, kimliği doğrulanmış bir ana öğeyi almalıdır. Aynı kiracının üretim anahtarları, geliştirme anahtarları, kısıtlı müşteri anahtarları ve farklı model yetkilerine sahip hizmet hesapları olabilir.

Belirleyici bir derleme dizisi:

1. Değişmez temel katalog revizyonunu yükleyin.
2. Kiracı üyeliğini, ekip üyeliğini ve anahtara özel izinleri çözümleyin.
3. Plan, coğrafya, veri yerleşimi ve sağlayıcı kısıtlamalarını uygulayın.
4. Geçerli kimlik bilgileri veya uyumlu dağıtımlar olmayan rotaları kaldırın.
5. Mevcut durum anlık görüntüsünü kullanarak rota hazırlığını değerlendirin.
6. Hayatta kalan rotaları genel model kayıtlarında toplayın.
7. Yalnızca hayatta kalan en az bir rota tarafından desteklenen API yüzeyi döndür.

Hem ekip hem de anahtar bağışları mevcut olduğunda kesişim semantiğini kullanın. Kısıtlı bir ekibe atanan anahtar, yalnızca kiracının daha geniş bir plana sahip olması nedeniyle daha geniş bir erişim elde etmemelidir. Bu, yazılım ekipleri için yapay zeka modeli erişim kontrolünü öngörülebilir hale getirir ve yanlışlıkla ifşa edilmesini azaltır.

Listeyi tut ve alma davranışı aynı

GET /v1/models/{model}, liste işlemiyle aynı yetkilendirme yüklemini çalıştırmalıdır. Aksi takdirde, saldırgan başarılı, yasaklanmış ve bulunamadı yanıtlarını karşılaştırarak gizli tanımlayıcıları sıralayabilir.

Anahtarın göremediği bir model için, bilinmeyen bir model için kullanılan genel hatanın aynısını döndürün. Başka bir kiracının bunu kullanıp kullanamayacağını, hangi sağlayıcının barındırdığını veya hangi yetkinin kilidini açacağını açıklamayın. Yönetim API'leri yetkili operatörlere daha ayrıntılı nedenler sunabilir.

API uyumluluğunu açıkça temsil edin

Bir modelin varlığı her uç noktanın desteklendiği anlamına gelmez. Sohbet Tamamlamaları, Yanıtlar, yerleştirmeler, görüntü oluşturma, gerçek zamanlı, toplu ve Anthropic Mesajların farklı istek ve akış sözleşmeleri vardır.

Dolayısıyla rota kabulü hem modeli hem de API yüzeyini kabul etmelidir:

admit(key, public_model_id, api_surface, request_features)

Sonuç, uyumlu bir katalog revizyonunu ve bir veya daha fazla uygun rotayı tanımlamalıdır. Örneğin, bir model chat.completions'ı destekleyebilir ancak responses'yi destekleyemez veya Yanıtları yalnızca yerleşik araçlar olmadığında destekleyebilir. Uyumluluk istenen özelliklere bağlı olduğunda supports_responses gibi tek bir Boole değeri yetersiz olabilir.

Öneri: muhafazakar yetenekler yayınlayın. Bir özelliğin tanıtımını yalnızca ağ geçidinin onu uygun rota kümesinde uygulayabildiği veya onu belirleyici olarak destekleyen bir rota seçebildiği durumlarda yapın. Sağlayıcı aile adından görüntü girişi, araç çağrısı veya yapılandırılmış çıktı çıkarımı yapmayın.

Meta veriler eklerken SDK uyumluluğunu koruyun

OpenAI-uyumlu istemcilerin beklediği standart alanları sabit tutun:

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

Ad alanı uzantısı çarpışma riskini azaltır, ancak bazı istemciler bilinmeyen alanları atar. Uygulamaların ayrıntılı seçim verilerine ihtiyacı varsa sürümlendirilmiş bir şemaya sahip ayrı bir kimliği doğrulanmış model bilgisi uç noktası sağlayın. /v1/models sayısını SDK'lar, komut satırı araçları ve model seçiciler için yeterince küçük tutun.

Sabit veya sağlık açısından filtrelenmiş listeleri seçin

İki makul kullanılabilirlik politikası mevcuttur.

Durum filtreli katalog: hiçbir rota şu anda sağlıklı olmadığında bir modeli gizleyin. Bu, başarısız çağrıları en aza indirir, ancak olaylar sırasında kataloglar dalgalanabilir ve istemci tarafı seçimlerini geçersiz kılabilir.

Kararlı katalog: availability: temporarily_unavailable raporunu verirken yetkili ürünleri listelemeye devam edin. Bu, otomasyon ve taşıma araçları için daha kolaydır ancak istemciler, uzantıyı anlamadıkları sürece yine de arama yapmayı deneyebilir.

Pratik bir varsayılan, dağıtılmamış, yasaklanmış, kullanımdan kaldırılmış veya kimlik bilgilerine uygun olmayan modelleri gizlerken, güvenilir istemciler için açık bir duruma sahip, geçici olarak kullanılamayan modelleri korumaktır. Minimum uyumluluk uç noktası, mevcut istemcilerin durum meta verilerini yorumlayamaması durumunda kullanılamayan girişleri atlayabilir.

Tahmin: Daha zengin model seçimine sahip istemciler, giderek daha fazla yetenek ve kullanılabilirlik meta verilerine bağımlı hale gelecek. Bu davranış genel olarak güvenilir hale gelinceye kadar, sunucu tarafı yol girişinin yetkili kalması gerekir.

Eski izinleri sunmadan derlenmiş katalogları önbelleğe alın

Mümkünse katalogları istek yolunun dışında derleyin. Bir önbellek anahtarı en az şunu içermelidir:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Ekip üyeliği, model hibeleri, fiyatlandırma planları, sağlayıcı kimlik bilgileri, dağıtım durumu veya yönlendirme politikası değiştiğinde etkilenen girişleri geçersiz kılın. Kısa geçerlilik süresi değerleri, iptal olaylarının yerine geçmez: Kısa bir eski dönem bile yeni yasaklanmış bir modeli ortaya çıkarabilir.

Sağlayıcı mutabakatı eşzamansız olabilir. Sağlayıcı kontrol düzlemi kesintisi sırasında bilinen son kataloğu koruyun, gözlem süresini kaydedin ve yeni belirsiz rotaların uygun hale gelmesini önleyin. Bu, eski keşifleri yeni bir rotanın kullanılabilir olduğunun kanıtı olarak ele almadan listelemenin duyarlı olmasını sağlar.

Kataloğu bir kabul sözleşmesi olarak test edin

En güçlü uyumluluk özelliği basittir: Bir anahtara döndürülen her model ve API yüzey için, rota girişinin aynı katalog ve sistem durumu revizyonu altında başarılı olması gerekir.

Şunlar için otomatik testler ekleyin:

• İzin verilen bir anahtar, kendisine atanan modelleri görüyor ve alıyor.
• Liste girişlerini veya alınabilen meta verileri görmeyen yasaklı bir anahtar.
• Ekip kısıtlamaları anahtar erişimini genişletmek yerine daraltıyor.
• Yalnızca sohbete yönelik bir dağıtım, Yanıtlar için duyurulmuyor.
• Bağımlı rotalarını kaldıran, devre dışı bırakılmış bir kimlik bilgisi.
• Beklenen değişmez katalog revizyonuna çözümlenen bir takma ad.
• Varsayılan katalogdan kaldırılan kullanımdan kaldırılmış bir model.
• Hibeler, üyelikler veya politikalar değiştikten sonra önbelleğin geçersiz kılınması.
• Ayırt edilemeyen genel hatalara neden olan bilinmeyen ve gizli model kimlikleri.
• Reklamı yapılan her özelliğin en az bir uygun rotası vardır.

Sentetik problar bir rotanın işe yaradığına dair kanıt ekleyebilir ancak kota tüketir, maliyetli olabilir ve her özellik kombinasyonunu kapsayamaz. Bunları temsili rota sınıfları için kullanın ve bunları dağıtım durumu, kimlik bilgisi kontrolleri ve gerçek trafik durumu ile birleştirin.

Kararları açıklamak için yeterli kanıtı kaydedin

Kabul edilen veya reddedilen her istek için katalog revizyonunu, talep edilen genel model kimliğini, API yüzeyini, çözümlenen rotayı, yetenek sözleşmesini, politika revizyonunu ve yapılandırılmış kabul nedenini kaydedin. Bilgi istemi içeriğini yalnızca bu amaç için depolamaktan kaçının.

Uygulama sırası basittir: standart kaydı tanımlayın, sağlayıcı uzlaştırıcıları oluşturun, anahtar başına görünümleri derleyin, liste yapın ve bir yetkilendirme yüklemini alın, rota kabulünü aynı revizyona bağlayın ve önbellekleri etkinleştirmeden önce negatif testler ekleyin. Bu parçalar yerine oturduğunda /v1/models, "bu anahtar neyi çağırabilir?" sorusuna güvenilir bir yanıt haline gelir. gevşek bir şekilde filtrelenmiş bir envanter yerine.

İlgili okuma

• Yanıtlar API uyumluluk katmanı tasarlama