灵能API API中转站故障排查接入教程：使用记录、渠道状态与请求日志定位

API 中转站接入跑通以后，真正考验团队的是故障排查能力。接口突然 401、请求偶发超时、模型名报错、成本突然升高、业务同学说“刚才没返回”，如果没有一套固定排查链路，工程师很容易在代码、网络、**之间来回猜。🧭

这篇用 灵能API **截图做一套排查教程，按“仪表盘确认环境、密钥页核对配置、使用记录定位请求、渠道状态判断上游”的顺序梳理。图片已对可能涉及敏感信息的位置做遮罩，适合写进团队内部 SOP。

一、先判断问题属于哪一类

排查前先分类，比直接改代码更重要。API 调用失败通常可以分成四类：配置问题、请求问题、额度问题、通道问题。分类清楚后，排查路径会短很多。

一个实用原则：先看**有没有记录。如果***全没有这次请求，优先查业务代码、网络和环境变量；如果**有请求但失败，再根据状态码和耗时继续定位。

二、仪表盘：确认当前**状态和入口

仪表盘适合做第一步确认：是否登录到正确账号、当前**是否能正常访问、左侧导航是否完整、是否能进入密钥、使用记录和渠道状态页面。这个动作看似基础，但能快速排除“截图不是同一个**”“账号不一致”“路径进错了”这类低级问题。

• 确认当前**可正常打开，不是登录页、404 或网络错误。
• 确认使用的是团队约定的账号或工作区，避免拿错环境排查。
• 确认能进入密钥、使用记录、渠道状态等关键页面。
• 如果**整体访问慢，先不要急着怀疑业务代码。

三、密钥页：排查 401 和环境变量未生效

401 或鉴权失败是最常见的问题。不要只看代码里写了什么，要确认服务运行时真正读到了哪个 Key。很多线上问题来自环境变量没有重新加载、测试 Key 被误用于生产、旧 Key 被删除但服务还在使用。

OPENAI_API_KEY=sk-your-prod-key
OPENAI_*ASE_**L=https://api.灵能API.ai/v1
SERV***_NAME=order-sum**ry-worker
SERV***_ENV=prod
REQUEST_TIMEOUT_MS=15000

注意不要把真实 Key 打进日志。可以只打印前后少量字符或 Key 的哈希，用于确认配置是否更新。

四、使用记录：定位有没有这次请求

使用记录是排查链路里最有用的页面之一。它能回答三个关键问题：请求有没有到达中转站、请求大概发生在什么时候、失败集中在哪类模型或任务。

• 按时间窗口筛选：先定位用户反馈问题的具体分钟级时间段。
• 按服务名或任务类型对齐：业务日志里要保存 request_id 和 service_name。
• 按模型拆分：看是否某个模型失败率或耗时异常升高。
• 按消耗观察：如果 token 突然升高，优先查上下文是否被误传整份数据。

{
  "request_id": "req_20260721_07001",
  "service_name": "knowledge-*ase-api",
  "task_type": "document_qa",
  "model": "claude-sonnet-4-6",
  "status": "failed",
  "error_code": "timeout",
  "latency_ms": 18002
}

如果业务日志里没有 request_id，**记录和业务问题很难对上。建议所有调用都生成 request_id，并把它写进应用日志、错误提示和**追踪字段。

五、状态码排查：不要把所有失败都当成同一类

只有临时性错误才适合重试。参数错误、模型名错误、**ON 格式错误，重试只会制造更多失败记录；超时、限流、上游 5xx 才适合进入备用模型或延迟队列。

六、渠道状态：判断是不是上游通道问题

当多个业务服务同时出现超时，或者同一模型突然变慢，就要看渠道状态。渠道状态正常时，优先回到业务代码和网络；渠道状态异常时，应该启动降级策略，而不是让所有请求继续堆积。

• 如果只有一个服务失败，优先查该服务的 Key、参数和网络。
• 如果多个服务同时失败，优先查渠道状态和公共配置。
• 如果只有某个模型异常，尝试切换备用模型或调整路由。
• 如果请求普遍变慢，先降低批量任务并发，保护前台实时请求。

七、业务日志：**记录必须能和代码对齐

**能告诉你请求状态，但业务日志能告诉你这个请求来自哪个用户动作、哪个任务、哪个队列。两边字段对齐后，排查效率会明显提高。

const trace = {
  request_id: crypto.randomUUID(),
  service_name: process.env.SERV***_NAME,
  task_type: "ticket_sum**ry",
  model: selectedModel,
  user_id_hash: hashUser(user.id),
};

logger.info({ ...trace, stage: "llm_request_start" });
const result = await client.chat.completions.create(payload);
logger.info({ ...trace, stage: "llm_request_done", usage: result.usage });

不要在日志里写入原始 Key、完整用户输入、手机号、邮箱、客户合同等敏感信息。排查需要的是结构化元数据，而不是把所有内容都存下来。🔐

八、常见排查剧本

九、降级和兜底：排查时也要保护业务

排查不能影响用户体验。线上请求出现异常时，应该优先保证业务可用：前台实时请求可以返回简短兜底，**批量任务可以暂停或降并发，高风险任务可以转人工。

• 实时问答：超时后提示稍后重试或转人工，不让页面一直等待。
• 摘要任务：失败后保留原文入口，允许用户手动查看。
• 批量任务：失败 *lock 单独重试，避免整批任务反复跑。
• 高风险任务：模型异常时不自动给结论，进入人工复核队列。

十、上线前排查能力清单

• 所有请求是否都有 request_id，并能在业务日志里查到。
• 是否记录 service_name、task_type、model、latency_ms 和错误码。
• 是否能从**使用记录对齐到具体业务服务。
• 是否区分 400、401、429、5xx 和 timeout 的处理方式。
• 是否有备用模型、降级提示和重试退避策略。
• 是否避免在日志、截图和文档里泄露 Key、账号、邮箱和用户原文。

十一、建议落库字段

建议保存 request_id、service_name、task_type、environment、selected_model、status、error_code、latency_ms、input_tokens、output_tokens、fall*ack_used、retry_count、created_at。排查类字段不用太复杂，但必须稳定。

有了这些字段，团队可以按服务统计失败率，按模型统计耗时，按任务类型统计成本，也能在用户反馈问题时快速回放调用链路。

十二、推荐排查顺序

遇到问题时，先问四个问题：业务日志有没有开始调用；**使用记录有没有这次请求；状态码属于配置、参数、额度还是通道；是否需要降级保护用户体验。这个顺序能避免无效猜测，也能让多人协作排查时有共同语言。

API 中转站的价值不只是把请求转出去，更重要的是让团队能看见请求：谁发起、什么时候发起、用了哪个模型、失败在哪里、成本多少。排查链路搭好以后，线上问题会少很多慌乱。✅