كيفية استخدام Gemini Decisions API؟

لاستخدام واجهة Gemini Decisions API، احصل على مفتاح من Google AI Studio، وثبّت google-genai الإصدار 3.2 أو أحدث، ثم استدعِ client.decisions.create() مع النموذج gemini-decision-1، ومدخل مشترك واحد input، وخريطة من الأسئلة المكتوبة questions (noul أو choice أو score). ستحصل على احتمال مُعاير وقيمة confidence لكل سؤال، وبدون أي رموز إخراج.

في الأسفل: كل خطوة بلغة Python وJavaScript وREST، من أول سؤال نعم/لا لديك حتى التوجيه حسب درجة الثقة، وإنشاء مجموعة اختبارات لخطوط CI.

ما هي واجهة Gemini Decisions API؟

واجهة Gemini Decisions API هي نقطة نهاية ضمن واجهة Gemini Developer API (v1beta) تجيب عن الأسئلة ذات الخيارات المغلقة بدلًا من توليد النصوص. ترسل مدخلًا واحدًا متعدد الوسائط وحتى 1,000 سؤال مستقل. يقيّم النموذج gemini-decision-1 كل خيار في تمريرة أمامية واحدة ويعيد احتمالات معايَرة يمكن لشفرتك التفرّع بناءً عليها مباشرة.

أعلنت Google عنها في 11 نوفمبر 2026. وتحدد الوثائق الرسمية ثلاثة أنواع من الأسئلة:

نوع السؤال	استخدمه لـ	يعيد
`noul`	التحقق مما إذا كانت العبارة صحيحة (نعم/لا)	`noul` (من 0.01 إلى 0.99)، `confidence`
`choice`	اختيار خيار واحد من 2 إلى 255 خيارًا	`choice`، `probabilities`، `confidence`
`score`	التقييم وفق مستويات مرتبة من 2 إلى 255	`score`، `probabilities`، `legend`، `confidence`

التسعير هو 0.10 دولار لكل مليون رمز إدخال، و0 دولار للإخراج، وفقًا لـصفحة أسعار Gemini API. يُحتسب المدخل المشترك في الفاتورة مرة واحدة لكل طلب، بغض النظر عن عدد الأسئلة التي تطرحها. إذا كنت قد قرأت دليلنا حول كيفية استخدام واجهة OpenAI Decisions API، فستشعر بالألفة مع الشكل العام، لكن الحقول الموضحة أدناه خاصة بـ Gemini.

الخطوة 1: احصل على مفتاح API وثبّت حزمة SDK

افتح Google AI Studio وأنشئ مفتاح API.
صدّره: export GEMINI_API_KEY="your-key".
ثبّت الإصدار 3.2 من حزمة SDK أو أحدث: pip install -U google-genai أو npm install @google/genai@latest.

يمكنك تجربة الأسئلة دون شفرات أولًا عبر Decisions Playground، الذي يصدّر شفرات قابلة للتشغيل.

الطبقة المجانية، بتاريخ 12 نوفمبر 2026: تدرج صفحة حدود المعدل 200 طلب في الدقيقة، و50,000 رمز في الدقيقة، و10,000 طلب يوميًا في الطبقة المجانية. الإدخال مجاني هناك، لكن صفحة الأسعار تشير إلى أن بيانات الطبقة المجانية «تُستخدم لتحسين منتجاتنا: نعم»، لذا احتفظ ببيانات العملاء الحقيقية في طبقة مدفوعة. لمزيد من المعلومات عن الحصص المجانية من Google، راجع دليلنا حول الطبقة المجانية لـ Gemini API.

الطبقة	RPM	TPM	RPD
مجانية	200	50,000	10,000
الطبقة 1	1,500	1,000,000	50,000
الطبقة 2	5,000	4,000,000	غير محدود
الطبقة 3	15,000	10,000,000	غير محدود

الخطوة 2: اطرح أول سؤال noul (نعم/لا)

يعيد السؤال من نوع noul احتمال أن تكون الإجابة "نعم". لاحظ إصدار API v1beta: فنقطة النهاية غير متاحة على v1.

Python:

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}")

JavaScript:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.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?" },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);

REST:

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?" }
    }
  }'

