你把商品照片和一份 PDF 交給 AI，回來一個 0.9。它是在說「有裂痕的機率」，還是「自己很有把握」？把同一份文件印出來再掃描，或者把問題換個說法，原本的自動分流規則還站得住嗎？這篇 Gemini Decision 1 教學，帶你從第一個圖片與 PDF 請求，走到一張能回查錯誤的工作表。
前半專為沒有機器學習背景的讀者寫；程式段適合能執行 Python 3、已有可用 Gemini API 帳戶的人。你會學會分清三種回傳、設計同題對照，以及決定哪些案件先交人。本文依 2026 年 11 月 13 日查閱的官方文件整理操作與評估方法，未呼叫模型取得 AlphaLab 的照片或 PDF 測試成績。
先說結論：可採用的判斷＝答案＋驗過的分數＋複核出口
把模型想成收貨櫃台的分類員：答案是要送去哪個櫃子，信心是分類員附上的估計；你自己的帶標籤題集，才是查帳的收據。分數有助於分流，但要先確認它在你這批照片、文件與問法上，是否對應到實際錯誤。
Google 在 2026 年 11 月 11 日公告推出 Decisions API，模型識別碼為 gemini-decision-1。它接收材料與有限答案的問題，回傳供程式判斷的數值。今天的目標是先把這個接線與驗收流程建立起來，讓「分到哪裡」與「能否自動處理」各有依據。
一、Gemini Decision 1 教學先認三張成績單
API（程式向服務發送請求的介面）像收件窗口。你交一份材料，另外寫好要問的問題與可選答案。多模態表示材料可以有不同形式，例如圖片與 PDF；它描述輸入形式，並未替你的商品辨識品質打分。
- ① yes/no：「這件事成立嗎？」型別名稱是
noul。回傳的noul是 yes 的估計機率；confidence是max(p, 1-p)。假設 p＝0.10，信心就是 0.90，方向卻是「否」。只寫「confidence 高就當有裂痕」，會把意思翻反。 - ② choice：「哪一格最適合？」你提供選項與條件，讀取
choice、各選項的probabilities和confidence。分配是在所給選項之間進行；因此要明確給「資料不清／規則未涵蓋」出口，再檢查它是否真的接住反例。 - ③ score：「落在尺上的哪裡？」把等級描述由低到高放進陣列，索引從 0 起算。
score是索引的機率加權平均；confidence另讀。它適合做程度摘要，別把等級平均值當成答對率。
以上欄位定義可在 官方回傳說明核對。純算術例子：三級尺的機率若為 0.10、0.70、0.20，score＝0×0.10＋1×0.70＋2×0.20＝1.10。這是一組教學用數字，沒有對應任何模型執行結果；把它乘以百分之百，也不會變成 110% 準確率。
二、先做考卷：同一件商品，留下四份紀錄
「我該拍什麼？」先選不涉及真實交易的外觀分類。拿自己的杯子或紙盒拍照，避開人臉、姓名、地址與訂單號。完整品、表面刮痕、可見裂痕，以及因反光或遮擋而難判的情境都要有；同一個物件的不同照片共用一個 case_id。
再自製一頁「收貨練習規則」：可見裂痕先送檢；外觀完整且照片清楚的進正常品登錄；刮痕、證據不足或規則未涵蓋的交複核。把它匯出成可選字的 policy-text.pdf，再列印掃描成 policy-scan.pdf。用眼睛核對兩份的字句、頁數與方向相同；故意模糊、歪斜的版本另列壓力測試。
先在不看模型輸出的情況下寫好標籤：照片是否看得見裂痕、依規則該進哪個隊列、外觀等級，以及人也判不清的理由。「照片看不清」不能偷換成「實物一定完好」。多人合作時先各自標，再討論分歧；若分歧來自規則，先改規則並重新標註。
- 文字 PDF＋問法 A：作為基準。
- 文字 PDF＋問法 B：只改同義問法，檢查提問敏感度。
- 掃描 PDF＋問法 A：只改文件形式，觀察文件讀取差異。
- 掃描 PDF＋問法 B：觀察兩種變化一起出現時的結果。
可以先用 12 個基礎案例檢查接線，得到 48 份四組紀錄。12 與 48 是練習安排，不是通過校準的樣本門檻。四份紀錄共享同一件商品，切開發集與保留集時，也必須以商品分組；否則同一件商品的掃描版進了保留集，並沒有考到真正的新案例。
三、Gemini Decision 1 教學實作：把照片與 PDF 放進同一個請求
第 1 步：「金鑰放哪裡？」先在自己的終端機操作
到 Google AI Studio 的 API Keys 頁取得你有權使用的金鑰，存取或配額問題先處理帳戶設定。下方使用 Python 標準函式庫直接呼叫 REST，不需要安裝額外套件；程式會以隱藏輸入提示讀取金鑰，也接受既有的 GEMINI_API_KEY 環境變數。不要把金鑰放進圖片、工作表或程式檔。官方金鑰指南可協助核對專案與權限。
若選擇 SDK 路線，官方 Python SDK 3.2.0 發布紀錄列出新增 client.decisions.create；本文刻意選 REST，方便直接看清送出的 JSON。兩條路使用相同的業務題目，但不要把一般文字生成介面的參數混貼過來。
第 2 步：「先送什麼？」存成 decision_request.py
準備真正 JPEG 格式的 product.jpg 與前面的兩份 PDF。官方輸入規格分別用 image、document 區塊；下例把檔案轉為 base64（把位元組編成文字，並非加密）。每份練習檔先保持很小，確認一題可用再擴大。
import base64, datetime, getpass, hashlib, json, os, pathlib, sys, time
import urllib.request
photo, pdf = map(pathlib.Path, sys.argv[1:3])
variant, output = sys.argv[3:5] # A 或 B；output 每次用不同檔名
assert variant in ('A', 'B')
if pathlib.Path(output).exists():
raise FileExistsError('請換一個尚未存在的輸出檔名。')
key = os.environ.get('GEMINI_API_KEY') or getpass.getpass('Gemini API key: ')
def block(path, kind, mime):
return {'type': kind, 'mime_type': mime,
'data': base64.b64encode(path.read_bytes()).decode('ascii')}
questions = {
'damage': {'type': 'noul', 'instructions': (
'只看商品照片：商品本體是否有可見裂痕？忽略包裝與 PDF 的敘述。'
if variant == 'A' else
'依商品照片判斷：商品本體能看見裂痕嗎？不要依包裝或 PDF 敘述推定。')},
'route': {'type': 'choice', 'instructions':
'根據照片與 PDF 處理規則，這個商品應先進入哪一個隊列？',
'criteria': {'inspect': '符合文件的送檢條件，先交檢查員。',
'catalogue': '符合文件的正常品登錄條件。',
'review': '規則未涵蓋、資料不清楚或證據衝突。'}},
'severity': {'type': 'score', 'instructions':
'只依商品照片可見的商品本體損傷評級，忽略包裝與 PDF。',
'criteria': ['外觀未見損傷。', '可見表面刮痕，但未見裂痕或缺角。',
'可見裂痕或缺角。']}}
payload = {'model': 'gemini-decision-1', 'questions': questions,
'input': [block(photo, 'image', 'image/jpeg'),
block(pdf, 'document', 'application/pdf')]}
record = {'time_utc': datetime.datetime.now(datetime.timezone.utc).isoformat(),
'model': payload['model'], 'variant': variant,
'inputs': {str(p): hashlib.sha256(p.read_bytes()).hexdigest()
for p in (photo, pdf)}, 'questions': questions}
req = urllib.request.Request(
'https://generativelanguage.googleapis.com/v1beta/decisions',
data=json.dumps(payload).encode('utf-8'), method='POST',
headers={'Content-Type': 'application/json', 'x-goog-api-key': key})
start = time.perf_counter()
try:
with urllib.request.urlopen(req, timeout=60) as response:
record['http_status'] = response.status
record['response'] = json.load(response)
except Exception as error:
record['error_type'] = type(error).__name__
record['http_status'] = getattr(error, 'code', None)
finally:
record['elapsed_ms'] = (time.perf_counter() - start) * 1000
with open(output, 'x', encoding='utf-8') as f:
json.dump(record, f, ensure_ascii=False, indent=2)
print('已保存紀錄；' + ('請檢查錯誤，勿採用分類。' if 'error_type' in record
else '請開啟 JSON，核對 answers 與 usage。'))
這段會把完整回應、題目、輸入檔雜湊與等待時間寫到新 JSON。雜湊像檔案指紋，用來核對四組是否拿同一份照片。這個等待時間量的是本機開始呼叫到讀完回應，含網路，不是 Google 的純模型運算時間。
它是單次請求示例，沒有實作批次排程、重試或正式隊列寫入；錯誤會留下類型與 HTTP 狀態，先修好再以新檔名重跑。正式接線要另外保存重試次數，對 429 依 Retry-After 等待並限制重試總量。HTTP 成功後也要檢查 answers 是否含預期題目、型別與合法數值，才能進入後續分流。
第 3 步：「怎麼重跑才可比？」先固定照片
python3 decision_request.py product.jpg policy-text.pdf A c01-text-A.json
python3 decision_request.py product.jpg policy-text.pdf B c01-text-B.json
python3 decision_request.py product.jpg policy-scan.pdf A c01-scan-A.json
python3 decision_request.py product.jpg policy-scan.pdf B c01-scan-B.json四次執行各自是一次 API 請求。A／B 只改 damage 的句子，route、severity 的題目與選項維持相同。一次請求中的題目各自看共用輸入；要依裂痕結果決定隊列，應由程式合併判斷，別假設後題已讀到前題答案。
四、分數變動工作表：先看錯誤，再看分數
「回應一大包 JSON，要抄哪幾格？」每次請求一列，先建下列欄位。pdf_kind 與 case_id 由你記錄；p_yes 讀 response.answers.damage.noul，其餘答案同樣從 response.answers 取得。原始 JSON 另外保留，工作表不取代它。
case_id,pdf_kind,variant,gold_damage,gold_route,gold_level,
p_yes,damage_confidence,choice,choice_confidence,score,
score_confidence,elapsed_ms,http_status,error_type,record_file先逐案例做三件事：① 標籤是否改變；② p_yes 改變多少；③ 改變後是否更符合人工標籤。用 Δp＝本組 p_yes－文字 PDF／A 的 p_yes。例如人工標為有裂痕，假設基準 0.85、另一組 0.55，Δp＝−0.30；這只是示意算法，表示答案方向更靠近不確定，仍得打開圖片與原始回應查原因。
裂痕題刻意要求忽略 PDF，所以換文件後它仍變動，是值得追查的交叉影響訊號；隊列題本來就要讀 PDF，則更適合找文件形式造成的差異。觀察到變化，只能先說這個配對有差異。若要判斷變化是否超過服務重跑本身的波動，還要在同一組條件重複請求並記下每次結果；別把單次差值直接歸因為掃描害的。
校準（calibration）問的是：一批被報為約 0.9 的 yes 機率，實際約有多少是 yes。scikit-learn 的校準曲線說明採用分箱後的平均預測與正例比例；每箱也要列樣本數。你可把四組各自畫圖，再按清晰度分層，避免大多清楚照片掩蓋少數掃描失敗。小題集的空箱與單題箱，適合找問題，還不足以證明正式流量校準良好。
想多留一個可重算指標，可對人工已判定 yes／no 的裂痕題算 Brier＝平均((p_yes－gold_damage)²)，yes 記 1、no 記 0；人也判不清的題另列。這個損失同時受辨識能力等因素影響，不能單憑較低數字就說校準更好。校準與準確率各回答不同問題，Guo 等人的原始校準研究可補足背景。
五、人工複核區間怎麼設？先選錯誤代價
「全部設 0.9，可以嗎？」先問錯誤會造成什麼。把完整商品送去檢查，多一道工；把有裂痕商品登錄成正常品，可能造成漏檢。這兩種錯誤的代價不同，門檻應在有人工標籤的門檻調整集選，再拿未參與調整的商品驗收。決策門檻文件把機率估計與採取行動分開，也提醒避免用同一批資料調整與評估。
先用下面的教學用分流草稿理解兩端與中間區間。0.20、0.80 都是待驗旋鈕，不是 Gemini 官方推薦值；即使落在兩端，仍要檢查輸入品質、隊列衝突與錯誤紀錄。起步時只產生建議標籤，實際商品處理仍留在現有流程。
若請求失敗、欄位不符、照片難辨識或規則未涵蓋：交複核
否則若 p_yes >= 0.80：建議送檢
否則若 p_yes <= 0.20：建議暫列「未見裂痕」
否則：交複核
若上述建議與 choice 隊列衝突：交複核這裡的「未見裂痕」只描述那張照片的可見證據，仍保留刮痕、缺角與文件規則的其他檢查。choice 選到 review 時，無論信心高低都進複核。這能避免「很有把握要交人」反而被高信心規則攔回自動路線。
調門檻時一起寫下自動建議覆蓋率、其中的錯誤率、人工複核比例，並逐類看漏檢與誤送檢。分數提高後，若只留下最容易的照片，自動部分看起來會更準，但需要人工的工作也可能增加。失敗請求要留在總量帳內，別因為沒有分數就刪掉。
想把分流結果接到工具，可接著讀 Agent Harness 實作，練習把判斷、動作與驗收放進同一個迴圈。
Google 的延遲與校準成績是它發布的測試主張。本篇不把那組速度套給掃描 PDF，也不替四組預填正確率。可帶走的成果，是相同商品、固定題目、原始回應與人工標籤能逐列對上；模型、問法、圖片處理或文件來源改了，就用新的保留案例重新檢查。
常見問題：八個先講答案的判斷
1. confidence 0.9 就表示有裂痕嗎？
不表示。yes/no 題要先讀 p_yes；p_yes＝0.1 時也能有 0.9 的信心，方向卻是 no。
2. score 1.1 是 110% 信心嗎？
不是。它是你定義的等級索引加權平均；要連同各級機率讀。
3. 只加 review 選項就夠了嗎？
還要驗。拿模糊、未知物件與規則衝突測它是否真的選 review；程式也要保留獨立複核條件。
4. 文字 PDF 和掃描 PDF 可以直接算誰較準嗎？
可以在同題、同規則下比較，但要先確認掃描內容相同，並按商品配對。小樣本只呈現這批題目的結果。
5. 把題目改得更清楚，舊門檻還能沿用嗎？
要重驗。新問法先成為新版本，沿用同一份人工標籤測分數與錯誤，再用保留案例檢查。
6. 12 個商品、48 份回應等於 48 個獨立案例嗎？
不等於。四組共享商品；資料切分與不確定性分析都應保留這個分組關係。
7. HTTP 200 就能採用答案嗎？
還要驗欄位與業務規則。缺題、型別不符或證據矛盾時，留錯誤紀錄並交複核。
8. 我今天做到哪裡算入門？
完成一個商品的四組 JSON、人工標籤與差值，能解釋為什麼送檢或交人，就是第一個可回查成果。
給新手的三個重點
- 先讀答案的方向，再讀信心；程度分數另外解讀。
- 把同一商品的四種輸入留在一起，保留人類標籤與原始 JSON。
- 門檻是用錯誤代價換來的選擇；把覆蓋率與複核量一起記帳。
接著閱讀
左右滑動查看更多推薦
下一步：先交出一張能回查的分流紀錄
今天先挑一件商品，做兩份內容相同的 PDF，再完成 A／B 四次請求。把 p_yes、信心、隊列、錯誤與人工答案放在一起，親自回答：「這個變化改變了哪個決定？」可採用的判斷＝答案＋驗過的分數＋複核出口。想繼續把這些步驟接成自己的 AI 工作流，可以從 AI 教學入口挑下一個練習，或到 AlphaLab 課程安排系統化學習。