1. مقدمة
لا تحتاج معظم برامج الخلفية إلى نموذج ذكاء اصطناعي لكتابة الفقرات، بل تحتاج فقط إلى إجابة سريعة وموثوقة عن سؤال محدّد: نعم أم لا؟ أي فريق دعم يملك هذا الطلب؟ ما مدى أهمية الأمر؟
أثارت أدوات التصنيف المخصّصة المبكرة، مثل Jev من TypeSafe AI، اهتمام المطوّرين مؤخرًا بنماذج "نعم/لا" من خلال إظهار ما يحدث عند التخلي عن إنشاء ملفات JSON البطيئة التي تعتمد على الرموز المميّزة، وتقييم القرارات ذات المجموعة المغلقة في خطوة واحدة.
توفّر Gemini Decisions API من Google DeepMind (المستندة إلى gemini-decision-1) هذه الإمكانية بشكلٍ مدمج في حزمة تطوير البرامج (SDK) لـ google-genai، ما يتيح لك تقييم ما يصل إلى 1,000 سؤال من نوع yes/no (noul) وخيارات متعدّدة (choice) ومقياس مرتّب (score) في عملية واحدة مع احتمالات معايرة وصفر رموز مميّزة للمخرجات ودعم مدمج للوسائط المتعدّدة في النصوص والصور والصوت والفيديو وملفات PDF.
المهام التي ستنفّذها
- إعداد بيئة Python محلية والربط بـ
gemini-decision-1باستخدام مفتاح واجهة برمجة تطبيقات Google AI Studio - يمكنك تشغيل برامج نموذجية تتراوح بين توجيه الطلبات وقواعد السلامة واتخاذ القرارات المستندة إلى البيانات المتعددة الوسائط، ما يساعدك في فهم Gemini Decisions API.
ما ستتعلّمه
- لماذا يؤدي توجيه طلب إلى نموذج لغوي كبير للمحادثة للحصول على JSON إلى حدوث مشاكل في وقت الاستجابة والتكلفة والتحليل والثقة في قرارات التوجيه البسيطة؟
- كيفية عمل أنواع الأسئلة الثلاثة:
noul(نعم/لا) وchoice(تحديد خيار واحد) وscore(مقياس مرتّب) معًا في طلب واحد منclient.decisions.create. - كيفية التحكّم في إنفاق الرموز المميّزة المتعدّدة الوسائط باستخدام
resolutionوفحص الاستخدام باستخدامinput_tokens_by_modality
المتطلبات
- الإصدار 3.11 من Python أو إصدار أحدث و
gitمثبّتان على جهازك (أو Google Cloud Shell). - مفتاح Gemini API من Google AI Studio (لا حاجة إلى إعداد مشروع على Google Cloud لهذا الدرس التطبيقي حول الترميز).
2. فهم Gemini Decisions API
Why Asking a Chat LLM for JSON Slows Down Backends
تم إنشاء النماذج اللغوية الكبيرة المخصّصة للدردشة لإجراء محادثات مع الأشخاص. عندما تطلب من مساعد كتابة رسالة إلكترونية أو شرح خطأ، من الطبيعي أن تنتظر بضع ثوانٍ بينما تظهر الكلمات على الشاشة.
تبدأ المشاكل عندما تستخدم خدمات الخلفية سير عمل المحادثة نفسه لاتخاذ قرار سريع بشأن التوجيه، مثل تحديد مكان إرسال "أين طلبي رقم 19028؟" أو ما إذا كان من الآمن تنفيذه تلقائيًا.
يؤدي استخدام نماذج Chat في حالات الاستخدام هذه إلى بطء الردود وتكلفتها العالية، والأهم من ذلك، إلى هشاشتها، ما يؤدي إلى ثقة غير موثوقة في اتخاذ إجراء معيّن أو المضي قدمًا في اتجاه معيّن للوكلاء.
طريقة عمل gemini-decision-1
بدلاً من إنشاء نصّ من إنشاء الذكاء الاصطناعي رمزًا تلو الآخر، يقرأ gemini-decision-1 إدخالك مرة واحدة ويقيّم جميع أسئلتك في عملية واحدة، ما يتيح له تقديم احتمالات دقيقة مباشرةً.

