Gemini Decisions API 接入教程：零输出计费与多模态实战

Google Gemini Decisions API 接入教程：150ms 多模态决策与零输出计费实战

在构建生产级 AI 应用时，开发者常常面临一个典型的架构矛盾：许多高频任务（如意图路由、工具选择、内容合规初筛、多模态工单分级）并不需要模型长篇大论地生成文本，只需要从固定选项中快速给出一个带有置信度的判断。根据 [Google 官方博客发布的 Gemini Decisions API 公告]https://blog.google/innovation-and-ai/technology/developers-tools/gemini-decisions-api/，Google DeepMind 正式推出了专为封闭集判定设计的 Gemini Decisions API 与配套模型 gemini-decision-1。

与传统的生成式接口不同，Gemini Decisions API 跳过了逐 Token 解码过程，在单次前向传播（Single Forward Pass）中直接计算候选答案的校准概率。它支持同时传入文本、图像、音频、视频和 PDF（最高 256K Tokens），并在一次请求中并发评估最多 1,000 个独立问题，端到端延迟低至 150–250ms。在计费方面，gemini-decision-1 输入价格为 $0.10 / 1M Tokens，且输出 Token 完全零计费（$0）（价格与功能以官方最新公布为准）。本教程将带你从零完成该接口的接入、代码实战与成本测算。

Gemini Decisions API 能帮你做到什么与前置条件

在传统的 Agent 架构中，如果你用生成式接口（如 [Gemini API 更新日志]https://ai.google.dev/gemini-api/docs/changelog中的 gemini-3.5-flash-lite）做分类或打分，不仅要承担思维链（Thinking Tokens）和 JSON 结构化输出的 Token 开销，还要容忍数百毫秒乃至数秒的解码延迟。接入 Gemini Decisions API 后，你可以在以下四大场景获得显著收益：

1. 动态模型路由（Model Routing）：在毫秒级内判断用户提问的复杂度，将简单查询分流至轻量模型，仅将复杂推理任务交给 [Gemini 4 Carbon]https://blog.google/innovation-and-ai/models-and-research/gemini-models/gemini-4-carbon-now-available/等旗舰模型（Google 内部在 Gemini Notebook 中采用该方案降低了最高 40% 的日常查询延迟）。
2. 多模态内容审核与工单定级：一次性传入一段客服通话录音、一张破损商品照片和一份 PDF 理赔单，同时完成合规检查、责任归属分类与严重程度打分。
3. MCP 工具调用安全网关：在执行外部工具调用前，并发校验多条安全策略规则，识别潜在的提示词注入或越权行为。[内链：MCP 协议安全实践指南]
4. RAG 上下文相关性重排与评分：对召回的多个文档片段批量执行置信度打分，过滤低于阈值的噪声片段。

接入前置条件

在开始编写代码前，请确认满足以下环境与账号要求：

• 账号与 API Key：拥有 Google 账号并登录 Google AI Studio 获取 API Key。gemini-decision-1 在 AI Studio 提供免费原型测试额度（No-cost tier），生产环境建议使用已绑定结算账户的 Paid Tier 项目。
• 开发环境：Python 3.10 及以上版本，并安装最新版官方 SDK google-genai（建议 pip install -U google-genai，版本需 >= 1.50.0 以支持 client.decisions 命名空间），或直接使用支持 HTTPS 请求的 curl 工具。
• 接口版本：当前 Decisions 端点位于 v1beta API 版本下，初始化客户端时需显式指定 api_version="v1beta"。
• 费用标准：输入 $0.10 / 1M Tokens，输出 $0 / 1M Tokens，无额外思维链 Token 费用或独立 OCR/语音转写附加费（以官方最新公布为准）。

分步骤操作：三种决策原语与参数配置

根据 [Gemini Decisions API 官方技术说明]https://blog.google/innovation-and-ai/technology/developers-tools/gemini-decisions-api/，该接口复用与 Interactions API 相同的 input 内容块格式，核心在于通过 questions 字典定义需要评估的问题集合。每个问题支持以下三种原语类型（Decision Primitives）：

