تغییر زیرساخت OpenAI Python SDK به HTTPX2 و حذف وابستگی به certifi

اگر از کتابخانه پایتون OpenAI برای اتصال به مدل‌ها استفاده می‌کنید، باید بدانید که لایه ارتباطی برنامه‌های شما تغییر کرده است. این تغییر در نگاه اول نامرئی است، اما در محیط‌های خاصِ استقرار، می‌تواند باعث قطع کامل دسترسی به API شود.

طبق اعلام رسمی OpenAI در ۲۸ اوت ۲۰۲۶، OpenAI Python SDK اکنون برای تمامی کلاینت‌های هم‌گام و ناهم‌گام از HTTPX2 استفاده می‌کند. این مهاجرت اساساً نحوه تعامل SDK با لایه شبکه، به‌ویژه در مدیریت وابستگی‌ها و گواهینامه‌های امنیتی را تغییر داده است.

برای اکثر توسعه‌دهندگان، این انتقال هیچ تأثیری بر کد فعلی ندارد. اگر کلاینت OpenAI یا AsyncOpenAI را بدون تعریف یک http_client سفارشی ساخته‌اید، تمام فراخوانی‌های API، استریم‌ها، مدل‌های پاسخ، احراز هویت، تنظیمات بازگشت (Retry) و مهلت‌های زمانی عددی بدون تغییر به کار خود ادامه می‌دهند. برای مثال، مقداردهی ساده‌ای مثل client = OpenAI(timeout=30.0) همچنان کاملاً عملیاتی است.

با این حال، یک تغییر ساختاری مهم رخ داده است: SDK دیگر بسته قدیمی httpx را به‌صورت ترانزیتی (Transitively) نصب نمی‌کند. این یعنی اگر برنامه‌ای دارید که صرفاً به‌دلیل نصب بودن SDK به httpx دسترسی داشت و آن را وارد (Import) می‌کرد، اکنون باید آن را به‌طور صریح به لیست وابستگی‌های خود اضافه کنید یا تمام آن Importها را به httpx2 منتقل نمایید.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی استانداردهای امنیتی مدل‌های زبانی اشاره کردیم، جابه‌جایی لایه‌های زیرساختی معمولاً برای افزایش پایداری در مقیاس سازمانی انجام می‌شود. این رویکرد بهینه‌سازی زیرساخت‌ها مشابه تلاش‌های اخیر در حوزه کاهش هزینه‌های عملیاتی است، همان‌طور که مسیریاب Speko توانست هزینه‌های تبدیل گفتار به متن را به شدت کاهش دهد.

گواهینامه‌های TLS و ذخیره‌گاه‌های اعتماد

یک چرخش راهبردی در نحوه تأیید گواهینامه‌های TLS رخ داده است. پیش از این، SDK گواهینامه‌ها را بر اساس بسته CA که توسط certifi ارائه می‌شد، تأیید می‌کرد. اما بر اساس مستندات openai-python در گیت‌هاب، HTTPX2 اکنون به‌طور پیش‌فرض از ذخیره‌گاه اعتماد سیستم‌عامل (OS Trust Store) استفاده می‌کند و SDK دیگر certifi را به‌صورت پیش‌فرض نصب نمی‌کند.

این تغییر می‌تواند در محیط‌های زیر باعث بروز خطا و قطع اتصال شود:

• ایمیج‌های بسیار سبک کانتینر (Minimal Images) که فاقد گواهینامه‌های CA سیستم هستند.
• شبکه‌های شرکتی که از پروکسی‌های بازرسی TLS (TLS-inspecting proxies) استفاده می‌کنند.
• استقرارهایی که بر بسته‌های سفارشی یا تغییریافته certifi متکی بوده‌اند.

برای حل این مشکل، توسعه‌دهندگان می‌توانند گواهینامه‌های CA را مستقیماً در ذخیره‌گاه اعتماد سیستم‌عامل نصب کنند یا از متغیرهای محیطی برای پیکربندی بسته‌های صریح استفاده نمایند. SDK در حالت پیش‌فرض (trust_env=True) متغیرهای SSL_CERT_FILE (برای یک بسته خاص .pem) و SSL_CERT_DIR (برای دایرکتوری گواهینامه‌ها) را می‌شناسد.

