国产大模型 API 接入代码示例教程

文章导读
把国产大模型 API 接进自己的项目,先要判断的是接口形态能不能套进现有调用链:请求地址、鉴权头、消息体结构、返回字段是否与已用的客户端一致。多数国产厂商提供与 OpenAI 风格相近的 /chat/completions 接口,但参数名、必填项、流式分片细节并不完全一致。比较稳妥的做法是把地址、密钥、模型名抽成配置,先用最小请求打通,再逐步加超时、错误分类和流式处理,而不是一次性把业务逻辑全塞进
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

把国产大模型 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 逐块输出。
  • 数据边界:送出去的文本是否包含用户隐私或内部资料,是否需要先脱敏。

如果以上信息只能确认一半,建议先只在测试环境打通最小请求,不要直接接入线上业务链路。

按这个顺序处理

第一步,把可变项抽成环境变量,代码里不出现明文密钥:

国产大模型 API 接入代码示例教程
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 字段,方便后面定位是网络问题还是参数问题。

国产大模型 API 接入代码示例教程

改完后怎么验证

验证要分正常路径和异常路径两轮,只看“有没有返回文字”不够。

  1. 正常请求:跑一次最小调用,检查返回对象里 choices[0].message.content 非空,finish_reason 和 usage 字段存在。预期信号是结构稳定、每次都能拿到同一组键名。
  2. 鉴权异常:故意用错误密钥发一次请求,确认返回 401 而不是 200 空字符串。这条能验证错误没有被吞掉。
  3. 参数异常:把 max_tokens 或 messages 改成明显不合法值,确认服务端返回 4xx 且错误信息可读,而不是客户端长时间挂起。
  4. 流式拼接:用 "".join(chat_stream(...)) 收集输出,与同步调用结果对比,确认没有丢字、没有把 JSON 片段当正文输出。
  5. 超时行为:把 timeout 调到很小的值,确认调用方拿到超时异常并进入回退分支。

一轮下来,如果错误都能被区分为鉴权、限流、参数、网络四类,接入层就基本可用了。

容易忽略的边界

兼容层不等于完全等价。常见差异包括:max_tokens 的上限与含义、temperature 的可选范围、是否支持 response_format 或函数调用、流式分片中是否包含 usage 统计。把参数硬编码在业务代码里,换模型时就要全量改动,建议集中在一处映射。

国产大模型 API 接入代码示例教程

密钥只能放在服务端。任何把 API Key 下发到浏览器或移动端的做法都不适用,即使厂商文档里写了前端直连示例,也要结合自身场景确认。

模型名和接口地址存在变更可能,建议把 model 名称放在配置里并保留一个可切换的备用值;当某个模型下线或改名时,回退方式是切到配置中的备选模型,而不是临时改代码发版。若厂商接口与现有客户端不兼容,回退建议是自己维护一个薄适配层,把字段映射集中在适配层,业务侧保持稳定调用签名。

另外,长文本和并发请求要单独评估:单次请求体过大可能被网关直接拒绝,高并发可能先触发限流。这类问题通常需要结合自己的配额和网络环境确认,不宜直接照搬他人参数。