شروع به کار با Gemini Decisions API

۱. مقدمه

بیشتر نرم‌افزارهای پس‌بک درواقع برای نوشتن پاراگراف‌ها به مدل هوش مصنوعی نیاز ندارند، بلکه فقط به پاسخی سریع و قابل‌اعتماد برای یک سؤال محدود نیاز دارند: بله یا نه؟ کدام تیم پشتیبانی مالک این بلیت است؟ چقدر فوری است؟

طبقه‌بندهای اختصاصی اولیه مانند TypeSafe AI's Jev اخیراً با نشان دادن اینکه چه اتفاقی می‌افتد وقتی تولید JSON آهسته و توکن‌به‌توکن را کنار می‌گذارید و تصمیمات مجموعه بسته را در یک مرحله امتیازدهی می‌کنید، علاقه توسعه‌دهندگان را به مدل‌های «بله/خیر» برانگیخته‌اند.

‫Gemini Decisions API از Google DeepMind (با بهره‌گیری از gemini-decision-1) این قابلیت را به‌صورت بومی به کیت توسعه نرم‌افزار google-genai می‌آورد و به شما امکان می‌دهد تا ۱٬۰۰۰ سؤال yes/no (noul)، چندگزینه‌ای (choice)، و مقیاس ترتیبی (score) را در یک مرحله با احتمالات کالیبره‌شده، ژتون‌های خروجی صفر، و پشتیبانی چندحالتی داخلی در نوشتار، عکس، صدا، ویدیو، و PDF ارزیابی کنید.

کارهایی که انجام خواهید داد

  • محیط Python محلی راه‌اندازی کنید و بااستفاده از کلید میانای برنامه‌سازی کاربردی Google AI Studio به gemini-decision-1 متصل شوید.
  • برنامه‌های نمونه‌ای را اجرا کنید که از مسیریابی بلیت‌ها، قوانین ایمنی، و تصمیم‌گیری داده‌های چندوجهی را شامل می‌شود و به شما کمک می‌کند Gemini Decisions API را درک کنید.

آنچه خواهید آموخت

  • چرا درخواست از مدل زبانی بزرگ گپ برای JSON باعث ایجاد تأخیر، هزینه، تجزیه، و مشکلات اطمینان در تصمیم‌گیری‌های مسیریابی ساده می‌شود.
  • نحوه عملکرد سه نوع سؤال: noul (بله/نه)، choice (انتخاب یک گزینه)، و score (مقیاس مرتب‌شده)، با هم در یک تماس client.decisions.create.
  • نحوه کنترل کردن هزینه کردن توکن چندحالتی بااستفاده از resolution و بازرسی کردن استفاده با input_tokens_by_modality.

آنچه نیاز خواهید داشت

  • Python 3.11+ و git در دستگاهتان (یا Google Cloud Shell) نصب شده باشد.
  • کلید Gemini API از Google AI Studio (برای این codelab، نیازی به راه‌اندازی پروژه Google Cloud نیست).

‫۲. آشنایی با Gemini Decisions API

Why Asking a Chat LLM for JSON Slows Down Backends

مدل‌های زبانی بزرگ گپ برای مکالمه با افراد ساخته شده‌اند. وقتی از دستیاری می‌خواهید ایمیلی بنویسد یا اشکالی را توضیح دهد، چند ثانیه انتظار برای جاری شدن کلمات روی صفحه کاملاً طبیعی به‌نظر می‌رسد.

مشکلات زمانی شروع می‌شوند که سرویس‌های پس‌زمینه از همان گردش کار گپ فقط برای تصمیم‌گیری سریع درباره مسیریابی استفاده می‌کنند، مثلاً تصمیم‌گیری درباره اینکه «سفارش شماره ۱۹۰۲۸ من کجاست؟» را به کجا ارسال کنند یا اینکه آیا انجام خودکار آن ایمن است یا نه.

استفاده از مدل‌های Chat برای این موارد استفاده باعث می‌شود پاسخ‌ها بسیار کند، پرهزینه و مهم‌تر از همه شکننده باشند، که منجر به اطمینان غیرقابل‌اعتماد در انجام یک اقدام خاص یا ادامه دادن در جهتی خاص برای نماینده‌ها می‌شود.

نحوه عملکرد gemini-decision-1

‫gemini-decision-1 به‌جای تولید متن به‌صورت نشان‌به‌نشان، ورودی شما را یک‌بار می‌خواند و همه سؤالات شما را در یک مرحله امتیازدهی می‌کند و احتمالات کالیبره‌شده را مستقیماً برمی‌گرداند.

