OpenAI Uyumlu API Ağ Geçidine Geçiş: Temel URL'yi Çevirmeden Önce Bir Uyumluluk Sözleşmesi Oluşturun

base_url, api_key ve model'yi değiştirmek, basit bir sohbet demosunun OpenAI uyumlu API ile uyumlu olması için genellikle yeterlidir. Üretim geçişinin güvenli olduğunu kanıtlamak yeterli değildir.

Hatalar genellikle daha sonra ortaya çıkar: akışlı araç çağrıları farklı bir biçimde gelir, JSON şema modu göz ardı edilir, bir yerleştirme modeli farklı bir vektör boyutu döndürür, kullanım alanları eksik, bir yan etkiyi iki kez göndermeyi yeniden dener veya sağlayıcıya özgü bir akıl yürütme seçeneği sessizce hiçbir şey yapmaz. Pratik amaç, özette bir uç noktanın "OpenAI uyumlu" olup olmadığını sormak değildir. Amaç, uygulamalarınızın OpenAI şeklindeki sözleşmenin hangi bölümlerine bağlı olduğunu tanımlamak, bu bölümleri test etmek ve yalnızca sözleşme açık hale geldikten sonra bir ağ geçidi üzerinden yönlendirmektir.

Bu kılavuz, bir ekibin sağlayıcıya özel SDK'lardan veya dağınık uyumlu uç noktalardan OpenAIuyumlu bir ağ geçidine güvenilirliği, kullanım ilişkilendirmesini ve geri alma seçeneklerini korurken nasıl taşınacağını gösterir.

Bu geçişte gerçek, öneri ve tahmin nedir?

Gerçekler: Çeşitli sağlayıcılar, API'lerinin bazı bölümleri için OpenAI-uyumlu yolları veya SDK kullanımını belgelemektedir. Google, OpenAI Python ve TypeScript kitaplıkları aracılığıyla Gemini erişimini ve API anahtarını, temel URL'yi ve modeli değiştirerek REST'i belgeler ve aynı zamanda halihazırda OpenAI kitaplıklarını kullanmayan uygulamalar için doğrudan Gemini API kullanımını önerir. Gemini'ın uyumluluk belgeleri; sohbet tamamlamaları, akış, işlev çağırma, görüntü anlama, yerleştirmeler, muhakeme çabası eşlemeleri ve ekstra istek gövdeleri aracılığıyla sağlayıcıya özel seçenekleri kapsar. AI, birden fazla modalite için OpenAI REST ve SDK uyumluluğunu birlikte belgeliyor, ancak matrisi aynı zamanda Asistanlar, İş Parçacığı ve Çalıştırmalar gibi desteklenmeyen OpenAI şeklindeki yüzeyleri de listeliyor. Mistral, temel URL'yi ve model adını değiştirerek OpenAI uyumlu istemciler için bir geçiş yolunu belgeliyor. Groq, OpenAI yollu sohbet tamamlama uç noktalarını açığa çıkarır. vLLM, parametre farklılıklarını belgelemenin yanı sıra tamamlamalar ve sohbet için OpenAI uyumlu bir sunucu sunar. OpenAI Agents SDK belgeleri, OpenAI dışı sağlayıcıların çoğunun henüz yeni Responses API'ı desteklemediği ve Sohbet Tamamlama modunun genellikle daha güvenli uyumluluk hedefi olduğu konusunda uyarıyor.

Öneriler: Uyumluluğu test edilmiş bir uygulama sözleşmesi olarak değerlendirin. Uygulamalarınızın kullandığı tam uç noktaların ve özelliklerin envanterini çıkarın, bir sağlayıcı ve model yetenek matrisi oluşturun, trafik geçişinden önce uyumluluk testleri yazın, ağ geçidi sınırında bilinen istek ve yanıt farklılıklarını normalleştirin ve uygulama bazında anahtarlar ve geri alma profilleriyle kullanıma açın.

Tahmin: OpenAI-uyumlu yüzeyler, en düşük sürtünmeli entegrasyon katmanı olarak kullanışlı olmaya devam edecek, ancak sağlayıcıya özgü özellikler farklılık göstermeye devam edecek. Uyumluluk sözleşmesi sürdüren ekipler, yeni modelleri resmi olmayan "kendisini değiştirme" varsayımlarına dayanan ekiplere göre daha hızlı benimseyebilecektir.

