大多数时候,你向 AI 模型提问,并不想要一篇长文作为回答。你想要的是“yes”“billing”或“7 分(满分 10)”,好让代码选一个分支继续执行。Google 新推出的 Gemini Decisions API 正是为此而生,而且输出完全免费。
本指南将教你如何用 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 或更高版本,以及
v1betaAPI 版本。文档称该 API 仅在 v1beta 上提供。
什么时候该用别的工具
Decisions API 适合答案集合固定的路由、过滤和规则检查。如果你需要生成文本、摘要,或符合你自定义 JSON 架构的值,Google 建议改用 Interactions API。如果你更想把模型放在自己的硬件上运行,我们的 Ollama 指南介绍了这条路线。
资料来源
链接最后检查于 2026 年 11 月 15 日。





写评论