24a8561b90232d7f.jpeg

  • داده‌واحد برونداد صفر (۰٫۱۰ دلار / ۱ میلیون داده‌واحد ورودی، ۰ دلار داده‌واحد برونداد): چون مدل هرگز نوشتار یا داده‌واحد اندیشیدن تولید نمی‌کند، total_output_tokens همیشه 0 است. input هم‌رسانی‌شده شما یک‌بار در هر تماس صورت‌حساب می‌شود، صرف‌نظر از اینکه چند سؤال پیوست کنید.
  • محاسبه مدل ۵۰ تا ۱۰۰ میلی‌ثانیه: بدون تولید کدبه‌کد، محاسبه مدل سریع و قابل‌پیش‌بینی باقی می‌ماند، حتی زمانی که ۱۰، ۵۰، یا ۱۰۰ سؤال را در یک درخواست می‌پرسید.
  • چندحالتی آماده استفاده: نوشتار، تصویر، صدا، ویدیو، و سند PDF را باهم در پنجره بافت ۲۶۲٬۱۴۴ نشانه‌ای ارزیابی می‌کند و تنظیمات resolution (low، medium، high، ultra_high) را روی تصاویر و ویدیوها اعمال می‌کند تا مصرف نشانه‌ها را کنترل کند.

The Three Question Types (noul, choice, score)

هر تماس با client.decisions.create یک واژه‌نامه questions می‌گیرد که هر سؤال از یکی از سه نوع زیر استفاده می‌کند:

تایپ کردن

زمان استفاده

What Comes Back

noul (Yes / No)

بررسی اینکه آیا گزاره‌ای درست است («آیا این تزریق پیام‌واره است؟»)

noul (yes probability in [0.01, 0.99]) and confidence

انتخاب (۲ تا ۲۵۵ گزینه)

انتخاب یک برنده از واژه‌نامه ثابت («کدام تیم مالک این است؟»)

انتخاب (کلید برنده)، نقشه احتمالات، و اطمینان

امتیاز (۲ تا ۲۵۵ سطح)

رتبه‌بندی فوریت، شدت، یا کیفیت در فهرست مرتب‌شده (۰ تا K - ۱)

امتیاز (میانگین وزنی)، راهنما، احتمالات، و اطمینان

راهنمای گام‌به‌گام سریع به زبان انگلیسی ساده

تصور کنید مشتری این پیام را ارسال می‌کند: «سفارش شماره ۱۹۰۲۸ من کجاست؟ می‌توانی بگویی کی می‌رسد؟» در اینجا نحوه عملکرد هر نوع سؤال در آن پیام در یک فراخوانی API آورده شده است:

  • ‫**noul** (بله / نه) — «آیا می‌توانیم بدون دخالت انسان به‌طور خودکار به این پاسخ دهیم؟»: سؤال بله/خیر ارسال می‌کنید. آنچه برمی‌گردد noul = 0.98 و confidence = 0.98 است، یعنی ۹۸٪ احتمال دارد که پاسخ «بله» باشد. (اگر پاسخ به‌وضوح «نه» بود، noul = 0.02 و confidence = 0.98 را می‌دیدید.)
  • **choice** (Pick One Option) — "Which team should handle this message?": فهرست ثابتی از گزینه‌ها مثل 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 برای قطعی زنده).

۳. قبل‌از شروع

۱. دریافت کلید Gemini API

کلیدهای میانای Google AI Studio API را در مرورگرتان باز کنید، با حساب Google خود به سیستم وارد شوید، و کلید میانای API را ایجاد یا کپی کنید.

۲. همسانه‌سازی مخزن نمونه و راه‌اندازی 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"

۴. مثال ۱: مسیریابی بلیت‌های پشتیبانی

در این مثال اول، 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 شما تصمیم می‌گیرد که آستانه چقدر سخت‌گیرانه باشد.

اجرای ۱الف: سؤال ساده پیگیری سفارش

اجرای دستورات با سؤال پیش‌فرض پیگیری سفارش:

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، همین تماس در حدود ۱۵۵ تا ۱۹۵ میلی‌ثانیه تمام می‌شود.)

اجرای ۱ب: درخواست استرداد مبلغ ۱۴۰ دلاری تأییدنشده

اکنون یک $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 با اطمینان ۹۹٫۹۳٪ آن را در صف «صورت‌حساب» قرار می‌دهد.
  • آیا کد باید آن را به‌طور خودکار اجرا کند؟ (can_auto_resolve = 0.4282 -> decision: false): واگذاری مجدد $70 فقط از یک ادعای نوشتاری نیاز به درستی‌سنجی دارد. چون 0.4282 کمتر از حد آستانه auto.noul >= 0.80 ما است، decision دوباره false می‌شود.

۵. مثال ۲: اجرای ۸ بررسی خط‌مشی در یک تماس

