Gemini API 怎样为工具参数提供枚举约束

我在把一个“查询天气”的自然语言入口接成工具调用时，最容易踩的坑不是函数名，而是参数值：温度单位明明只有摄氏和华氏，模型却可能从描述里推断出一个业务代码不认识的写法。Gemini API 的做法是把固定选项直接写进参数 Schema 的 enum，让工具声明携带可读的候选集合。

官方地址：https://ai.google.dev/gemini-api/docs/function-calling

只要参数的合法值是一个稳定、有限的集合，就在该属性里使用 enum；但它只负责描述工具参数的允许范围，真正执行前仍应在应用侧做白名单判断、权限判断和业务校验。

先把“有限选项”从描述里分离出来

enum 适合表达“只能从这几个值中选”的参数，例如 celsius、fahrenheit，或一个灯光工具的 daylight、cool、warm。如果参数值来自数据库、用户输入或不断变化的配置，就不要为了看起来严格而把一长串动态值硬编码进声明。

我通常先问三个问题：候选值是不是有限的？每个候选值是不是有稳定含义？业务代码能不能对未知值采取明确动作？三个答案都为“是”时，才把它放进 enum。Google 的示例也是把 enum 放在具体参数属性中，而不是放在整个函数声明旁边。

在 FunctionDeclaration 的属性中写 enum

下面用 Python 字典表示一个工具声明。unit 的类型是字符串，enum 给出两个合法值，required 则说明调用时必须提供这个字段。代码里的注释只解释关键约束，避免把每一行都写成注释。

from google import genai

client = genai.Client()

get_weather = {
    "type": "function",
    "name": "get_weather",
    "description": "按城市和单位查询天气。",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "城市名称，例如 Shanghai。",
            },
            "unit": {
                "type": "string",
                # enum 把单位限制在业务真正支持的两个值内。
                "enum": ["celsius", "fahrenheit"],
                "description": "温度单位，只能使用 celsius 或 fahrenheit。",
            },
        },
        # required 只说明字段必须出现，不替代 enum 的取值约束。
        "required": ["city", "unit"],
    },
}

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="查询上海今天的摄氏温度。",
    config=genai.types.GenerateContentConfig(tools=[get_weather]),
)

print(response.function_calls)  # 读取模型给出的结构化工具调用。

这里的关键不是把候选值写得越多越好，而是让候选集合与实际函数实现保持同一份语义。description 用来解释参数用途和格式，enum 用来列出固定值，required 用来要求字段出现，三者不要互相替代。

参数从声明到调用会经过哪些边界

把一次调用拆成数据流后，问题会清楚很多：用户意图先进入模型，工具声明提供参数结构，模型返回函数名和 arguments，最后才由应用代码执行。Gemini 不会替你调用本地函数；工具调用返回后，执行权仍在应用侧。

如果请求“用华氏度查询”，理想的调用参数会类似下面这样。它是返回结构示例，不是某次本机运行日志。

{
  "name": "get_weather",
  "args": {
    "city": "Shanghai",
    "unit": "fahrenheit"
  }
}

实际项目里不要只因为返回值看起来像合法 JSON 就执行。先根据函数名选择处理器，再对每个参数做白名单、权限和业务规则判断。

在应用侧保留最后一道白名单

我会把 enum 看成给模型看的接口契约，把应用侧集合看成给执行器看的安全边界。两处最好共用常量或由同一份配置生成，至少也要在代码评审时成对更新。

ALLOWED_UNITS = {"celsius", "fahrenheit"}

def execute_weather_call(args: dict) -> dict:
    # 执行外部请求前拒绝未知单位，避免把模型输出直接拼进业务路径。
    city = args.get("city")
    unit = args.get("unit")
    if not isinstance(city, str) or not city.strip():
        raise ValueError("city 不能为空")
    if unit not in ALLOWED_UNITS:
        raise ValueError(f"不支持的温度单位: {unit}")

    # 这里才进入真正的天气服务适配层；实际项目还应补权限和超时处理。
    return weather_client.query(city=city.strip(), unit=unit)

这样做有两个好处：模型即使给出未知值，也不会直接触发外部动作；未来候选值变化时，工具声明和执行器的差异会更容易被发现。对于有权限影响的工具，还要把用户身份、资源范围和速率限制放在同一层检查。

enum、required 和业务校验不要混为一谈

例如 region 可能是固定枚举，但“这个用户是否能访问该 region”仍是业务校验；date 可能是必填字符串，但日期是否存在、是否允许预约，也不能靠 required 解决。

什么时候不应该使用 enum

如果候选值来自实时库存、租户配置或数据库记录，不要把全部值固化在每次请求的工具声明中。更合适的方式是先提供一个查询工具，让模型拿到当前可选项，再把用户选中的稳定标识传给后续工具；或者只约束一个小的动作类型，把动态标识交给应用侧查询和校验。

另一个边界是“看似有限、实际经常变化”的状态字段。把服务端频繁新增的状态写成 enum，会让声明更新滞后。此时可以在 description 中解释格式，执行前用版本化的服务端规则校验，并把未知值记录为可观测事件。

小结

Gemini API 为工具参数提供枚举约束的最小写法，就是在具体属性里设置 type: "string" 和 enum: [...]，再用 required 管理字段是否出现。模型返回函数调用后，应用仍要重新检查白名单、权限、资源和实时业务状态。固定集合用 enum，动态集合用查询或服务端校验，才能让声明清晰又不把业务规则误塞进静态 Schema。

相关问题

enum 能不能只写在 description 里？

不建议。description 是自然语言提示，固定候选应使用机器可读的 enum，同时保留 description 解释每个值的语义。

写了 enum 还需要应用侧校验吗？

需要。enum 改善工具声明和模型参数生成，但外部动作前仍应做白名单、权限、资源和实时状态检查。

动态数据库记录适合放进 enum 吗？

通常不适合。候选集合变化频繁时，应先查询可用记录，或把动态标识交给应用侧按当前数据校验。