Migreren naar HTTPX2

Gebruik van de standaard HTTP-client

Als u een OpenAI- of AsyncOpenAI-client aanmaakt zonder een http_client op te geven, blijven uw bestaande API-aanroepen, geparseerde responsmodellen, streaming API's, authenticatie, retries en numerieke timeouts gewoon werken:

from openai import OpenAI
client = OpenAI(timeout=30.0)
response = client.responses.create(model="gpt-5.5", input="Hello")

Er is geen extra installatie van HTTPX2 vereist:

pip install openai

Indien uw applicatie httpx alleen importeerde omdat een eerdere versie van de SDK dit indirect installeerde, dient u nu zelf de httpx-afhankelijkheid toe te voegen of deze imports te migreren naar httpx2. De installatie van de SDK installeert httpx niet langer automatisch voor u.

TLS-certificaten en trust stores

HTTPX2 wijzigt de standaard TLS trust store, wat ook gevolgen heeft voor applicaties die de standaard HTTP-client van de SDK gebruiken. Waar HTTPX voorheen certificaten verifieerde tegen de CA-bundel van certifi, maakt HTTPX2 nu gebruik van de trust store van het besturingssysteem. De SDK installeert certifi dan ook niet meer.

Dit kan leiden tot problemen met de certificaatverificatie in de volgende scenario's:

  • Minimale container-images zonder systeem-CA-certificaten.
  • Omgevingen die gebruikmaken van corporate TLS-inspecterende proxies.
  • Implementaties die vertrouwden op een aangepaste of gewijzigde certifi-bundel.

U kunt dit oplossen door de vereiste CA-certificaten te installeren in de trust store van het besturingssysteem, of door een expliciete certificaatbundel te configureren:

export SSL_CERT_FILE=/path/to/ca-bundle.pem

Als alternatief kunt u een directory met vertrouwde CA-certificaten configureren:

export SSL_CERT_DIR=/path/to/ca-directory

Deze omgevingsvariabelen worden gerespecteerd wanneer trust_env=True is (dit is de standaardinstelling). Om trust expliciet te beheren op een aangepaste client, kunt u een ssl.SSLContext doorgeven via verify:

import ssl
from openai import OpenAI, DefaultHttpx2Client
ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))

Gebruik DefaultAsyncHttpx2Client(verify=ssl_context) voor de equivalente asynchrone configuratie. De aiohttp-transport van de SDK gebruikt dezelfde HTTPX2 TLS-instellingen.

Gebruik van een aangepaste HTTP-client

Gebruik HTTPX2-clients en HTTPX2-configuratieobjecten. De SDK biedt helpers die de aanbevolen timeouts, connection-pools en redirect-standaarden behouden:

import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

# Client met proxy
proxy_client = OpenAI(http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080"))

# Client met aangepast transport en timeout
transport_client = OpenAI(
    http_client=DefaultHttpx2Client(
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
        timeout=httpx2.Timeout(30.0, connect=5.0),
    )
)

# Asynchrone client met timeout
async_client = AsyncOpenAI(http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0)))

Direct aangemaakte instanties van httpx2.Client en httpx2.AsyncClient worden ook ondersteund. Bij een directe constructie zijn de eigen standaardwaarden van HTTPX2 van kracht, tenzij u deze zelf configureert.

De bestaande namen DefaultHttpxClient en DefaultAsyncHttClient blijven werken, maar maken nu HTTPX2-clients aan. Geef de voorkeur aan DefaultHttpx2Client en DefaultAsyncHttpx2Client om expliciet te maken welke client-familie wordt gebruikt.

Dit geldt ook voor configuraties op moduleniveau:

import openai
openai.http_client = openai.DefaultHttpx2Client()

Timeouts, URL's, transports en verbindingsinstellingen

Vervang HTTPX-specifieke objecten door de corresponderende HTTPX2-objecten:

Oud object (HTTPX)Nieuw object (HTTPX2)
httpx.Clienthttpx2.Client
httpx.AsyncClienthttpx2.AsyncClient
httpx.Timeouthttpx2.Timeout
httpx.URLhttpx2.URL
httpx.Limitshttpx2.Limits
httpx.HTTPTransporthttpx2.HTTPTransport
httpx.AsyncHTTPTransporthttpx2.AsyncHTTPTransport
httpx.MockTransporthttpx2.MockTransport

Een voorbeeld van een gedetailleerde SDK-timeout wordt nu als volgt geschreven:

import httpx2
from openai import OpenAI
client = OpenAI(timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0))

Numerieke timeout-waarden en bestaande string-URL's blijven ongewijzigd. Aangepaste transport-subklassen, mounted transports, proxy-integraties en connection-pool instrumentatie moeten nu gericht zijn op de transport-interfaces van HTTPX2.

Authenticatie en event hooks

Authenticatie-handlers en hooks ontvangen nu HTTPX2-request- en response-objecten. Werk aangepaste auth-classes en annotaties dienovereenkomstig bij:

import httpx2
from openai import OpenAI, DefaultHttpx2Client

