في أغلب الأحيان حين تطرح سؤالًا على نموذج ذكاء اصطناعي، لا تريد مقالًا كاملًا في الرد. تريد «نعم» أو «billing» أو «7 من 10»، حتى يختار الكود مسارًا ويمضي. واجهة Gemini Decisions API الجديدة من Google مصممة لهذا تحديدًا، ولا تتقاضى شيئًا مقابل الإخراج.
يوضح لك هذا الدليل كيف تجري أول استدعاء بلغة Python وبأداة curl، وكيف تقرأ أنواع الإجابات الثلاثة، وكيف تتجنب الفخاخ التي توثّقها Google. وهو يعكس وثائق Google حتى 15 نوفمبر 2026. تحققنا من صحة صياغة أمثلة Python وcurl (الكود يُترجم وجسم JSON يُحلَّل بنجاح). أما الاستدعاءات الحقيقية فتحتاج إلى مفتاح API خاص بك، لذا فالمخرجات النموذجية أدناه هي تلك الواردة في الوثائق.
ما هي Decisions API فعلًا؟
أطلقتها Google في 11 نوفمبر 2026 مع نموذج اسمه Gemini Decision 1 (gemini-decision-1). بدلًا من كتابة نص، يقيّم النموذج الخيارات التي تعطيه إياها ويعيد احتمالات. وتقول Google إن الطلب الواحد يمكن أن يحمل حتى 1,000 سؤال حول مُدخل مشترك، وتقدّر متوسط زمن الاستجابة الكامل بين 150 و250 مللي ثانية للمدخلات التي تصل إلى 16K رمز.
السعر 0.10 دولار أمريكي لكل مليون رمز إدخال، والإخراج دائمًا صفر رموز. ويُحتسب المُدخل المشترك مرة واحدة لكل طلب مهما كان عدد الأسئلة. وتوجد فئة مجانية في Google AI Studio، وتذكر صفحة الأسعار لدى Google أن بياناتك فيها قد تُستخدم لتحسين منتجاتها، أما الفئة المدفوعة فتقول إنها لا تُستخدم.
لاحظ Simon Willison أن نموذج Google ينتمي إلى فئة صغيرة تضم منافسَين اثنين. وبحسب روايته، يكلّف Gemini Decision 1 مثل نموذج القرار GPT-6 Luna من OpenAI، بينما نموذج اسمه Jev أرخص بسعر 4.2 سنت لكل مليون. ووجد أيضًا غرابة: يعيد Jev وOpenAI قيمة قاطعة 1.0 أو 0.0 لأسئلة نعم/لا، بينما أعاد Gemini أرقامًا أكثر ليونة مثل 0.92 و0.05.
ما الذي تحتاجه
- مفتاح Gemini API من Google AI Studio.
- Python مع Google GenAI SDK بالإصدار 3.2 أو أحدث. ومستخدمو JavaScript يحتاجون إلى
@google/genai. - أي عميل HTTP، إذا كنت تفضّل الاستغناء عن الـ SDK.
الخطوة 1: ثبّت الـ SDK واضبط مفتاحك
pip install -U google-genai
export GEMINI_API_KEY=your-key-here
يقرأ مثال curl في وثائق Google المفتاح من GEMINI_API_KEY. وللاطلاع على نظرة أوسع حول استدعاء Gemini من Python وJavaScript وcurl، راجع دليلنا لواجهة Gemini 4 Hydrogen API.
الخطوة 2: اطرح أول سؤال نعم/لا
هذا هو مثال البدء السريع من وثائق Google. احفظه باسم decisions.py:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
result = client.decisions.create(
model="gemini-decision-1",
input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
questions={
"is_damaged": {
"type": "noul",
"instructions": "Did the item arrive damaged?",
},
},
)
answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")
شغّل python decisions.py. تعرض الوثائق استجابة قيمتها 0.99 لكل من احتمال «نعم» ودرجة الثقة، مع total_output_tokens عند 0. والمفتاح الذي تختاره (is_damaged) مجرد تسمية؛ فالنموذج لا يراه أبدًا، لذا ضع السؤال كاملًا في instructions.
الخطوة 3: جرّبها باستخدام curl
الواجهة عبارة عن طلب POST واحد، لذا لا حاجة إلى أي SDK:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-decision-1",
"input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
"questions": {
"is_damaged": {
"type": "noul",
"instructions": "Did the item arrive damaged?"
}
}
}'
الخطوة 4: تعرّف على أنواع الأسئلة الثلاثة
| النوع | استخدمه من أجل | هل يحتاج إلى criteria؟ | ما الذي تحصل عليه |
|---|---|---|---|
noul | التحقق من عبارة نعم/لا | لا | noul (من 0.01 إلى 0.99)، confidence |
choice | اختيار خيار واحد من 2 إلى 255 | نعم، خريطة تربط كل خيار بوصفه | choice, probabilities, confidence |
score | التقييم وفق مستويات مرتّبة تبدأ من 0 | نعم، قائمة بالمستويات | score, probabilities, legend, confidence |
يبدو سؤال choice هكذا (المُدخل النموذجي في الوثائق هو “I was charged twice for my order.” [تم خصم ثمن طلبي مرتين]):
questions={
"department": {
"type": "choice",
"instructions": "Which department should handle this request?",
"criteria": {
"billing": "Payments, invoices, and refunds.",
"technical": "Problems using the product.",
"shipping": "Delivery and tracking.",
"other": "Anything outside these categories.",
},
},
}
قيمة score هي المتوسط المرجّح بالاحتمالات لأرقام المستويات، لذا قد تقع بين مستويين. ويُظهر مقال Flavio Copes القيمة 1.12 على مقياس من ثلاثة مستويات.
الخطوة 5: دع درجة الثقة تقرر من ينفّذ
تحمل كل إجابة قيمة confidence من 0 إلى 1، وهي الاحتمال المقدّر لصحة الإجابة الأولى. وتقترح Google استخدام الإجابة لاختيار إجراء، ودرجة الثقة لتقرير ما إذا كان الكود سينفذه:
answer = result.answers["department"]
if answer.confidence >= 0.7:
route_to(answer.choice)
else:
route_to("human_review")
هنا route_to هي دالتك الخاصة. وتنصح Google بتحديد العتبات انطلاقًا من أمثلة مصنّفة من حركة المرور الخاصة بك، لا بنسخ القيمة 0.7.
الخطوة 6: اجمع أسئلتك في دفعة واحدة
ضع الأسئلة المستقلة حول المُدخل نفسه في طلب واحد. يُحتسب المُدخل المشترك مرة واحدة، ويمكن المزج بين الأنواع. ويوجّه مثال Google تذكرة دعم فني عبر فحص عيب بنعم/لا، واختيار إجراء من أربعة، وتقييم احتمال المغادرة على أربعة مستويات، في استدعاء واحد. ولا يمكن للأسئلة أن ترى بعضها.
حدود يجدر بك معرفتها
| الحد | القيمة |
|---|---|
| عدد الأسئلة لكل طلب | من 1 إلى 1,000 |
| نافذة السياق | 262,144 رمزًا، تشمل المُدخل والأسئلة |
| الفئة المجانية | 200 طلب في الدقيقة، و10,000 في اليوم |
| الفئة 1 (Tier 1) | 1,500 طلب في الدقيقة، و50,000 في اليوم |
الأخطاء الشائعة وحلولها
- لا يحدث شيء عند التحقق من اليقين. تقع احتمالات نعم/لا دائمًا بين 0.01 و0.99، لذا فإن اختبار
noul > 0.99لا يتحقق أبدًا. اضبط العتبات ضمن هذا النطاق. - المُدخل العشوائي يحصل على تسمية رغم ذلك. توزّع أسئلة الاختيار الاحتمال على خياراتك حتى لو لم يناسب أيٌّ منها. أضف خيار
otherمع وصف، وتحقق من درجة الثقة. - خيارك الشامل ليس الأخير. ترتّب الواجهة مفاتيح الخيارات أبجديًا، لذا يأتي
none_of_the_aboveقبلshippingلا في النهاية. استخدم خيارًا شاملًا موصوفًا مثلother. - خطأ 400. يظهر عند تجاوز أحد الحدود، أو فشل التحقق من المفتاح، أو تفعيل فلاتر الأمان. ويذكر جسم الخطأ قيمة
codeمثلsafety. - الوسائط لا تُحمَّل. روابط YouTube وعناوين
gs://غير مدعومة. استخدم URI من Files API، أو رابط HTTPS عامًا أو موقّعًا، أو بيانات base64 مضمّنة. - فاتورتك ترتفع تدريجيًا مع مستند طويل. لا يوجد تخزين مؤقت للسياق ولا Batch API، لذا يُحتسب المُدخل المتكرر كاملًا. اطرح كل الأسئلة في طلب واحد بدلًا من ذلك.
- نتائج غريبة مع نصوص المستخدمين. تحذّر Google من أن المُدخل قد يحاجج لصالح تصنيفه الخاص. ضع شخصًا أو فحصًا ثانيًا قبل أي شيء يحرّك المال.
- مشكلات في الإعداد. تأكد من أن لديك SDK بالإصدار 3.2 أو أحدث وإصدار الواجهة
v1betaقبل تصحيح أي شيء آخر. وتقول الوثائق إن الواجهة متاحة في v1beta فقط.
متى تستخدم شيئًا آخر
استخدم Decisions API للتوجيه والتصفية والتحقق من القواعد مع مجموعة ثابتة من الإجابات. وإذا احتجت إلى نص مولَّد أو ملخصات أو قيم تتبع مخطط JSON خاصًا بك، فإن Google توجّهك إلى Interactions API بدلًا منها. وإذا كنت تفضّل تشغيل النماذج على عتادك الخاص، فإن دليلنا لـ Ollama يشرح هذا الطريق.
المصادر
آخر تحقق من الروابط في 15 نوفمبر 2026.





اكتب ردًّا