1. Adım: mevcut tüm AI çağrılarının envanterini çıkarın

Kod değişiklikleriyle değil envanterle başlayın. Ekipler, tüm AI çağrılarının sohbet tamamlamaları gibi göründüğünü varsaydığında ve gizli bağımlılıkları yalnızca sürümden sonra keşfettiğinde taşıma işlemi başarısız olur.

Çağrı sitesi başına bir satır oluşturun. Planlanmış işleri, dahili araçları, not defterlerini, arka plan çalışanlarını, değerlendirme donanımlarını ve müşteriye yönelik hizmetleri dahil edin.

app: support-assistant
owner: customer-platform
current_provider: provider_a
current_sdk: provider_a_python_sdk
endpoint_shape: chat.completions
model: provider-a-large-2026
features:
  - streaming
  - tool_calls
  - json_schema_output
  - usage_accounting
latency_budget_ms: 8000
retry_policy: retry_429_5xx_no_tool_side_effects
monthly_volume_estimate: 2.4M requests
rollback_contact: oncall-customer-platform

Her çağrıyı yalnızca modele göre değil, uç noktaya ve özelliğe göre sınıflandırın. Tek bir model adı, nasıl kullanıldığına bağlı olarak çok farklı uyumluluk gereksinimlerini gizleyebilir.

Envanter kontrol listesi

• Sohbet: mesajlar, sistem talimatları, sıcaklık, en yüksek puan, maksimum belirteçler, durdurma dizileri.
• Akış: sunucu tarafından gönderilen etkinlik ayrıştırıcı, son parçalar, akışta kullanım, iptal davranışı.
• Araçlar: işlev şemaları, paralel çağrılar, bağımsız değişken JSON, araç sonuç mesajları, yan etki güvenliği.
• Yapılandırılmış çıkışlar: JSON modu, JSON şeması, katı doğrulama, geri dönüş onarım mantığı.
• Görme veya çok modlu giriş: resim URL'si, base64, MIME işleme, ayrıntı parametreleri.
• Yerleştirmeler: model kimliği, vektör boyutu, normalleştirme beklentileri, dizin uyumluluğu.
• Dosyalar ve toplu iş: yükleme API'leri, iş yoklama, iptal, çıktı biçimleri.
• Akıl yürütme kontrolleri: akıl yürütme çabası, bütçeyi düşünme, gizli belirteçler, sağlayıcıya özel ayarlar.
• Hatalar: hız sınırı şekli, zaman aşımı şekli, içerik politikası hataları, yeniden denenebilir durum kodları.
• Kullanım ve faturalandırma: bilgi istemi belirteçleri, tamamlama belirteçleri, önbelleğe alınmış belirteçler, akıl yürütme belirteçleri, maliyet tahsis etiketleri.

Bu adımın çıktısı bir bağımlılık haritasıdır. Basit bir OpenAI-uyumlu API profiliyle hangi uygulamaların taşınabileceğini ve hangi uygulamaların bağdaştırıcı çalışması gerektirdiğini size bildirir.

2. Adım: bir uyumluluk sözleşmesi tablosu oluşturun

Uyumluluk sözleşmesi, her uygulama özelliği için ağ geçidinin neyi garanti etmesi gerektiğini ve onu nasıl test edeceğinizi belirten bir tablodur. Mühendislik ve ürün ekiplerinin kullanıma sunma kararları vermesine yetecek kadar spesifik olmalıdır.

Bu tablo aynı zamanda aşırı söz vermeyi de önler. Bir sağlayıcı sohbeti ve yerleştirmeleri destekliyor ancak dosyalar veya asistanlar benzeri bir iş akışını desteklemiyorsa, sözleşmede bunu belirtmelidir. "Desteklenmiyor", üretim sürprizinden kaçındığı takdirde geçerli bir taşıma sonucudur.

3. Adım: Model kimliklerini dağıtmak yerine model profilleri oluşturun

Her uygulamada sabit kodlu bir model kimliğini başka bir sabit kodlu model kimliğiyle değiştirmeyin. Model profillerini kullanın.

profile: support-chat-fast
openai_model_alias: support-chat-fast
provider: provider_b
provider_model: provider-b/chat-large-fast
endpoint: chat.completions
features:
  streaming: true
  tools: true
  structured_outputs: schema_validated
  vision: false
  embeddings: false