برای کنترل دقیق‌تر، SDK اجازه می‌دهد یک ssl.SSLContext را از طریق پارامتر verify ارسال کنید. این کار در کلاینت‌های هم‌گام با استفاده از DefaultHttpx2Client و در پیکربندی‌های ناهم‌گام با DefaultAsyncHttpx2Client امکان‌پذیر است. ترنسپورت aiohttp در این SDK نیز از همین تنظیمات TLS مربوط به HTTPX2 پیروی می‌کند.

پیاده‌سازی کلاینت‌های سفارشی

توسعه‌دهندگانی که از کلاینت‌های سفارشی استفاده می‌کنند، باید اشیاء قدیمی را با معادل‌های HTTPX2 جایگزین کنند. برای حفظ تنظیمات توصیه‌شده در مورد استخر اتصالات (Connection Pool)، تغییر مسیر (Redirect) و مهلت زمانی (Timeout)، استفاده از کلاس‌های کمکی DefaultHttpx2Client و DefaultAsyncHttpx2Client توصیه می‌شود.

اگرچه نام‌های قدیمی مثل DefaultHttpxClient و DefaultAsyncHttpxClient هنوز کار می‌کنند، اما آن‌ها اکنون در لایه‌های داخلی یک کلاینت HTTPX2 می‌سازند. توسعه‌دهندگان تشویق می‌شوند تا از نسخه‌های نام‌گذاری شده با Httpx2 استفاده کنند تا خانواده کلاینت به‌طور صریح در کد مشخص باشد. این قانون در مورد پیکربندی‌های سطح ماژول از طریق openai.http_client نیز صدق می‌کند. این تغییر در نحوه تعریف کلاینت‌ها، یادآور تحولاتی است که در پلتفرم 0mcp برای تبدیل مستندات OpenAPI به ابزارهای اجرایی مشاهده می‌کنیم تا تعامل با مدل‌ها استانداردتر شود.

نقشه‌راه جایگزینی اشیاء

برای حفظ سازگاری و جلوگیری از خطاهای تایپی، موارد زیر را جایگزین کنید:

• httpx.Client $\rightarrow$ httpx2.Client
• httpx.AsyncClient $\rightarrow$ httpx2.AsyncClient
• httpx.Timeout $\rightarrow$ httpx2.Timeout
• httpx.URL $\rightarrow$ httpx2.URL
• httpx.Limits $\rightarrow$ httpx2.Limits
• httpx.HTTPTransport $\rightarrow$ httpx2.HTTPTransport
• httpx.AsyncHTTPTransport $\rightarrow$ httpx2.AsyncHTTPTransport
• httpx.MockTransport $\rightarrow$ httpx2.MockTransport

به‌عنوان مثال، تنظیم دقیق مهلت زمانی در SDK اکنون به این شکل پیاده‌سازی می‌شود: OpenAI(timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0)). البته توجه داشته باشید که مقادیر عددی ساده برای timeout و رشته‌های URL تغییری نکرده‌اند و همچنان معتبر هستند.

احراز هویت و قلاب‌های رویداد

مدیریت‌های احراز هویت و قلاب‌های رویداد (Event Hooks) نیز به‌طور مشابه تحت تأثیر قرار گرفته‌اند. این‌ها اکنون اشیاء درخواست و پاسخ HTTPX2 را دریافت می‌کنند. اگر از یک رابط احراز هویت یا ترنسپورت HTTP ارث‌بری (Subclass) کرده‌اید، باید کلاس متناظر در httpx2 را جایگزین کنید. همچنین میان‌افزارهای ردیابی (Tracing) شخص ثالث و ادغام‌های احراز هویت باید صراحتاً از HTTPX2 پشتیبانی کنند تا بتوانند به درستی عمل کنند.

