导航栏：首页 / AI开发参考资料 / OpenAI API 兼容格式参考资料 / 请求格式概览
在定义工具的参数时，我们可以通过了多种约束机制，帮助 AI 模型更准确地理解和生成参数。
以下是最常用的几种约束方式，每种都配有详细的解释和实际应用场景示例。
请注意：以下约束方式为 JSON Schema 标准约束，AI模型通常会遵循这些约束，但建议在生产环境中增加校验作为兜底，确保AI模型生成的响应信息，的确遵守了这些约束。
1. type（类型约束）
作用：明确指定参数的数据类型，防止 AI 生成错误类型的值。
| 类型值 | 含义 | 适用场景 |
|---|---|---|
"string" | 字符串 | 设备名称、状态描述、颜色名称等 |
"integer" | 整数 | 亮度级别、温度值、数量等离散数值 |
"number" | 数字（整数或浮点数） | 精确的温度值、湿度百分比等连续数值 |
"boolean" | 布尔值（true/false） | 开关状态、启用/禁用标志等 |
"array" | 数组 | 多个颜色值、多个设备ID列表等 |
"object" | 对象 | 复杂的配置参数、坐标信息等 |
示例：定义一个整数类型的亮度参数
"brightness": {
"type": "integer",
"description": "LED亮度，0-100之间的整数"
}实际效果：当用户说”把灯调亮”时，AI 会返回类似 85 的整数值，而不会返回 "很亮"（字符串）或 85.5（浮点数）。
2. enum（枚举值）
作用：把参数的候选取值限定在预定义的几个值里，避免模型生成 五花八门、代码无法处理的说法。
示例：LED 开关控制
"action": {
"type": "string",
"description": "LED控制动作",
"enum": ["on", "off"]
}实际效果：
| 用户指令 | AI 生成的参数 |
|---|---|
| “打开LED” | "on" |
| “把灯关掉” | "off" |
| “启动LED” | "on"（通过语义理解映射） |
| “熄灭灯光” | "off"（通过语义理解映射） |
关键点：即使用户使用同义词或不同表达方式，AI 也会将语义映射到 enum 中预定义的值。如果没有 enum，AI 可能会生成 "open"、"start"、"close" 等多种不同的值，导致 ESP32 程序无法处理。
3. minimum / maximum（数值范围）
作用：对数字类型参数设置上下限，确保 AI 生成的数值在硬件可接受的范围内。
示例：LED 亮度级别（本节重点）
"level": {
"type": "integer",
"description": "亮度级别，1-5级，其中1为最暗，5为最亮",
"minimum": 1,
"maximum": 5
}实际效果：
| 用户指令 | 无约束时 AI 可能返回 | 有约束时 AI 返回 |
|---|---|---|
| “调到最亮” | 10 或 100 或 255 | 5 |
| “调到最暗” | 0 或 1 | 1 |
| “中等亮度” | 50（百分比思维） | 3 |
为什么重要：本程序的亮度控制函数只接受 1-5 的范围。如果 AI 返回 100，程序要么报错，要么产生不可预期的行为。通过 minimum 和 maximum，我们在源头上就约束了 AI 的输出。
平台支持提醒（重要）：minimum / maximum 并不是在所有平台下都生效。因此不要把这两个字段当成”一定不会越界”的保证。
4. minLength / maxLength（字符串长度限制）
作用：标注字符串的最小、最大长度，引导模型生成长度合适的文本。
示例：设备名称
"device_name": {
"type": "string",
"description": "设备名称，用于在APP中显示",
"minLength": 1,
"maxLength": 20
}实际效果：
| 用户指令 | AI 生成的参数 | 是否符合约束 |
|---|---|---|
| “命名为客厅灯” | "客厅灯"（3个字符） | 符合（1 ≤ 3 ≤ 20） |
| “命名为我的超级智能多功能客厅主照明灯” | 会被截断为 "我的超级智能多功能客"（15个字符） | 符合（不超过20） |
| “命名为空” | ""（0个字符） | 不符合（小于1），AI 会重新生成 |
应用场景：在需要将设备名称显示在 OLED 屏幕或手机 APP 上的场景中，限制长度可以确保 UI 显示正常，不会出现文字截断或溢出。
实用提醒：
- 可选的固定名称用
enum； - 用户自由输入的名称，把长度要求写进
description。 - 模型响应的字符长度校验和截断交给设备代码进行二次确认，确保满足要求。
5. pattern（正则表达式）
作用：标注字符串需要满足的格式（例如时间、编号格式），引导模型按格式生成。
示例：时间格式（HH:MM）
"time": {
"type": "string",
"description": "定时时间，格式为HH:MM，例如07:30",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
}实际效果：
| 用户指令 | AI 生成的参数 | 是否匹配正则 |
|---|---|---|
| “早上七点半” | "07:30" | 匹配 |
| “晚上十一点” | "23:00" | 匹配 |
| “凌晨一点” | "01:00" | 匹配 |
| “二十五点” | 不会生成 "25:00" | 不匹配（小时不能超过23） |
应用场景：定时任务、闹钟设置、预约开关等需要精确时间格式的场景。正则表达式确保 AI 生成的时间字符串可以被 sscanf() 等函数正确解析。
注意：
根据多方开发者反馈，包括 OpenAI 在内的主流 AI 厂商对正则表达式约束（pattern）的支持存在不确定性。虽然模型通常会尝试遵循 pattern 约束，但在复杂场景下可能出现不遵循的情况。有开发者指出虽然模型能看到 pattern 并尝试遵循，但可靠性不如 type、enum 等简单约束。
基于此，我们建议在条件允许的情况下，将 pattern 约束方式替换为更简单的约束方式，因为pattern约束的可靠性相对较低。
6. format（语义化格式）
作用：用预定义的语义格式提示常见数据形态（如日期、时间、邮箱、URI 等），比手写正则更直观，模型通常会尊重 format 提示。
| format 值 | 含义 | 示例 |
|---|---|---|
"date" | 日期（YYYY-MM-DD） | "2026-10-30" |
"date-time" | ISO 8601 日期时间 | "2026-10-30T08:00:00Z" |
"time" | 时间（HH:MM:SS） | "07:30:00" |
"email" | 邮箱 | "user@example.com" |
"uri" | URI | "https://..." |
示例：定时任务的日期与时间
"scheduled_at": {
"type": "string",
"description": "定时执行时间",
"format": "date-time"
}说明：format 与 pattern 一样属于 软提示（默认模式下不强制校验），适合表达常见格式意图；严格校验仍需业务代码完成。若目标模型/模式不支持 format，可回退为 pattern。
7. description（语义引导）
归类说明：description 是 JSON Schema 的 元数据字段，本身 不是约束（没有任何强制/限制能力），只是给模型提供自然语言上下文。它之所以放在这里，是因为它往往是 最有效、最重要的引导手段，但请与真正的约束区分对待。
作用：虽然不是硬性约束，但清晰的自然语言描述是最关键的引导手段，能极大提升模型理解意图的准确性。通过清晰自然的描述 极大提升 模型理解意图的准确性，是性价比最高的”软性约束”。
示例：温度设置
"temperature": {
"type": "integer",
"description": "目标温度，单位摄氏度，范围16-30度。例如：用户说'有点冷'对应22度，'很热'对应26度",
"minimum": 16,
"maximum": 30
}实际效果：
| 用户指令 | 无 description 时 AI 可能返回 | 有详细 description 时 AI 返回 |
|---|---|---|
| “有点冷” | 随机值（如 18） | 22（根据描述中的示例推断） |
| “很热” | 随机值（如 30） | 26（根据描述中的示例推断） |
最佳实践：在 description 中提供：
- 单位信息（如”摄氏度”、”百分比”）
- 具体示例（如”1为最暗，5为最亮”）
- 映射关系（如”用户说’有点冷’对应22度”）
8. items（数组元素约束）
作用：当参数是数组时，用 items 定义每个元素的结构，并可配合 minItems / maxItems 限制数组长度。
示例：RGB 颜色列表
"colors": {
"type": "array",
"description": "要显示的颜色列表，最多3种颜色",
"items": {
"type": "string",
"enum": ["red", "green", "blue", "yellow", "white"]
},
"minItems": 1,
"maxItems": 3
}实际效果：
| 用户指令 | AI 生成的参数 |
|---|---|
| “显示红色和蓝色” | ["red", "blue"] |
| “显示彩虹色” | ["red", "green", "blue"]（限制最多3种） |
| “不要显示颜色” | 不会生成 []（因为 minItems: 1） |
应用场景：批量控制多个设备、设置多色呼吸灯效果、配置场景模式等需要列表参数的场景。
小结
| 约束类型 | 作用 | 典型应用场景 |
|---|---|---|
type | 限定数据类型 | 确保 AI 返回整数而非字符串 |
enum | 枚举可选值 | 开关状态、模式选择等离散值 |
minimum / maximum | 数值范围 | 亮度级别、温度值等连续数值范围 |
minLength / maxLength | 字符串长度 | 设备名称、显示文本等 |
pattern | 正则匹配 | 时间格式、设备ID格式等 |
| 语义化格式 | 用预定义的语义格式提示常见数据形态 |
description | 语义提示 | 提供单位、示例、映射关系 |
items | 数组元素结构 | 颜色列表、设备列表等 |
最佳实践：组合使用类型 + 范围 + 描述 + 必填声明，可以让 AI 模型生成最准确、最可靠的参数。例如本节亮度控制的参数定义就同时使用了 type（integer）、description（语义说明）、minimum/maximum（范围约束）和 required（必填声明）四种约束方式。