Gemini 4 Argon API: محادثة Python مع البث بالتنسيق الأصلي

تستخدم المحادثة عبر API لنموذج Gemini 4 Argon محتوى Gemini الأصلي: contents والأدوار وparts. الطلب الأول صغير. أما الأصعب فهو حفظ الاستجابة بصورة صحيحة قبل إرسال سؤال لاحق. إعادة بناء دور النموذج من النص الظاهر وحده قد تُفقد المحتوى الموقّع، وإضافة رسالة تحميل فارغة إلى السجل قد تجعل الطلب التالي غير صالح.

يستخدم هذا الدليل مكتبة Python القياسية ونقطة النهاية الأصلية في SeedRouter، ويغطي المحادثة النصية والبث. يشرح مرجع API الكامل جميع مواصفات المعلمات؛ أما هذا المقال فيتابع طلباً واحداً حتى يصبح جزءاً من محادثة قابلة للاستخدام.

قبل الطلب الأول

تحتاج إلى Python 3 ومفتاح API من SeedRouter ورصيد كافٍ في حسابك. احتفظ بالمفتاح في متغير بيئة باسم SEEDROUTER_API_KEY؛ ولا تضعه في الشيفرة المصدرية أو في حزمة تُرسل إلى المتصفح. قد تترتب رسوم على كل رسالة ترسلها. لا يعيد المثال المحاولة تلقائياً ولا يرسل طلبات متابعة.

معرّف النموذج هو gemini-4-argon، ويُوضع النموذج في مسار نقطة النهاية. توثّق Google هذا التنسيق في دليل التوليد بالتنسيق الأصلي. تستخدم SeedRouter مصادقة Bearer كما هو موضح أدناه.

إرسال طلب واحد إلى API لنموذج Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

الاستجابة سلسلة من الأحداث التي يرسلها الخادم، وليست مستند JSON واحداً. يحتوي كل حدث data: على JSON بتنسيق Gemini الأصلي. يظهر النص المرئي في candidates[].content.parts[].text، بينما تحتوي بعض الأجزاء على التفكير أو التوقيعات بدلاً منه. وقد يصل usageMetadata منفصلاً عن النص، لذا اقرأ حتى الحدث الأخير قبل اعتبار الإجابة مكتملة.

ميزانية الإخراج الصغيرة هنا مقصودة لإجراء فحص أولي للتشغيل. يستهلك التفكير هذه الميزانية أيضاً، ولذلك قد تكون الاستجابة غير مكتملة. زدها بقرار واضح للمهام الأصعب؛ ولا تحوّل الإجابة غير المكتملة إلى حلقة إعادة محاولات غير مرئية للمستخدم.

تشغيل محادثة من دورين باستخدام Python

نزّل مثال Python الكامل، واحفظه محلياً، ثم شغّل:

python3 gemini-4-argon-chat.py

اسأل «Explain a mutex in one sentence»، ثم «Give a Python example of that idea». ينتظر البرنامج إدخالك قبل كل طلب. أدخل سطراً فارغاً للإنهاء. القاعدة الأساسية لحفظ السجل هي:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

يوفّر البرنامج القابل للتنزيل إعدادات التوليد أيضاً، ويحلّل إطارات SSE، ويطبع النص غير المصنّف كتفكير فقط، ولا يحفظ السجل إلا بعد سبب إنهاء STOP مع مصفوفة parts غير فارغة. يترك خطأ API أو انقطاع البث أو الإجابة الفارغة السجل السابق كما هو. ولا يعيد إرسال الرسالة بصمت.

يوضح المقتطف القصير أعلاه بنية البيانات؛ شغّل الملف الكامل للحصول على معالجة الطلبات كاملة. للعمل دون بث، تكون العملية المقابلة هي generateContent، وتعرض الأمثلة المرجعية الاستخدام مع cURL وPython وNode.js وGo.

الاحتفاظ بأجزاء parts الأصلية، لا بمؤشر التحميل

يجب أن يحتوي الطلب الثاني على ثلاثة أدوار فعلية: رسالة المستخدم الأولى، واستجابة النموذج المكتملة، ورسالة المستخدم الثانية. عبارة «جارٍ التفكير…» المؤقتة في الواجهة ليست دوراً إضافياً للنموذج.

يشير خطأ مثل contents.3.parts: Too small: expected array to have >=1 items إلى أن عنصر المحتوى الرابع يحتوي على مصفوفة parts فارغة. تبدأ الفهرسة من الصفر. افحص طريقة بناء السجل قبل تغيير الموجّه أو النموذج. ينتمي مؤشر التحميل إلى حالة العرض؛ ولا ينبغي أن يتحوّل أبداً إلى { "role": "model", "parts": [] } داخل الطلب.

