提示词模板如何给变量设置默认值和类型

我第一次把一个可复用提示词接进服务时，最容易漏掉的不是提示词内容，而是变量契约：tone 没传时怎么办，task 传了空格算不算有值，调用方到底应该传字符串还是别的对象。实践下来，比较稳的做法是把平台模板和应用侧 schema 分开：模板变量负责替换输入，类型、默认值和缺失错误由请求入口统一处理。

官方文档：https://platform.openai.com/docs/

为什么默认值和类型应该放在应用侧

OpenAI 的 Prompt 管理页允许在模板中写入类似 {user_goal} 的变量；Responses API 的请求结构则把提示词引用和变量放在 prompt 对象里。它解决的是“把哪一份模板、替换成哪些值”，并不等于替应用定义业务字段的完整类型系统。

所以我会把边界画成三层：调用方提供原始输入，应用侧变量契约负责类型、默认值和必填判断，最后才形成发给模型的变量对象。这样即使模板里仍然只有 {audience}、{tone}、{task}，代码也能明确回答“缺谁报错、缺谁补默认值”。

先把变量契约写成明确类型

我通常先定义“调用者可以传什么”，再定义“模板最终需要什么”。下面的 task 是必填字符串，audience 和 tone 允许省略；默认值集中放置，后续换产品语气时不必到处改字面量。

type PromptVars = {
  audience?: string;
  tone?: string;
  task: string;
};

const DEFAULTS = {
  audience: "后端开发者",
  tone: "简洁、给出可执行示例"
} as const;

function normalizePromptVars(input: Partial) {
  // 先补可选变量的默认值，避免模板收到 undefined。
  const task = input.task?.trim();
  if (!task) {
    // 必填变量在请求离开应用前失败，错误更容易定位。
    throw new Error("task 是必填变量，不能是空字符串");
  }

  return {
    audience: input.audience?.trim() || DEFAULTS.audience,
    tone: input.tone?.trim() || DEFAULTS.tone,
    task
  };
}

这里有两个细节值得保留。第一，Partial只表示调用入口允许缺省，不表示模板最终可以缺字段；返回对象才是已经补全的结果。第二，trim()要在必填判断前执行，否则一串空格会绕过校验。

把默认值和缺失错误放在调用入口

归一化函数返回的对象才进入 API 请求。示例中的 pmpt_xxx 和版本号需要替换成自己在 Playground 中发布的 Prompt ID 与版本；不要把它们写成用户输入，更不要让每个业务调用点各自拼默认值。

const vars = normalizePromptVars({
  task: "把订单取消规则改写成三条检查清单",
  tone: "面向产品经理"
});

const response = await client.responses.create({
  model: "gpt-5",
  prompt: {
    id: "pmpt_xxx",
    version: "1",
    // 这里只发送已完成类型收窄和默认补全的变量。
    variables: vars
  }
});

如果 task 缺失，错误会在调用模型前出现；如果只缺 tone，模板仍能得到稳定的默认语气。这个区别很重要：把所有字段都静默填默认值，会让真正的业务漏传变得难以察觉。

模板版本变化时怎么判断是否要同步

模板只改措辞，变量名不变时，调用侧通常不用改；增加、删除或重命名变量时，必须同步修改 PromptVars、默认值和示例调用。若线上需要稳定行为，可以在请求里固定版本；若希望跟随最新发布版本，则使用 Prompt ID 的默认行为，但要把版本变更纳入评测和回滚流程。

我会保留下面这张小清单：模板变量名是否与类型定义逐字一致；必填字段是否有空字符串测试；默认值是否符合当前业务语气；Prompt ID 和版本是否记录在配置中；模板发布后是否重新跑一组固定输入。它比在每个业务函数里临时判断更容易维护。

常见问题

OpenAI 模板变量能直接声明 default 和 type 吗？

不要假设能直接声明完整 schema。将类型、默认值和缺失策略放在应用侧，再把归一化后的值传入模板更稳妥。

可选变量传空字符串应该使用默认值吗？

如果空字符串没有业务含义，可以像示例一样先 trim() 再回退默认值；如果空字符串代表“明确关闭”，就应改用独立的布尔字段表达。

为什么不在模板文本里写默认值？

模板文本只能影响模型看到的内容，不能阻止错误输入进入请求。把校验放在入口，错误有明确调用栈，也能复用于不同模板版本。

Python 调用也需要同样的契约吗？

需要。语言可以不同，但应保持相同的变量名、必填规则和默认值；否则同一个 Prompt 在不同服务里会出现不一致的输入边界。