تعرض وثائق Google هذه الاستجابة (مثال من الوثائق، وليس من تجاربنا):

{
  "answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
  "usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}

عندما يكون معنى "نعم" غامضًا، أضف criteria مع true_description وfalse_description. قاعدة واحدة يجب تذكرها: تقع قيم noul دائمًا بين 0.01 و0.99، لذا فإن أي حد أدنى أعلى من 0.99 لن يتحقق أبدًا.

الخطوة 3: أضف أسئلة choice وscore

ضع الأسئلة المستقلة حول المدخل نفسه في طلب واحد. يُحتسب المدخل في الفاتورة مرة واحدة؛ وكل سؤال يضيف رموزه الخاصة فقط.

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order and the export page crashes in Safari.",
    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.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

هناك ثلاث تفاصيل من الوثائق تربك المستخدمين:

يتم ترتيب مفاتيح choice أبجديًا قبل التقييم. استخدم other كخيار شامل، وليس none_of_the_above الذي يترتب قبل الخيارات الحقيقية.
معايير score قائمة مرتبة من الأدنى إلى الأعلى وتبدأ الفهرسة من 0. القيمة score المعادة هي متوسط مرجّح بالاحتمالات، لذا قد تقع بين المستويات (تعرض الوثائق القيمة 1.12).
النموذج لا يرى مفاتيح أسئلتك أبدًا. اكتب السؤال الكامل في instructions.

للحصول على مستوى محدد من قيمة score، خذ الإدخال الأعلى احتمالًا:

sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])

الخطوة 4: أرسل الصور وملفات PDF والصوت

يقبل input سلسلة نصية، أو كتلة محتوى واحدة، أو قائمة كتل، بنفس تنسيق كتل واجهة Interactions API. الكتل المدعومة هي text وimage وaudio وvideo وdocument (بصيغة PDF فقط).

import base64

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo and form for return #8821.\n"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
        {"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
        "form_signed": {
            "type": "noul",
            "instructions": "Is the return form in the PDF signed by the customer?",
        },
    },
)