احتفظ بكل جزء تعيده الاستجابة بالترتيب، بما في ذلك thoughtSignature وأي أجزاء معلّمة كتفكير، حتى لو أخفتها الواجهة. يشرح دليل توقيعات التفكير من Google سبب ضرورة بقاء هذه الحقول المعتمة في الأدوار اللاحقة. لا تعدّل توقيعاً أو تختلقه أو تعيد بناءه. خزّن السجل الأصلي منفصلاً عن النص المعروض في واجهتك.

ينطبق مبدأ الحفظ نفسه على المحادثات التي تستخدم الأدوات، لكن تنفيذ أداة وإرجاع نتيجتها يتطلب حلقة تطبيق أوسع. هذا المثال النصي لا ينفّذ تلك الحلقة، ولا ينبغي تقديمه بوصفه وكيلاً برمجياً متكاملاً.

قراءة الاستخدام ومعالجة الإيقاف

في الطلبات المباشرة، احتفظ بآخر قيم استخدام يبلّغ عنها البث. لا تجمع قراءات الاستخدام التراكمية المتكررة داخل الطلب نفسه. الإدخال العادي يساوي promptTokenCount مطروحاً منه cachedContentTokenCount؛ ويشمل الإخراج المفوتر كلاً من candidatesTokenCount وthoughtsTokenCount. يحوّل دليل الأسعار هذه العدادات إلى ميزانية.

يوقف Ctrl+C المثال من دون إرسال طلب آخر. إيقاف القراءة محلياً لا يثبت أن التوليد البعيد لم يستهلك توكنات. إذا انتهى البث قبل وصول الاستخدام، فراجع سجل الاستخدام في حسابك. يستبعد المثال الدور غير المكتمل من السجل اللاحق احتياطاً؛ أما حفظ الإجابات الجزئية فهو قرار مستقل في تصميم التطبيق.

أما long decode فهو حالة أخرى مستقلة. يستأنف سبب الإنهاء CONTINUATION التوليد الأصلي باستخدام توكن متابعة، ولا يمثّل رسالة مستخدم جديدة. تشترط Google الطلب الأصلي وأحدث توكن، من دون إلحاق الإخراج الجزئي بـcontents. راجع دليل long decode. يتوقف هذا البرنامج التمهيدي بدلاً من تنفيذ المتابعة تلقائياً.

ما الذي تم التحقق منه؟

اجتاز البث النصي الأساسي اختباراً محلياً من البداية إلى النهاية عبر Playground في SeedRouter. تُفحص معالجة البيانات وإدارة السجل في المثال باستخدام تدفقات مصطنعة، تشمل أجزاء موقّعة واستجابات فارغة وحالات انقطاع. هذه البيانات تختبر البرنامج، وليست عمليات تشغيل إضافية للنموذج. لا تزال الأدوات والوسائط والمتابعة بحاجة إلى اختبارات منفصلة للإمكانات قبل وصفها بأنها تكاملات تم التحقق منها.

أسئلة حول API

هل يمكن استبدال اسم نموذج OpenAI بـgemini-4-argon؟

هذا وحده لا يحوّل تنسيقات الرسائل. يستخدم الدليل حقلي Gemini الأصليين contents وparts. تأكد من أن العميل يدعم هذا البروتوكول وطريقة المصادقة ونقطة النهاية التي تضبطها.

لماذا تكون الإجابة فارغة رغم استهلاك توكنات؟

قد يستهلك التفكير ميزانية الإخراج، كما قد تمنع إعدادات السلامة أو التوليد غير المكتمل ظهور نص مرئي. افحص سبب الإنهاء والاستخدام. لا تضف دور نموذج فارغاً ولا تكرر الطلب المدفوع تلقائياً.

هل يعني سياق بمليون توكن إخراج مليون توكن؟

لا. يتشارك الإدخال والتفكير والإخراج السياق نفسه. وللتوليد الطويل حدود لكل طلب أيضاً، وقد يحتاج إلى متابعة. ضع الميزانية للمجموع المشترك، لا لحصتين منفصلتين للإدخال والإخراج.

إضافة الميزات بعد عمل المحادثة

ابدأ بإجابة مكتملة واحدة، ثم تأكد من أن الدور الثاني يتلقى المحتوى الأصلي كما هو. أبقِ سجل API لنموذج Gemini 4 Argon منفصلاً عن حالة العرض عند إضافة المرفقات أو الأدوات أو التخزين الدائم. انتقل إلى Playground النموذج ودليل الوصول للاستخدام التفاعلي ومتطلبات الحساب.