游戏 AI / 系统课时

处理超时重试与接口错误

处理超时重试与接口错误

NPC 对话接通模型后,玩家可能遇到长时间等待、请求超时、接口限流、鉴权失败或服务异常。直接把所有失败都显示成“网络错误”,会让玩家无法判断能否继续操作。本篇使用 Node.js 实现有限重试、整体超时和主动取消,并将不同异常映射成可读的 NPC 对话状态。

学习目标

  • 区分超时、限流、鉴权失败、服务端错误及玩家主动取消,明确哪些情况可以重试。
  • 配置单次请求超时、最多两次自动重试和整个对话的等待上限。
  • 使用 AbortController 取消未完成的调用,并把底层异常转换为可供游戏 UI 使用的状态。

按错误类型决定是否重试

LLM API 的失败结果不应该使用同一种处理方式。比如 HTTP 401 通常意味着服务端凭证错误,再试十次也不会恢复;HTTP 429 可能是暂时达到请求速率限制,等待后才有机会成功。

先建立一张处理表:

现象或状态 可能原因 是否重试 玩家看到的状态
HTTP 401 API Key 无效 否 NPC 服务配置异常
HTTP 403 项目或账号权限不足 否 NPC 服务配置异常
HTTP 429 速率限制或配额问题 有条件,有限次数 NPC 正忙,请稍后再试
HTTP 5xx 上游服务暂时异常 是,有限次数 NPC 服务暂时不可用
连接超时或临时网络故障 请求没有及时完成 是,有限次数 NPC 响应超时或连接异常
HTTP 400 请求参数不合法 否 本次请求无法处理
玩家主动取消 关闭对话、切换 NPC 否 已取消本轮对话

一次重试不等于一次新的玩家操作。重试时应沿用同一轮输入,不重复追加聊天历史,不额外创建任务,也不要让客户端连续弹出多条相同错误提示。

OpenAI Node SDK 默认会对部分连接错误和 HTTP 408、409、429、5xx 响应进行最多两次自动重试。通过 maxRetries 可以修改或关闭这一行为。如果使用 SDK 的内置重试,就不要在外围再无条件添加一层同样的重试循环,否则实际请求次数会超出预期。

设计等待、截止时间与取消状态

游戏对话通常需要两层时间限制:单次网络调用不能无限等待,整个对话轮次也必须有总时间上限。只有单次超时而没有总体截止时间,自动重试可能让玩家等待远超预期。

本例采用以下参数:

参数 取值 含义
timeout 4000 ms 每次 SDK 请求尝试的超时设置
maxRetries 2 初始尝试后最多自动重试两次
总等待上限 15000 ms 包括调用、重试及等待时间
取消信号 AbortController 玩家主动结束当前对话轮次

因此一轮调用最多有三次请求尝试,但整个操作还受 15 秒截止时间约束。SDK 的实际退避等待会影响总时长,超过整体时间预算时直接取消剩余操作。

NPC 请求超时重试及主动取消的状态转换流程

界面状态至少应区分 sending、success、timeout、rate_limited、config_error、service_error 和 cancelled。其中 sending 是正在等待,cancelled 表示玩家不再需要结果,不应弹出与服务器故障相同的错误提示。

当玩家切换到另一名 NPC、关闭对话框或离开场景时,当前请求就失去了展示对象。应立即触发取消,并在 UI 层使用轮次标识检查返回结果是否仍属于当前对话。

编写带错误分类的 NPC 调用器

使用 Node.js 20.3 或更新版本,在空目录中安装官方 SDK,并配置可用的环境变量 OPENAI_API_KEY。以下是 Bash 安装命令;其中密钥占位符必须替换为真实值。

bash
npm init -y
npm install openai
export OPENAI_API_KEY='<YOUR_API_KEY>'

预期结果:依赖安装完成,当前进程能够从环境变量中读取模型调用凭证。不要把真实密钥写入源文件或提交到版本控制系统。

创建 resilient-npc.mjs。代码使用 SDK 内置重试处理临时错误,用 AbortSignal.timeout() 设置整个轮次的截止时间,再通过 AbortSignal.any() 合并玩家取消和超时信号。

js
import OpenAI from 'openai';

const client = new OpenAI({
  timeout: 4000,
  maxRetries: 2
});

const cancel = new AbortController();
const deadline = AbortSignal.timeout(15000);
const signal = AbortSignal.any([cancel.signal, deadline]);

function readableError(error) {
  // 玩家主动取消和总超时优先于底层网络错误分类。
  if (cancel.signal.aborted) {
    return { state: 'cancelled', message: '已取消本轮对话' };
  }
  if (deadline.aborted) {
    return { state: 'timeout', message: '等待过久,请稍后再试' };
  }

  if (error instanceof OpenAI.AuthenticationError ||
      error instanceof OpenAI.PermissionDeniedError) {
    return { state: 'config_error', message: 'NPC 服务配置异常,请联系管理员' };
  }
  if (error instanceof OpenAI.RateLimitError) {
    return { state: 'rate_limited', message: 'NPC 正忙,请稍后再试' };
  }
  if (error instanceof OpenAI.APIConnectionTimeoutError) {
    return { state: 'timeout', message: 'NPC 响应超时,请重试' };
  }
  if (error instanceof OpenAI.APIConnectionError) {
    return { state: 'network_error', message: '连接异常,请检查网络' };
  }
  if (error instanceof OpenAI.InternalServerError) {
    return { state: 'service_error', message: 'NPC 服务暂时不可用' };
  }

  return { state: 'request_error', message: '本次请求无法处理' };
}

