Gemini Decisions API 快速入门:用 Python 和 curl 获取是/否、选择和评分答案

Google 的 Gemini Decisions API 返回的是概率而不是文本,输出 token 不计费。本文提供 Python 和 curl 的分步快速入门,并介绍限制和常见陷阱。

Graphic showing a quickstart for the Gemini Decisions API with a yes, choice and score answer card.

大多数时候,你向 AI 模型提问,并不想要一篇长文作为回答。你想要的是“yes”“billing”或“7 分(满分 10)”,好让代码选一个分支继续执行。Google 新推出的 Gemini Decisions API 正是为此而生,而且输出完全免费。

在 Mindloop Experience 上观看:Gemini Decisions API: 1,000 Questions in One Call for $0.10 per Million Tokens

本指南将教你如何用 Python 和 curl 发起第一次调用、读懂三种答案,并避开 Google 文档中提到的陷阱。内容以 Google 截至 2026 年 11 月 15 日的文档为准。我们检查了 Python 和 curl 示例的语法(代码可以编译,JSON 请求体可以正常解析)。真实调用需要你自己的 API 密钥,因此下文的示例输出均来自官方文档。

Decisions API 到底是什么

Google 于 2026 年 11 月 11 日推出了它,配套模型名为 Gemini Decision 1(gemini-decision-1)。这个模型不写文本,而是为你给出的选项打分并返回概率。Google 表示,一个请求最多可以针对同一份输入携带 1,000 个问题;对于不超过 16K token 的输入,端到端延迟中位数为 150 到 250 毫秒。

价格为每百万输入 token 0.10 美元,输出始终为零 token。共享输入每个请求只计费一次,无论你问多少个问题。Google AI Studio 提供免费层级,Google 的定价页面称,免费层级的数据可能会被用于改进其产品;付费层级则不会。

Simon Willison 指出,Google 的这款模型属于一个只有两个竞争对手的小众类别。据他介绍,Gemini Decision 1 的价格与 OpenAI 的 GPT-6 Luna 决策模型相同,而一款名为 Jev 的模型更便宜,每百万 token 只要 4.2 美分。他还发现了一个特点:对于是/否问题,Jev 和 OpenAI 会直接返回 1.0 或 0.0,而 Gemini 返回的是 0.92、0.05 这样更柔和的数值。

你需要准备什么

  • 一个来自 Google AI Studio 的 Gemini API 密钥。
  • 装有 Google GenAI SDK 3.2 或更高版本的 Python。JavaScript 用户需要 @google/genai。
  • 任意 HTTP 客户端,如果你不想用 SDK 的话。

第 1 步:安装 SDK 并设置密钥

终端
pip install -U google-genai
export GEMINI_API_KEY=your-key-here

Google 文档中的 curl 示例从 GEMINI_API_KEY 读取密钥。想更全面地了解如何从 Python、JavaScript 和 curl 调用 Gemini,可以参阅我们的 Gemini 4 Hydrogen API 指南。

第 2 步:提出第一个是/否问题

这是 Google 文档中的快速入门示例。将它保存为 decisions.py:

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

运行 python decisions.py。文档显示,“yes”的概率和置信度都为 0.99,total_output_tokens 为 0。你选择的键名(is_damaged)只是一个标签,模型根本看不到它,所以要把完整的问题写进 instructions。

第 3 步:用 curl 试一试

这个 API 只是一个 POST 请求,因此不需要任何 SDK:

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

第 4 步:了解三种问题类型

类型用途需要 criteria 吗?返回内容
noul判断一个是/否陈述否noul(0.01 到 0.99)、confidence
choice从 2 到 255 个选项中选一个是,选项到描述的映射choice, probabilities, confidence
score按从 0 开始的有序等级打分是,等级列表score, probabilities, legend, confidence

一个 choice 问题如下所示(文档中的示例输入是“I was charged twice for my order.”[我的订单被扣了两次款]):

代码
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.",
        },
    },
}

score 的值是各等级编号按概率加权的平均值,因此可能落在两个等级之间。Flavio Copes 的文章中,在三级量表上得到的结果是 1.12。

第 5 步:让置信度决定由谁执行

每个答案都带有一个 0 到 1 之间的 confidence,即最高答案正确的估计概率。Google 建议用答案来选择动作,用置信度来决定代码是否执行它:

代码
answer = result.answers["department"]
if answer.confidence >= 0.7:
    route_to(answer.choice)
else:
    route_to("human_review")

这里的 route_to 是你自己的函数。Google 建议根据你自己流量中带标注的样本来设定阈值,而不是照搬 0.7。

第 6 步:批量提问

把针对同一输入、彼此独立的问题放进一个请求。共享输入只计一次,而且可以混合不同类型。Google 的示例在一次调用中为一张客服工单做路由:一个是/否缺陷判断、一个四选一的动作选择,以及一个四级流失评分。各个问题之间互相不可见。

需要了解的限制

限制项数值
每个请求的问题数1 到 1,000
上下文窗口262,144 token,包含输入和问题
免费层级每分钟 200 次请求,每天 10,000 次
第 1 层级(Tier 1)每分钟 1,500 次请求,每天 50,000 次

常见错误及解决方法

  • 检查“确定无疑”时什么都没发生。是/否概率始终在 0.01 到 0.99 之间,所以 noul > 0.99 这样的判断永远不会成立。请在这个范围内设置阈值。
  • 无意义的输入也会被贴上标签。即使没有一个选项合适,选择题也会把概率分配到你的各个选项上。添加一个带描述的 other 选项,并检查置信度。
  • 兜底选项没有排在最后。API 会按字母顺序对选项键排序,所以 none_of_the_above 会排在 shipping 之前,而不是最后。请使用带描述的兜底选项,例如 other。
  • 出现 400 错误。当你超出限制、密钥校验失败或触发安全过滤时,就会返回这个错误。错误响应体会给出一个 code,例如 safety。
  • 媒体无法加载。不支持 YouTube 链接和 gs:// 地址。请使用 Files API URI、公开或签名的 HTTPS 链接,或内联 base64 数据。
  • 处理长文档时账单悄悄上涨。这里没有上下文缓存,也没有 Batch API,重复的输入会全额计费。请把所有问题放在一个请求里一次问完。
  • 用户文本导致结果异常。Google 提醒,输入内容可能会为自己的分类“辩护”。凡是涉及资金流动的操作,前面都要有人工或第二道检查。
  • 配置出问题。在排查其他问题之前,先确认你使用的是 SDK 3.2 或更高版本,以及 v1beta API 版本。文档称该 API 仅在 v1beta 上提供。

什么时候该用别的工具

Decisions API 适合答案集合固定的路由、过滤和规则检查。如果你需要生成文本、摘要,或符合你自定义 JSON 架构的值,Google 建议改用 Interactions API。如果你更想把模型放在自己的硬件上运行,我们的 Ollama 指南介绍了这条路线。

资料来源

链接最后检查于 2026 年 11 月 15 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。