def log_request(request: httpx2.Request) -> None:
    print(request.method, request.url)

client = OpenAI(http_client=DefaultHttpx2Client(event_hooks={"request": [log_request]}))

Als u een HTTP-authenticatie- of transport-interface subclasset, subclass dan de bijbehorende httpx2-klasse. Third-party instrumentatie, tracing middleware en auth-integraties moeten expliciet HTTPX2 ondersteunen.

Ruwe responsen, streaming en uitzonderingen

Geparseerde SDK-responsmodellen zijn ongewijzigd. Wanneer u een native HTTPX2-client gebruikt, behoren de transport-gerichte objecten tot HTTPX2:

import httpx2
from openai import OpenAI
client = OpenAI()
response = client.models.with_raw_response.list()
assert isinstance(response.http_response, httpx2.Response)
assert isinstance(response.http_request, httpx2.Request)

Bij gebruik van een native client gebruikt u cast_to=httpx2.Response wanneer u een niet-geparseerde HTTP-respons aanvraagt. Streaming response wrappers tonen eveneens HTTPX2-respons-objecten.

Applicatiecode moet gewoonlijk SDK-uitzonderingen opvangen, zoals openai.APITimeoutError en openai.APIConnectionError. Bij een native client is de onderliggende transportoorzaak van een uitzondering een HTTPX2-uitzondering.

Deze type-garanties gelden alleen voor native HTTPX2-clients. Een geïnjecteerde legacy HTTPX-client produceert httpx.Request, httpx.Response en HTTPX transport-uitzonderingen, zelfs als cast_to=httpx2.Response wordt meegegeven.

aiohttp

De ondersteunde aiohttp extra maakt gebruik van een HTTPX2-native transport. Deze installeert geen legacy HTTPX of de externe httpx-aiohttp adapter:

pip install 'openai[aiohttp]'
from openai import AsyncOpenAI, DefaultAioHttpClient
client = AsyncOpenAI(http_client=DefaultAioHttpClient())

DefaultAioHttpClient() is een httpx2.AsyncClient. Applicaties die deze helper gebruiken, hoeven het transport niet direct aan te maken of te importeren.

Request mocking en tests

Mocks moeten HTTPX2-requests onderscheppen en HTTPX2-responses retourneren. Bijvoorbeeld:

import httpx2
from openai import OpenAI

def handler(request: httpx2.Request) -> httpx2.Response:
    return httpx2.Response(
        200,
        request=request,
        json={"object": "list", "data": []},
    )

client = OpenAI(http_client=httpx2.Client(transport=httpx2.MockTransport(handler)))
assert client.models.list().data == []

Indien uw testsuite gebruikmaakt van RESPX, update dan naar een HTTPX2-compatibele RESPX-versie of fork. Een RESPX-versie die alleen legacy HTTPX patcht, kan de standaard HTTPX2-client van de SDK niet onderscheppen. Als u deze integratie niet direct kunt migreren, kunt u de onderstaande tijdelijke legacy-client noodoplossing gebruiken.

Tijdelijke noodoplossing: een legacy HTTPX-client

Applicaties die afhankelijk zijn van een HTTPX-only transport, integratie of mocking-bibliotheek kunnen expliciet legacy HTTPX installeren en een legacy client injecteren:

pip install openai httpx

Ondersteuning voor legacy HTTPX is alleen beschikbaar tijdens runtime. De publieke type-annotaties van de SDK accepteren HTTPX2-clients, waardoor het direct doorgeven van een legacy client faalt bij statische typecontrole (zoals in mypy of Pyright). Gebruik cast(Any, ...) of een gerichte type-ignore wanneer u bewust voor dit compatibiliteitspad kiest:

from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))

De asynchrone vorm vereist dezelfde workaround:

from typing import Any, cast
import httpx
from openai import AsyncOpenAI
client = AsyncOpenAI(http_client=cast(Any, httpx.AsyncClient()))

Legacy clients behouden de HTTPX request, response en exception families. Vraag ruwe responsen aan als httpx.Response, gebruikmakend van dezelfde type-checking workaround:

from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
response = client.get("/models", cast_to=cast(Any, httpx.Response))
assert isinstance(response, httpx.Response)

Het meegeven van cast_to=httpx2.Response converteert een legacy HTTPX-respons niet naar een HTTPX2-respons. U dient de legacy-afhankelijkheid zelf te installeren en te onderhouden. Let op: ondersteuning voor legacy HTTPX is bedoeld als migratiehulpmiddel en kan in de toekomst worden stopgezet.

Bestaande legacy aiohttp-adapters

Als u een bestaande httpx-aiohttp integratie moet behouden, installeer deze dan expliciet en injecteer de legacy client:

pip install openai httpx-aiohttp
from typing import Any, cast
from httpx_aiohttp import HttpxAiohttpClient
from openai import AsyncOpenAI
client = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient()))

Dit pad is gedekt door specifieke compatibiliteitstests, maar blijft een tijdelijke noodoplossing. Geef de voorkeur aan openai[aiohttp] en DefaultAioHttpClient() voor nieuwe code.