官方 SDK 用法速记
官方 SDK 把鉴权、重试、超时、流式解析这些重复工作封装掉了：Python 与 Node 的用法高度相似，都是先构造客户端，再调用资源方法，返回值是带类型的对象。直接手写 HTTP 请求并非不行，但重试、退避、流式解析与错误分类都要自己实现一遍。选 SDK 的关键收益，就在于这些边界情况的处理已经过验证。
基本信息
| Python 包 | 官方提供的对话与嵌入客户端包 |
|---|---|
| Node 包 | 官方 Node 客户端，支持 ESM 与 CommonJS |
| 鉴权 | 客户端初始化时读环境变量，避免硬编码 |
| 内置能力 | 自动重试、超时、流式迭代、类型定义 |
| 可调参数 | 最大重试次数、超时时间、基础地址 |
| 异步支持 | Python 有异步客户端，Node 天然异步 |
两端常用写法对照
| 操作 | Python | Node |
|---|---|---|
| 初始化 | 构造客户端并读取环境变量 | new 客户端并传入密钥 |
| 调用 | 资源方法加关键字参数 | 资源方法加对象参数 |
| 流式 | 开启流式后迭代返回对象 | 开启流式后用异步迭代 |
| 用量 | 读取返回对象的用量字段 | 读取返回对象的用量字段 |
| 异常 | 按异常类型分支处理 | 按异常状态码分支处理 |
| 自定义地址 | 初始化时传入基础地址 | 初始化时传入基础地址 |
典型使用场景
- 业务服务接入：在封装层统一处理鉴权、重试与日志
- 流式对话：用 SDK 的迭代接口直接消费增量
- 批处理脚本：脚本里循环调用并累计用量
- 异步服务：高并发场景用异步客户端提高吞吐
- 本地调试：用 SDK 快速验证提示词与参数
Python 最小调用
Python 最小调用
from openai import OpenAI
client = OpenAI(timeout=30, max_retries=3) # 密钥由环境变量提供
r = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "你好"}],
)
print(r.choices[0].message.content) # 文本结果
print(r.usage) # 用量统计，便于成本核算Node 侧等价写法
Node 侧等价写法
import OpenAI from "openai";
const client = new OpenAI({ timeout: 30000, maxRetries: 3 });
const r = await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "你好" }],
});
console.log(r.choices[0].message.content);
// 流式：把 stream 设为 true，用异步迭代逐块消费增量SDK 的默认重试只覆盖可恢复错误：参数与鉴权类错误不会重试，这类问题要直接暴露到日志与告警里，而不是靠等待自动恢复。
升级 SDK 主版本前先看变更说明：资源方法与参数命名偶有调整，生产环境应锁定版本，并在测试环境先跑一轮再发布。