如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

将提示词从对象迁移到代码中

将托管对象中的提示词迁移到应用代码中。

OpenAI 正在逐步弃用 API 中可复用的提示词对象。自 2026 年 6 月 3 日起,OpenAI 将不再鼓励创建提示词对象,并计划于 2026 年 11 月 30 日停用 v1/prompts。最新时间安排请参阅弃用公告。

要停止使用 OpenAI API 平台的提示词功能,请将托管 prompt 对象中的提示词内容迁移到应用代码中。这样,您就能更好地控制提示词的审查、测试、部署和版本管理流程。

迁移前:使用提示词对象

使用提示词对象
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  prompt: {
    id: "pmpt_123",
    version: "1",
    variables: {
      customer_name: "Acme",
      issue: "billing question",
    },
  },
});

迁移后:将提示词直接写入代码

将提示词直接写入代码
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6.2-astra",
  input: [
    {
      role: "system",
      content:
        "You are a helpful support assistant. Be concise, accurate, and friendly.",
    },
    {
      role: "user",
      content:
        "Customer name: Acme. Issue: billing question. Write a response to the customer.",
    },
  ],
});

console.log(response.output_text);

使用 Codex 迁移

使用 OpenAI Developers 插件和 OpenAI Docs 技能,您可以自动完成迁移,并更快地使用 OpenAI API 开发应用。

$openai-docs 请更新此项目,将提示词存储在代码中,不再使用提示词对象。

迁移时需要做哪些调整

将提示词文本存储在代码库中,并在调用 Responses API 时将生成的消息直接作为 input 传入。这样,API 请求就无需再引用已保存的提示词对象。

  • 将提示词内容移入源代码,让提示词变更与产品逻辑变更遵循相同的审查和发布流程。
  • 用函数参数替代提示词变量,让应用显式传入动态值,并明确指定其类型。
  • 通过 input 传入消息,调用 Responses API 时无需再使用 prompt 对象。
  • 在代码仓库中管理提示词版本,使用 Git 提交、PR 审查以及测试或评估来管理变更。
  • 将静态内容放在前面,动态内容放在后面,以便继续利用提示词缓存,因为只有前缀完全匹配时才会命中缓存。

示例

使用辅助函数构建提示词
import OpenAI from "openai";

const client = new OpenAI();

function buildSupportPrompt({
  customerName,
  issue,
}: {
  customerName: string;
  issue: string;
}): OpenAI.Responses.ResponseInput {
  return [
    {
      role: "system",
      content:
        "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.",
    },
    {
      role: "user",
      content: `Customer name: ${customerName}. Issue: ${issue}. Write a response to the customer.`,
    },
  ];
}

const response = await client.responses.create({
  model: "gpt-6.2-astra",
  input: buildSupportPrompt({
    customerName: "Acme",
    issue: "billing question",
  }),
});

迁移后的好处

您可以更好地控制提示词的开发和发布流程。提示词与产品代码存放在一起,变更通过 PR 提交,测试和评估可以在 CI 中运行。您还可以通过自己的配置或功能开关来管理逐步发布或实验。

请避免将提示词分散写在代码库各处。创建一个小型 prompts/ 模块,为每个提示词定义一个具名构建函数,并添加轻量级评估样例,让提示词变更与产品逻辑变更接受相同的审查。