OpenAI stellt mit Version 3.0 seines Python SDKs den HTTP-Unterbau von httpx auf httpx2 um. Die OpenAI-API bleibt kompatibel; für produktive Deployments sind Trust-Store, Custom Clients, Proxies, Mocks und Telemetrie jedoch ein echtes Migrationsprojekt.
Das Release erschien am 12. August 2026. Für den Standardfall bleibt der Anwendungs-Code erfreulich ruhig: OpenAI(), Responses, Streaming, Authentifizierung, Retries und numerische Timeouts behalten laut Migrationsleitfaden ihre bisherigen Schnittstellen. Die relevante Änderung liegt eine Schicht tiefer – dort, wo Teams das SDK in Container, Unternehmensnetzwerke und eigene Transport- oder Testinfrastruktur eingebettet haben.
Was sich mit SDK 3.0 konkret ändert
pip install openaiinstalliert künftighttpx2; das bisher transitivehttpxwird nicht mehr automatisch mitgeliefert.- HTTPX2 verwendet standardmäßig den Trust Store des Betriebssystems statt des CA-Bundles von
certifi. - Eigene Clients, Transports, Timeout-Objekte, Auth-Handler, Event Hooks, Request-Mocks und Instrumentierung müssen auf HTTPX2-Äquivalente umgestellt werden.
- Legacy-HTTPX lässt sich vorübergehend explizit injizieren – ist aber nur zur Laufzeit kompatibel und wird von mypy/Pyright nicht als regulärer SDK-Pfad akzeptiert.
Der operative Stolperstein: Zertifikate
Die Umstellung des Trust Stores ist der Teil, der auch Teams ohne eigene HTTP-Integration treffen kann. Minimal-Container ohne System-CA-Zertifikate, TLS-inspektierende Corporate Proxies und Deployments mit modifiziertem certifi-Bundle können Zertifikatsfehler sehen. OpenAI nennt als Gegenmaßnahmen einen gepflegten OS-Trust-Store, SSL_CERT_FILE, SSL_CERT_DIR oder einen expliziten ssl.SSLContext.
# Explizites CA-Bundle für Umgebungen mit eigener PKI
export SSL_CERT_FILE=/path/to/ca-bundle.pem
Wer einen eigenen Client konfiguriert, migriert die Transportobjekte mit:
import ssl
from openai import OpenAI, DefaultHttpx2Client
context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=context))
Upgrade-Checkliste für Plattformteams
- Dependencies prüfen: Gibt es Imports von
httpx, die bisher nur durchopenaiverfügbar waren? - Container testen: Einen echten TLS-Handshake im Zielimage und hinter dem Unternehmens-Proxy ausführen.
- Integration prüfen: Eigene Transports, Hooks, Authentifizierung, OpenTelemetry-/APM-Instrumentierung und Response-Handling auf HTTPX2-Typen umstellen.
- Tests migrieren: Mocks müssen HTTPX2 Requests und Responses verarbeiten; HTTPX-only RESPX-Setups reichen für den Default-Client nicht mehr.
- Escape Hatch begrenzen: Falls Legacy-HTTPX kurzfristig injiziert wird, als befristete technische Schuld dokumentieren – inklusive eigener Dependency und Type-Checking-Ausnahme.
Warum das mehr als ein Dependency-Update ist
SDK-Major-Releases werden oft als API-Upgrade gelesen. Hier ist die API gerade nicht der kritische Punkt. Die Änderung verschiebt die operative Vertrauensbasis und die Typfamilie des gesamten HTTP-Rands. Für reine Standardclients ist das Upgrade klein. Für Plattformen mit kontrolliertem Egress, internem PKI-Modell oder tiefem Observability-Stack ist es ein Deployment- und Regressionstest.
Pragmatische Entscheidung: Nicht blind upgraden, aber auch nicht dramatisieren: Erst Image, Proxy und Tests gegen 3.0 validieren; anschließend Custom-Integrationen gezielt auf HTTPX2 umstellen.
Leave a Reply