步骤一：准备共享多模态输入（Shared Input）

input 参数接收一个数组，单次请求的总上下文上限为 256K Tokens（在 16K Tokens 以内时，模型计算中位延迟稳定在 50–100ms）。你可以混合传入文本（text）、图像（image）、音频（audio）、视频（video）和文档（pdf）。最关键的计费优势在于：无论你在 questions 中定义了 1 个还是 1,000 个问题，共享的 input 内容在单次请求中只计费一次。

步骤二：定义三种决策问题类型

在 questions 对象中，每个键名（Key）代表你自定义的决策字段名，其值包含 type、instructions 和可选的 criteria：

1. noul（是非判定 / Yes-No）：评估某项条件是否成立，返回成立的概率（0 到 1 之间）。支持通过 criteria 为 true 和 false 补充细化判定标准。
2. choice（多选一 / Multiple Choice）：从 2 到 255 个候选选项中选出最匹配的一项，返回胜出选项标识及所有候选项的归一化概率分布。criteria 以键值对形式定义每个选项的语义描述。
3. score（有序量表打分 / Ordered Rubric）：按从 0 开始的有序等级列表对输入进行评级，返回连续加权总分（Weighted Score）以及每个等级对应的概率。criteria 为按严重程度或质量递增的字符串数组。

步骤三：解析置信度并设置人工兜底阈值

接口返回的每道题结果均包含校准后的概率或置信度分数（0.0–1.0）。在生产代码中，建议设定明确的置信度水位线（例如 0.85）：当最高选项概率高于 0.85 时自动放行执行；若介于 0.50 至 0.85 之间，则触发二次校验或转交人工审核队列。

完整可运行的代码示例（Python 与 cURL）

下面以“电商售后与门店巡检多模态联合判定”为例，展示如何在一次 API 请求中同时完成是非检测（noul）、处理动作路由（choice）与严重度分级（score）。

1. Python SDK 完整写法

依赖环境：Python >= 3.10，安装依赖 pip install "google-genai>=1.50.0"，并在环境变量中配置 GEMINI_API_KEY。

import os
from google import genai

# 1. 初始化客户端，显式指定 v1beta 版本
client = genai.Client(
    api_key=os.environ.get("GEMINI_API_KEY"),
    http_options={"api_version": "v1beta"}
)

def evaluate_counter_inspection():
    # 2. 发起单次多模态决策请求（共享输入仅计费 1 次）
    result = client.decisions.create(
        model="gemini-decision-1",
        input=[
            {
                "type": "image",
                "uri": "https://storage.googleapis.com/generativeai-downloads/images/spill.jpg",
                "mime_type": "image/jpeg",
            },
            {
                "type": "text",
                "text": "上午 9 点客户会议前的茶水间台面巡检记录。",
            },
        ],
        questions={
            # 类型一：是非题 (noul)
            "has_spill": {
                "type": "noul",
                "instructions": "台面上是否存在未清理的液体泼洒痕迹？",
            },
            # 类型二：多选题 (choice，支持 2-255 个选项)
            "next_action": {
                "type": "choice",
                "instructions": "当前场景应采取哪种清理或响应动作？",
                "criteria": {
                    "wipe_with_cloth": "台面仅有小范围泼洒，且旁边备有抹布或纸巾可快速擦拭。",
                    "dispatch_janitorial": "地面存在大面积积水、碎玻璃或持续漏水等安全隐患。",
                    "ready_for_meeting": "台面干净整洁，可直接接待客户。",
                },
            },
            # 类型三：有序量表打分 (score，从 0 级开始递增)
            "severity": {
                "type": "score",
                "instructions": "请评估当前台面脏乱或隐患的严重程度。",
                "criteria": [
                    "0级：干净整洁，无需处理。",
                    "1级：轻微局部泼洒，可自行快速清理。",
                    "2级：严重泼洒或存在滑倒、触电等安全隐患。",
                ],
            },
        },
    )

    # 3. 打印返回的校准概率与决策结果
    print("决策原始响应：", result)
    return result