- عدم استخدام رموز مميّزة للمخرجات (0.10 دولار أمريكي لكل مليون رمز مميّز للمدخلات، و0 دولار أمريكي للرموز المميّزة للمخرجات): بما أنّ النموذج لا ينشئ أبدًا نصًّا من إنشاء الذكاء الاصطناعي أو رموزًا مميّزة للتفكير، تكون قيمة
total_output_tokensدائمًا0. يتم تحصيل رسومinputالمشترَكة مرة واحدة لكل طلب، بغض النظر عن عدد الأسئلة التي ترفقها. - عملية حوسبة النموذج تستغرق من 50 إلى 100 ملي ثانية: بدون إنشاء الرموز المميّزة واحدًا تلو الآخر، تظل عملية حوسبة النموذج سريعة ويمكن توقّعها حتى عند طرح 10 أو 50 أو 100 سؤال في طلب واحد.
- متعدد الوسائط وجاهز للاستخدام: يقيّم النصوص والصور والصوت والفيديو ومستندات PDF معًا في نافذة سياق تتسع لـ 262,144 رمز مميز، مع إعداد
resolution(lowوmediumوhighوultra_high) على الصور والفيديو للتحكّم في إنفاق الرموز المميزة.
أنواع الأسئلة الثلاثة (noul، choice، score)
يستدعي كل طلب إلى client.decisions.create قاموس questions حيث يستخدم كل سؤال أحد الأنواع الثلاثة التالية:
النوع | حالات الاستخدام | ما تتم استعادته |
noul (نعم / لا) | التحقّق مما إذا كانت العبارة صحيحة ("هل هذا حقن طلبات؟") | noul (احتمال "نعم" في [0.01, 0.99]) والثقة |
choice (من خيارَين إلى 255 خيارًا) | اختيار فائز واحد من قاموس ثابت ("أي فريق يملك هذا؟") | والخيار (المفتاح الفائز) وخريطة الاحتمالات والثقة |
النتيجة (من مستويَين إلى 255 مستوى) | تقييم مدى الإلحاح أو الخطورة أو الجودة في قائمة مع ترتيب (من 0 إلى K - 1) | النتيجة (المتوسط المرجح) ووسيلة الإيضاح والاحتمالات والثقة |
A Quick Plain-English Walkthrough
لنفترض أنّ أحد العملاء أرسل هذه الرسالة: "أين طلبي رقم 19028؟ هل يمكنك إخباري عندما يصل؟" في ما يلي طريقة عمل كل نوع من الأسئلة في تلك الرسالة من خلال طلب بيانات من واجهة برمجة التطبيقات واحد:
- **
noul** (نعم / لا) — "هل يمكننا الإجابة عن هذا السؤال تلقائيًا بدون تدخّل بشري؟": أرسِل سؤالاً تكون إجابته نعم أو لا. النتيجة التي تظهر هيnoul = 0.98وconfidence = 0.98، ما يعني أنّ هناك احتمالاً بنسبة %98 أن تكون الإجابة "نعم". (إذا كانت الإجابة "لا" بشكل واضح، فسيظهر لكnoul = 0.02وconfidence = 0.98). - **
choice** (يُرجى تحديد خيار واحد) — "أي فريق يجب أن يتعامل مع هذه الرسالة؟": يمكنك إرسال قائمة ثابتة من الخيارات، مثلorder_statusوbilling_refundوaccount_accessوother. ما يتم عرضه هو المفتاح الفائز (choice = "order_status") ومستوى الثقة (0.9995) وتفاصيل الاحتمالات لكل خيار، والتي يبلغ مجموعها1.0. - **
score** (مقياس مرتّب) — "ما مدى أهمية هذه الرسالة؟": يتم إرسال مقياس مرتّب من الأدنى (0) إلى الأعلى (3)، مثل["Low", "Medium", "High", "Critical"]. النتيجة التي تظهر هي متوسط مرجّح للاحتمالات بين0و3(score = 0.15لسؤال تتبُّع روتيني مقابل ما يقرب من2.98لانقطاع الخدمة المباشر).
3- قبل البدء
1. الحصول على مفتاح Gemini API
افتح مفاتيح واجهة برمجة التطبيقات في Google AI Studio في المتصفّح، وسجِّل الدخول باستخدام حسابك على Google، وأنشئ مفتاح واجهة برمجة تطبيقات أو انسخه.
2. استنساخ نموذج المستودع وإعداد Python
افتح وحدة طرفية، واستنسِخ المستودع المصاحب gcp-gemini-decisions-hybrid-gateway، وأنشئ بيئة افتراضية، وثبِّت التبعيات:
git clone https://github.com/rominirani/gcp-gemini-decisions-hybrid-gateway.git
cd gcp-gemini-decisions-hybrid-gateway
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
صدِّر GEMINI_API_KEY في جلسة الوحدة الطرفية نفسها:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
4. المثال 1: توجيه طلبات الدعم
في هذا المثال الأول، سنفحص ونشغّل scripts/quickstart_decisions.py، الذي يطرح جميع أنواع الأسئلة الثلاثة: department (choice) وcan_auto_resolve (noul) وurgency (score) في طلب بيانات واحد من واجهة برمجة التطبيقات.
فحص الرمز
في ما يلي طلب client.decisions.create الأساسي داخل scripts/quickstart_decisions.py:
from google import genai
client = genai.Client(api_key=api_key, http_options={"api_version": "v1beta"})
result = client.decisions.create(
model="gemini-decision-1",
input=query_text,
questions={
"department": {
"type": "choice",
"instructions": "Which operational queue should handle this customer message?",
"criteria": {
"order_status": "Order tracking, delivery dates, or shipment status.",
"billing_refund": "Duplicate charges, invoices, credits, or refund requests.",
"subscription_cancel": "Canceling or pausing a recurring subscription.",
"account_access": "Password resets, expired 2FA/MFA codes, or login lockouts.",
"complex_incident": "Production outages, HTTP 500 errors, or legal questions.",
"other": "Anything outside these specific categories.",
},
},
"can_auto_resolve": {
"type": "noul",
"instructions": "Can this request be fulfilled deterministically by an automated "
"backend lookup or webhook without custom investigation?",
"criteria": {
"true_description": "Routine single-intent request such as checking tracking.",
"false_description": "Outage, legal question, or ambiguous billing dispute.",
},
},
"urgency": {
"type": "score",
"instructions": "Rate the operational urgency and severity of this message.",
"criteria": [
"Low: Routine informational or tracking question.",
"Medium: Standard account, subscription, or billing request.",
"High: Time-sensitive customer impact or repeated billing failure.",
"Critical: Production-halting outage, data loss risk, or security incident.",
],
},
},
)
dept = result.answers["department"]
auto = result.answers["can_auto_resolve"]
urg = result.answers["urgency"]
# The API returns raw probabilities; our script sets the cutoff for auto-handling (80%):
auto_decision = auto.noul >= 0.80
يُرجى ملاحظة السطر الأخير (auto.noul >= 0.80): لا تفرض واجهة برمجة التطبيقات Decisions API حدًا أقصى ثابتًا، بل تعرض الاحتمال الأولي noul (من 0.01 إلى 0.99)، ويحدّد رمز Python البرمجي مدى صرامة الحدّ الأدنى.
التشغيل 1A: سؤال بسيط حول تتبُّع الطلبات
شغِّل النص البرمجي باستخدام السؤال التلقائي لتتبُّع الطلبات:
python scripts/quickstart_decisions.py
سيظهر لك ردّ JSON مباشر مشابه لما يلي:
{
"query": "Where is my order #19028? Can you tell me when it arrives?",
"model": "gemini-decision-1",
"latency_ms": 944.61,
"department": {
"choice": "order_status",
"confidence": 0.9995,
"probabilities": {
"billing_refund": 0.0001,
"other": 0.0001,
"complex_incident": 0.0002,
"subscription_cancel": 0.0,
"order_status": 0.9995,
"account_access": 0.0001
}
},
"can_auto_resolve": {
"noul_probability_yes": 0.98,
"confidence": 0.98,
"decision": true
},
"urgency": {
"expected_score_0_to_3": 0.1524,
"top_level": "Low: Routine informational or tracking question.",
"confidence": 0.8717
},
"suggested_action": "DISPATCH_TRACKING_WEBHOOK",
"usage": {
"total_input_tokens": 424,
"total_output_tokens": 0,
"estimated_cost_usd": 4.24e-05
}
}
(ملاحظة: يشمل وقت الاستجابة المحلي للطلب الأول إعداد اتصال TLS الأولي من جهازك. وعند تشغيل الطلب في Google Cloud Run في us-central1، ينتهي الطلب نفسه في غضون 155 إلى 195 ملي ثانية تقريبًا).
Run 1B: Unverified $140 Refund Request
الآن، أرسِل مطالبة بشأن تحصيل رسوم مكرّرة بقيمة $140 بدون إرفاق أي فاتورة بعد:
python scripts/quickstart_decisions.py \
"I was billed twice ($140 total) on invoice #8812 for one seat. Refund $70 right now."
افحص الناتج المباشر:
{
"query": "I was billed twice ($140 total) on invoice #8812 for one seat. Refund $70 right now.",
"model": "gemini-decision-1",
"latency_ms": 602.23,
"department": {
"choice": "billing_refund",
"confidence": 0.9993,
"probabilities": {
"other": 0.0001,
"complex_incident": 0.0,
"order_status": 0.0001,
"billing_refund": 0.9993,
"subscription_cancel": 0.0004,
"account_access": 0.0001
}
},
"can_auto_resolve": {
"noul_probability_yes": 0.4282,
"confidence": 0.5718,
"decision": false
},
"urgency": {
"expected_score_0_to_3": 1.3634,
"top_level": "Medium: Standard account, subscription, or billing request.",
"confidence": 0.5987
},
"suggested_action": "INITIATE_BILLING_WORKFLOW",
"usage": {
"total_input_tokens": 433,
"total_output_tokens": 0,
"estimated_cost_usd": 4.33e-05
}
}
انظر إلى كيفية عمل هذين السؤالين المستقلين معًا:
- أين يجب إرسال هذا الطلب؟ (
department = billing_refund,0.9993): يطلب العميل استرداد الأموال المدفوعة مقابل فاتورة، لذا فإنّgemini-decision-1متأكد بنسبة %99.93 من أنّ الطلب ينتمي إلى قائمة انتظار الفوترة. - هل يجب أن ينفّذ الرمز البرمجي ذلك تلقائيًا؟ (
can_auto_resolve = 0.4282->decision: false): يجب التحقّق من صحة إعادة$70من مطالبة نصية وحدها. بما أنّ0.4282أقل من الحدّ الأدنى المطلوب فيauto.noul >= 0.80، ستعودdecisionإلىfalse.
5- المثال 2: إجراء 8 عمليات تحقّق من السياسات في طلب واحد
في تطبيقات الخلفية الحقيقية، تحتاج الرسالة الواردة عادةً إلى أكثر من عملية تحقّق واحدة قبل أن يصل الرمز إلى قاعدة بيانات أو يشغّل أداة. في النماذج اللغوية الكبيرة للمحادثة، يؤدي إجراء 8 طلبات منفصلة إلى مضاعفة وقت الاستجابة وتحصيل رسوم مقابل نص الإدخال 8 مرات، في حين أنّ حشو 8 قواعد في طلب JSON ضخم واحد يجعل النموذج يفوّت الحالات الاستثنائية.
لنلقِ نظرة على scripts/parallel_guardrails.py، الذي يقيّم 8 عمليات فحص مستقلة (حقن الطلبات، ومعلومات تكشف الهوية الشخصية/الأسرار الأولية، والأهلية لاسترداد الأموال الفوري، والتهديدات باسترداد المبالغ المدفوعة، وقائمة الانتظار المستهدفة، واختيار الأداة، ومخاطر التوقف عن استخدام الخدمة، ومستوى إساءة الاستخدام) في طلب واحد من decisions.create.
طريقة عمل النص البرمجي
الخطوة 1: تمرير البيانات الوصفية للحدث والنص معًا كإدخال
من خلال تمرير قاموس JSON متسلسل كـ input، يمكن لـ gemini-decision-1 التحقّق من الحقول المنظَّمة (مثل amount_usd وorder_age_days) إلى جانب رسالة العميل ذات التصميم المرن، مع فوترة الحمولة المشتركة مرة واحدة فقط:
event = {
"event_id": "evt-03-clean-refund",
"customer_tier": "PREMIUM",
"order_age_days": 6,
"amount_usd": 34.0,
"message": "Order #77102 arrived yesterday with a cracked mug handle. Could I get a $34 refund?",
}
الخطوة 2: تقييم جميع الأسئلة الثمانية في جولة واحدة
نحدّد 4 أسئلة من النوع noul وسؤالَين من النوع choice وسؤالَين من النوع score في EIGHT_PARALLEL_QUESTIONS ونمرّرها في طلب واحد:
EIGHT_PARALLEL_QUESTIONS = {
"prompt_injection_attempt": { "type": "noul", "instructions": "...", "criteria": {...} },
"contains_raw_pii_or_secrets": { "type": "noul", "instructions": "...", "criteria": {...} },
"eligible_for_instant_refund": {
"type": "noul",
"instructions": "Does this request qualify for instant automated refund under policy "
"(amount <= $50, order_age_days <= 30, clear defect or duplicate)?",
"criteria": {...},
},
"threatens_chargeback_or_legal": { "type": "noul", ... },
"target_queue": { "type": "choice", ... },
"selected_mcp_tool": { "type": "choice", ... },
"churn_risk": { "type": "score", ... }, # 0..3 (Low -> Severe)
"abuse_toxicity": { "type": "score", ... }, # 0..2 (Benign -> Hostile)
}
result = client.decisions.create(
model="gemini-decision-1",
input=json.dumps(event), # Shared input — billed once
questions=EIGHT_PARALLEL_QUESTIONS, # All 8 questions scored in parallel
)
a = result.answers
الخطوة 3: دمج الإجابات مع قواعد الأولوية في Python
بما أنّ كل سؤال يعرض نتيجته المستقلة داخل result.answers، يتحقّق رمز Python أولاً من مخاطر الأمان (حقن الطلبات والمعلومات السرية المسرَّبة) قبل السماح بأي عملية ردّ أموال مبرمَجة:
if a["prompt_injection_attempt"].noul >= 0.70:
gate_verdict = "QUARANTINE_ADVERSARIAL_INPUT"
elif a["contains_raw_pii_or_secrets"].noul >= 0.75:
gate_verdict = "REDACT_PII_BEFORE_STORAGE"
elif a["threatens_chargeback_or_legal"].noul >= 0.75 or a["churn_risk"].score >= 2.3:
gate_verdict = "ROUTE_TO_VIP_RETENTION_SPECIALIST"
elif a["eligible_for_instant_refund"].noul >= 0.85 and a["selected_mcp_tool"].confidence >= 0.80:
gate_verdict = "AUTO_EXECUTE_INSTANT_REFUND"
else:
gate_verdict = f"DISPATCH_{a['selected_mcp_tool'].choice.upper()}"
تشغيل النص البرمجي
نفِّذ scripts/parallel_guardrails.py لاختبار ثلاث عيّنات من الرسائل: محاولة حقن الطلبات، ومفتاح واجهة برمجة تطبيقات sk_live_... تم لصقه عن طريق الخطأ، وطلب ردّ أموال سليم بشأن كوب تالف من $34:
python scripts/parallel_guardrails.py
راجِع الناتج المباشر في جميع الأحداث التجريبية الثلاثة:
[
{
"event_id": "evt-01-injection",
"gate_verdict": "QUARANTINE_ADVERSARIAL_INPUT",
"questions_evaluated_in_parallel": 8,
"latency_ms": 626.34,
"signals": {
"prompt_injection_prob": 0.9766,
"raw_pii_prob": 0.0426,
"instant_refund_prob": 0.0275,
"target_queue": "security_trust",
"selected_mcp_tool": "quarantine_security_event"
},
"usage": { "total_input_tokens": 977, "total_output_tokens": 0, "estimated_cost_usd": 9.77e-05 }
},
{
"event_id": "evt-02-pii-leak",
"gate_verdict": "REDACT_PII_BEFORE_STORAGE",
"questions_evaluated_in_parallel": 8,
"latency_ms": 724.48,
"signals": {
"prompt_injection_prob": 0.0548,
"raw_pii_prob": 0.9755,
"instant_refund_prob": 0.0292,
"target_queue": "security_trust",
"selected_mcp_tool": "quarantine_security_event"
},
"usage": { "total_input_tokens": 999, "total_output_tokens": 0, "estimated_cost_usd": 9.99e-05 }
},
{
"event_id": "evt-03-clean-refund",
"gate_verdict": "AUTO_EXECUTE_INSTANT_REFUND",
"questions_evaluated_in_parallel": 8,
"latency_ms": 625.68,
"signals": {
"prompt_injection_prob": 0.0133,
"raw_pii_prob": 0.01,
"instant_refund_prob": 0.9676,
"target_queue": "billing_ops",
"selected_mcp_tool": "issue_instant_credit"
},
"usage": { "total_input_tokens": 987, "total_output_tokens": 0, "estimated_cost_usd": 9.87e-05 }
}
]
تبلغ تكلفة تقييم جميع عمليات التحقّق الثمانية معًا حوالي 0.000099 دولار أمريكي لكل حدث مع 0 رمز مميّز للمخرجات.
6. المثال 3: التحقّق من الصور وملفات PDF بدون تكنولوجيا التعرّف البصري على الأحرف
عادةً، عندما يرسل المستخدم مطالبة مع مرفق، مثل صورة فحص منشأة أو فاتورة PDF، يتعيّن على الواجهة الخلفية تشغيل مسار منفصل للتعرّف البصري على الأحرف أو الرؤية أولاً لاستخراج النص قبل تشغيل قواعد التوجيه. بما أنّ gemini-decision-1 هو نموذج متعدد الوسائط، يمكننا إرسال كل من المطالبة المكتوبة والمرفق الأوّلي معًا في طلب واحد إلى decisions.create.
ما سنختبره
يختبر scripts/multimodal_triage.py سيناريوهَين، يجمع كل منهما بين ادّعاء مكتوب قصير ومرفق:
السيناريو 1: صورة فحص المنشأة (دقة منخفضة مقابل دقة عالية)
- الادّعاء المكتوب للمستخدم: "التحقّق من طاولة غرفة الاستراحة قبل اجتماع العميل في الساعة 9 صباحًا. تم رصد بقعة قهوة صغيرة بجانب قطعة قماش للمسح".
الصورة المرفقة (03-multimodal-triage/spill.jpg): تعرض بقعة قهوة داكنة صغيرة على منضدة فاتحة اللون وبجانبها قطعة قماش منقوشة للمسح:

السيناريو الثاني: فاتورة PDF مكرّرة (بايتات PDF أولية، بدون التعرّف البصري على الأحرف)
- مطالبة المستخدم المكتوبة: "تم تحصيل مبلغ 45 دولار أمريكي مرتين (بإجمالي 90 دولار أمريكي) في الفاتورة INV-8812. أرفقتُ فاتورة بتنسيق PDF."
- ملف PDF مرفق (
03-multimodal-triage/sample_invoice_8812.pdf): فاتورة من صفحة واحدة تتضمّنLine 1: Pro Plan Monthly Subscription ... $45.00وLine 2: Pro Plan Monthly Subscription [DUPLICATE] $45.00(المجموع:$90.00).
ما نتوقّع رؤيته
- صورة الانسكاب (دقة منخفضة مقابل دقة عالية): يجب أن ترصد كلتا العمليتين الانسكاب الصغير على المنضدة وتقدّم الإجابة نفسها، مع أنّ دقة
lowتستخدم عددًا أقل بكثير من الرموز المميّزة للصور. - فاتورة PDF (بدون التعرّف البصري على الأحرف): إرفاق
sample_invoice_8812.pdfيثبت أنّه تم تحصيل الرسوم من العميل مرتين، لذا يجب أن يقرأ النموذج ملف PDF مباشرةً ويوافق على ردّ الأموال.
الاطّلاع على الرمز
بدلاً من تمرير سلسلة واحدة إلى input، يمرّر scripts/multimodal_triage.py قائمة بمجموعات المحتوى، بدءًا من مجموعة text (تنتهي بـ \n)، تليها إما مجموعة image أو مجموعة document (application/pdf):
# For Run 1a & 1b: Pass an image URL and set resolution ("low" vs. "high")
image_block = {
"type": "image",
"uri": "https://storage.googleapis.com/generativeai-downloads/images/spill.jpg",
"mime_type": "image/jpeg",
"resolution": "low", # or "high" in Run 1b
}
# For Run 2: Read raw PDF bytes from disk and base64-encode them as a "document" block
# (Note: PDF document blocks do not take a "resolution" setting)
pdf_block = {
"type": "document",
"data": base64.b64encode(pdf_bytes).decode("ascii"),
"mime_type": "application/pdf",
}
result = client.decisions.create(
model="gemini-decision-1",
input=[
{"type": "text", "text": f"Claim Statement: {claim_text}\nAttached Evidence:\n"},
media_block, # either image_block or pdf_block
],
questions=MULTIMODAL_QUESTIONS,
)
لمقارنة استخدام الرموز المميّزة بين resolution="low" وresolution="high"، يقرأ النص البرمجي أيضًا result.usage.input_tokens_by_modality، الذي يقسّم الرموز المميّزة للإدخال إلى "text" مقابل "image".
تشغيل النص البرمجي والتحقّق من النتائج
python scripts/multimodal_triage.py
افحص الردّ المباشر بتنسيق JSON في جميع عمليات التشغيل الثلاث:
[
{
"experiment": "1a_photo_resolution_low",
"resolution": "low",
"evidence_supports_claim_prob": 0.9532,
"disposition": "local_cleanup_or_self_service",
"disposition_confidence": 0.9863,
"severity_expected_0_to_3": 1.0319,
"tokens_by_modality": { "text": 441, "image": 266 },
"total_input_tokens": 707,
"total_output_tokens": 0,
"estimated_cost_usd": 7.07e-05
},
{
"experiment": "1b_photo_resolution_high",
"resolution": "high",
"evidence_supports_claim_prob": 0.9154,
"disposition": "local_cleanup_or_self_service",
"disposition_confidence": 0.9825,
"severity_expected_0_to_3": 1.0471,
"tokens_by_modality": { "text": 441, "image": 1064 },
"total_input_tokens": 1505,
"total_output_tokens": 0,
"estimated_cost_usd": 0.0001505
},
{
"experiment": "2_pdf_duplicate_invoice_zero_ocr",
"resolution": null,
"latency_ms": 676.98,
"evidence_supports_claim_prob": 0.9578,
"disposition": "automated_credit_or_replacement",
"disposition_confidence": 0.9367,
"severity_expected_0_to_3": 1.9849,
"tokens_by_modality": { "text": 587, "image": 520 },
"total_input_tokens": 1107,
"total_output_tokens": 0,
"estimated_cost_usd": 0.0001107
}
]
هناك خلاصتان سريعتان من الناتج:
lowاستخدمت الدقة رموزًا مميزة للصور أقل بـ 4 مرات (266 مقابل 1,064): قدّمت كلتا العمليتين الإجابة نفسها بالضبط (local_cleanup_or_self_serviceبمستوى ثقة يزيد عن %98). يمكنك حفظ"high"أو"ultra_high"للنصوص الصغيرة أو المطبوعات الدقيقة.- فاتورة PDF التي وافقت على ردّ الأموال بدون استخدام ميزة "التعرّف البصري على الأحرف": بعد إرفاق
sample_invoice_8812.pdf، انتقلevidence_supports_claim_probإلى0.9578واختار النموذجautomated_credit_or_replacementفي غضون 677 ملي ثانية تقريبًا.
7. تهانينا
تهانينا! لقد استخدمت Gemini Decisions API (
gemini-decision-1
) في Python لتوجيه طلبات الدعم باستخدام احتمالات معايرة، وتشغيل 8 إجراءات وقائية مستقلة للأمان والسياسات في عملية واحدة، والتحقّق من الصور وفواتير PDF بدون خطوة منفصلة للتعرّف البصري على الأحرف، وكل ذلك بدون استخدام أي رموز مميزة للمخرجات.
عندما تكون مستعدًا للمتابعة، يمكنك الاطّلاع على المجلدات الإضافية في المستودع المصاحب، بما في ذلك 02-hybrid-gateway/ (نشر خدمة Cloud Run سريعة تسلّم الطلبات المعقّدة إلى gemini-3.8-flash) و06-adk-workflows/ (الجمع بين Decisions API وGoogle ADK 2.0 Workflows).
المستندات المرجعية
- منشور الإطلاق الرسمي: اتّخاذ قرارات سريعة بشأن الخيارات المحدودة باستخدام Gemini Decisions API
- مستندات المطوّرين: دليل Gemini Decisions API (ذكاء Google الاصطناعي للمطوّرين)
- مساحة تجربة تفاعلية: تجربة Gemini Decision 1 في Google AI Studio
- مستودع الرموز البرمجية النموذجية: https://github.com/rominirani/gcp-gemini-decisions-hybrid-gateway