大模型 API 接入完全指南：从拿 key 到上线

上周有个做内部工具的哥们跟我吐槽：接了三个大模型平台的 API，代码里散落着五六个不同风格的 HTTP 调用，某天凌晨报警——某个 key 被风控冻结了，业务直接挂了两小时才发现。问题不在技术难度（大模型 API 说白了就是 HTTP 请求），而在于流程没跑顺：key 怎么存、模型怎么选、messages 怎么拼、流式怎么接、错误怎么兜底、token 怎么算账，这六件事任何一个环节偷懒，都会在生产环境变成故障。

大模型 API 接入的核心流程分六步：获取 API key → 选模型与端点 → 构造 messages 数组 → 发 HTTP/SDK 请求 → 处理流式响应 → 控制 token 成本。本文串讲每个环节的关键决策和我踩过的坑，并链向各步骤的详细示例。

第一步：获取并管理 API Key

几乎所有大模型平台（OpenAI、Anthropic、Moonshot、DeepSeek 等）都采用 Bearer token 鉴权。注册账号后在控制台生成 sk-xxx 格式的 key，注意：

• key 只在生成时显示一次，请立即存入环境变量（OPENAI_API_KEY）或密钥管理服务，切勿硬编码进代码。
• 为不同项目/环境使用不同 key，方便按 key 追踪用量和吊销。
• 如需多平台统一入口，可通过聚合 API 服务（如力达云）用一个 key 调多个模型。

# 推荐：通过环境变量注入
export OPENAI_API_KEY="sk-xxx"

这里再说几个我见过最多的真实翻车场景，都是低级但致命的：

第一个坑：key 直接提交进了 git。 最常见的路径是本地 .env 文件没加进 .gitignore，一次 git add . 全带进去，推到 GitHub 之后几分钟内就可能被扫描机器人抓走（很多平台的 key 前缀是公开格式，扫描器专门盯着 sk- 开头的字符串爬）。补救方法不是删了那次提交就完事——git 历史里还留着，得用 git filter-repo（比老的 filter-branch 更快更安全）或者 BFG Repo-Cleaner 把历史里的敏感字符串整体清除，并且必须同时去平台控制台把这个 key 吊销重新生成，光清 git 历史不吊销 key 没有任何意义，因为泄漏的那一刻它就已经在别人手里了。

第二个坑：一个 key 走遍测试和生产。 你以为省事，出问题时却没法区分是测试脚本疯狂调用刷爆了额度，还是生产环境真实流量涨了。按环境拆分 key（OPENAI_API_KEY_DEV / OPENAI_API_KEY_PROD），配合平台后台的用量看板分别监控，出问题定位能从”猜”变成”看一眼就知道”。

第三个坑：CI/CD 里把 key 打印到日志。 排查问题时手滑加了一行 console.log(process.env) 或者 echo $OPENAI_API_KEY 忘了删，CI 日志通常是团队内可见甚至外部可见的，等于把 key 广播了一遍。规范做法是用 CI 平台的 Secrets 管理（GitHub Actions 的 secrets.*、GitLab CI 的 Protected Variables），并且养成习惯：任何涉及密钥的调试输出，打印前先脱敏（只留前 4 位后 4 位，中间用星号）。

第二步：选模型与 API 端点

主流平台均提供兼容 OpenAI Chat Completions 格式的端点，只需修改 base_url 即可切换模型：

平台/模型	base_url 示例	常用模型名
OpenAI	https://api.openai.com/v1	gpt-4o, gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
Moonshot	https://api.moonshot.cn/v1	moonshot-v1-8k
力达云聚合	https://api.lidayun.com/v1	多模型统一接入

选型建议：快速原型用低成本小模型（如 gpt-4o-mini）；生产任务按准确率/上下文长度/价格三角权衡。

这个”三角权衡”具体怎么权衡，给你一个我自己用的判断顺序，别一上来就冲着榜单第一名去：

1. 先看任务复杂度，再看模型能力。 如果任务是结构化提取、简单分类、短文本摘要这类”确定性高”的活儿，小模型（如 gpt-4o-mini、deepseek-chat）跑评测集往往已经够用，没必要为了”更聪明”多花几倍的钱。只有涉及多步推理、长链条工具调用、代码级别的复杂逻辑生成，才值得上旗舰模型。
2. 上下文长度按实际场景倒推，别只看参数表最大值。 平台宣传的”支持 128k 上下文”是理论上限，不代表你能稳定用满——超长上下文会拖慢首字延迟（TTFT），而且很多模型在上下文靠后段落的”记忆”会打折扣（业内俗称 lost in the middle）。如果你的场景是单轮问答，8k-16k 窗口基本够用；做长文档问答、代码库级别的 RAG，才需要认真挑长上下文模型并做检索缩短提示词。
3. 价格按”每千次请求成本”折算，不要只看单价。 模型 A 每百万 token 比模型 B 贵一倍，但如果 A 的输出更精炼（同样任务耗费的 token 数更少），实际每次请求成本反而可能更低。建议接入前先拿真实业务的 10-20 条样本跑一遍，用 usage 字段实测token 消耗，再乘以官方单价对比，别拍脑袋。

另外提一句：base_url 这种”改一行代码切平台”的能力，前提是对方接口严格兼容 OpenAI 的请求/响应格式（包括 choices[0].message、usage 字段结构、错误码语义）。有些平台号称兼容，细节字段却有出入（比如 finish_reason 取值不同、流式分片粒度不同），换平台之后务必跑一遍你的错误处理和流式解析逻辑，不要假设”能跑起来”等于”完全兼容”。

第三步：构造 messages 数组

Chat Completions API 的核心是 messages 数组，每条消息有 role（system/user/assistant）和 content 字段：

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "你是一个代码助手，回答简洁准确。"},
    {"role": "user", "content": "用 Python 写一个冒泡排序"}
  ],
  "max_tokens": 512
}

多轮对话只需把历史 assistant 回复也追加进 messages，保持上下文连续。注意 messages 越长消耗 token 越多，长对话需做窗口截断或摘要压缩。

三个角色各自的用法要分清楚，很多人接入时把这块搞混：

• system：一条对话只放一次，放在数组第一位，用来设定角色人设、输出格式约束（比如”只输出 JSON，不要多余解释”）。它不是用来塞业务数据的，塞多了反而会让模型”分心”去遵循格式而忽略具体任务。
• user：用户的实际输入，多轮对话里每一轮用户说的话都单独作为一条 user 消息追加，不要把历史对话拼接成一整段字符串塞进一条消息里——那样模型没法区分”谁说的话”，容易答非所问。
• assistant：模型上一轮的回复，原样追加回去，让模型”看到自己说过什么”，这是多轮对话保持连贯的关键。

窗口截断具体怎么做，给你两种可落地的策略，选哪种取决于你的场景：

1. 滑动窗口法：只保留最近 N 轮对话（比如最近 10 轮），更早的历史直接丢弃。实现简单，代价是模型会”忘记”很久以前聊过的内容，适合客服、闲聊这类对早期上下文依赖不强的场景。
2. 摘要压缩法：当历史消息的估算 token 数接近模型上下文上限的 70%-80% 时，用一次额外的模型调用把前面的对话压缩成一段摘要，替换掉原始的多轮消息，再把摘要作为一条 system 或 user 消息插入。这种方式能保留长期语境，代价是多了一次调用的延迟和成本，适合客户支持工单、长篇协作写作这类需要”记住来龙去脉”的场景。

估算 token 数不要用字符数除以某个系数去瞎猜，中文和英文的分词比例差异很大（中文大致 1 个汉字约等于 1.5-2 个 token，英文大致 4 个字符 1 个 token，仅供粗估，不同模型的分词器结果不同）。真实项目里建议直接用官方提供的 tokenizer 库（如 tiktoken）精确计算，或者干脆用每次请求返回的 usage.prompt_tokens 做滑动统计，比自己拍脑袋估算靠谱得多。

第四步：发送请求（Python / Node.js）

推荐用官方 SDK，内置重试与错误处理。以 OpenAI 兼容 SDK 为例，改 base_url 即跨平台。

Python 完整示例见 Python 调用大模型 API 完整示例；Node.js 示例见 Node.js 接入大模型 API。

最简 Python 片段：

from openai import OpenAI

client = OpenAI(api_key="sk-xxx", base_url="https://api.lidayun.com/v1")
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

用官方 SDK 而不是自己拼 requests.post，图的是它内置了这几样东西，自己手写很容易漏掉：

• 自动重试：SDK 默认会对 429（限流）、500/503（服务端异常）这类瞬时性错误做有限次数的自动重试，并且内置了指数退避（每次重试间隔翻倍），你不用自己实现基础的重试逻辑。
• 连接池复用：底层用 httpx 或类似库维护长连接，避免每次请求都重新建立 TCP 连接和 TLS 握手，高并发场景下这个差异很明显。
• 超时分层控制：SDK 通常支持分别设置连接超时和读取超时（比如 timeout=httpx.Timeout(connect=5.0, read=60.0)），流式响应尤其需要给读取超时留足余量，不然长回复还没生成完就被你自己的超时掐断了。

有个真实报错场景值得说一下：如果你看到 openai.APITimeoutError 或者请求卡住几十秒最后超时失败，先别怀疑网络，去查两件事——一是 max_tokens 是不是设得过大导致模型生成时间过长，二是你的 timeout 参数是不是用了 SDK 默认值（有些版本默认只有十几秒，对于非流式的长回复请求明显不够）。把非流式请求的读取超时手动调到 60-120 秒，通常就能解决这类超时报错。

第五步：处理流式输出（SSE）

对话类应用强烈建议开启 stream=True，服务端以 SSE 格式逐 token 推送，用户即见即看，体验更好：

for chunk in client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一首短诗"}],
    stream=True,
):
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

SSE 原理、各语言（Python/JS）的边收边渲染实现，详见 流式输出 SSE：原理与各语言实现。

流式输出这里有几个容易被忽略的实操细节，接入前最好都验证一遍：

• 别用 requests 库直接消费流式响应。 老版本的 requests 对 SSE 这类长连接、逐块返回的响应支持不好，容易出现”缓冲区攒够一批才吐出来”的假流式现象（表现上看起来像是等了很久才一次性蹦出一大段文字，而不是逐字打印）。用官方 SDK 或者 httpx 的流式接口（stream=True 配合 iter_lines()），才能真正做到边收边处理。
• 网络中断要区分”服务端主动结束”和”连接意外断开”。 正常结束时流会发送一个特殊的结束标记（不同平台格式略有不同，OpenAI 兼容格式通常是 data: [DONE]），你的解析逻辑要能识别这个标记并正常收尾；如果是连接被防火墙、代理或者网络抖动意外掐断，通常会抛出连接异常，这时候需要你自己捕获异常并决定是否重连——注意流式请求不适合简单重试，因为重新发起会导致模型从头重新生成，浪费 token 又拖慢体验，更合理的做法是记录已经收到的部分内容，重连后提示用户”回复被中断，是否继续”。
• 前端渲染要做防抖，不要每收到一个 token 就触发一次重排（reflow）。 高频率的 DOM 更新会导致页面卡顿，尤其在移动端更明显。实践中常见做法是攒够一小段字符（比如遇到标点符号或者达到固定字符数）再批量渲染一次，兼顾”看起来是流式”和渲染性能。

第六步：错误处理与成本控制

错误处理：

HTTP 状态码	含义	处理建议
401	key 无效或过期	检查环境变量 / 重新生成 key
429	速率限制或额度不足	指数退避重试；充值或升级限额
500/503	服务端异常	重试 + 降级到备用模型
400	请求格式错误	检查 messages 结构与参数

成本控制：

• 用 max_tokens 硬限制单次输出长度，防止意外超支。
• prompt 缓存（某些平台支持）：相同 system prompt 重复请求时只计费一次。
• 生产环境对每个请求记录 usage.total_tokens，按用户/业务线分摊成本。
• 测试阶段用低成本小模型，上线前再切换。

常见问题

API key 泄漏了怎么办？ 立即在平台控制台吊销该 key，重新生成并更新所有引用处。检查 git 历史是否有误提交，可用 git filter-branch 或 BFG 清除。

为什么返回内容被截断？ 通常是 max_tokens 设置过小，或模型的上下文窗口已满。调大 max_tokens，或对长对话做窗口截断再重发。

如何判断用哪个模型？ 先用最小/最便宜的模型跑通业务逻辑，再用评测集对比准确率；如果准确率不达标再升级模型，避免过度花费。

聚合 API 和直接调原厂有什么区别？ 聚合 API 提供统一 key 和端点，内置负载均衡与故障转移，适合需要多模型兜底或统一计费的场景；直接调原厂延迟更低，适合单一强依赖场景。

---

本文是 access 集群的 pillar 文章，各环节详见：Python 调用大模型 API 完整示例、Node.js 接入大模型 API、流式输出 SSE：原理与各语言实现。更多接入资料见接入教程专题。需要一个 key 调通多个主流大模型？申请力达云聚合 API 内测。