if __name__ == "__main__":
    evaluate_counter_inspection()

2. cURL（REST API）请求写法

如果你的后端服务使用 Go、Rust 或 Java，可直接通过 HTTP POST 调用 v1beta 下的 Decisions 端点：

curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      {
        "type": "image",
        "uri": "https://storage.googleapis.com/generativeai-downloads/images/spill.jpg",
        "mime_type": "image/jpeg"
      },
      {
        "type": "text",
        "text": "上午 9 点客户会议前的茶水间台面巡检记录。"
      }
    ],
    "questions": {
      "has_spill": {
        "type": "noul",
        "instructions": "台面上是否存在未清理的液体泼洒痕迹？"
      },
      "next_action": {
        "type": "choice",
        "instructions": "当前场景应采取哪种清理或响应动作？",
        "criteria": {
          "wipe_with_cloth": "台面仅有小范围泼洒，且旁边备有抹布或纸巾。",
          "dispatch_janitorial": "存在大面积积水、碎玻璃或持续漏水隐患。",
          "ready_for_meeting": "台面干净整洁，可直接使用。"
        }
      },
      "severity": {
        "type": "score",
        "instructions": "评估当前台面脏乱的严重程度。",
        "criteria": [
          "干净整洁，无需处理。",
          "轻微局部泼洒。",
          "严重泼洒或存在安全隐患。"
        ]
      }
    }
  }'

常见报错和解决方法

在集成 gemini-decision-1 的过程中，开发者最容易遇到以下 4 类报错：

1. AttributeError: 'Client' object has no attribute 'decisions' 或 404 Not Found
   • 原因：本地安装的 google-genai SDK 版本过旧，或初始化 genai.Client 时未指定 http_options={"api_version": "v1beta"}（默认稳定版端点尚未挂载 decisions 路由）。
   • 解决方法：执行 pip install -U google-genai 升级 SDK，并在代码中显式声明 api_version="v1beta"。[内链：Google GenAI SDK 升级指南]
2. 400 INVALID_ARGUMENT: choice criteria count must be between 2 and 255
   • 原因：在 choice 类型问题中，传入的 criteria 候选项少于 2 个（只有一个选项无法构成选择），或超过了单题 255 个选项的硬性上限。
   • 解决方法：若只需判断单一条件是否满足，请将 type 改为 "noul"；若分类标签超过 255 个，建议拆分为两级层次化问题（先判定大类 Choice，再判定子类 Choice）放入同一个 questions 字典中并发评估。
3. 400 INVALID_ARGUMENT: too many questions in a single request (max 1000)
   • 原因：单次请求的 questions 字典键数量超过了 1,000 题上限，或者总输入（含 input 与所有问题的 instructions/criteria）超出了 256K Tokens 窗口。
   • 解决方法：将超大规则集按最多 1,000 题一批进行分块请求，或精简每道题 criteria 中的冗余描述文本。
4. 400 INVALID_ARGUMENT: unsupported question type 'boolean'
   • 原因：受传统 JSON Schema 习惯影响，将是非题的 type 误写成了 "boolean" 或 "yes_no"。
   • 解决方法：严格按照官方文档规范，将是非题的 type 字段设置为 "noul"。

费用估算和使用建议

根据 [Google 官方公布的定价规则]https://blog.google/innovation-and-ai/technology/developers-tools/gemini-decisions-api/，gemini-decision-1 的计费公式非常透明（以官方最新公布为准）：

$$\text{单次请求费用} = \frac{\text{共享 Input Tokens} + \sum(\text{各题 Instructions 与 Criteria Tokens})}{1,000,000} \times \$0.10 + \$0\text{（输出免费）}$$

实战账单测算示例：
假设你运营一个日均处理 100,000 次多模态客服工单的路由系统，每次请求包含 1 张截图 + 1 段用户描述（合计约 1,500 Tokens），并同时评估 20 个审核与分类问题（合计约 500 Tokens）：

