تحديث Google Gemini Python SDK v3.0: تغييرات كاسرة، الانتقال إلى v1، واعتماد httpx2 في التيرمينال

أطلقت جوجل رسمياً الإصدار الجذري الجديد Google Gemini Python SDK v3.0، حاملاً معه تغييرات جوهرية تفرض على المطورين إعادة ضبط مشاريعهم البرمجية وسلاسل أدواتهم فوراً. ويأتي هذا التحديث ليعيد ترتيب آلية الاتصال بخوادم واجهات البرمجة التوليدية، بالتوازي مع التطورات السريعة التي يشهدها مجتمع التطوير التوليدي، وما رصدناه مؤخراً في دليل بناء التطبيقات عبر Google AI Studio وتكامل الوكلاء مع تحديث Google Antigravity الجديد.

التحول الافتراضي إلى واجهة v1 واختفاء أسماء النماذج المستعارة

التغيير الأبرز في هذا الإصدار هو تحويل نقطة النهاية الافتراضية لحسابات المطورين من v1beta إلى الإصدار المستقر v1. ورغم أن هذا التحول يمنح التطبيقات استقراراً طويل الأمد، إلا أنه يحمل أثراً كاسراً مباشراً (Breaking Change)؛ إذ لم تعد الأسماء المستعارة الشهيرة مثل gemini-flash-latest و gemini-pro-latest متاحة على v1، لأنها مخصصة حصراً لبيئة البيتا التجريبية.

إذا كانت تطبيقاتك تعتمد على هذه الأسماء، ستواجه أخطاء توقف مفاجئة ما لم تحدد اسم النموذج الصريح أو تعيد توجيه عميل الربط لاستخدام بيئة البيتا عبر التيرمينال (Terminal):

# ترقية المكتبة البرمجية إلى الإصدار الثالث
pip install --upgrade google-genai

# استعادة سلوك v1beta الافتراضي عبر متغير البيئة في التيرمينال
export GOOGLE_GENAI_API_VERSION=v1beta

# أو تثبيت توافقية httpx القديمة عند الحاجة
pip install "google-genai[httpx]"
export GOOGLE_GENAI_HTTP_CLIENT=httpx

أما على مستوى الكود داخل بايثون، فيمكنك تمرير خيارات الاتصال الصريحة عبر HttpOptions بكل سهولة:

from google import genai
from google.genai import types

# تثبيت إصدار v1beta صراحة داخل الشيفرة البرمجية
client = genai.Client(
 http_options=types.HttpOptions(api_version='v1beta')
)

response = client.models.generate_content(
 model='gemini-flash-latest',
 contents='اشرح الفروق الجوهرية في بنية الحزم الجديدة'
)
print(response.text)

اعتماد عميل httpx2 وتغيير إدارة شهادات الأمان SSL

قرر فريق هندسة جوجل استبدال عميل الشبكة الافتراضي ليصبح httpx2 بدلاً من httpx الكلاسيكي، مع إزالة الأخير من قائمة التثبيت التلقائي. يترافق هذا التغيير مع تحديث أمني حيوي: يعتمد httpx2 افتراضياً على مخزن شهادات الأمان الموثوقة الخاص بنظام التشغيل عبر مكتبة truststore بدلاً من الاعتماد المطلق على حزمة certifi، ما يحل مشاكل شهادات الشركات والشبكات الداخلية المعقدة.

يتطلب هذا التحول تحديث استيرادات المشاريع القائمة التي تستخدم عملاء مخصصين، حيث يكفي في أغلب الحالات تعديل سطر الاستيراد إلى import httpx2 as httpx لضمان استمرار عمل الـ Middleware وضوابط زمن الاستجابة (Latency) دون انقطاع، وفق التوثيق المنشور على مستودع googleapis الرسمي على GitHub.

جدول المقارنة: الفروق الجوهرية بين v2.x و v3.0

يوضح الجدول التالي التغييرات التقنية المباشرة التي يجب الانتباه إليها قبل الترقية:

أسئلة شائعة حول ترقية Google Gemini Python SDK v3.0

لماذا توقفت استدعاءات نماذج gemini-flash-latest بعد الترقية؟

لأن المكتبة أصبحت تتصل افتراضياً بواجهة v1 المستقرة التي لا تدعم الأسماء المستعارة التلقائية؛ لحل المشكلة، استبدل الاسم برقم الإصدار الثابت، أو عيّن متغير البيئة GOOGLE_GENAI_API_VERSION=v1beta.

هل يؤثر تحديث المكتبة الجديد على عملاء Vertex AI والشركات؟

لا، أكدت جوجل أن العملاء الذين يستخدمون vertexai=True أو enterprise=True لن يتأثروا بهذا التغيير، وسيظل اتصالهم الافتراضي مضبوطاً على v1beta1 دون أي تعديل في الكود.

كيف أتعامل مع كود قديم يعتمد على تخصيصات مكتبة httpx القديمة؟

يمكنك تثبيت الحزمة الإضافية عبر تشغيل pip install "google-genai[httpx]" في التيرمينال (Terminal) وتعيين متغير البيئة GOOGLE_GENAI_HTTP_CLIENT=httpx لاستعادة العميل القديم دون تغيير بنيتك الحالية.