request_policy:
  drop_unsupported_params: false
  reject_unknown_params: true
  pass_through_extra_body: ["reasoning_effort"]
fallback_profile: support-chat-safe
cost_center_required: true

Bu profil, ağ geçidi sağlayıcı eşlemesinin sahibiyken uygulamalara sabit bir ad verir. Ayrıca düz model ad alanı yerine ad alanlı model kimlikleri kullanan sağlayıcıları da yönetir. Uygulama support-chat-fast kodunu ister; ağ geçidi, bunun şu anda Birlikte tarzı bir ad alanı modeliyle, Gemini uyumlu bir modelle, Mistral uyumlu bir modelle, bir Groq sohbet modeliyle, kendi kendine barındırılan bir vLLM uç noktasıyla veya başka bir onaylanmış hedefle eşleşip eşleşmediğine karar verir.

Buradaki ödün, yönetişim yüküdür. Profiller belgelenmeli, gözden geçirilmeli ve versiyonları oluşturulmalıdır. Avantajı, taşıma, geri alma ve model değiştirme işlemlerinin her uygulamanın yeniden konuşlandırılmasını gerektirmemesidir.

4. Adım: Geçişten önce uyumluluk testlerini yazın

Uygunluk testleri, sözleşmenizi her hedef profil için doğrulayan küçük, tekrarlanabilir kontrollerdir. İlk kullanıma sunmadan önce ve sağlayıcı, model, SDK veya ağ geçidi bağdaştırıcısı değiştiğinde çalıştırılmalıdır.

Minimum test paketi

• Altın istem testleri: Belirleyici istemler gönderin ve yanıt şeklini, bitiş nedenini, güvenlik davranışını ve temel anlamsal gereksinimleri doğrulayın. Uygulama gerçekten buna bağlı olmadığı sürece tam ifadelere gerek duymayın.
• Akış ayrıştırıcı testleri: İstemcinizin her parçayı ayrıştırabildiğini, son metni yeniden oluşturabildiğini, iptal işlemini gerçekleştirebildiğini ve akışın tamamlandığını algılayabildiğini doğrulayın.
• Araç çağrısı gidiş dönüşleri: Bir araç çağrısını zorlayın, bağımsız değişkenleri ayrıştırın, sahte bir araç çalıştırın, araç sonucunu döndürün ve modelin doğru şekilde devam ettiğini onaylayın.
• Araç çağrısı akış testleri: Kısmi bağımsız değişken deltalarının, araç çalıştırılmadan önce arabelleğe alınabileceğini ve yeniden oluşturulabileceğini doğrulayın. Değilse, söz konusu profil için artımlı araç yürütmeyi devre dışı bırakın.
• JSON şema doğrulaması: Geçerli çıktıyı, geçersiz çıktıyı, eksik alanları, ekstra alanları ve ret veya hata durumlarını test edin.
• Gömme boyut kontrolleri: Mevcut bir dizini yeniden kullanmadan önce vektör uzunluğunu, sayısal türü ve hedef vektör dizini ile uyumluluğunu doğrulayın.
• Yeniden deneme ve yetersizlik testleri: 429, 500, zaman aşımı ve kısmi akış hatalarını simüle edin. Araç yan etkilerinin yanlışlıkla tekrarlanmadığından emin olun.
• Kullanım mutabakatı: Ağ geçidi kullanım kayıtlarını sağlayıcı tarafından bildirilen kullanım alanlarıyla ve fatura defteri beklentilerinizle karşılaştırın.

Testleri üretim trafiği modellerine yakın tutun. Tek bir "şiir yaz" istemi, araçlara, JSON, yerleştirmelere ve kullanım hesaplamasına bağlı bir iş akışı hakkında neredeyse hiçbir şeyi kanıtlamaz.

5. Adım: Ağ geçidi sınırındaki tuhaflıkları normalleştirin

OpenAI uyumlu bir ağ geçidi, uygulama kodu değişikliklerini azaltmalıdır, ancak her sağlayıcının aynı şekilde davrandığını iddia etmemelidir. Bilinen farklılıklar için bağdaştırıcıları kullanın ve davranışı görünür hale getirin.