• 单次请求总输入：1,500 + 500 = 2,000 Tokens
• 每日总输入量：100,000 × 2,000 = 200,000,000 Tokens（即 200M Tokens）
• 每日 API 总成本：200 × $0.10 = $20.00（平均每次 20 题联合多模态判定仅需 $0.0002）。

相比之下，若使用 gemini-3.5-flash-lite 通过生成 JSON 的方式逐题回答，不仅需要支付输出与思维链 Token 费用，据 Google 官方基准测算，其综合成本约为 Gemini Decisions API 的近 5 倍。[内链：主流大模型 API 价格对比表]

工程落地建议：

1. 合并同源问题（Batching Questions）：尽量把针对同一份文档、图片或对话的所有检查项（如合规性、语言识别、情绪打分、部门路由）合并到同一次 decisions.create 调用中，充分利用“共享输入只收一次费且 1–100 题延迟几乎持平”的特性。
2. 善用生态集成：目前 google-genai SDK、OpenRouter、LangChain、Vercel、LiteLLM、Pydantic AI、Pipecat 和 LiveKit 均已在推进对该接口的原生支持，现有基于这些框架的项目可直接将其挂载为前置 Router 节点。

总结

Gemini Decisions API 与 gemini-decision-1 的推出，标志着大模型 API 正在从“万物皆生成（Text-to-Text）”走向“生成与判别解耦”。对于中文开发者而言，利用其 150–250ms 的低延迟、单次 1,000 题的多模态并发评估能力以及 $0.10/1M 输入、零输出计费的定价策略，可以大幅削减 Agent 网关、内容风控与多模态分类流水线的推理账单。

常见问题

1. Gemini Decisions API 收费吗？有没有免费额度？

收费标准为输入每百万 Tokens $0.10（$0.10 / 1M input tokens），输出 Tokens 完全免费（$0）。同时，Google 在 Google AI Studio 中为开发者提供了免费层级（No-cost tier），可用于开发阶段的原型验证与接口联调（具体限额以官方最新公布为准）。

2. Gemini Decisions API 和 OpenAI 的 Decisions API 有什么区别？

根据 OpenAI API Changelog 与 [Google 官方博客]https://blog.google/innovation-and-ai/technology/developers-tools/gemini-decisions-api/，OpenAI 的 Decisions API（基于 gpt-6-luna，10 月 22 日 GA）主要支持文本与图像输入，单次请求最多支持 400 个问题；而 Google 的 Gemini Decisions API（基于 gemini-decision-1）原生支持文本、图像、音频、视频和 PDF 五种模态输入（最高 256K 上下文），单次请求最多支持 1,000 个问题，且输出 Token 零计费。

3. gemini-decision-1 可以用来生成文本解释或修改建议吗？

不可以。gemini-decision-1 是专为封闭集决策（Closed-set decisions）设计的判别式端点，它不进行逐 Token 文本生成，只返回各候选选项的校准概率、胜出项或量表加权得分。如果需要生成文字反馈，建议先用 gemini-decision-1 判定问题类别和严重度，仅在命中特定条件时路由给生成式模型。

4. 单次请求评估 100 道题会比评估 1 道题慢很多吗？

不会。由于 gemini-decision-1 在单次前向传播中并行评分而非串行解码，根据 Google 官方实测数据，在 16K Tokens 上下文以内，从评估 1 道题增加到 100 道题，延迟曲线几乎保持水平，模型计算中位延迟稳定在 50–100ms（端到端延迟约 150–250ms）。

参考来源

- [Gemini Decisions API: Fast, calibrated multimodal decisions - Google Blog](https://blog.google/innovation-and-ai/technology/developers-tools/gemini-decisions-api/)（2026-11-11 / 2026-11-12）
- [Release notes - Gemini API - Google AI Studio](https://ai.google.dev/gemini-api/docs/changelog)（2026-11-11）
- [Changelog | OpenAI API - OpenAI Developers](https://developers.openai.com/api/docs/changelog)（2026-11-05）