OpenAI Responses API output_text 与 output 结构如何选择

如果你的页面只需要把模型回答显示出来，优先使用 SDK 提供的 output_text 便捷字段；如果还要处理工具调用、拒答、注释、多个输出项或记录完整响应，就应当读取 output，并按每个对象的 type 解析。最容易出错的写法是把 output[0].content[0].text 当成固定协议，因为 Responses API 的输出数组可能包含多个不同类型的项目。

官方地址：https://platform.openai.com/docs/

记住一个简单判断：展示纯文本，选 output_text；理解响应结构、保存元数据或驱动下一步工具逻辑，选 output。两者不是二选一的接口版本，而是同一响应的不同消费层。

1. 先看消费目标：你需要的是文本还是完整响应

Responses API 返回的是一个响应对象。官方文档把模型生成的内容放在 output 数组中，而部分 SDK 额外提供 output_text 作为聚合后的文本便利属性。也就是说，output_text 适合“把回答交给用户”，output 适合“判断模型还返回了哪些类型的项目”。

2. 普通文本展示直接使用 output_text

最简单的问答接口通常只关心模型给用户看的文字。此时可以让 SDK 创建响应，然后读取 response.output_text。这比手写多层循环更适合作为页面接口的第一版，但服务端仍应把“没有文本”的情况当作一种正常边界，而不是无条件拼接空字符串。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  // 模型名从部署配置读取，避免把环境差异写死在业务代码里。
  model: process.env.OPENAI_MODEL,
  input: "用两句话解释为什么 output_text 适合普通文本展示。",
});

if (typeof response.output_text !== "string" || response.output_text.length === 0) {
  // 没有可展示文本时交给上层决定提示、重试或展示其他状态。
  throw new Error("Responses API 没有返回可展示的文本");
}

console.log(response.output_text);

这个入口的价值是清楚表达业务意图：调用方要的是“可显示的文字”，不需要知道响应数组里是否还有其它内部项目。它不等于响应只有一条消息，也不适合拿来判断工具调用是否发生。

3. 什么时候必须保留 output

当请求可能触发工具、返回拒答、带有文件或 URL 注释，或者你要把完整响应记录到日志与数据库时，直接保存 output 更稳妥。官方文档特别提醒，数组的长度和顺序取决于模型响应，数组里可能出现工具调用、推理相关项目或多个消息项目，不能假定第一个元素就是最终文本。

因此，下面两种代码的语义不同：

// 适合只把文本交给页面或下游消息系统。
const visibleText = response.output_text;

// 适合保留响应结构，供工具路由、审计和后续解析使用。
const outputItems = response.output ?? [];

如果只是把 output 序列化后保存，建议保留响应 ID、状态和完整输出项；不要把它转换成只剩一段字符串后再声称可以恢复原始结构。相反，如果你的业务只需要文字，保存 output_text 可以减少下游耦合。

4. 正确解析 output：按类型找文本，不要写死下标

需要完整控制时，应遍历 output，先判断项目类型，再进入消息的 content。只有内容项类型为 output_text 且确实有字符串文本时，才把它加入可展示文本。这样即使前面出现工具调用，或一条消息里出现多个内容项，也不会因为数组下标变化而取错数据。

function collectOutputText(response) {
  const chunks = [];

  for (const item of response.output ?? []) {
    // 非 message 项可能是工具调用，不能直接读取 content。
    if (item.type !== "message") {
      continue;
    }

    for (const part of item.content ?? []) {
      // 只收集真正的文本内容，拒答或其他类型留给专门分支处理。
      if (part.type === "output_text" && typeof part.text === "string") {
        chunks.push(part.text);
      }
    }
  }

  // 多段文本合并时保留段落边界，避免词语黏在一起。
  return chunks.join("\n\n");
}

const text = collectOutputText(response);
console.log(text);

这个函数没有假设 output 一定非空，也没有假设第一个项目是 message。它只做“收集文本”这一件事；工具调用的参数、拒答原因和注释需要业务按自己的协议单独处理。

5. 文本、工具调用和拒答要分开处理

一个常见误区是把所有输出项都转换成字符串，然后让前端自行猜字符串含义。更清晰的做法是先建立分类结果：文本交给展示层，工具调用交给工具路由，拒答交给状态提示，其他未知类型记录类型名并保留原对象。这样 API 增加新的输出项时，系统至少不会静默把它当成普通文字。

function inspectOutput(response) {
  const result = { text: [], toolCalls: [], refusals: [], unknown: [] };

  for (const item of response.output ?? []) {
    if (item.type === "message") {
      for (const part of item.content ?? []) {
        if (part.type === "output_text") {
          result.text.push(part.text ?? "");
        } else if (part.type === "refusal") {
          // 拒答不是普通文本，保留独立状态供产品决定展示方式。
          result.refusals.push(part);
        }
      }
    } else if (item.type === "function_call") {
      // 函数工具项目不能直接显示给用户，先交给受控的工具处理器。
      result.toolCalls.push(item);
    } else {
      // 未知类型原样保留，便于升级 SDK 后定位新结构。
      result.unknown.push(item);
    }
  }

  return result;
}

具体工具类型名称应以你所用 SDK 的类型定义和当前官方 API 参考为准。这里的重点不是穷举所有类型，而是保留“先分型、再处理”的边界。

6. 结构化数据不要把 output_text 当成校验结果

如果模型返回的是订单摘要、字段提取结果或路由决策，业务需要的是稳定的数据结构，而不是一段看起来像 JSON 的文本。此时应使用 Responses API 支持的结构化输出配置，并在客户端按照 SDK 提供的结构化结果能力或明确的 JSON 解析流程处理。output_text 可以帮助你拿到文本内容，但它本身不保证字段存在、类型正确或满足业务约束。

可以按下面的边界选择实现：

• 用户阅读：读取 output_text，对空文本和拒答显示明确状态。
• 工具编排：遍历 output，识别工具项目后进入白名单路由。
• 审计与调试：保存响应 ID、状态和原始 output，避免只保留聚合文字。
• 业务数据：启用结构化输出，并对解析后的字段做应用层校验。

7. 一份可执行的选择清单

可以把最终决策压缩成四个问题：

1. 页面是否只需要给用户看一段文字？是，就从 output_text 开始。
2. 是否需要知道工具调用、拒答或注释？是，就保留 output 并按类型处理。
3. 是否把 output[0] 当成稳定的最终答案？不要，数组长度和顺序不是业务协议。
4. 是否需要严格字段？不要只依赖文本，改用结构化输出和应用层校验。

最终原则很简单：output_text 是面向文本消费者的便捷层，output 是面向程序消费者的结构层。先根据消费目标选入口，再对非文本和异常状态保留明确分支，Responses API 的解析代码就不会被某一次响应的数组顺序绑死。

常见问题

output_text 和 output 是两个不同的 API 请求参数吗？

不是。它们描述的是同一个 Responses API 响应对象的不同读取方式：output 是完整输出项集合，output_text 是部分官方 SDK 提供的文本聚合便利属性。

为什么不能直接读取 output[0].content[0].text？

因为响应数组可能包含多个项目，项目类型也可能不是 message；即使是 message，内容项也可能不是文本。按 type 遍历才能处理工具调用、拒答和多段文本。

只记录 output_text 会丢失什么？

可能丢失工具调用、拒答对象、注释、响应项类型以及调试所需的完整结构。纯展示场景可以只记文本，审计或编排场景应保存完整响应。