OpenAI Python SDK'si HTTPX2'ye geçti: TLS güveni ve özel client kurulumları değişti

Ne değişti

Openai-python deposunda yayımlanan ve Hacker News ana sayfasında öne çıkan bir migration rehberine göre OpenAI Python SDK'si, senkron ve asenkron HTTP client'larını HTTPX'ten HTTPX2'ye taşıdı. httpx2 paketi openai ile birlikte otomatik olarak kuruluyor; eski httpx paketi artık kurulmuyor.

Rehber, yaşanacak etkileri iki gruba ayırıyor: SDK'nın varsayılan client'ını kullanan uygulamalar ve özel bir HTTP client'ı geçenler. Varsayılan client kullananlar büyük ölçüde etkilenmiyor — API çağrıları, parse edilmiş response modelleri, streaming API'leri, authentication, retry'lar ve sayısal timeout'lar ek bir kurulum gerektirmeden çalışmaya devam ediyor.

Farkında olmadığınız bağımlılık

En yakın etkilerden biri, SDK'nın önceki bir sürümü transitif olarak httpx'i kurduğu için yalnızca bu amaçla httpx'i import eden kodları vuruyor. Rehber, bu uygulamalara httpx'i doğrudan bir bağımlılık olarak tanımlamalarını ya da import'ları httpx2'ye taşımalarını söylüyor; çünkü SDK'yı kurmak artık onlara httpx sağlamıyor.

TLS güveni artık işletim sisteminden geliyor

En geniş etki alanına sahip değişikliğin özel client'larla ilgisi yok. HTTPX daha önce sertifikaları certifi'nin CA bundle'ına göre doğruluyordu; HTTPX2 ise bunun yerine işletim sisteminin güven deposunu kullanıyor ve SDK artık certifi'yi hiç kurmuyor. Bu, varsayılan client'ı kullanan uygulamalar için bile geçerli.

Rehber, doğrulamanın başarısız olabileceği üç senaryoya dikkat çekiyor: sistem CA sertifikaları bulunmayan minimal container imajları, kurumsal TLS incelemesi yapan proxy'lerin arkasındaki ortamlar ve özel ya da değiştirilmiş bir certifi bundle'ına güvenen dağıtımlar. Çözümler arasında gerekli CA sertifikalarını işletim sisteminin güven deposuna kurmak ya da SSL_CERT_FILE ve SSL_CERT_DIR ortam değişkenlerini açık bir bundle veya dizine yönlendirmek yer alıyor. Her iki değişken de trust_env etkinken (varsayılan davranış bu şekilde) dikkate alınıyor. Açık kontrol için uygulamalar bir ssl.SSLContext'i DefaultHttpx2Client veya DefaultAsyncHttpx2Client'ın verify argümanı üzerinden geçebilir; SDK'nın aiohttp transport'u da aynı TLS ayarlarını paylaşıyor.

Özel client'lar, hook'lar ve ham response'lar

Kendi HTTP client'ını enjekte eden uygulamaların HTTPX2 client'larına ve yapılandırma nesnelerine geçmesi gerekiyor: httpx2.Client, httpx2.AsyncClient, httpx2.Timeout, httpx2.URL, httpx2.Limits ve transport sınıfları httpx karşılıklarının yerini alıyor. SDK, önerilen timeout, connection-pool ve redirect varsayılanlarını koruyan DefaultHttpx2Client ve DefaultAsyncHttpx2Client yardımcılarını sunuyor; eski DefaultHttpxClient isimleri hâlâ çalışıyor ama artık HTTPX2 client'ları oluşturuyor. Sayısal timeout değerleri ve string URL'ler değişmedi.

Authentication handler'ları ve event hook'ları artık HTTPX2 request ve response nesneleri aldığından, özel auth alt sınıflarının ve type annotation'ların güncellenmesi, üçüncü taraf instrumentation veya tracing middleware'lerinin ise açık HTTPX2 desteği eklemesi gerekiyor. Parse edilmiş response modelleri dokunulmadı, ancak ham response ile çalışan kodlar yerel bir client üzerinde httpx2.Response ve httpx2.Request nesneleri görüyor; openai.APIConnectionError ve openai.APITimeoutError gibi SDK hatalarının altında HTTPX2 exception'ları yer alıyor. aiohttp extra'sı artık eski HTTPX'i veya harici httpx-aiohttp adaptörünü kurmadan HTTPX2 yerleşik bir transport kullanıyor ve DefaultAioHttpClient yardımcısı bir httpx2.AsyncClient.

Testler, mocking ve çıkış kapısı

Test suite'lerine özel bir dikkat ayrılmış. Mock'lar HTTPX2 request'lerini yakalayıp HTTPX2 response'ları döndürmeli; RESPX kullanıcıları ise HTTPX2 uyumlu bir sürüme geçmeli, çünkü yalnızca eski HTTPX'i patch'leyen bir RESPX sürümü SDK'nın varsayılan client'ını yakalayamaz.

Hemen geçemeyecek ekipler için rehber, yalnızca runtime'a ait bir çıkış kapısı belgeliyor: eski httpx'i açıkça kurun ve eski bir httpx.Client veya httpx.AsyncClient enjekte edin. SDK'nın genel type annotation'ları yalnızca HTTPX2 client'larını kabul ettiğinden, bu yol mypy ve Pyright statik kontrollerinde başarısız olur ve Any'ye cast yapmayı ya da hedefli bir type-ignore gerektirir. Geçiş süresince eski client'lar eski request, response ve exception ailelerini koruyor.

Neden önemli

Bu, en yaygın kurulan Python paketlerinden birinin transport katmanından teslim edilen bir breaking change; TLS kayması, kod hiç dokunulmasa bile production'da başarısız olabileceği anlamına geliyor — özellikle sistem CA sertifikalarını hiç bulundurmayan ince container imajlarında. Ayrıca ekosistem genelinde bir sürtünmeye işaret ediyor: HTTPX üzerine kurulu mocking, tracing ve authentication araçları, daha fazla kütüphane aynı yolu izledikçe HTTPX2 desteği eklemek zorunda kalacak. Ekipler transitif httpx import'larını denetlemeli, dağıtım imajlarındaki sertifika yönetimini doğrulamalı ve tamamen geçmeyi ya da geçici eski yola bel bağlamayı yakında karar vermeli.