در برنامه‌های واقعی پسین، پیام ورودی معمولاً به بیش‌از یک بررسی نیاز دارد تا کد شما به پایگاه داده برسد یا ابزاری را راه‌اندازی کند. با مدل‌های زبانی بزرگ گپ، انجام ۸ تماس جداگانه تأخیر شما را چندبرابر می‌کند و متن ورودی شما را ۸ بار صورت‌حساب می‌کند—درحالی‌که گنجاندن ۸ قانون در یک پیام‌واره JSON بزرگ باعث می‌شود مدل موارد حاشیه‌ای را ازدست بدهد.

بیایید scripts/parallel_guardrails.py را بررسی کنیم که ۸ بررسی مستقل (تزریق پیام‌واره، اطلاعات شخصی حساس/رازهای خام، واجدشرایط بودن برای استرداد فوری، تهدیدهای بازپرداخت، صف هدف، انتخاب ابزار، خطر ریزش، و سطح سوءاستفاده) را در یک تماس decisions.create ارزیابی می‌کند.

نحوه عملکرد دستورگان

مرحله ۱: فراداده رویداد و نوشتار را باهم به‌عنوان ورودی ارسال کنید

ارسال فرهنگ لغت 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?",
}

مرحله ۲: امتیازدهی به هر ۸ سؤال در یک مرحله

ما ۴ سؤال 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

مرحله ۳: ترکیب کردن پاسخ‌ها با قوانین اولویت در 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 }
  }
]

ارزیابی هر ۸ بررسی باهم تقریباً ۰٫۰۰۰۰۹۹ دلار به‌ازای هر رویداد با ۰ نشانه برونداد هزینه دارد.

‫۶. مثال ۳: بررسی عکس‌ها و فایل‌های PDF بدون OCR

معمولاً وقتی کاربری ادعایی را با پیوست (مثلاً عکس بازرسی تأسیسات یا فاکتور PDF) ارسال می‌کند، ابتدا باطن شما باید یک خط لوله OCR یا بینایی جداگانه را فقط برای استخراج نوشتار اجرا کند تا قوانین مسیریابی بتوانند اجرا شوند. چون gemini-decision-1 ذاتاً چندحالتی است، می‌توانیم هم ادعای کتبی و هم پیوست خام را باهم در یک فراخوانی decisions.create ارسال کنیم.

آنچه قرار است آزمایش کنیم

scripts/multimodal_triage.py دو سناریو را آزمایش می‌کند—هرکدام یک ادعای کتبی کوتاه را با یک پیوست جفت می‌کنند:

سناریو ۱: عکس بازرسی تسهیلات (وضوح پایین درمقابل وضوح بالا)

  • ادعای کتبی کاربر: «بررسی پیشخوان اتاق استراحت قبل‌از جلسه مشتری در ساعت ۹ صبح. کمی قهوه کنار دستمال پاک‌کننده ریخته است.»

عکس پیوست‌شده (03-multimodal-triage/spill.jpg): لکه قهوه تیره کوچکی را روی پیشخوان روشن نشان می‌دهد که دستمال طرح‌داری برای پاک کردن درست کنار آن قرار دارد:

3012ce039ce45cd5.jpeg

سناریو ۲: فاکتور PDF تکراری (بایت‌های PDF خام، بدون OCR)

  • ادعای کتبی کاربر: «در صورت‌حساب 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 (بدون OCR): پیوست کردن 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 وضوح از ۴ برابر داده‌واحد تصویری کمتر استفاده کرد (۲۶۶ درمقابل ۱٬۰۶۴): هر دو اجرا دقیقاً پاسخ یکسانی دادند (local_cleanup_or_self_service با اطمینان بیش‌از ۹۸٪). "high" یا "ultra_high" را برای متن‌های ریز یا چاپ‌های ظریف ذخیره کنید.
  • فاکتور PDF استرداد وجه را با صفر OCR تأیید کرد: با پیوست شدن sample_invoice_8812.pdf، evidence_supports_claim_prob به 0.9578 پرید و مدل automated_credit_or_replacement را در حدود ۶۷۷ میلی‌ثانیه انتخاب کرد.

‫۷. تبریک می‌گوییم

تبریک! از Gemini Decisions API ( استفاده کرده‌اید

gemini-decision-1

) در Python برای مسیریابی بلیت‌های پشتیبانی با احتمالات کالیبره‌شده، اجرای ۸ حفاظ ایمنی و خط‌مشی مستقل در یک گذر، و تأیید عکس‌ها و فاکتورهای PDF بدون مرحله OCR جداگانه، همه با صفر توکن خروجی.

وقتی آماده بودید که فراتر بروید، پوشه‌های اضافی را در مخزن همراه بررسی کنید—ازجمله 02-hybrid-gateway/ (استقرار یک سرویس سریع Cloud Run که بلیت‌های پیچیده را به gemini-3.8-flash واگذار می‌کند) و 06-adk-workflows/ (ترکیب Decisions API با Google ADK 2.0 Workflows).

اسناد مرجع