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

预测输出

在预先知道大部分响应内容时,降低模型响应延迟。

预测输出可以在大量输出 Token 已知时,加快 Chat Completions 的 API 响应。最常见的场景是对文本文件或代码文件稍作修改后重新生成整个文件。您可以通过 Chat Completions 的 prediction 请求参数提供预测内容。

目前,最新版的 gpt-4o、gpt-4o-mini、gpt-4.1、gpt-4.1-mini 和 gpt-4.1-nano 模型都支持预测输出。下面介绍如何使用预测输出降低应用的响应延迟。

代码重构示例

如果您需要重新生成文本文档或代码文件,而要修改的内容很少,预测输出尤其有用。假设您希望 GPT-4o 模型重构一段 JavaScript 代码,将 username 属性(属于 User 类)重命名为 email:

class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;

只有上面第 4 行需要修改,文件的其余内容保持不变。将代码文件的现有内容用作预测文本,即可降低重新生成整个文件的延迟。文件越大,累计节省的时间就越多。

在下面的示例中,预计模型的最终输出与原代码文件非常相似,因此我们通过 SDK 的 prediction 参数将原文件内容作为预测文本传入。

使用预测输出重构 JavaScript 类
import OpenAI from "openai";

const code = `
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`.trim();

const openai = new OpenAI();

const refactorPrompt = `
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`;

const completion = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [
    {
      role: "user",
      content: refactorPrompt,
    },
    {
      role: "user",
      content: code,
    },
  ],
  store: true,
  prediction: {
    type: "content",
    content: code,
  },
});

// Inspect returned data
console.log(completion);
console.log(completion.choices[0].message.content);

模型除了返回重构后的代码,还会返回用量数据。下面是省略了 choices 字段的响应节选:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1786652188,
  "model": "gpt-4.1-2025-04-14",
  "usage": {
    "prompt_tokens": 59,
    "completion_tokens": 24,
    "total_tokens": 83,
    "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 14,
      "rejected_prediction_tokens": 2
    }
  },
  "system_fingerprint": "fp_6ddb4f7408"
}

accepted_prediction_tokens 和 rejected_prediction_tokens 分别表示 usage 对象中记录的已采纳和已拒绝的预测 Token 数量。在本例中,预测文本中有 14 个 Token 被采纳,用于加快响应,另有 2 个被拒绝。

被拒绝的 Token 仍按 API 生成的其他补全 Token 的费率计费,因此使用预测输出可能会增加请求费用。

流式响应示例

当 API 以流式方式返回响应时,预测输出降低延迟的效果更明显。下面沿用上面的代码重构示例,这次使用 OpenAI SDK 的流式响应功能。

在流式响应中使用预测输出
import OpenAI from "openai";

const code = `
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`.trim();

const openai = new OpenAI();

const refactorPrompt = `
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`;

const completion = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [
    {
      role: "user",
      content: refactorPrompt,
    },
    {
      role: "user",
      content: code,
    },
  ],
  store: true,
  prediction: {
    type: "content",
    content: code,
  },
  stream: true,
});

// Inspect returned data
for await (const chunk of completion) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

预测文本在响应中的位置

无论预测文本出现在生成的响应中的什么位置,都可以降低响应延迟。假设您提供的预测文本是下面这个简单的 Hono 服务器的代码:

import { serve } from "@hono/node-server";
import { serveStatic } from "@hono/node-server/serve-static";
import { Hono } from "hono";

const app = new Hono();

app.get("/api", (c) => {
  return c.text("Hello Hono!");
});

// You will need to build the client code first: `pnpm run ui:build`.
app.use(
  "/*",
  serveStatic({
    rewriteRequestPath: (path) => `./dist${path}`,
  })
);

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
  fetch: app.fetch,
  port,
});

您可以使用类似下面的提示词,让模型重新生成文件:

为这个应用添加一个 GET 路由,使其返回文本 "hello world"。
添加该路由后,重新生成整个应用文件,不要添加任何额外的 Markdown 格式。

模型的响应可能如下所示:

import { serve } from "@hono/node-server";
import { serveStatic } from "@hono/node-server/serve-static";
import { Hono } from "hono";

const app = new Hono();

app.get("/api", (c) => {
  return c.text("Hello Hono!");
});

app.get("/hello", (c) => {
  return c.text("hello world");
});

// You will need to build the client code first: `pnpm run ui:build`.
app.use(
  "/*",
  serveStatic({
    rewriteRequestPath: (path) => `./dist${path}`,
  })
);

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
  fetch: app.fetch,
  port,
});

虽然预测文本分布在响应的新增内容前后,省略了 choices 字段的响应节选仍会显示被采纳的预测 Token 数量:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1731014771,
  "model": "gpt-4o-2024-08-06",
  "usage": {
    "prompt_tokens": 203,
    "completion_tokens": 159,
    "total_tokens": 362,
    "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 60,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_9ee9e968ea"
}

这次,最终响应采用了预测文本中的全部文件内容,因此没有任何预测 Token 被拒绝。太好了!🔥

限制

使用预测输出时,请留意以下事项和限制。

  • 只有 GPT-4o、GPT-4o mini、GPT-4.1、GPT-4.1 mini 和 GPT-4.1 nano 系列模型支持预测输出。
  • 提供预测内容时,即使其中的 Token 未出现在最终补全结果中,也仍按补全 Token 的费率计费。要了解最终响应中有多少预测 Token 未被采用,请查看 rejected_prediction_tokens 属性(位于 usage 对象中)。
  • 使用预测输出时,以下 API 参数受到限制:
    • n:不支持大于 1 的值。
    • logprobs:不支持。
    • presence_penalty:不支持大于 0 的值。
    • frequency_penalty:不支持大于 0 的值。
    • audio:预测输出与音频输入和输出不兼容。
    • modalities:仅支持 text 模态。
    • max_completion_tokens:不支持。
    • tools:预测输出目前不支持函数调用。