把国产大模型 API 接进自己的项目,先要判断的是接口形态能不能套进现有调用链:请求地址、鉴权头、消息体结构、返回字段是否与已用的客户端一致。多数国产厂商提供与 OpenAI 风格相近的 /chat/completions 接口,但参数名、必填项、流式分片细节并不完全一致。比较稳妥的做法是把地址、密钥、模型名抽成配置,先用最小请求打通,再逐步加超时、错误分类和流式处理,而不是一次性把业务逻辑全塞进接入层。
接入国产大模型 API 的可操作路径是:先用环境变量固定 base_url、api_key、model 三项,发一条最小 chat 请求确认返回结构,再补 401/429/超时三类错误处理和流式拼接。适用场景是通过 HTTP 直连或兼容层调用;不适用把密钥写进前端、或指望所有厂商参数完全等价的场景。验证以返回结构完整、错误码可区分、流式分片可拼接为准,模型能力差异需另行评估。
先确认当前场景和目标
动手写代码前,先把下面几项确认清楚,任何一项缺失都会在后面变成排查成本:
- 鉴权方式:请求头是
Authorization: Bearer <key>还是厂商自定义 header,密钥存放在服务端环境变量还是配置中心。 - 接口形态:是否兼容 OpenAI 风格的消息体(
messages数组 +role/content),不兼容时字段映射表要先列出来。 - 模型标识:调用时使用的 model 名称,是否区分在线版本与快照版本。
- 调用方式:同步一次性返回,还是需要
stream: true逐块输出。 - 数据边界:送出去的文本是否包含用户隐私或内部资料,是否需要先脱敏。
如果以上信息只能确认一半,建议先只在测试环境打通最小请求,不要直接接入线上业务链路。
按这个顺序处理
第一步,把可变项抽成环境变量,代码里不出现明文密钥:

export LLM_BASE_URL="https://api.example.com/v1"
export LLM_API_KEY="your-key"
export LLM_MODEL="your-model-name"
第二步,写一个最小可运行请求。下面的片段是通用骨架,BASE_URL、model 以及鉴权头需要按实际厂商文档替换,路径 /chat/completions 也要以对方给出的为准:
import os, json, requests
BASE_URL = os.environ["LLM_BASE_URL"].rstrip("/")
API_KEY = os.environ["LLM_API_KEY"]
MODEL = os.environ["LLM_MODEL"]
def chat(prompt, timeout=30):
url = BASE_URL + "/chat/completions"
headers = {
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": prompt}],
"temperature": 0.3,
"max_tokens": 512,
"stream": False,
}
resp = requests.post(url, headers=headers,
data=json.dumps(payload), timeout=timeout)
if resp.status_code == 401:
raise RuntimeError("鉴权失败:检查 API Key 与请求头格式")
if resp.status_code == 429:
raise RuntimeError("触发限流:退避后重试,或降低并发")
resp.raise_for_status()
data = resp.json()
return data["choices"][0]["message"]["content"], data.get("usage")
第三步,需要流式输出时单独封装,注意分片是 SSE 行,可能夹杂空行和结束标记,拼接逻辑要能容忍不完整行:
def chat_stream(prompt, timeout=60):
url = BASE_URL + "/chat/completions"
payload = {"model": MODEL, "stream": True,
"messages": [{"role": "user", "content": prompt}]}
with requests.post(url, headers={"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json"},
json=payload, stream=True, timeout=timeout) as r:
r.raise_for_status()
for line in r.iter_lines(decode_unicode=True):
if not line or not line.startswith("data:"):
continue
piece = line[5:].strip()
if piece == "[DONE]":
break
delta = json.loads(piece).get("choices", [{}])[0].get("delta", {})
if delta.get("content"):
yield delta["content"]
第四步,把超时、重试、日志放在调用方而不是散落在业务代码里,记录请求耗时、状态码和 usage 字段,方便后面定位是网络问题还是参数问题。

改完后怎么验证
验证要分正常路径和异常路径两轮,只看“有没有返回文字”不够。
- 正常请求:跑一次最小调用,检查返回对象里
choices[0].message.content非空,finish_reason和usage字段存在。预期信号是结构稳定、每次都能拿到同一组键名。 - 鉴权异常:故意用错误密钥发一次请求,确认返回 401 而不是 200 空字符串。这条能验证错误没有被吞掉。
- 参数异常:把
max_tokens或messages改成明显不合法值,确认服务端返回 4xx 且错误信息可读,而不是客户端长时间挂起。 - 流式拼接:用
"".join(chat_stream(...))收集输出,与同步调用结果对比,确认没有丢字、没有把 JSON 片段当正文输出。 - 超时行为:把 timeout 调到很小的值,确认调用方拿到超时异常并进入回退分支。
一轮下来,如果错误都能被区分为鉴权、限流、参数、网络四类,接入层就基本可用了。
容易忽略的边界
兼容层不等于完全等价。常见差异包括:max_tokens 的上限与含义、temperature 的可选范围、是否支持 response_format 或函数调用、流式分片中是否包含 usage 统计。把参数硬编码在业务代码里,换模型时就要全量改动,建议集中在一处映射。

密钥只能放在服务端。任何把 API Key 下发到浏览器或移动端的做法都不适用,即使厂商文档里写了前端直连示例,也要结合自身场景确认。
模型名和接口地址存在变更可能,建议把 model 名称放在配置里并保留一个可切换的备用值;当某个模型下线或改名时,回退方式是切到配置中的备选模型,而不是临时改代码发版。若厂商接口与现有客户端不兼容,回退建议是自己维护一个薄适配层,把字段映射集中在适配层,业务侧保持稳定调用签名。
另外,长文本和并发请求要单独评估:单次请求体过大可能被网关直接拒绝,高并发可能先触发限流。这类问题通常需要结合自己的配额和网络环境确认,不宜直接照搬他人参数。