OpenAI Python SDK chuyển sang sử dụng HTTPX2

Di chuyển sang HTTPX2

OpenAI Python SDK hiện sử dụng HTTPX2 cho các HTTP client đồng bộ và bất đồng bộ. HTTPX2 được cài đặt tự động cùng với openai; gói httpx trước đây thì không. Hướng dẫn này giải thích những thay đổi đối với các ứng dụng tương tác với lớp HTTP của SDK.

Nếu bạn sử dụng HTTP client mặc định của SDK

Nếu bạn khởi tạo một client OpenAI hoặc AsyncOpenAI mà không cung cấp http_client, các lệnh gọi API, mô hình phản hồi đã phân tích cú pháp, API streaming, xác thực, thử lại (retries) và thời gian chờ (timeouts) bằng số hiện có của bạn vẫn tiếp tục hoạt động:

Không cần cài đặt thêm hoặc cài đặt riêng HTTPX2:

Nếu ứng dụng của bạn import httpx chỉ vì một SDK trước đó đã cài đặt nó một cách gián tiếp, hãy thêm dependency httpx của riêng bạn hoặc chuyển các import đó sang httpx2. Việc cài đặt SDK hiện không còn tự động cài đặt httpx cho bạn nữa.

Chứng chỉ TLS và kho lưu trữ tin cậy (trust stores)

HTTPX2 thay đổi kho lưu trữ tin cậy TLS mặc định, bao gồm cả các ứng dụng sử dụng HTTP client mặc định của SDK. Trước đây, HTTPX xác thực chứng chỉ dựa trên CA bundle do certifi cung cấp. Thay vào đó, HTTPX2 sử dụng kho lưu trữ tin cậy của hệ điều hành và SDK không còn cài đặt certifi nữa.

Điều này có thể làm gián đoạn việc xác thực chứng chỉ trong các image container tối giản không có chứng chỉ CA hệ thống, các môi trường sử dụng proxy kiểm tra TLS của doanh nghiệp và các bản triển khai dựa vào certifi bundle tùy chỉnh hoặc đã sửa đổi. Hãy cài đặt các chứng chỉ CA cần thiết vào kho lưu trữ tin cậy của hệ điều hành hoặc cấu hình một certificate bundle cụ thể:

Ngoài ra, hãy cấu hình một thư mục chứa các chứng chỉ CA đáng tin cậy:

Các biến môi trường này được ưu tiên khi trust_env=True, đây là thiết lập mặc định. Để kiểm soát độ tin cậy một cách rõ ràng trên một client tùy chỉnh, hãy truyền một ssl.SSLContext thông qua tham số verify:

Sử dụng DefaultAsyncHttpx2Client(verify=ssl_context) cho cấu hình bất đồng bộ tương đương. Transport aiohttp của SDK sử dụng cùng các thiết lập TLS của HTTPX2.

Nếu bạn cung cấp một HTTP client tùy chỉnh

Hãy sử dụng các HTTPX2 client và các đối tượng cấu hình HTTPX2. SDK cung cấp các trình hỗ trợ giúp bảo toàn các giá trị mặc định được khuyến nghị về thời gian chờ, connection-pool và chuyển hướng (redirect):

Các instance httpx2.Client và httpx2.AsyncClient được khởi tạo trực tiếp cũng được hỗ trợ. Khi bạn khởi tạo client trực tiếp, các giá trị mặc định của chính HTTPX2 sẽ được áp dụng trừ khi bạn tự cấu hình chúng.

Các tên DefaultHttpxClient và DefaultAsyncHttpxClient hiện có vẫn tiếp tục hoạt động, nhưng hiện sẽ khởi tạo các HTTPX2 client. Hãy ưu tiên sử dụng DefaultHttpx2Client và DefaultAsyncHttpx2Client khi muốn làm rõ họ HTTP client đang sử dụng.

Cấu hình ở cấp độ module cũng tuân theo quy tắc tương tự:

Thời gian chờ, URL, transport và các thiết lập kết nối

Thay thế các đối tượng dành riêng cho HTTPX bằng các đối tượng HTTPX2 tương ứng:

Ví dụ, một cấu hình thời gian chờ chi tiết của SDK sẽ trở thành:

Các giá trị thời gian chờ dạng số không thay đổi. Các URL dạng chuỗi hiện có không thay đổi. Các lớp con transport tùy chỉnh, transport được gắn (mounted), tích hợp proxy và công cụ đo lường connection-pool phải nhắm mục tiêu vào các giao diện transport của HTTPX2.

Xác thực và các event hook

Các trình xử lý xác thực và hook sẽ nhận các đối tượng request và response của HTTPX2. Hãy cập nhật các lớp xác thực và chú thích (annotations) tùy chỉnh cho phù hợp:

Nếu bạn tạo lớp con từ một giao diện xác thực HTTP hoặc transport, hãy tạo lớp con từ lớp httpx2 tương ứng. Các công cụ đo lường của bên thứ ba, middleware theo dõi (tracing) và các tích hợp xác thực phải hỗ trợ rõ ràng HTTPX2.

Phản hồi thô (raw responses), streaming và ngoại lệ

Các mô hình phản hồi SDK đã phân tích cú pháp không thay đổi. Khi sử dụng native HTTPX2 client, các đối tượng hướng transport sẽ thuộc về HTTPX2:

Với native client, hãy sử dụng cast_to=httpx2.Response khi yêu cầu một phản hồi HTTP chưa phân tích cú pháp. Các trình bao bọc phản hồi streaming cũng hiển thị các đối tượng phản hồi HTTPX2. Mã ứng dụng thường nên bắt các ngoại lệ của SDK như openai.APITimeoutError và openai.APIConnectionError; với native client, nguyên nhân transport cơ bản của ngoại lệ là một ngoại lệ HTTPX2.

Các đảm bảo về kiểu dữ liệu này chỉ áp dụng cho các native HTTPX2 client. Một legacy HTTPX client được tiêm vào sẽ tạo ra các ngoại lệ httpx.Request, httpx.Response và transport của HTTPX thay thế, ngay cả khi cast_to=httpx2.Response được cung cấp.

aiohttp

Phần mở rộng aiohttp được hỗ trợ sử dụng một transport native của HTTPX2. Nó không cài đặt legacy HTTPX hoặc adapter httpx-aiohttp bên ngoài:

DefaultAioHttpClient là một httpx2.AsyncClient. Các ứng dụng sử dụng trình hỗ trợ này không cần phải khởi tạo hoặc import transport trực tiếp.

Mocking request và kiểm thử (tests)

Các mock phải chặn (intercept) các request của HTTPX2 và trả về các response của HTTPX2. Ví dụ:

Nếu bộ kiểm thử của bạn sử dụng RESPX, hãy cập nhật lên phiên bản RESPX tương thích với HTTPX2 hoặc fork. Một phiên bản RESPX chỉ vá lỗi cho legacy HTTPX sẽ không thể chặn HTTPX2 client mặc định của SDK. Nếu bạn không thể chuyển đổi tích hợp đó ngay lập tức, giải pháp tạm thời dưới đây cho phép các thiết lập RESPX chỉ dùng HTTPX cũ tiếp tục hoạt động trong khi bạn thực hiện chuyển đổi.

Giải pháp tạm thời: sử dụng legacy HTTPX client

Các ứng dụng phụ thuộc vào transport, tích hợp hoặc thư viện mocking chỉ hỗ trợ HTTPX có thể cài đặt rõ ràng legacy HTTPX và tiêm một legacy client:

Hỗ trợ legacy HTTPX chỉ dành cho thời gian chạy (runtime). Các chú thích kiểu dữ liệu công khai của SDK chấp nhận các HTTPX2 client, vì vậy việc truyền trực tiếp một legacy client sẽ làm thất bại quá trình kiểm tra kiểu tĩnh trong mypy, Pyright và các công cụ tương tự. Hãy sử dụng cast(Any,...) hoặc type-ignore có mục tiêu khi cố tình chọn lộ trình tương thích này:

Dạng bất đồng bộ cũng yêu cầu cách giải quyết tương tự:

Các legacy client bảo toàn các họ request, response và ngoại lệ của HTTPX. Hãy yêu cầu phản hồi thô dưới dạng httpx.Response, sử dụng cách giải quyết kiểm tra kiểu tương tự cho lớp phản hồi cũ: