Python 调大模型 API,本身代码不长,坑大多集中在三处:模型名写错、Base URL 多一个斜杠、流式输出没有逐字返回。下面按可复制的顺序,把 TT-5.4 mini API接入 与流式输出完整走一遍。
一、动手前先确认三件事
无论你用官方 SDK 还是自己拼 HTTP 请求,Python 侧能控制的只有三样东西:请求发到哪里、用谁的身份发、指定调用哪个模型。这三样任何一项不对,表现出的错误都很像,所以先把它们理清楚,再写代码会省很多时间。
- API Key:在服务商控制台创建,通常只在创建时完整显示一次,复制后建议放进环境变量,不要硬编码在脚本里,更不要提交到 Git。
- Base URL:请求的基础地址。是否以
/v1 结尾、是否带末尾斜杠,各家要求不同,以控制台或文档给出的写法为准。 - 模型名称:必须与服务端「模型广场 / 模型列表」中显示的字符串逐字符一致,大小写、连字符、空格都可能影响匹配结果。
如果你希望一个地址、一个 Key 就能切换不同厂商的模型,省去逐家注册和配置的时间,可以先把 通联AI中转站 的控制台当作入口:在里面查看可用模型、生成 API Key、复制 Base URL,再回到 Python 里替换对应变量即可,代码结构基本不用改。
二、Python 环境与最小可用请求
1. 安装依赖并配置环境变量
OpenAI 兼容协议目前是主流写法,Python 侧用同一套 SDK 就能发起对话请求。先安装依赖,再把 Key 和地址写进环境变量。
pip install openai # Linux / macOS export TL_API_KEY="你的API Key" export TL_BASE_URL="控制台给出的Base URL" # Windows PowerShell # $env:TL_API_KEY="你的API Key" # $env:TL_BASE_URL="控制台给出的Base URL"
2. 非流式请求:先跑通再谈优化
第一次接入,建议先用最普通的非流式调用验证链路。只有这一步返回正常,才说明 Key、地址、模型名三项都没问题。
import os from openai import OpenAI client = OpenAI( api_key=os.environ["TL_API_KEY"], base_url=os.environ["TL_BASE_URL"], ) resp = client.chat.completions.create( model="控制台显示的模型名称", # 例如模型中列出的名称 messages=[ {"role": "user", "content": "用三句话说明什么是流式输出"} ], ) print(resp.choices[0].message.content)
如果这里报 404 或「model not found」,优先回头检查模型名的拼写;如果报 401,检查 Key 是否复制完整、是否已被删除或过期。具体可用名称与鉴权方式,以控制台当前显示为准。
3. 流式输出:让回复逐字出现
流式输出的本质是把一次完整响应拆成多个数据块逐步返回。Python 侧只需要多一个 stream=True,再循环读取。
stream = client.chat.completions.create( model="控制台显示的模型名称", messages=[ {"role": "user", "content": "写一段 100 字左右的产品开场白"} ], stream=True, ) for chunk in stream: if not chunk.choices: continue # 结尾块可能只携带用量信息 piece = chunk.choices[0].delta.content if piece: print(piece, end="", flush=True)
这里有两个容易被忽略的细节:一是部分响应块只带统计信息、choices 为空,所以循环里要先判断;二是 delta.content 可能是 None,直接拼接字符串会报错。把这两处兜住,多数「流式跑一半崩掉」的问题就不会出现。
三、流式输出的工程细节
能跑通代码和能上线是两回事。流式场景下,用户对「首字出现时间」很敏感,对「中途断掉」更敏感。下面这张表可以作为配置自查清单。
| 配置项 | 作用 | 常见写法问题 | 检查方法 |
|---|
api_key | 身份鉴权 | 前后带空格、含换行符 | 打印长度或 repr() 查看首尾字符 |
base_url | 请求地址前缀 | 多写或漏写 /v1 | 与控制台、文档中的地址逐字比对 |
model | 指定调用的模型 | 大小写、连字符不一致 | 不要把模型名写死在多处,集中成一个常量 |
stream | 开启逐块返回 | 未加 flush,日志里看不出效果 | 本地打印是否能逐段出现 |
timeout | 控制等待上限 | 沿用默认值,长文本生成中途超时 | 按业务最长生成时间适当放宽 |
提醒:不同 SDK 版本、不同兼容协议在字段命名上可能存在差异。代码跑不通时,先确认你参考的是当前正在使用的 SDK 版本对应的文档,而不是几个月前的示例。
四、常见报错与排查顺序
遇到问题不要盲改代码,按下面的顺序从外向内排查,通常两三步就能定位。
- 401 / 403:Key 错误、失效或权限不足。重新生成一枚 Key 再试,排除复制污染。
- 404:路径或模型名不对。先确认 Base URL 是否包含或省略了版本路径,再核对模型名称。
- 429:请求频率或并发超出限制。加入退避重试,避免在
while 里无间隔重发。 - 流式无输出或长时间静默:可能是中间层做了缓冲。检查代理设置、确认使用
flush,并观察是否是网络中断导致连接被提前关闭。 - 返回值缺字段:先打印整块响应的结构,再决定取哪个字段,不要凭记忆写
choices[0]。
把上面这些问题在测试环境跑一遍,再把 model 名、base_url、超时时间抽成配置文件,后续换模型时只改配置,不动业务逻辑。
五、把接入方式固定下来
TT-5.4 mini API接入 跑通之后,真正的成本往往不在于写代码,而在于维护:不同模型对应不同地址、不同 Key、不同计费口径,团队里几个人各存一份,换人接手就要重新翻记录。这也是越来越多开发者倾向用聚合入口的原因。
通联AI中转站 提供的思路是统一接入:一个 Base URL 对接多种兼容协议,API Key、余额与调用情况在同一个控制台里管理,需要切换模型时主要改的是 model 字段。对已经在用 OpenAI 兼容写法的项目,可以先核对控制台给出的地址、模型名称与兼容协议,再逐步替换配置,不必一次性改动全部代码。具体可用模型、计费规则与接入说明,以 通联AI中转站官网 当前展示的信息为准。
代码已经能跑起来了?下一步是把 Key、Base URL 和模型名称换成你自己的。注册通联账号后,在控制台创建 API Key、复制接口地址、从模型列表中选出要用的型号,再回到上面那段示例里替换三个变量,就能完成第一次流式测试。
注册通联AI中转站,获取 API Key 开始调用