OpenAI Python SDK 入门实战：从 0 到常见能力全覆盖

1. 先建立正确认知：你在调用什么

当你写下这行代码：

from openai import OpenAI
client = OpenAI(api_key="...")

本质是在做三件事：

通过 SDK 生成标准 HTTP 请求
带上身份凭证（OPENAI_API_KEY）
请求云端模型服务并获取结果

也就是说，openai 库是你与模型服务之间的“客户端封装层”，它让你不用手写底层 HTTP 细节。

2. 环境准备（最小可用）

2.1 安装依赖

pip install openai

2.2 配置 API Key（推荐环境变量）

export OPENAI_API_KEY="sk-xxxx"

可选：

export OPENAI_MODEL="gpt-4o-mini"
export OPENAI_BASE_URL="https://your-compatible-endpoint/v1"

OPENAI_BASE_URL 只在代理或兼容端点场景下使用，标准接入可以不设置。

3. OpenAI Python 库核心方法速查表

基于 openai>=1.0 官方库（from openai import OpenAI → client = OpenAI()）整理：常用入口、作用与主要参数。下列调用均挂在 client 上；与 0.x 时代的 ChatCompletion.create() 等类方法写法不同，请勿混淆。

方法及作用	参数及参数含义
`client.chat.completions.create()` 核心对话接口：多轮对话、问答、文本创作（GPT-3.5/4/4o 等）	① model：必选，模型名称（如 `gpt-4o-mini`） ② messages：必选，消息列表，如 `[{"role":"user","content":"..."}]` ③ temperature：可选，随机性（约 0～2；越低越稳，越高越发散） ④ max_tokens：可选，生成长度上限（token） ⑤ top_p：可选，核采样（0～1；常与 temperature 二选一调优） ⑥ stream：可选，是否流式输出 ⑦ stop：可选，停止生成的标记序列 ⑧ frequency_penalty：可选，重复惩罚（约 -2～2）
`client.embeddings.create()` 文本向量化：语义检索、聚类、相似度	① model：必选，嵌入模型（如 `text-embedding-3-small`） ② input：必选，单条字符串或多条列表 ③ encoding_format：可选，向量编码（如默认浮点 / `base64`） ④ dimensions：可选，输出维度（部分新嵌入模型支持）
`client.completions.create()` 文本补全（单段 prompt 续写）；多用于 Instruct 旧式模型	① model：必选（如 `gpt-3.5-turbo-instruct`） ② prompt：必选，输入提示 ③ temperature / max_tokens / stop 等与 Chat 类似，含义相近
`client.images.generate()` 文生图	① prompt：必选，画面描述 ② n：可选，张数（依模型限制，如 1～10） ③ size：可选，如 `1024x1024` 等 ④ response_format：可选，如 `url`、`b64_json` ⑤ model：可选，如 `dall-e-3`、`dall-e-2`
`client.audio.transcriptions.create()` 语音转文字	① file：必选，音频文件对象（如 mp3/wav/m4a） ② model：必选，识别模型（常用 `whisper-1`） ③ language：可选，语言提示（如 `zh`） ④ prompt：可选，风格/词汇提示以提升准确率 ⑤ response_format：可选，如 `json`、`text`
`client.files.create()` 上传文件：微调、Batch、Assistants 等	① file：必选，待上传文件（二进制可读对象或路径按 SDK 用法传入） ② purpose：必选，用途（如 `fine-tune`、`assistants`、`batch` 等，以文档为准）
`client.fine_tuning.jobs.create()` 创建微调任务（openai≥1.0 中为 jobs 资源；非旧名 `FineTunes.create`）	① training_file：必选，已上传文件的 file id ② model：可选，基底模型 ③ hyperparameters：可选，如 `n_epochs` 等（以当前 API 为准）
`OpenAI(...)` 初始化客户端：密钥、代理、超时等	① api_key：API 密钥（可省略，读环境变量 `OPENAI_API_KEY`） ② base_url：可选，兼容端点 / 代理根 URL ③ timeout：可选，请求超时 ④ max_retries：可选，失败重试次数

4. OpenAI Python SDK 方法知识字典（按方法分类）

4.1 `OpenAI(...)`：创建客户端

作用：初始化 SDK 客户端
常用参数：api_key、base_url
推荐：优先用环境变量 OPENAI_API_KEY

常见传参方式（按场景选一个）：

import os
from openai import OpenAI

# 方式 A：推荐。只要环境变量里有 OPENAI_API_KEY 即可
# export OPENAI_API_KEY="sk-xxxx"
client = OpenAI()

# 方式 B：显式传 API Key（测试脚本常用，生产不建议明文写死）
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# 方式 C：兼容端点 / 代理（比如企业网关）
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url="https://your-proxy-or-compatible-endpoint/v1",
)

# 方式 D：集中 kwargs，方便按环境切换
kwargs = {"api_key": os.getenv("OPENAI_API_KEY")}
base_url = os.getenv("OPENAI_BASE_URL", "").strip()
if base_url:
    kwargs["base_url"] = base_url
client = OpenAI(**kwargs)

4.2 `client.chat.completions.create(...)`：对话生成

作用：最常用文本生成入口
常用参数：model、messages、temperature、max_tokens
常见读取（取模型回复正文）：resp.choices[0].message.content

为什么这样读：

resp 是完整响应对象
choices 是候选答案列表（通常至少 1 个）
choices[0] 表示第一个候选答案
message.content 才是最终文本内容

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手"},
        {"role": "user", "content": "用一句话解释 API Key"},
    ],
    temperature=0.3,
)
text = resp.choices[0].message.content or ""
print(text)

4.3 `client.chat.completions.create(..., stream=True)`：流式输出

作用：边生成边返回，适合聊天 UI
读取方式：遍历 chunk，读取 chunk.choices[0].delta.content

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "给我 3 条学习 API 的建议"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)

4.4 `response_format={"type":"json_object"}`：JSON 结构化输出

作用：让模型按 JSON 返回，便于程序处理
常用搭配：json.loads(...)
注意：仍要做 JSON 解析异常兜底

import json

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是学习规划助手，只输出 JSON"},
        {"role": "user", "content": "给我 3 天 Python+OpenAI 学习计划"},
    ],
    response_format={"type": "json_object"},
    temperature=0.2,
)
data = json.loads(resp.choices[0].message.content or "{}")
print(data)

4.5 `tools` / `tool_choice`：Function Calling

作用：让模型决定是否调用你定义的函数
核心流程：模型返回 tool_calls -> 代码执行函数 -> 把工具结果回传模型

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询城市天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]

# 1) 入参（给模型）
messages = [
    {"role": "system", "content": "你是天气助理，需要时调用工具。"},
    {"role": "user", "content": "北京今天天气如何？顺便给穿衣建议。"},
]

first = client.chat.completions.create(
    model="gpt-4o-mini",   # 模型入参
    messages=messages,     # 对话入参
    tools=tools,           # 工具定义入参
    tool_choice="auto",    # 让模型自己决定是否调用
)

# 2) 出参（模型先返回 tool_calls）
msg = first.choices[0].message
tool_calls = msg.tool_calls or []

# 3) 你的代码执行工具，并把结果回传给模型
messages.append(msg.model_dump(exclude_none=True))
for tc in tool_calls:
    args = json.loads(tc.function.arguments or "{}")
    city = args.get("city", "beijing")

    # 这里模拟真实函数返回
    tool_result = {"city": city, "temp_c": 21, "condition": "sunny"}

    messages.append(
        {
            "role": "tool",
            "tool_call_id": tc.id,
            "content": json.dumps(tool_result, ensure_ascii=False),
        }
    )

second = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,   # 回传了 tool 结果的消息数组
)

# 4) 最终出参（可直接展示给用户）
final_text = second.choices[0].message.content or ""
print(final_text)

关键入参/出参对应关系：

入参：model、messages、tools、tool_choice
第一轮出参：first.choices[0].message.tool_calls
工具回传消息：{"role":"tool","tool_call_id":"...","content":"..."}
最终出参：second.choices[0].message.content

4.6 `client.embeddings.create(...)`：向量生成

作用：把文本转向量
适用：RAG、检索、相似度、去重
读取：resp.data[0].embedding

emb = client.embeddings.create(
    model="text-embedding-3-small",
    input="OpenAI Python SDK 基本用法",
)
vec = emb.data[0].embedding
print(len(vec), vec[:8])