benchrمشوّه، أم مجرد غير متطابق
عائلتا فشل تتشاركان هذه الحالة. الأولى مملّة: خطأ مطبعي في اسم حقل، أو حقل مطلوب مُغفَل، أو نص في موضع رقم. ستجدها بقراءة حمولتك مقابل التوثيق المرجعي، بتمهّل، كما تدقّق عقداً.
العائلة الثانية أكثر مكراً، وهي التي تلتهم فترات الظهيرة. الجسم سليم تماماً — لكن على إصدار API مختلف. يشحن Google قدرات جديدة إلى v1beta قبل v1، فميزة منسوخة من صفحة توثيق قد تكون مجهولة لدى النقطة الطرفية التي أوصتك بها صفحة توثيق أخرى. أمثلة SDK المختلطة، والمقتطفات المنسوخة، وإصدار افتراضي غير مثبّت، تمتزج كلها في طلب صالح في كل مكان إلا حيث أرسلته.
الاستجابة
جسم نموذجي، في قالب Google القياسي حيث يكرّر حقل code الرقمي حالة HTTP ويحمل status اسم gRPC:
{
"error": {
"code": 400,
"message": "The request body is malformed.",
"status": "INVALID_ARGUMENT"
}
}الصياغة الدقيقة تختلف حسب الفشل، والرسالة نادراً ما تسمّي الحقل المذنب. هذا الصمت هو سبب تفوّق طريقة إعادة البناء أدناه على التحديق في السجلات.
أعد البناء من طلب أدنى
أثبت أن الأنابيب سليمة أولاً. أصغر استدعاء صالح لـ generateContent يضع النموذج في مسار الرابط ويرسل مُدخل contents واحداً:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{ "parts": [ { "text": "Say hello." } ] }
]
}'إن نجح هذا، فقد انحرف مخططك في موضع أعلى منه: أعد حقولك الحقيقية واحداً تلو الآخر وسيظهر الخطأ 400 عند الإضافة بالضبط التي تكسره. وإن فشل حتى الاستدعاء الأدنى، فاشكُك في الرابط قبل الجسم — اسم النموذج ومقطع الإصدار يسببان من هذه الأخطاء أكثر مما تسببه أي حمولة.
ثبّت إصداراتك
ثلاث عادات تجعل هذا الخطأ نادراً. ضع إصدار API في الرابط صراحةً وعامله كإعداد، حتى تستدعي كل بيئة النقطة الطرفية نفسها بشكل مثبت. تحقّق من الحمولات مقابل مخطط قبل الإرسال؛ فحص JSON Schema صغير في CI يلتقط أسماء الحقول المنحرفة قبل سنوات من أن يلتقطها مستخدم. وحين تنتقل بين خطوط النماذج، أعد قراءة ملاحظات الإصدار بدل افتراض أن شكل الطلب انتقل معك — الحقول تظهر، وتُعاد تسميتها، وتغيّر أنواعها عبر الأجيال. إن كان الانتقال إلى Gemini 3.1 Pro هو ما أظهر الخطأ، فإن المتتبّع يبيّن ما تغيّر أيضاً حول النموذج الذي اعتمدته للتو.