للصوت، مرر كتلة مثل {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. حدود تستحق المعرفة:

بيانات base64 المضمّنة محدودة بـ 100 ميغابايت لكل طلب (50 ميغابايت لملفات PDF)؛ وعناوين URL الخارجية محدودة بـ 15 ميغابايت لكل منها.
حدّد نوع MIME الحقيقي. ترفض الواجهة النوع application/octet-stream.
عناوين YouTube ومعرّفات gs:// غير مدعومة. استخدم Files API، أو عنوان HTTPS عام أو موقّع، أو بايتات مضمّنة.
تقايض قيمة resolution (low، medium، high، ultra_high) التفاصيل البصرية بالرموز. وخيار ultra_high للصور فقط.

الخطوة 5: اقرأ الاحتمالات ودرجة الثقة

تحمل كل إجابة قيمة confidence من 0 إلى 1، وهي الاحتمال المقدّر بأن الإجابة الأعلى صحيحة. بالنسبة لـ choice وscore، فهي تساوي احتمال النتيجة الأعلى. وبالنسبة لـ noul، فهي تساوي max(noul, 1 - noul).

لذا فإن قيمة noul تساوي 0.03 تعني ثقة بقيمة 0.97: فالنموذج متأكد من أن الإجابة "لا".

الخطوة 6: وجّه الإجابات منخفضة الثقة إلى مسار احتياطي

استخدم القيمة لاختيار الإجراء، ودرجة الثقة لتقرير ما إذا كنت ستنفذ الإجراء تلقائيًا:

a = result.answers
dept = a["department"]

if dept.confidence >= 0.7 and dept.choice != "other":
    route_to(dept.choice)
elif dept.confidence >= 0.4:
    route_to_fallback_model(ticket)   # a bigger model reasons it out
else:
    route_to("human_review")

قيمتا القطع 0.7 و0.4 مجرد قيم افتراضية: توصي Google بتحديد العتبات بناءً على أمثلة موسومة من حركتك الفعلية. قاعدتان إضافيتان من الوثائق:

أسئلة choice توزع الاحتمال دائمًا على خياراتك، حتى عندما لا يناسبها أي منها. اربطها بفحص نطاق مثل: «هل تتعلق هذه الرسالة بطلب شراء؟»
تعامل مع المدخل كبيانات غير موثوقة. قد تدافع رسالة المستخدم عن تصنيف معين لنفسها. احتفظ بمراجعة بشرية أو فحص ثانٍ في المدفوعات وغيرها من الإجراءات عالية المخاطر.

Flowchart of confidence-based routing: a Decisions API answer with confidence of 0.7 or higher runs automatically, 0.4 to 0.7 goes to a fallback model, and below 0.4 goes to human review

الخطوة 7: دع وكيل البرمجة الخاص بك يختبرها باستخدام Apidog CLI

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

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

ثم أعط وكيلك توجيهًا واحدًا:

In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.

يقرأ الوكيل مخطط كل حمولة، ويتحقق من صحتها، ويكتب الموارد، ويشغّل مجموعة الاختبارات:

apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports

كل علامة أعلاه مأخوذة من apidog run --help في الإصدار CLI 2.2.12. الآن أي تغيير في التوجيه أو المعايير يقلب قرار إحدى حالات الاختبار سيُفشل التشغيل. أضف نفس الأمر apidog run ... -r cli,junit إلى GitHub Actions، وسيُظهر ملف JUnit أي تذكرة انقلبت؛ ويحتوي دليل Apidog CLI لخطوط CI/CD على ملف سير العمل، فيما يغطي Apidog CLI في Claude Code إعداد الوكيل. تغطي الخطة المجانية من Apidog حتى 4 مستخدمين.

الحدود وما لا يدعمه بعد

من حدود واجهة Decisions API، بتاريخ 12 نوفمبر 2026:

من 1 إلى 1,000 سؤال لكل طلب، ضمن نافذة سياق تبلغ 262,144 رمزًا.
لا يوجد تخزين مؤقت للسياق، ولا واجهة Batch API، ولا استدلال Flex أو Priority. المدخل المتكرر عبر الطلبات يُحتسب في الفاتورة بالكامل.
حجب السلامة يعيد رمز HTTP 400 مع error.code مثل safety أو prohibited_content، وليس إجابة.
متاح على Gemini Developer API (v1beta) فقط. تقول Google إن دعم Vertex AI «قادم قريبًا» دون تحديد تاريخ.

تُعلن Google عن زمن استجابة من 150 إلى 250 مللي ثانية من البداية إلى النهاية، شبه ثابت من 1 إلى 100 سؤال للمدخلات حتى 16 ألف رمز، وتقول إن Gemini Decision 1 يتصدّر مجموعة معايير القياس الخاصة بها بأدنى خطأ معايرة. هذه أرقام Google؛ قِس زمن الاستجابة على مدخلاتك الخاصة قبل تصميم أنظمتك بناءً عليها.

الأسئلة الشائعة

هل واجهة Gemini Decisions API مجانية؟ توجد طبقة مجانية يكون فيها الإدخال مجانيًا، بحد أقصى 200 طلب في الدقيقة، و50,000 رمز في الدقيقة، و10,000 طلب يوميًا (بتاريخ 12 نوفمبر 2026). قد تُستخدم بيانات الطبقة المجانية لتحسين منتجات Google. أما الطبقة المدفوعة فتسعّر بـ 0.10 دولار لكل مليون رمز إدخال.

ماذا تعني noul؟ إنه نوع الأسئلة نعم/لا. حقل noul هو احتمال أن تكون الإجابة "نعم"، بين 0.01 و0.99.

أي إصدار من API أحتاج؟ v1beta. اضبط http_options={"api_version": "v1beta"} في Python، أو apiVersion: "v1beta" في JavaScript، أو استدعِ /v1beta/decisions عبر REST.

هل يعمل على Vertex AI؟ ليس بعد. إنه متاح على Gemini Developer API فقط؛ وتدرج Google Gemini في Google Cloud كقادم قريبًا.

كيف أحدد عتبة الثقة؟ وسم بضع مئات من المدخلات الحقيقية، وشغّلها عبر الواجهة، ثم اختر نقطة القطع التي يتساوى عندها coût الإجراءات التلقائية الخاطئة مع تكلفة المراجعة البشرية.