Diese Seite ist derzeit nur auf Chinesisch verfügbar. Navigation und Menus sind bereits auf Deutsch.

Trace、告警与排障

InOneAPI 为每个请求生成请求级 Trace，记录计费与诊断所需的元数据，包括状态、TTFT、总延迟、路由渠道、重试、Token 和成本。响应头 X-Gateway-Trace-ID 是客户端日志与控制台记录之间的关联键。

记录 Trace ID

const response = await fetch("https://api.inoneapi.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INONEAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "YOUR_MODEL_ID",
    messages: [{ role: "user", content: "你好" }],
  }),
});

console.log({
  traceId: response.headers.get("X-Gateway-Trace-ID"),
  status: response.status,
});

推荐同时记录业务请求 ID、项目、Key 名称和状态码，但不要记录 API Key、完整提示词或模型回复。

阅读 Trace

字段用途
模型与渠道确认实际路由结果
状态码与错误码区分鉴权、参数、限流和上游错误
TTFT判断首 Token 响应速度
总延迟判断完整请求耗时
重试次数发现不稳定渠道或重试风暴
输入、输出、缓存 Token核对用量和上下文增长
请求成本定位高费用请求和模型

告警建议

以下是建议监测目标，需按控制台实际可配置项设置；未提供的指标请在应用监控系统补充：

  • 预算达到 50%、80% 和 100%。
  • 错误率或超时率异常升高。
  • P95 TTFT 或总延迟持续回退。
  • 单个 Key 请求量或费用突然增加。
  • Agent 重试次数、并发或循环调用异常。
  • 渠道熔断和恢复事件。

告警可以通过控制台、微信或邮件发送。每条告警应包含项目、Key、模型、时间窗口和可关联 Trace，避免只发送“调用失败”。

排障顺序

  1. 检查请求 URL、方法和协议。
  2. 检查 API Key、项目状态、模型权限和预算。
  3. 核对模型 ID、输入模态与参数能力。
  4. 根据状态码和 error.gateway_code（或上游的 error.code）判断是否可重试。
  5. 在 Trace 中查看路由、上游渠道、重试和耗时。
  6. 对比同项目、同模型的其他请求，判断是单次数据问题还是渠道问题。

常见状态：401 表示鉴权失败；403 表示权限或模型范围不允许；404 常见于模型或资源 ID 错误；402 表示余额、预算或项目状态问题；429 表示限流或容量约束；5xx 可能来自网关或上游。

成本或延迟突增

成本突增时先按项目、Key 和模型筛选，再检查输入上下文、输出长度、缓存命中和重试。延迟突增时分别比较 TTFT 与总延迟：TTFT 变慢更可能是排队或首 Token 问题，总延迟变慢也可能来自输出变长。

向支持人员反馈时提供时间范围、Trace ID、模型 ID、状态码和可复现步骤，不要发送真实 Key 或敏感提示词。

Tracing und Fehlerbehebung · Dokumentation · InOneAPI