// 终端输入 cancel 模拟玩家关闭对话框时触发的取消事件。
process.stdin.setEncoding('utf8');
process.stdin.on('data', (line) => {
  if (line.trim() === 'cancel') cancel.abort();
});

console.log('请求中;输入 cancel 后回车可取消');

try {
  const response = await client.responses.create({
    model: 'gpt-4.1-mini',
    instructions: '你是城门守卫。用中文简短回复,不替玩家执行任何游戏操作。',
    input: '城门什么时候关?',
    max_output_tokens: 120
  }, { signal });

  const reply = response.output_text?.trim() || 'NPC 暂时没有台词';
  console.log('success: ' + reply);
} catch (error) {
  const result = readableError(error);
  // 面向玩家只展示安全提示;详细错误与请求ID留给服务端日志。
  console.log(result.state + ': ' + result.message);
} finally {
  process.stdin.pause();
}

这里的 timeout: 4000 是 SDK 调用尝试的超时配置,maxRetries: 2 表示允许的附加重试次数,不是总调用次数。AbortSignal.any() 会在玩家取消或整体截止时间到达时使组合信号进入中止状态。

错误分类安排在 SDK 重试结束之后,因此不会每次短暂失败都通知玩家。对于鉴权与权限错误,SDK 不会通过重复发送解决问题;对于网络连接异常、限流和服务端故障,则可能先执行允许的自动重试。

OpenAI.APIConnectionTimeoutError 与其他连接错误分别处理,是为了让玩家看到更准确的提示。服务端可以另外记录 HTTP 状态码、请求 ID 和重试次数,用于故障排查,但不应把包含内部细节的异常对象直接发送给游戏客户端。

运行并验证成功与取消

确保 OPENAI_API_KEY 已设置,在终端执行:

bash
node resilient-npc.mjs

预期输出(模型正常返回时):

text
请求中;输入 cancel 后回车可取消
success: <NPC_REPLY>

<NPC_REPLY> 代表模型实时生成的台词,内容并不固定。由于使用了真实 API,实际成功与否取决于网络、账户权限、模型可用性及请求时的服务状态。

再次运行,在请求尚未结束时输入 cancel 并按回车,预期输出为:

text
请求中;输入 cancel 后回车可取消
cancelled: 已取消本轮对话

如果模型已经先一步返回成功,取消输入就不会再改变本轮结果。测试总超时时,应使用可控的延迟测试环境;不建议通过持续制造真实 API 故障来检验重试次数。

可以按以下条件检查异常处理:

  1. 有效凭证与网络:正常收到回复后,程序输出 success 并退出等待。
  2. 主动取消:请求尚未完成时输入 cancel,程序输出 cancelled,不会再进入新的 SDK 重试。
  3. 无效凭证:使用一个非空但无效的测试密钥时,若 API 返回 HTTP 401,程序输出 config_error,不继续重试;恢复正确密钥后再进行正常测试。
  4. 请求超时:单次尝试超过 4 秒时进入 SDK 超时处理;如果仍有重试机会且未超过总等待上限,可以再次尝试。
  5. 整体截止时间:总等待达到 15 秒时取消仍在进行的请求,向调用方返回超时状态。
  6. 限流或上游异常:可在单元测试中模拟 429、5xx 和连接错误,检查最大尝试次数以及最终的用户可读状态,而不是依赖线上随机故障。

将错误结果接入游戏对话界面

以上代码演示的是服务端调用器,实际游戏应让可信后端执行 SDK 请求,再向游戏客户端返回业务状态。不要把服务器的 API Key 或原始异常直接交给客户端。

UI 可以按状态执行以下操作:

业务状态 对话框行为
sending 显示等待提示,暂时禁止重复提交
success 更新 NPC 台词,解除等待
timeout 显示“回应超时”,允许玩家主动重新发送
rate_limited 显示“NPC 正忙”,进入适当冷却时间
config_error 显示服务不可用,不鼓励玩家反复重试
network_error 或 service_error 显示连接或服务故障,保留重新尝试入口
cancelled 安静地关闭等待状态,不覆盖其他 NPC 的对话

在 Unity 中可以把取消动作接到关闭面板、退出交互或切换 NPC 的事件;在 Web UI 中可以使用 AbortController.abort() 取消 fetch。如果游戏客户端调用自己的后端,客户端中止 HTTP 请求后,后端还应通过连接断开或显式取消协议尽可能停止对应的上游工作。

最后为每轮对话分配一个独立的 requestId 或递增轮次编号。接收回复时先核对当前 NPC、当前轮次与界面是否仍然有效,核对失败就丢弃旧结果。这样即使服务器响应晚于玩家切换目标的操作,过期台词也不会错误地显示到新 NPC 的对话框中。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理超时重试与接口错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通