Ağ geçidi uyumluluk gereksinimleri

Codex ağ geçitleri burada açıklanan Responses API davranışlarını korumalıdır: uç noktalar, akış, konuşmanın devamı, araç çağrıları, kimlik doğrulama, yönlendirme ve yararlı hatalar.

İstekler ve uç noktalar

Bir ağ geçidi sağlayıcısını wire_api = "responses" ile yapılandırın. https://gateway.example.com/v1 gibi bir temel URL için ağ geçidi, POST /v1/responses isteklerini kabul etmeli ve istemcinin kullandığı istek ve yanıt alanlarını korumalıdır. Çalışan bir Chat Completions veya Anthropic Messages uç noktası, Responses uyumluluğunu kanıtlamaz.

Sağlık ve model listesi uç noktaları, isteğe bağlı operasyonel yardımcı araçlardır. Bunlar bir Codex konuşmasını sınamaz veya araç desteğini kanıtlamaz.

Akış

Sunucu tarafından gönderilen olayları (SSE), yanıtın tamamını arabelleğe almak yerine artımlı olarak iletin. Başarılı sonlandırmayı bildiren response.completed olayı da dahil olmak üzere olay türlerini ve yüklerini koruyun. İstemcinin başarısız bir yanıtı takılmış bir bağlantıdan ayırt edebilmesi için hata ve başarısızlık olaylarını iletin.

Akışın tamamını ağ geçidinin yanı sıra yük dengeleyiciler ve ters proxy'ler üzerinden de doğrulayın. Tamamlanmış bir akış olmadan alınan metin yanıtı yeterli değildir.

Konuşmanın devamı

Sonraki turlarda yeniden gönderilen konuşma girdisini koruyun. Ağ geçidi, bir sonraki tur için gereken önceki mesajları, araç çağrılarını ve araç sonuçlarını kabul etmelidir.

WebSocket veya artımlı aktarımı etkinleştirirseniz bunun previous_response_id davranışını da doğrulayın. Durum tutmayan bir HTTP Responses yolu, bu devam mekanizmasını gerektirmeden yeniden gönderilen girdiyi kullanabilir.

Araçlar

İşlev çağrısı öğelerini ve bunlarla eşleşen function_call_output öğelerini, çağrıları sonuçlarla ilişkilendiren tanımlayıcılar da dahil olmak üzere koruyun. Döngünün tamamı çalışmalıdır: Codex bir çağrı alır, aracı çalıştırır, sonucunu gönderir ve nihai bir yanıt alır.

Başarılı bir metin isteği bu döngüyü doğrulamaz. Etkinleştirmeyi planladığınız gerçek modelleri ve istemci özelliklerini test edin. Bir ağ geçidinin istek alanını kabul etmesi, üst sağlayıcı modelinin ilgili yeteneği uyguladığını kanıtlamaz.

Kimlik doğrulama ve üst bilgiler

Dağıtım için seçilen istemci kimlik doğrulama mekanizmasını destekleyin: env_key veya komut destekli bearer token'lar ya da özel bir üst bilgide gönderilen kimlik bilgileri için env_http_headers. Gizli üst bilgi değerleri için ortam değişkenlerini kullanın; bunları yapılandırmaya sabit olarak yazmayın. Yapılandırma ve kimlik bilgisi yardımcısı sözleşmesi için özel sağlayıcı başvuru belgesine bakın.

Geliştiricilerin kimliğini, ağ geçidinin üst sağlayıcı kimliğinden ayrı olarak doğrulayın. Yönetici anahtarlarını ve üst sağlayıcı kimlik bilgilerini ağ geçidinde tutun. Yönlendirme ve kullanıcıyla ilişkilendirme işlemlerinizin bağlı olduğu üst bilgileri koruyun; kimlik bilgilerinin süresinin dolmasını, yenilenmesini ve iptal edilmesini test edin.

Model yönlendirmesi ve meta veriler

Codex'e sunulan her model adı hedeflenen üst sağlayıcı modeline yönlendirilmelidir. Modelin kendisi hakkında verdiği açıklamaya güvenmek yerine rotayı ağ geçidi kayıtlarında doğrulayın.

