OpenAI Python SDK chuyển sang HTTPX2: Những điểm cần kiểm tra

Có gì mới

OpenAI Python SDK hiện dùng HTTPX2 cho cả HTTP client đồng bộ và bất đồng bộ. Khi cài openai, package httpx2 được cài tự động; SDK không còn kéo theo httpx hoặc certifi.

Nếu ứng dụng chỉ tạo OpenAI hoặc AsyncOpenAI với client mặc định, các lệnh gọi API, response model đã parse, streaming, xác thực, retry và timeout dạng số vẫn hoạt động như trước:

from openai import OpenAI

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

Ứng dụng từng import httpx chỉ vì dependency này được SDK cài gián tiếp phải khai báo httpx của riêng mình hoặc chuyển import sang httpx2.

Thay đổi quan trọng

TLS chuyển sang trust store của hệ điều hành

HTTPX trước đây xác minh certificate bằng CA bundle của certifi. HTTPX2 dùng trust store của hệ điều hành, và SDK không còn cài certifi. Thay đổi này có thể làm hỏng xác minh TLS trong container tối giản chưa có system CA, môi trường có proxy giải mã TLS hoặc deployment từng sửa bundle của certifi.

Có thể chỉ định bundle hoặc thư mục CA bằng biến môi trường:

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

Các biến này được dùng khi trust_env=True, cũng là mặc định. Nếu cần kiểm soát tường minh, truyền ssl.SSLContext vào client:

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))

Custom client, transport và type

Code dùng custom HTTP client cần đổi các object tương ứng từ httpx sang httpx2: Client, AsyncClient, Timeout, URL, Limits, HTTPTransport, AsyncHTTPTransport và MockTransport. Hai helper DefaultHttpxClient và DefaultAsyncHttpxClient vẫn tồn tại nhưng nay tạo client HTTPX2; code mới nên dùng tên rõ ràng DefaultHttpx2Client và DefaultAsyncHttpx2Client.

import httpx2
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    http_client=DefaultHttpx2Client(
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
        timeout=httpx2.Timeout(30.0, connect=5.0),
    )
)

Auth handler, event hook và transport subclass sẽ nhận request/response của HTTPX2. Với native HTTPX2 client, raw response, streaming wrapper và nguyên nhân gốc của transport exception cũng thuộc họ type HTTPX2. Application nên tiếp tục bắt exception cấp SDK như openai.APITimeoutError và openai.APIConnectionError khi có thể.

aiohttp và test

Extra openai[aiohttp] nay dùng transport native của HTTPX2 và không cài adapter httpx-aiohttp cũ. DefaultAioHttpClient() là một httpx2.AsyncClient.

Mock trong test cũng phải chặn request HTTPX2 và trả response HTTPX2:

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 == []

Nếu test suite dùng RESPX, cần phiên bản hỗ trợ HTTPX2 hoặc một fork tương thích. Bản chỉ patch legacy HTTPX sẽ không chặn request của client mặc định mới.

Cách nâng cấp

1. Kiểm tra dependency tree và thêm httpx trực tiếp nếu ứng dụng vẫn import package cũ.
2. Xác nhận image production có system CA cần thiết; test riêng proxy TLS doanh nghiệp và custom bundle.
3. Đổi custom client, timeout, transport, auth, hook và annotation sang type của httpx2.
4. Cập nhật mock và instrumentation để chúng thực sự quan sát request HTTPX2.
5. Chạy lại test cho streaming, raw response, retry, timeout và certificate failure.

Nếu chưa thể di chuyển một integration, SDK vẫn cho phép cài httpx và inject legacy client. Đây chỉ là lối thoát tạm thời: type annotation công khai của SDK chấp nhận HTTPX2, nên mypy hoặc Pyright cần cast(Any, ...) hay một type-ignore có chủ đích. Legacy client giữ nguyên request, response và exception của HTTPX; truyền cast_to=httpx2.Response không chuyển đổi response cũ thành type mới.

Với code chỉ dùng API cấp cao của SDK, migration có thể rất nhỏ. Rủi ro tập trung ở ranh giới transport—CA, proxy, custom client, tracing và test—nên đó là nơi cần kiểm tra trước khi nâng phiên bản.