OpenAI API 前端集成完整指南：流式响应、错误处理与成本控制

OpenAI API 前端集成完整指南

很多团队第一次接 OpenAI API，会直接在浏览器里发请求，等到要上线时才发现一连串问题一起冒出来：密钥暴露、超时无反馈、前端卡住、成本失控、日志无法追踪。

真正的难点从来不是“能不能调通接口”，而是能不能把它接成一个可上线、可观察、可回滚的产品能力。

这篇文章解决 5 个核心问题：

问题	常见错误做法	更稳的做法
密钥管理	把 API Key 放前端环境变量	通过服务端代理调用
响应体验	等完整结果返回再显示	走流式输出
失败恢复	统一报“请求失败”	区分超时、限流、模型错误
成本治理	只看账单总额	按功能、用户、模型拆账
线上排障	只有浏览器报错	建立 request id 与日志链路

1. 前端接 OpenAI API，第一件事不是写 UI，而是画边界

OpenAI API 适合放在“前端产品能力”的中间层，而不是直接暴露给浏览器。

推荐的调用路径是：

前端负责采集输入、展示状态、渲染结果。
服务端路由负责鉴权、拼装参数、调用模型、记录日志。
监控层负责统计耗时、token、错误率与重试次数。

最小架构可以写成：

// server/api/ai/chat.post.ts
import OpenAI from 'openai'

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const result = await client.responses.create({
    model: 'gpt-4.1-mini',
    input: body.input,
  })

  return {
    output: result.output_text,
    requestId: result.id,
  }
})

这样做的价值不是“更规范”，而是给后面的权限、限流、日志和模型切换留出空间。

2. 流式响应不是锦上添花，而是大模型产品的基础体验

如果一个回答要等 8 秒才完整显示，用户会把这 8 秒理解成“页面卡住了”。

流式输出能把等待拆成三层体验：

用户立刻看到“已开始生成”。
中间过程持续有反馈。
结果没结束前也能提前阅读前半段。

在 Nuxt 或 Next 里，最稳的做法都是服务端流式转发：

const stream = await client.responses.create({
  model: 'gpt-4.1-mini',
  input,
  stream: true,
})

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    controller.enqueue(encoder.encode(`data: ${event.delta}\n\n`))
  }
}

前端再按块接收，而不是按字符暴力刷新。这样可以减少频繁重排，也更容易在移动端控制性能。

3. 失败处理要按“可恢复性”分层，不要统一弹错

最差的错误处理方式，是不管什么原因都告诉用户“生成失败，请重试”。

更实用的分层是：

可立即重试：偶发网络闪断、网关超时。
需降级：主模型拥堵，切小模型继续。
需停止：参数非法、权限不足、配额耗尽。

可以先定义统一错误结构：

interface AiErrorPayload {
  code: 'TIMEOUT' | 'RATE_LIMIT' | 'INVALID_REQUEST' | 'BUDGET_EXCEEDED'
  message: string
  retryable: boolean
  requestId?: string
}

前端再根据 retryable 决定展示“重试”“稍后再试”还是“联系管理员”。

4. 成本控制不能只看 token，要看“哪种功能最烧钱”

大模型成本失控，通常不是因为一次请求太贵，而是因为团队根本不知道钱花在哪。

上线前至少要记 4 个维度：

功能名：聊天、总结、改写、生成页面。
模型名：大模型还是轻模型。
用户维度：匿名、登录用户、团队账户。
请求结果：成功、取消、超时、重试。

推荐把“预算治理”拆成一个最小表：

维度	示例	目的
功能	`landing_copy_generate`	找出高消耗入口
模型	`gpt-4.1-mini`	对比模型 ROI
输入大小	4200 tokens	判断是否需要压缩
输出大小	1800 tokens	判断提示是否过宽
是否重试	`true`	找到浪费来源