Dağıtılan Codex sürümünün tanıdığı bir ad kullanın veya özel bir takma ad için eşleşen bir katalog sağlayın. Model kullanılabilirliğini ve geçiş meta verilerini de inceleyin: yerine geçecek her model istekleri ağ geçidi üzerinden almalıdır. Kuruluşa ait, geçiş içermeyen bir takma ad için katalog kaydındaki upgrade değerini null olarak ayarlayın. Katalog meta verileri istemci davranışına yön verir; bir modele yetenek eklemez veya ağ geçidi rotaları oluşturmaz. Bağlam sınırlarını, akıl yürütme seçeneklerini ve araçları gerçek üst sağlayıcı modeli ve sağlayıcıyla karşılaştırarak doğrulayın. Genel bir ağ geçidi bağlantısı, Codex'in yerleşik sağlayıcı entegrasyonlarının yaptığı meta veri düzenlemelerini otomatik olarak almaz.

Tanınan model adları

Dağıttığınız Codex sürümünün tanıdığı model adını ağ geçidi takma adı ve Codex model değeri olarak aynen kullanın. Üst sağlayıcının modeli desteklediğini ve kuruluşunuzun modeli onayladığını doğrulayın.

codex --version çıktısını kontrol edin ve Codex model kataloğunda eşleşen rust-v<version> etiketini seçin. Özel bir derleme için kaynak commit'ini kullanın; masaüstü dağıtımlarında paketle gelen CLI sürümüyle eşleştirin. Bu sürümün tanıdığı adları bulmak için kayıtların slug değerlerini kontrol edin. Ağ geçidi modelin yeteneklerini değiştiriyorsa ad tanınıyor olsa bile bu farkları yansıtan katalog meta verileri sağlayın.

Hatalar

İstemci kimlik doğrulama hataları, bilinmeyen model rotaları, istek sınırları ve üst sağlayıcı hataları arasındaki yararlı ayrımları koruyun. Tüm hataları genel bir 500 yanıtına indirgemeyin. Token'ları, sağlayıcı kimlik bilgilerini veya hassas istek içeriğini açığa çıkarmadan, hatanın oluştuğu katmanı teşhis etmeye yetecek bilgi döndürün.

Veri ve araç sınırları

Model trafiği şu yolu izler:

Codex client -> LLM gateway -> model provider

İstemci, bir geliştirici kimlik bilgisiyle ağ geçidinde kimlik doğrular. Ağ geçidi, modele erişmek için üst sağlayıcı kimlik bilgisini kullanır. Model isteklerine dahil edilen prompt'lar, kaynak alıntıları, araç argümanları ve araç sonuçları ağ geçidinden geçebilir. Günlük kaydı, saklama, hassas bilgileri maskeleme, erişim ve dışa aktarma denetimlerini buna göre ayarlayın.

Model ağ geçidi, Codex'in kurduğu her bağlantıyı yönlendirmez. Yerel komutlar istemcinin yürütme ortamında çalışır. MCP server'lar, eklenti hizmetleri, tarayıcı ve uygulama etkileşimleri ile etkinleştirilen diğer hizmetler ayrı ağ yollarına ve kimlik bilgilerine sahip olabilir. Model sağlayıcısı yapılandırması bu izinleri vermez veya bunların ağ denetimlerinin yerini almaz. Bu sınırlar için Ajan onayları ve güvenlik ve MCP sayfalarına bakın.

Uygunluk kontrol listesi

Dağıtılan her istemci, ağ geçidi ve model birleşimi için kanıt kaydedin:

• Responses istek ve yanıt alanları.
• Artımlı SSE iletimi ve başarılı sonlandırma.
• Yeniden gönderilen girdiyle devam turları.
• Seçilen aktarım kullanıyorsa previous_response_id.
• İşlev çağrıları, eşleşen sonuçlar ve nihai yanıt.
• Doğru model yönlendirmesi ve eşleşen meta veriler.
• Kullanıcı bazında ilişkilendirme, yenileme ve iptal.
• Yararlı kimlik doğrulama, yönlendirme, istek sınırı ve üst sağlayıcı hataları.
• Hassas bilgileri maskelenmiş tanılama verileri ve hedeflenen günlük kaydı ilkesi.

Yapılandırmayı dağıtmadan önce bu kanıtları toplamak için kullanıma sunma testi prosedürünü kullanın.