Normalleştirme isteğinde bulun

• Model takma adları: Uygulamaya yönelik kararlı profil adlarını sağlayıcıya özel model kimlikleriyle eşleyin.
• Desteklenmeyen parametreler: Desteklenmeyen parametreleri varsayılan olarak açık bir hatayla reddedin. Sessiz bırakma, demolar sırasında kullanışlıdır ve üretimde tehlikelidir.
• Sağlayıcıya özel seçenekler: Akıl yürütme veya düşünme kontrolleri gibi kontrollü geçiş alanlarına yalnızca belgelenmiş model profillerinde izin verin.
• Mesaj dönüşümü: Hedef sağlayıcının farklı bir şekil beklediği sistem, geliştirici, kullanıcı, asistan ve araç mesajlarını normalleştirin.
• Zaman aşımı bütçeleri: SDK varsayılanın birikmesine izin vermek yerine, başvuru düzeyinde tek bir son tarih uygulayın.

Yanıt normalleştirme

• Metin ve araç seçenekleri: Asistan metni, araç çağrıları ve bitiş nedenleri için tutarlı bir şekil döndürün.
• Akış parçaları: Ortak deltaları normalleştirin ve ara belleğe almanın gerekli olduğu yerleri belgeleyin.
• Kullanım alanları: Mağaza sağlayıcısının yerel kullanımına ek olarak normalleştirilmiş istem, tamamlama ve mevcut olduğunda toplam jeton sayıları.
• Hata şekli: Durum kodlarını, yeniden denenebilirliği, sağlayıcı hata kodunu ve istek kimliğini tek bir hata şemasında eşleyin.
• Maliyet meta verileri: Daha sonra analiz etmek için uygulama, ekip, profil, sağlayıcı, model ve ortam etiketlerini ekleyin.

Temel denge, taşınabilirlik ile sağlayıcının gücüdür. En küçük ortak yüzeye normalleştirme, değiştirilebilirliği artırır. Sağlayıcıya özel alanlara izin vermek, gelişmiş yetenekleri korur ancak her geçiş seçeneği, profil belgelerinin ve test matrisinin parçası haline gelir.

6. Adım: Uygulamaya özel anahtarlar ve geri alma profilleriyle kullanıma sunma

Taşıma işlemi, kodun yeniden dağıtımı olmadan geri alınabilmelidir. Her uygulama, ortam ve ekip için ayrı API tuşları kullanın. Tek bir paylaşılan anahtar, kullanım ilişkilendirmesini ve acil durumda geri dönüşü zorlaştırır.

Güvenli bir kullanıma sunma sırası şuna benzer:

1. Geliştirme profili: Ağ geçidi üzerinden yalnızca yerel ve aşamalı trafiği yönlendirin. İstek şekli ve ayrıştırıcı sorunlarını düzeltin.
2. Gölge testleri: Kullanıcının görebildiği çıktıyı etkilemeden destek teknisyeni isteklerini yeni profile yeniden oynatın. Şema geçerliliğini, araç davranışını, gecikme sınıfını ve kullanım alanlarını karşılaştırın.
3. Küçük üretim dilimi: Trafiğin düşük bir yüzdesini veya bir dahili kiracıyı taşıyın. Hataları, yeniden denemeleri, kullanıcıya yönelik kalite sinyallerini ve maliyeti izleyin.
4. Uygulama başına genişletme: Her seferinde bir uygulamayı taşıyın. Aynı risk profilini paylaşmadıkları sürece sohbeti, yerleştirmeleri, toplu işlemleri ve dosyaları birlikte taşımayın.
5. Geri alma profili: İyi olduğu bilinen bir sağlayıcı/model profilini, uygulamaya yönelik aynı takma adın veya hızlı bir yapılandırma anahtarının arkasında kullanılabilir durumda tutun.
6. Taşıma sonrası kilit: Kararlı hale geldikten sonra, trafiğin ağ geçidi kontrollerini atlayamaması için doğrudan sağlayıcı anahtarlarını uygulama ortamlarından kaldırın.

Geri alma, diğer yollar gibi test edilmelidir. Ağ geçidinde bir model profili değiştirilebiliyorsa bu anahtarı sessiz bir dönemde test edin ve uygulama günlüklerinin, kullanım analizlerinin ve faturalandırma ilişkilendirmesinin tutarlı kaldığını doğrulayın.

