AI API Ağ Geçidinde Responses API Uyumluluk Katmanı Oluşturma
Responses API ağ geçidi yalnızca yeni bir rotaya sahip bir Sohbet Tamamlama proxy'si değildir. Birinci sınıf bir uyumluluk katmanıyla yanıt öğelerini, durumu, araç çağrılarını, akışları, akıl yürütme sürekliliğini, kullanım ilişkilendirmesini ve sürüm düşürme davranışını koruyun.
/v1/responses'u, her isteği /v1/chat/completions biçimine çevirerek ve şeklin yeterince yakın olmasını umarak uygulamayın. Bu bağdaştırıcı metin döndürebilir ancak geliştiricilerin önemsediği parçaları sessizce kaybedebilir: yanıt öğeleri, sunucu tarafı durumu, araç çağrıları, akıl yürütme sürekliliği, akış yaşam döngüsü olayları, iptal semantiği ve öğe düzeyinde kullanım ilişkilendirmesi.
Pratik amaç, Responses API'yi daha zengin bir protokol olarak ele alan bir uyumluluk katmanıdır. Mevcut istemciler için Sohbet Tamamlama desteğini sürdürün, ancak Yanıtları kendi durum modeli, akış normalleştiricisi, araç çağrısı defteri, yetenek matrisi ve geri dönüş kurallarıyla kendi ağ geçidi yüzeyi olarak oluşturun.
Gerçek nedir, politika nedir ve tahmin nedir?
Gerçekler: OpenAI, Responses API'yi web araması, dosya arama ve bilgisayar kullanımı gibi araçlara yönelik destek de dahil olmak üzere daha önce Sohbet Tamamlamaları ve Asistanlar arasında bölünmüş olan birleştirici yetenekler olarak tanımlıyor. API, önceki_response_id, akış, araç seçimi ve yerleşik araçlar gibi alanları ortaya çıkarır. SDK belgeleri, predivisponse_id'nin konuşma sürekliliği sağlayabildiğini, önceki talimatların otomatik olarak ileriye taşınmadığını ve hâlâ geçerli olmaları gerektiğinde yeniden gönderilmesi gerektiğini gösteriyor. OpenAI'nin akış referansı yalnızca belirteç deltaları yerine farklı yanıt yaşam döngüsü ve çıktı olaylarını içerir.
Öneriler: Bir ağ geçidi, bu anlambilimi varsayılan olarak düzleştirmek yerine korumalıdır. Hedef sağlayıcı gerekli davranışı destekleyemediğinde istekleri reddetmeli veya açıkça düşürmelidir.
Tahmin: Daha fazla aracı iş yükü, yanıt öğesi yapısına, araç yürütme izlerine ve durum bilgisi olan akıl yürütme bağlamına bağlı olacaktır. Bu kavramları modelleyen ağ geçitlerinin genişletilmesi artık Yanıtları kozmetik bir uç nokta olarak ele alan ağ geçitlerine göre daha kolay olacak.
Yanıtlar için ayrı bir uyumluluk sözleşmesi tanımlayın
İlk uygulama hatası, OpenAI uyumlu tek bir evrensel istek ve yanıt şeması anlamına geldiğini varsaymaktır. Pratikte /v1/chat/completions ve /v1/responses ayrı uyumluluk sözleşmeleri olmalıdır.
Paylaşılan bir kimlik doğrulama, faturalandırma, kota ve yönlendirme katmanını koruyun ancak protokol katmanını ayırın:
- Sohbet Tamamlamaları ortaya çıkıyor: mesajlar, seçimler, deltalar, sohbet biçimindeki araç çağrıları, eski istemci davranışı.
- Yanıtlar yüzeyi: giriş öğeleri, çıkış öğeleri, yanıt kimlikleri, önceki yanıt referansları, daha zengin araç etkinlikleri, yaşam döngüsü akışı etkinlikleri, akıl yürütmeyle ilgili alanlar ve son yanıt durumu.
Bu ayrım uygunluk testleri açısından önemlidir. Sohbet testlerini geçen bir sağlayıcı bağdaştırıcısı, önceki_response_id'yi, öğe sıralamasını, ret yapısını, barındırılan araç meta verilerini veya akış etkinliği adlarını
Asgari uyumluluk sözleşmesi aşağıdakilere cevap vermelidir:
- Hangi istek alanları kabul edilir, reddedilir, dönüştürülür veya yoksayılır?
- Hangi yanıt öğesi türleri korunur?
- Sağlayıcı ve modele göre hangi araç türleri desteklenir?
- Sağlayıcı konuşma durumunu koruyabilir mi, yoksa ağ geçidinin bunu sürdürmesi mi gerekir?
store=falseistendiğinde ne olur?- Hangi akış etkinlikleri garanti edilir?
- İptal, zaman aşımı ve kısmi kullanım nasıl kaydedilir?
Halihazırda bir AI API ağ geçidiniz varsa, Responses desteğini bir rota takma adı olarak değil, bir protokol genişletmesi olarak değerlendirin.
Kanonik yanıt öğesi modeli kullanın
Yanıtlar API'si birden fazla asistan mesajı döndürür. Farklı çıktı öğelerini ve olaylarını temsil edebilir. Ağ geçidinizin herhangi bir sağlayıcıyla eşleşmeden önce dahili bir kanonik modele ihtiyacı vardır.
Pratik bir dahili öğe şeması şu şekilde başlayabilir:
<ön>Öğe türlerini, her sağlayıcı bunları üretmeden önce bile ekleyin. Yararlı kategoriler şunları içerir:
- Metin çıkışı
- Retler
- İşlev çağrıları
- Uygulama tarafından gönderilen işlev çıktıları
- Mevcut olduğu durumlarda akıl yürütme özetleri veya akıl yürütmeyle ilgili meta veriler
- Dosya referansları
- Web araması, dosya arama, bilgisayar kullanımı veya barındırılan diğer araç etkinlikleri
- Nihai kullanım ve faturalandırma meta verileri
Amaç, özel bir şemayı kullanıcılara göstermek değil. Önemli olan, ağ geçidinin bilgileri denetlemeden, faturalandırmadan, yayınlamadan, yeniden oynatmadan veya dönüştürmeden önce bilgileri çöpe atmasını önlemektir.
Ağ geçidine ait bir durum defteri oluşturun
önceki_response_id, durum bilgisi olmayan sohbet proxy'si ile Yanıtlar uyumluluğu arasındaki farkı en çok ortaya koyan alandır. İstemci önceki bir yanıta başvuruyorsa ağ geçidinin bu kimliğin ne anlama geldiğini, kiracının bunu kullanmasına izin verilip verilmediğini ve sağlayıcının bundan devam edip edemeyeceğini bilmesi gerekir.
Kiracı ve yanıt kimliğine göre anahtarlanan bir durum defteri oluşturun:
<ön>Önemli kural: Kiracı bu saklama ve maliyet davranışına açıkça izin vermediği sürece sohbet geçmişinin tamamını yeniden oynatarak önceki_response_id kodunu otomatik olarak taklit etmeyin. Tekrar oynatma, belirteç maliyetini artırabilir, gizlilik durumunu değiştirebilir ve model davranışını değiştirebilir. Açık bir yetenek hatası döndürmek, uygulamanın saklamanızı veya yeniden kullanmanızı beklemediği, depolanan konuşma içeriğini sessizce göndermekten daha güvenlidir.
Durum işleme modları
- Sağlayıcı durumu: Yukarı akış sağlayıcı yeterli bağlamı depolar ve ağ geçidi, ağ geçidi yanıt kimliklerini sağlayıcı yanıt kimlikleriyle eşler.
- Ağ geçidi durumu: Ağ geçidi gerekli önceki öğeleri saklar ve izin verildiğinde bağlamı yeniden oluşturur.
- Durum yok: İstekte
store=falsekullanılıyor veya kiracı politikası saklamayı yasaklıyor. Sağlayıcı, ağ geçidini alıkoymadan isteği yerine getiremediği ve politikanın buna izin vermediği süreceönceki_response_idreddedilmelidir.
Ayrıca, uygulanmaya devam etmeleri gerektiğinde önceki talimatların müşteri tarafından yeniden gönderilmesi gerekebileceğini de unutmayın. Ağ geçidi, bu davranış açık bir kiracı politikasının parçası olmadığı sürece telafi etmek için gizli talimatlar icat etmemelidir.
Araçları göndermeden önce doğrulayın
Yanıtlar araç kullanımını daha merkezi hale getirir. Bir uyumluluk katmanı iki geniş kategoriyi ele almalıdır:
- Uygulama araçları: İstemci tarafından sağlanan, model sağlayıcının dışında yürütülen ve çıktıların API'ye geri gönderildiği işlev tanımları.
- Barındırılan sağlayıcı araçları: Web araması, dosya arama, bilgisayar kullanımı, kod yürütme, temellendirme veya sağlayıcı veya ağ geçidi tarafından kontrol edilen altyapı tarafından yürütülen benzer araçlar.
Girişte, yönlendirmeden önce araç şemalarını doğrulayın:
- Geçersiz JSON Şemasını erken reddedin.
- Maksimum şema boyutunu ve iç içe yerleştirme derinliğini zorunlu kılın.
- Sağlayıcı uyumluluğu için araç adlarını kontrol edin.
- Kiracı, anahtar, kullanıcı ve ortam kapsamlarını uygulayın.
- Veri yazan, para harcayan, hassas sistemlere erişen veya harici bağlayıcıları çağıran araçlar için onay kapılarını zorunlu kılın.
Uygulama işlevi çağrısı için sabit bir çağrı kimliğine ihtiyacınız var. Model, call_id ile bir işlev çağrısı yayınlar; uygulama bu kimliğe referans veren araç çıktısını gönderir; ağ geçidi her ikisini de aynı izde kaydeder. Bu birleştirme anahtarı olmadan denetim günlükleri ve yeniden denemeler belirsiz hale gelir.
Barındırılan araçlar için, gönderimden önce bütçe ayırın ve maliyeti daha sonra belirleyin. Barındırılan araçlar, olağan jeton hesaplamasının dışında ücretler ekleyebilir; bu nedenle, bu maliyetleri genel bir model çağrısı toplamının içinde gizlemek yerine, araç defterini birleşik AI API faturalandırmasına bağlayın.
Akış akışını belirteç metni olarak değil, etkinlik olarak normalleştirin
Bir sohbet proxy'si genellikle jeton deltalarını iletmekten kurtulabilir. Yanıtlar ağ geçidi bunu yapamaz. Akışın yaşam döngüsü anlamı vardır: bir yanıt başlayabilir, çıktı öğeleri başlayabilir ve tamamlanabilir, metin deltalar halinde gelebilir, araç çağrıları aşamalı olarak birleştirilebilir, kullanım akış sonunda veya akış sırasında gelebilir ve yanıt başarısız olabilir veya iptal edilebilir.
Bir ağ geçidi olay şeması tanımlayın ve ardından her sağlayıcı akışını bununla eşleştirin:
olay: yanıt_başladı
veri: { "response_id": "gw_resp_123", "status": "in_progress" }
olay: çıktı_item_startedveri: { "item_id": "item_1", "type": "text" }
olay: text_delta
data: { "item_id": "item_1", "delta": "Merhaba" }
olay: tool_call_delta
data: { "item_id": "item_2", "call_id": "call_abc", "arguments_delta": "{\"order" }
olay: kullanım_delta
veri: { "çıkış_belirteçleri": 12 }
olay: tamamlandı
data: { "response_id": "gw_resp_123", "usage": { ... } Önerilen normalleştirilmiş etkinlikler:
response_startedoutput_item_startedoutput_item_completedtext_deltarefusal_deltatool_call_deltatool_result_receivedusage_deltatamamlandıiptal edildibaşarısız oldu
İstemcinin bağlantısı kesildiğinde, sağlayıcı destekliyorsa iptal işlemini yukarı yönde yayın. Kısmi yanıt durumunu her iki şekilde de kaydedin. Sağlayıcı daha sonra gecikmeli bir geri arama veya son parça yoluyla son kullanımı geri verirse, defterin mutabakatını yapın. Akış uyumluluğu, gecikmeyle olduğu kadar hesaplama ve yaşam döngüsüyle de ilgilidir.
Sağlayıcı yetenek matrisi oluşturun
Çok modelli yönlendirme yalnızca ağ geçidinin neyin güvenli bir şekilde yönlendirilebileceğini anlaması durumunda kullanışlıdır. Model kataloğunuza Yanıtlara özel yetenekler ekleyin:
<ön>Yedekleme kayıp bilincinde olmalıdır. İstek yerleşik web araması gerektiriyorsa ve yedek sağlayıcı bunu gerçekleştiremiyorsa, arama yapmadan sessizce yanıt vermeyin. İstek, korunan muhakeme bağlamına bağlıysa ve geri dönüş yolu bunu koruyamıyorsa, bir yetenek hatası veya istemcinin açıkça tercih ettiği bir sürüm düşürme yanıtı döndürün.
Yararlı bir istek seçeneği:
<ön>Daha az hassas kullanım durumları için, kiracılar belirli kayıplı sürüm düşürmelere izin verebilir:
<ön>Ağ geçidi her iki durumda da geri dönüş kararını günlüğe kaydetmelidir. Bu, bir aracının sağlayıcı kesintisi veya modelin yeniden yönlendirilmesi sonrasında farklı davranması durumunda daha sonra hata ayıklamayı mümkün kılar.
Yanıt ve öğe düzeyinde kullanımı ilişkilendirin
Yanıt aramaları, araç çalıştırma, daha uzun bağlam, akıl yürütme belirteçleri, dosya arama, web araması veya tekrarlanan talimatlar içerebileceğinden, eşdeğer sohbet tamamlamalarından daha maliyetli olabilir. AI API kullanım analizi kontrol paneli için tek bir toplam jeton sayısı yeterli değildir.
Kullanımı iki düzeyde kaydedin:
- Yanıt düzeyi: kiracı, anahtar, kullanıcı, model, sağlayıcı, gecikme, son durum, giriş jetonları, çıktı jetonları, raporlanan akıl yürütme jetonları, toplam maliyet ve geri dönüş yolu.
- Öğe/araç düzeyi: araç adı, çağrı kimliği, barındırılan araç birimleri, dosya kimlikleri, varsa arama sorgusu sayısı, araç gecikmesi, araç maliyeti ve onay politikası sonucu.
Bu, geliştiricilerin somut soruları yanıtlamasına olanak tanır:
- Daha uzun durum, akıl yürütme çabası, araç çağrıları veya geri dönüş nedeniyle maliyet arttı mı?
- Barındırılan araç ücretlerini hangi kiracı veya API anahtarı oluşturuyor?
- Bir araç çağrısından sonra ancak son metinden önce hangi yanıt başarısız oldu?
- Hangi iptal edilen akışlar hâlâ yukarı akış kullanımına neden oluyor?
Sıfır saklama ve silme işlemlerini birinci sınıf bir davranış olarak ele alın
Sunucu tarafı durumu faydalıdır ancak ağ geçidinin saklama yükümlülüklerini değiştirir. Politikayı bir günlük kaydı ayarı olarak ele almak yerine protokol katmanına ekleyin.
Her Yanıt isteği için aşağıdakileri çözümleyin:
- Kiracıyı elde tutma politikası
- İstek düzeyi
depolamatercihi - Sağlayıcıyı elde tutma uyumluluğu
- Ağ geçidinin yeniden oynatılmasına izin verilip verilmediği
- Araç giriş ve çıkışlarının depolanıp depolanamayacağı
- Yanıt durumu için süre sonu ve silme davranışı
Saklama devre dışı bırakılırsa, ağ geçidi yine de minimum düzeyde operasyonel meta veriyi tutabilir: zaman damgaları, kimlikler, durum, jeton sayıları, maliyet ve politika kararları. Politika izin vermediği sürece ham istemleri, tam araç çıktılarını veya yeniden oluşturulmuş geçmişi depolamaktan kaçının.
Lansmandan önce eklenecek uyumluluk fikstürleri
Mutlu yol manuel testlerine güvenmeyin. Doğrudan OpenAI rotaları, sağlayıcı tarafından uyarlanan rotalar ve geri dönüş senaryoları genelinde protokol davranışını doğrulayan fikstürler ekleyin.
Minimum test seti
- Temel yanıt: metin öğesi, kararlı yanıt kimliği ve kullanımıyla döndürülür.
- Çoklu dönüş durumu: ikinci istek,
önceki_response_id'ye referans verir; ağ geçidi kiracının sahipliğini ve durum modunu doğrular. - Yinelenen talimatlar: atlanan talimatların ağ geçidi tarafından sessizce icat edilmediğini doğrulayın.
- Gidiş işlev çağrısı: model, çağrı kimliğini yayınlar; uygulama çıktıyı gönderir; son yanıt her iki kaydı da birleştirir.
- Barındırılan araç politikası: Yetkisiz yerleşik araç gönderilmeden önce engellenir.
- Akış sırası: yanıt başlangıcı, öğe başlangıcı, deltalar, öğe tamamlama, kullanım ve tamamlama geçerli sırayla yayınlanır.
- Akış iptali: istemci bağlantısının kesilmesi desteklendiğinde yukarı akış iptalini tetikler ve kısmi kullanımı kaydeder.
- Geri dönüş reddi: gerekli Yanıt anlambilimine sahip olmayan sağlayıcı, yetenek hatası döndürür.
- Kayıplı geri dönüş seçeneği: İzin verilen kayıplara sahip istek, açık bir sürüm düşürme işaretçisi alır.
- Sıfır saklama modu: durum tekrarı ve ağ geçidi tarafı istemi saklama engellenir.
Önerilen kullanıma sunma sırası
- Bir beta rotası ortaya çıkarın. Mevcut sohbet davranışını değiştirmeden
/v1/responsesekleyin. - Yerel Yanıt desteğine sahip sağlayıcılar için öncelikle doğrudan geçişi uygulayın. Kimlikleri, öğeleri, akışları, kullanımı ve hataları koruyun.
- Durum defterini ekleyin. Ağ geçidi kimliklerini sağlayıcı kimlikleriyle eşleyin ve kiracı sahipliğini zorunlu kılın.
- Kurallı öğeler ekleyin. Denetim, faturalandırma ve akışın yeniden yapılandırılması için gereken öğe meta verilerini saklayın.
- Araç yönetimi ekleyin. Şemaları doğrulayın, kapsamları uygulayın ve araç çağrısı birleştirmelerini kaydedin.
- Akış normalleştirmesi ekleyin. Sağlayıcıya özel akışları ağ geçidi yaşam döngüsü etkinliklerine dönüştürün.
- Yeteneklere duyarlı yönlendirme ekleyin. Varsayılan olarak yalnızca güvenli geri dönüşlere izin verin.
- Analiz ve faturalandırma yerleşimi ekleyin. Belirteci, gerekçeyi ve araç kullanımını ayrı ayrı ilişkilendirin.
- Uyumluluk notları yayınlayın. Geliştiricilere hangi alanların yerel, taklit edilmiş, desteklenmeyen veya kayıplı olduğunu söyleyin.
Harekete geçirilebilir sonuç
Responss API uyumluluk katmanı, yalnızca makul metin döndürmekle kalmayıp, protokolün anlamını da korumalıdır. Bunu beş dayanıklı nesne etrafında oluşturun: standart bir yanıt öğesi modeli, bir konuşma durumu defteri, bir araç çağrısı defteri, bir akış olayı normalleştiricisi ve bir sağlayıcı yetenek matrisi.
En güvenli varsayılan, sıkı uyumluluktur: Bir rota gerekli durumu, araçları, akıl yürütme bağlamını, akış olaylarını veya saklama davranışını koruyamıyorsa, açık bir yetenek hatası döndürün. Yalnızca geliştiriciler neyin bırakılacağını anladığında isteğe bağlı kayıplı geri dönüş ekleyin. Bu yaklaşım, otomatik düzleştirmeden daha az kullanışlı gelebilir ancak en kötü hata modunu önler: Uyumlu görünen ancak ilk etapta Responses API'yi kullanmasını sağlayan semantiği sessizce kaybeden bir uygulama.