دليل البدء السريع مع Gemini Decisions API: إجابات نعم/لا والاختيار والتقييم في Python وcurl

تعيد Gemini Decisions API من Google احتمالات بدلًا من النص، دون أي رموز إخراج مدفوعة. إليك دليل بدء سريع خطوة بخطوة مع Python وcurl، إضافة إلى الحدود والفخاخ.

Graphic showing a quickstart for the Gemini Decisions API with a yes, choice and score answer card.

في أغلب الأحيان حين تطرح سؤالًا على نموذج ذكاء اصطناعي، لا تريد مقالًا كاملًا في الرد. تريد «نعم» أو «billing» أو «7 من 10»، حتى يختار الكود مسارًا ويمضي. واجهة Gemini Decisions API الجديدة من Google مصممة لهذا تحديدًا، ولا تتقاضى شيئًا مقابل الإخراج.

شاهد على Mindloop Experience: Gemini Decisions API: 1,000 Questions in One Call for $0.10 per Million Tokens

يوضح لك هذا الدليل كيف تجري أول استدعاء بلغة 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.

بقلم Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

عن Mindloop Experience

الردود

اكتب ردًّا

المزيد من Mindloop Experience

كل مقالات Mindloop Experience

يمكنك التصفيق حتى 50 مرة.