上手第一小时卡住了：在求助之前先自己走一遍的排查清单

为什么第一小时最容易卡住

接入一个 LLM API 聚合站，本质上只做三件事：拿到 key、把请求指向正确的地址、在请求里写对模型名。听起来简单，但真实卡点几乎全部集中在这三步的细节上。先按下面的顺序自查，多数问题能在几分钟内定位。

第一项：密钥本身的问题

最常见的不是 key 错，而是 key 在传递过程中被改坏了。

• 首尾空白：从网页复制时很容易带上换行或空格。粘进环境变量、配置文件后，请求头里的 Authorization: Bearer <key> 就带上了多余字符。
• 被截断：某些终端或编辑器对长字符串有折行显示，手工选中复制可能少一截。
• 引号问题：在 .env 文件里给 key 加了引号，某些加载库会把引号也当成值的一部分；反过来，在 shell 里 export KEY=abc 不加引号，遇到特殊字符又会被解释。
• 用错了 key：同时持有多个站点的 key，或把测试用和正式的搞混。
• 前缀缺失：部分客户端要求自己拼 Bearer 前缀，某些 SDK 会自动加，混用时容易出现 Bearer Bearer xxx。

自查方法：先把 key 原样打印长度，或写一个最小请求（见下文）单独测试，不要在业务代码里排查。

第二项：base URL 指错了地方

聚合站的用法是「一个 key 调多个模型」，前提是请求真的发到了聚合站，而不是官方端点或其他服务。

• 很多 SDK（OpenAI 兼容风格）允许配置 base_url / baseURL，默认值指向官方。如果你只填了 key 没改地址，请求会打到官方端点，于是报「无效 key」——但这个 key 本身是好的。
• 注意地址是带版本路径还是不带：有的客户端要求填到域名根，有的要求填到 /v1 这类前缀，多填或少填一层都会 404。以文档给出的写法为准，不要凭印象拼。
• 尾部斜杠：有些拼接逻辑在 base URL 以 / 结尾时会生成双斜杠路径，部分网关会直接拒绝。
• 协议：确认是 https://，不要写成 http:// 或漏掉。

自查方法：打开客户端的调试日志或代理工具，看实际发出的完整 URL 是什么，与文档给出的地址逐字符比较。

第三项：USDC 充值没到账

站点用 Base 上的 USDC 充值、无 KYC，这带来便利，也带来一个常见误解：链上转账成功 ≠ 站内余额已可用。

• 网络选错：USDC 在多条链上都有发行，务必确认转的是 Base 网络。转到其他网络的同名资产通常无法自动入账。
• 等待确认：交易上链后仍需若干区块确认，站内入账可能滞后于区块浏览器显示的成功状态。先等一会儿再刷新。
• 地址核对：充值地址是否完整复制，是否包含大小写校验（地址大小写敏感的场景要特别注意）。
• 金额与手续费：确认到账金额是否被链上手续费或中转环节扣减，以及是否存在最低充值门槛。
• 余额口径：站内可能区分「充值余额」「赠送额度」「冻结中」等，界面显示的可用余额才是请求时真正扣减的那一份。

自查方法：先在区块浏览器用交易哈希确认交易状态与目标地址，再回站内看余额页面的可用额度，两边对得上再发请求。

第四项：模型 ID 拼写

聚合站的价值在于一个 key 能调 Claude、GPT、DeepSeek、Qwen、GLM、Kimi 等多个模型，但每个模型在接口里必须用站点规定的模型标识，不是产品宣传名。

• 大小写、连字符、版本后缀都可能有讲究，gpt-4o 和 GPT-4o 在多数实现里并不等价。
• 不同厂商的命名风格差异很大，从别处抄来的 ID 未必被当前站点接受。
• 模型可能分「对话」和「补全」「嵌入」等用途，用错类别会报参数或类型错误，看上去像 key 的问题。
• 若站点提供模型列表接口，直接拉一次列表，从返回值里挑 ID，比手工输入可靠得多。

自查方法：调用模型列表接口，把返回的 ID 复制粘贴到请求里，不要凭记忆写。

第五项：请求体与响应解析

key、地址、模型名都对了还报错，问题往往在请求体本身。

• 消息结构：messages 是否是数组，每项是否含 role 和 content，role 取值是否在允许范围内。
• 必填参数缺失：部分模型要求 max_tokens 之类的字段，缺失时报错信息可能很模糊。
• Content-Type：是否为 application/json。
• 流式开关：开了 stream 却按非流式解析，会看到空响应或解析异常；反之亦然。
• 响应结构差异：不同厂商在字段上可能有细微差别，直接用官方 SDK 的解析器时留意字段映射。

用最小请求做二分排查

出问题时不要在业务代码里改来改去。先用一个与业务无关的最小请求跑通：一条最短的 user 消息、非流式、只请求一个字段。

• 最小请求成功 → 问题在业务代码的参数、并发、超时或解析层。
• 最小请求也失败 → 问题在 key、base URL、模型 ID 或余额这四项里，回到上面逐项核对。

这个二分能把排查范围一次砍掉一半，比反复猜测高效得多。

错误信息怎么读

错误码本身也有信息量，先区分大类再细看：

• 认证类：指向 key 与请求头，优先查第一项。
• 404 / 路径类：指向 base URL 拼接，优先查第二项。
• 额度 / 计费类：指向余额与计费，优先查第三项，同时留意是否有未结算的占用。
• 参数 / 模型类：指向模型 ID 与请求体，优先查第四、五项。
• 超时 / 连接类：先排除本地网络与代理，再看是否请求体过大或流式未关闭。

求助前先准备好这些

如果自查后仍未解决，带着以下信息去问，能显著缩短往返：

• 最小请求的完整命令或代码片段（隐去 key）。
• 实际请求的完整 URL（同样隐去敏感部分）。
• 完整错误响应，包括状态码和响应体。
• 你已核对过的项，比如「base URL 按文档填写、模型 ID 从列表接口复制」。

关于成本的预期校正

顺带澄清一个常见误解，避免你在排查时被「是不是扣多了」干扰判断：本站按官方价 ×1.3 扣费，贡献 key 按官方价 ×1.1（优质 ×1.2）返 USDC。这是清晰的加价与返还关系，不是把成本压到官方价的一两折。核对账单时按这个口径去看，看到接近官方价 1.3 倍的扣减属于正常范围。