skip to content
66's Blog
Table of Contents

GPT-5 的发布让 AI 开发者们兴奋不已，但在实际使用过程中，不少开发者发现了一些”意外”的变化。如果你正准备从 GPT-4 迁移到 GPT-5，或者刚开始接触 GPT-5 API，这篇文章将帮你避开常见的坑。

1️⃣ Markdown 输出：默认关闭的格式化

问题现象

当你调用 GPT-5 API 时，可能会发现返回的内容是纯文本格式，没有任何 Markdown 标记，即使是需要层次结构的内容也是如此。

原因分析

GPT-5 在 API 中默认不使用 Markdown 格式化输出，这样设计是为了让不支持 Markdown 渲染的应用也能有良好的可读性。这与我们在 ChatGPT 网页版中看到的格式化输出有所不同。

解决方案

如果你需要层次良好、结构清晰的输出，请在 Prompt 中明确指定输出格式：

const response = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [
    {
      role: "user",
      content: "请介绍一下 React 的核心概念。Output format: markdown",
    },
  ],
});

或者在系统提示中设置：

const response = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [
    {
      role: "system",
      content:
        "You are a helpful assistant. Always format your responses in markdown.",
    },
    {
      role: "user",
      content: "请介绍一下 React 的核心概念",
    },
  ],
});

2️⃣ 随机性参数：告别 temperature 和 top_p

问题现象

在 GPT-5 系列模型中，你会发现熟悉的 temperature 和 top_p 参数不再可用，API 调用时设置这些参数会报错。

原因分析

GPT-5 系列移除了 temperature 和 top_p 参数，这可能是为了简化 API 接口或者因为新的模型架构不再需要这些参数来控制输出的随机性。

解决方案

如果你的应用需要可调节的随机性控制，请使用支持这些参数的 gpt-5-chat-latest 模型：

// ❌ 在 gpt-5 中不可用
const response = await openai.chat.completions.create({
  model: "gpt-5",
  temperature: 0.7,  // 这个参数会报错
  top_p: 0.9,        // 这个参数会报错
  messages: [...]
});


// ✅ 使用 gpt-5-chat-latest
const response = await openai.chat.completions.create({
  model: "gpt-5-chat-latest",
  temperature: 0.7,  // 正常工作
  top_p: 0.9,        // 正常工作
  messages: [...]
});

参数说明

  • temperature: 控制输出的随机性，范围 0-2，值越高输出越有创意。在 gpt-5 系列模型中，默认值为 1 且不可更改。

3️⃣ 输出长度限制：max_tokens 已成历史

问题现象

使用 max_tokens 参数限制输出长度时，可能会发现参数不生效或者收到弃用警告。

原因分析

推理模型（o 系列 / gpt-5 系列）已经弃用了 max_tokens 参数，这是为了更明确地区分输入和输出的 token 限制。

解决方案

请改用 max_completion_tokens 参数来明确限定输出 Token 上限：

// ❌ 已弃用的写法
const response = await openai.chat.completions.create({
  model: "gpt-5",
  max_tokens: 1000,  // 已弃用
  messages: [...]
});


// ✅ 推荐的写法
const response = await openai.chat.completions.create({
  model: "gpt-5",
  max_completion_tokens: 1000,  // 明确指定输出限制
  messages: [...]
});

参数对比

参数适用模型说明
max_tokensGPT-4 及更早版本限制总输出长度（已弃用）
max_completion_tokensGPT-5、o 系列明确限制完成部分的 token 数量

最佳实践建议

1. 版本兼容性处理

如果你的应用需要同时支持多个模型版本，建议做好兼容性处理：

function createChatCompletion(model, messages, options = {}) {
  const isGPT5Series = model.startsWith("gpt-5") || model.startsWith("o1");


  const params = {
    model,
    messages,
  };


  // 根据模型类型设置不同的参数
  if (isGPT5Series) {
    if (options.maxTokens) {
      params.max_completion_tokens = options.maxTokens;
    }
    // GPT-5 系列不支持 temperature 和 top_p（除非是 gpt-5-chat-latest）
    if (model === "gpt-5-chat-latest") {
      if (options.temperature) params.temperature = options.temperature;
      if (options.topP) params.top_p = options.topP;
    }
  } else {
    // GPT-4 及更早版本
    if (options.maxTokens) params.max_tokens = options.maxTokens;
    if (options.temperature) params.temperature = options.temperature;
    if (options.topP) params.top_p = options.topP;
  }


  return openai.chat.completions.create(params);
}

2. 输出格式统一

为了确保输出格式的一致性，建议在系统提示中统一设置：

const SYSTEM_PROMPT = `You are a helpful assistant.
Please format your responses in markdown for better readability.
Use appropriate headers, lists, and code blocks when necessary.`;

3. 错误处理

添加适当的错误处理来应对参数不兼容的情况：

try {
  const response = await openai.chat.completions.create(params);
  return response;
} catch (error) {
  if (error.message.includes("max_tokens")) {
    // 自动重试，使用新的参数名
    const newParams = { ...params };
    delete newParams.max_tokens;
    newParams.max_completion_tokens = params.max_tokens;
    return await openai.chat.completions.create(newParams);
  }
  throw error;
}

总结

GPT-5 的这些变化虽然可能会给迁移带来一些麻烦，但了解了这些要点后，适配工作就会变得简单许多：

  1. 需要 Markdown 输出：在 Prompt 中明确指定 Output format: markdown
  2. 需要随机性控制：使用 gpt-5-chat-latest 模型
  3. 限制输出长度：使用 max_completion_tokens 替代 max_tokens