Örnek: dağınık uç noktaları tek bir ağ geçidi sözleşmesiyle değiştirmek

Bir ekibin üç uygulaması olduğunu varsayalım:

• Akışlı sohbet ve araçları kullanan bir müşteri destek asistanı.
• Kesin JSON çıktısı gerektiren bir içerik sınıflandırıcı.
• Bir vektör veritabanında depolanan yerleştirmeleri kullanan bir arama hizmeti.

Riskli bir geçiş, üç uygulamayı da aynı temel URL'ye değiştirecek ve üç yeni model kimliği seçecektir. Daha güvenli bir geçiş, sözleşmeleri ayırır:

• destek sohbet profili: Akış, araç çağrıları, ara belleğe alınmış araç çağrısı deltaları, yeniden deneme sınıflandırması ve kullanım günlüğünü gerektirir.
• sınıflandırıcı-json profili: Şema doğrulaması, reddetme yönetimi gerektirir ve sessiz parametre bırakma işlemi gerektirmez.
• arama yerleştirme profili: Boyutun değişmesi durumunda sabit bir vektör boyutu ve dizin taşıma planı gerektirir.

Her profilin kendi uygunluk testleri ve kullanıma sunumu yapılır. Destek asistanının akış bağdaştırıcısı çalışmasına ihtiyacı olabilir. Şema doğrulaması modelin dışındaysa sınıflandırıcı hızlı bir şekilde geçebilir. Yerleştirme hizmeti, yerinde model değişimi yerine yeni bir dizin gerektirebilir. Ağ geçidi ekibe OpenAI uyumlu bir temel URL verir, ancak uyumluluk sözleşmesi geçişin dürüst olmasını sağlar.

Taşıma kontrol listesi

• Arka plan işleri ve dahili komut dosyaları da dahil olmak üzere tüm AI çağrı sitelerini listeleyin.
• Çağrıları uç nokta, özellik, model, sahip ve geri alma yoluna göre sınıflandırın.
• Sabit kodlu sağlayıcı model kimlikleri yerine uygulamaya yönelik model profillerini tanımlayın.
• Her sağlayıcı ve model profili için bir yetenek matrisi oluşturun.
• Profil açıkça geçişe izin vermediği sürece desteklenmeyen parametreleri reddet.
• Akış, araçlar, yapılandırılmış çıktılar, yerleştirmeler, hatalar, yeniden denemeler ve kullanım alanlarını test edin.
• İlişkilendirme ve kontrol için uygulama başına ve ortam başına API anahtarlarını kullanın.
• Kullanıcı tarafından görülebilen üretim trafiğinden önce gölge testleri çalıştırın.
• Tek seferde tek bir uygulamayı veya özellik sınıfını kullanıma sunun.
• Kod yeniden dağıtımları olmadan test edilmiş bir geri alma profilini kullanılabilir durumda tutun.

Harekete geçirilebilir sonuç

OpenAI ile uyumlu bir API ağ geçidi, yalnızca farklı bir URL değil, kontrollü bir taşıma katmanı haline geldiğinde en değerli hale gelir. Temel URL anahtarı, mekanik kod değişikliklerini azaltır. Uyumluluk sözleşmesi operasyonel riski azaltır.

Üretim trafiğini çevirmeden önce uygulamalarınızın gerçekte neyi gerektirdiğini yazın: akış davranışı, araç semantiği, şema garantileri, yerleştirme boyutları, yeniden deneme kuralları, kullanım alanları ve hata anlamları. Bu gereksinimleri model profillerine, bağdaştırıcı kurallarına ve uygunluk testlerine dönüştürün. Daha sonra uygulamaya özel anahtarlar, analizler ve geri alma profillerini kullanıma sunun.

Basit sohbet yolu işe yarıyorsa bunu iyi bir başlangıç ​​olarak değerlendirin. Geçişin geri kalanını veritabanı, kuyruk veya ödeme sağlayıcı değişikliğiyle aynı disiplini hak eden mühendislik işi olarak ele alın.

İlgili okuma

• birden fazla model sağlayıcı arasında yapılandırılmış çıktı doğrulama
• model değiştirme ve geri alma runbook'u
• kullanım analizi ve belirteç ağ geçidinde mutabakat