Node 与 Python 首次接入：一个第一次就能跑通的最小仓库

先把三件事定下来

首次接入失败，多半不是代码写错，而是三件事没想清楚：base URL 指向哪里、key 从哪里读、模型名写哪个。先把这三件事固定，再写调用逻辑。

• Base URL：聚合站的接口地址，后面所有请求都拼在它之上。
• API key：统一走环境变量，不写进代码、不进仓库。
• 模型名：用聚合站文档里给出的模型别名，而不是各厂商官方模型名。

聚合站的模型别名通常带上游前缀，例如区分 Claude、GPT、DeepSeek、Qwen、GLM、Kimi 各自的系列。别名是聚合站对外暴露的稳定标识，换上游时不需要改你的代码。

最小仓库结构

两种语言共用一套目录约定，便于对照：

starter/
  .env.example      # 只放变量名和占位值
  .gitignore        # 忽略 .env
  node/ 或 py/      # 具体调用代码

.env.example 里只写变量名，真实值由每位开发者本地填入 .env，.env 永远不进版本库。这是第一条纪律，后面所有步骤都建立在它之上。

Key 加载：只走环境变量

Node：用 process.env 读取，本地开发可用 dotenv 从 .env 载入。启动时做一次校验，缺失就直接抛错退出，而不是带着空字符串去发请求——那样只会拿到一个含义模糊的 401。

Python：用 os.environ 读取，本地可用 python-dotenv。同样在模块加载时校验，缺 key 立刻失败。

校验的目的不是防御攻击，而是把「配置错误」和「网络/上游错误」分开。初次接入时，这个区分能省掉大量排查时间。

模型别名：先选一个，跑通再换

不要一上来就写模型路由。第一个请求只用一个模型别名，确认链路通了，再考虑切换。

选别名时看两点：该别名在文档中标注的上下文能力是否够你测试，以及它是否属于你常用的上游系列。把别名写成代码里的一个常量或配置项，不要散落在多处。后续做多模型对比时，改动点只有这一处。

一次流式调用

流式是第一请求的最佳验证方式，因为你能立刻看到 token 逐个到达，而不是等到超时才知道哪里不对。

调用形态在所有兼容 OpenAI 风格的聚合站上基本一致：向 chat completions 端点发一个带 stream: true 的请求，然后逐块读取响应体，解析每行 data: 开头的负载，遇到结束标记就停止。

要点：

• 请求头带 Authorization: Bearer <key> 和 Content-Type: application/json。
• 逐块解析时要处理「一行被切成两半」的情况，用一个缓冲区累积再按行切分。
• 空行和心跳行跳过，不要当解析错误。
• 收到结束标记后主动关闭连接，别让进程挂住。

Node 用原生 fetch 拿 response.body，配合 TextDecoder 与一个字符串缓冲区即可，不必须引入 SDK。Python 用 requests 的 stream=True，对 iter_lines() 逐行处理，或用 httpx 的流式接口。两种写法都不依赖厂商 SDK，接聚合站时反而更省心。

一次带退避的重试

初次接入最常见的失败不是逻辑错，而是瞬时问题：网络抖动、上游短暂不可用、连接被提前关闭。所以第一个版本就该有重试，但只重试该重试的。

原则：

• 只重试幂等且可安全重放的请求。一次对话补全在没拿到完整响应前重放是安全的；但已经流出部分内容后再重试，会让调用方看到重复片段。流式场景下，建议在「尚未收到任何内容」时才重试。
• 区分错误类型。认证失败、请求体非法这类 4xx 不要重试，重试只会重复同样的错误。限流和服务端错误才值得退避重试。
• 指数退避加抖动。等待时间随次数增长，并加入随机量，避免多个客户端同时重试。
• 设上限。重试次数写死一个小值，超过就抛出原始错误，把判断权交回调用方。

写重试时把「第几次尝试」打进日志，出问题时一眼能看出是首次就失败还是重试后才失败。

首次跑通的检查顺序

按这个顺序排查，能覆盖绝大多数首次失败：

1. key 是否真的被读到（打印长度，不打印内容）。
2. base URL 是否正确拼接，路径是否重复或缺失。
3. 模型别名是否与文档完全一致，包括大小写和分隔符。
4. 请求头是否带了认证信息。
5. 若是流式，响应体是否被当作普通 JSON 解析了。

关于计费的一点说明

使用聚合站时，你的用量按官方价乘以固定系数扣费；如果你也向上游贡献 key，则按另一套系数以 USDC 结算返还。这不影响接入代码的写法，但值得在写第一个请求前就知道：成本是按实际用量线性计算的，所以调试阶段也应避免无意义的重复大请求。

接入本身不需要 KYC，充值走 Base 上的 USDC，这些都属于账户层面的事，与代码无关。代码要做的只有一件事：把 key 从环境变量读出来，正确发出第一个请求。