OpenAI chuyển SDK Python sang HTTPX2: Điều gì thay đổi cho nhà phát triển?

OpenAI vừa công bố bản cập nhật lớn cho Python SDK của mình khi chuyển hoàn toàn sang HTTPX2, thay thế cho HTTPX trước đây. Sự thay đổi này mang lại hiệu suất tốt hơn, cải thiện bảo mật TLS nhưng cũng đòi hỏi các nhà phát triển phải điều chỉnh code nếu đang dựa vào các tính năng tùy chỉnh của HTTPX cũ.

Bài viết này sẽ phân tích chi tiết những thay đổi quan trọng nhất, kèm theo hướng dẫn cụ thể cho từng trường hợp sử dụng khác nhau.

Điều gì thay đổi với người dùng mặc định?

Nếu bạn chỉ sử dụng SDK với cấu hình mặc định, không có gì phải lo lắng. Các chức năng cơ bản như gọi API, xử lý response, streaming, xác thực và timeout vẫn hoạt động bình thường:

from openai import OpenAI

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

Việc cài đặt vẫn đơn giản với lệnh pip install openai — không cần cài thêm bất kỳ package bổ sung nào.

Tuy nhiên, có một điểm cần lưu ý: HTTPX2 không còn tự động được cài đặt cùng SDK. Nếu ứng dụng của bạn từng import httpx chỉ vì nó đi kèm sẵn với OpenAI SDK, giờ đây bạn phải tự khai báo dependency này trong file requirements.txt hoặc pyproject.toml.

Bảo mật TLS và chứng chỉ số — Thay đổi lớn nhất

Đây có lẽ là thay đổi ảnh hưởng nhiều nhất đến các nhà phát triển. Trước đây, HTTPX xác minh chứng chỉ SSL dựa trên CA bundle từ thư viện certifi. HTTPX2 thay đổi cách tiếp cận này bằng cách sử dụng trust store của hệ điều hành.

Điều này có thể gây ra sự cố trong một số môi trường:

• Container images tối giản không có CA certificates hệ thống
• Môi trường doanh nghiệp sử dụng proxy TLS-inspecting
• Các hệ thống dựa vào custom certifi bundle

Giải pháp khắc phục:

# Sử dụng file CA bundle tùy chỉnh
export SSL_CERT_FILE=/path/to/ca-bundle.pem

# Hoặc sử dụng thư mục chứa CA certificates
export SSL_CERT_DIR=/path/to/ca-directory

Đối với những ai muốn kiểm soát chi tiết hơn, có thể truyền trực tiếp ssl.SSLContext:

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

Lưu ý cho nhà phát triển Việt Nam: Trong môi trường doanh nghiệp tại Việt Nam, nơi thường sử dụng các giải pháp tường lửa kiểm tra SSL (như các hệ thống bảo mật nội bộ), hãy đảm bảo đã cấu hình đúng trust store trước khi triển khai lên production.

Tùy chỉnh HTTP client — Cập nhật theo chuẩn mới

Nếu bạn sử dụng custom HTTP client, cần chuyển sang các class HTTPX2 mới:

Object cũ (HTTPX)	Object mới (HTTPX2)
httpx.Client	httpx2.Client
httpx.AsyncClient	httpx2.AsyncClient
httpx.Timeout	httpx2.Timeout
httpx.URL	httpx2.URL
httpx.Limits	httpx2.Limits
httpx.HTTPTransport	httpx2.HTTPTransport
httpx.AsyncHTTPTransport	httpx2.AsyncHTTPTransport
httpx.MockTransport	httpx2.MockTransport

Ví dụ về cấu hình timeout chi tiết:

import httpx2
from openai import OpenAI

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

Việc sử dụng proxy cũng được hỗ trợ tương tự:

from openai import OpenAI, DefaultHttpx2Client

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

Kiểm thử và mock — Nâng cấp bắt buộc

Nếu test suite của bạn sử dụng RESPX hoặc các thư viện mocking khác, cần cập nhật lên phiên bản tương thích HTTPX2. Code mock giờ phải sử dụng các object 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 == []

Bản vá tạm thời cho hệ thống cũ

OpenAI hiểu rằng việc chuyển đổi không thể hoàn tất ngay lập tức, vì vậy họ cung cấp escape hatch cho phép sử dụng HTTPX cũ:

pip install openai httpx

Sau đó inject legacy client:

from typing import Any, cast
import httpx
from openai import OpenAI

client = OpenAI(http_client=cast(Any, httpx.Client()))

Tuy nhiên, cần lưu ý: legacy support chỉ mang tính tạm thời và có thể bị loại bỏ trong tương lai. Với các dự án mới, hãy sử dụng HTTPX2 ngay từ đầu.

Hỗ trợ aiohttp

Với những ai sử dụng async, OpenAI cung cấp openai[aiohttp] extra:

pip install 'openai[aiohttp]'

from openai import AsyncOpenAI, DefaultAioHttpClient

client = AsyncOpenAI(http_client=DefaultAioHttpClient())

Kết luận

Việc chuyển sang HTTPX2 là một bước đi đúng hướng của OpenAI, mang lại nhiều cải tiến về bảo mật và hiệu suất. Mặc dù có một số thay đổi cần điều chỉnh, nhưng với hướng dẫn chi tiết trên, các nhà phát triển Việt Nam có thể dễ dàng nâng cấp ứng dụng của mình mà không gặp quá nhiều trở ngại.

Khuyến nghị: Nếu bạn đang phát triển ứng dụng sử dụng OpenAI SDK, hãy lên kế hoạch nâng cấp lên HTTPX2 ngay khi có thể. Đối với các dự án đã hoạt động ổn định, hãy dùng escape hatch tạm thời và lên lịch migration trong thời gian sớm nhất.