در صورت استفاده از with_raw_response اشیاء خروجی http_response و http_request اکنون نمونه‌هایی از httpx2.Response و httpx2.Request هستند. هنگام درخواست یک پاسخ تجزیه‌نشده (Unparsed) با یک کلاینت بومی، از cast_to=httpx2.Response استفاده کنید.

ترنسپورت ناهم‌گام و aiohttp

برای کاربران حالت ناهم‌گام، افزونه openai[aiohttp] اکنون از یک ترنسپورت بومی HTTPX2 استفاده می‌کند. این تغییر نیاز به آداپتور خارجی httpx-aiohttp را به‌طور کامل از بین می‌برد. کمک‌کننده DefaultAioHttpClient در لایه‌های زیرین یک httpx2.AsyncClient می‌سازد، به این معنی که برنامه‌هایی که از این Helper استفاده می‌کنند، نیازی به وارد کردن مستقیم ترنسپورت ندارند.

شبیه‌سازی درخواست‌ها و تست

مجموعه‌های تست که از RESPX استفاده می‌کنند، احتمالاً نیاز به به‌روزرسانی دارند. چون نسخه‌های RESPX که فقط httpx قدیمی را وصله (Patch) می‌کنند، نمی‌توانند کلاینت پیش‌فرض جدید را رهگیری کنند. توسعه‌دهندگان باید به نسخه‌ای سازگار با HTTPX2 مهاجرت کنند یا کتابخانه را فورک نمایند. اکنون Mockها باید اشیاء httpx2.Request را رهگیری کرده و اشیاء httpx2.Response برگردانند.

راه فرار موقت برای نسخه‌های قدیمی

به‌عنوان یک اقدام موقت، SDK اجازه می‌دهد یک کلاینت قدیمی HTTPX را از طریق cast(Any, httpx.Client()) تزریق کنید. این کار باعث می‌شود ادغام‌های فعلی شما در حین مهاجرت کار کنند، اما در ابزارهای بررسی نوع (Static Type Checking) مثل mypy یا Pyright خطا ایجاد می‌کند.

کلاینت‌های قدیمی، خانواده‌های درخواست، پاسخ و استثنائات (Exceptions) اصلی HTTPX را حفظ می‌کنند. اگر از این مسیر استفاده می‌کنید، باید پاسخ‌های خام را به صورت cast_to=cast(Any, httpx.Response) درخواست کنید. توجه داشته باشید که ارسال cast_to=httpx2.Response نمی‌تواند یک پاسخ قدیمی را به یک پاسخ HTTPX2 تبدیل کند.

برای کسانی که مجبور به حفظ ادغام httpx-aiohttp هستند، می‌توان این بسته را به‌طور صریح نصب کرده و کلاینت آن را به صورت AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient())) تزریق کرد. این یک کمک‌کار موقت برای مهاجرت است و ممکن است در آینده حذف شود.

این تغییر نشان‌دهنده حرکتی به سمت استانداردسازی امنیت در سطح سیستم‌عامل به‌جای استفاده از گواهینامه‌های بسته‌بندی شده در پایتون است. با حذف وابستگی به certifi شرکت OpenAI SDK خود را با رویه‌های امنیتی گسترده‌تر سیستم‌ها هم‌راستا کرده است، هرچند این موضوع مسئولیت پیکربندی صحیح گواهینامه‌های CA در ایمیج‌های کانتینر را بر عهده لایه DevOps می‌گذارد.

گام بعدی شما

• اگر از Docker استفاده می‌کنید، بررسی کنید که ایمیج‌های شما دارای گواهینامه‌های CA سیستم‌عامل باشند تا با خطای TLS مواجه نشوید.
• وابستگی‌های requirements.txt خود را بررسی کنید و اگر به httpx نیاز دارید، آن را به‌طور صریح اضافه کنید.
• در صورت استفاده از RESPX برای تست‌ها، کتابخانه را به آخرین نسخه سازگار با HTTPX2 به‌روزرسانی کنید.

اما تأثیر این تغییرات بر عملکرد استنتاج در مقیاس بالا هنوز کاملاً مشخص نیست — به تحلیل ما درباره بهینه‌سازی هزینه‌های استنتاج مراجعه کنید.