面向 Python 开发者的 OpenAI SDK 快速参考。 从第一次调用模型，到 Streaming、Structured Output、Function Calling、Web Search、File Search、Embedding 与多模态开发。

1. 安装

代码片段Bash
pip install -U openai

查看版本：

代码片段Bash
pip show openai

SDK 要求 Python 3.10+。

推荐把 API Key 放入环境变量。

Linux / macOS：

代码片段Bash
export OPENAI_API_KEY="sk-..."

Windows PowerShell：

代码片段powershell
$env:OPENAI_API_KEY="sk-..."

不建议直接写在代码中：

代码片段Python
client = OpenAI(api_key="sk-xxxx")

尤其不要把 API Key 提交到 Git。

2. 最重要的两个类

整个 SDK 首先记住：

代码片段Python
from openai import OpenAI, AsyncOpenAI

OpenAI

同步客户端：

代码片段Python
from openai import OpenAI
 
client = OpenAI()

适合：

  • 普通脚本
  • CLI
  • Notebook
  • 简单后端
  • 学习示例

AsyncOpenAI

异步客户端：

代码片段Python
from openai import AsyncOpenAI
 
client = AsyncOpenAI()

调用时：

代码片段Python
response = await client.responses.create(...)

适合：

  • FastAPI
  • 高并发服务
  • Agent 服务
  • Web 后端
  • 同时调用多个模型/API

同步和异步客户端的主要 API 基本一致。

3. SDK 的整体结构

可以把 client 理解成 OpenAI API 的入口：

代码片段Text
OpenAI
│
├── responses
├── chat.completions
├── embeddings
├── files
├── vector_stores
├── images
├── audio
│   ├── transcriptions
│   ├── translations
│   └── speech
├── moderations
├── models
├── batches
├── fine_tuning
├── uploads
├── conversations
├── evals
└── realtime / live ...

其中日常开发最重要的是：

代码片段Text
responses

新项目优先从：

代码片段Python
client.responses.create()

开始。

可以先形成一个最简单的认识：

代码片段Text
OpenAI()
   ↓
client.responses
   ↓
create()
   ↓
Response

4. 第一次调用模型

最简单的完整程序：

代码片段Python
from openai import OpenAI
 
client = OpenAI()
 
response = client.responses.create(
    model="gpt-5.6",
    input="用三句话解释什么是 Agent。"
)
 
print(response.output_text)

先记住这个模板：

代码片段Python
response = client.responses.create(
    model="...",
    input="..."
)
 
print(response.output_text)

这是整个 SDK 最重要的一段代码。

5. Response 对象

responses.create() 返回的是：

代码片段Python
Response

而不是普通字符串。

例如：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="什么是 RAG？"
)

常用字段：

代码片段Python
response.id
response.model
response.output
response.output_text
response.usage
response.status
response._request_id

最常用的是：

代码片段Python
response.output_text

output 和 output_text 的区别

不要默认：

代码片段Python
response.output[0]

一定就是最终文字。

output 中还可能出现：

代码片段Text
message
function_call
web_search_call
file_search_call
reasoning
...

例如一个 Agent 请求可能是：

代码片段Text
Response
│
├── reasoning
├── function_call
└── message

因此，单纯想取得最终文本时，优先：

代码片段Python
response.output_text

6. input 的两种常见写法

简单字符串

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="解释一下 Transformer。"
)

适合简单任务。

Message 形式

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input=[
        {
            "role": "user",
            "content": "解释一下 Transformer。"
        }
    ]
)

复杂应用通常会逐渐使用第二种形式。

它的结构更接近：

代码片段Text
input
└── message
    ├── role
    └── content

7. instructions

需要设置模型行为时，可以使用：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    instructions="""
你是一名资深 Python 工程师。
回答必须简洁，并提供代码示例。
""",
    input="解释 Python decorator。"
)
 
print(response.output_text)

可以简单理解为：

代码片段Text
instructions
    ↓
模型应该如何工作

input
    ↓
这一次具体要完成什么

典型结构：

代码片段Python
client.responses.create(
    model=MODEL,
    instructions=SYSTEM_PROMPT,
    input=user_input,
)

例如：

代码片段Python
SYSTEM_PROMPT = """
你是一名代码审查助手。
 
要求：
1. 优先指出实际 Bug
2. 不讨论无关风格问题
3. 提供修改建议
"""

然后：

代码片段Python
response = client.responses.create(
    model=MODEL,
    instructions=SYSTEM_PROMPT,
    input=code,
)

8. 常用参数

一个典型请求：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="分析这段代码。",
    max_output_tokens=2000,
)

常见参数包括：

代码片段Text
model
input
instructions
max_output_tokens
reasoning
tools
tool_choice
stream
store
previous_response_id
conversation
metadata
include
background

新手首先掌握：

代码片段Text
model
input
instructions
max_output_tokens
tools
stream

就足够覆盖大量场景。

9. Reasoning Effort

支持推理等级的模型可以配置：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    reasoning={
        "effort": "high"
    },
    input="分析这个复杂的软件架构问题。"
)

不同模型可能支持不同的 reasoning effort。

常见概念包括：

代码片段Text
none
low
medium
high
xhigh
max

具体支持范围取决于模型。

什么时候提高推理等级

简单提取、改写、分类：

代码片段Python
reasoning={"effort": "low"}

复杂架构分析、研究、规划：

代码片段Python
reasoning={"effort": "high"}

不要简单认为：

代码片段Text
reasoning 越高越好

通常还需要考虑：

代码片段Text
质量
延迟
成本

10. 模型怎么选

不要在整个项目里到处硬编码：

代码片段Python
model="..."

推荐集中配置：

代码片段Python
MODEL = "gpt-5.6"

然后：

代码片段Python
response = client.responses.create(
    model=MODEL,
    input="..."
)

基本选择思路：

代码片段Text
复杂推理任务
    ↓
高能力模型

大量普通任务
    ↓
均衡模型

大规模简单处理
    ↓
低延迟 / 低成本模型

图片生成
    ↓
Image 模型

Embedding
    ↓
Embedding 模型

实时语音
    ↓
Realtime / Live 模型

生产项目最好让模型 ID：

代码片段Text
配置化

而不是写死在业务逻辑中。

例如：

代码片段Python
import os
 
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.6")

11. Streaming 流式输出

普通调用：

代码片段Text
请求
 ↓
等待模型完整生成
 ↓
一次性返回

Streaming：

代码片段Text
请求
 ↓
文本片段
 ↓
文本片段
 ↓
文本片段
 ↓
完成

基本写法：

代码片段Python
from openai import OpenAI
 
client = OpenAI()
 
stream = client.responses.create(
    model="gpt-5.6",
    input="写一篇介绍 MCP 的短文。",
    stream=True,
)
 
for event in stream:
    print(event)

实际应用通常只处理文本增量事件：

代码片段Python
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Streaming 非常适合：

代码片段Text
聊天界面
Agent
长文本生成
代码生成
网页应用

用户不用等模型把所有文字生成完成后才看到结果。

12. Async Streaming

异步版本：

代码片段Python
from openai import AsyncOpenAI
 
client = AsyncOpenAI()
 
async def main():
    stream = await client.responses.create(
        model="gpt-5.6",
        input="介绍一下 RAG。",
        stream=True,
    )
 
    async for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

同步：

代码片段Python
for event in stream:

异步：

代码片段Python
async for event in stream:

这是两种客户端的重要区别之一。

13. Structured Output

很多应用并不想得到一段自然语言：

代码片段Text
这家公司的名称是 OpenAI，它属于 AI 行业……

而是希望得到：

代码片段JSON
{
  "name": "OpenAI",
  "industry": "AI"
}

这时应该使用 Structured Output。

Python SDK 与 Pydantic 的结合非常方便。

先定义模型：

代码片段Python
from pydantic import BaseModel
 
 
class Person(BaseModel):
    name: str
    age: int
    occupation: str

然后：

代码片段Python
response = client.responses.parse(
    model="gpt-5.6",
    input="张三今年28岁，是一名Python开发工程师。",
    text_format=Person,
)
 
person = response.output_parsed
 
print(person.name)
print(person.age)
print(person.occupation)

此时得到的：

代码片段Python
person

本身就是：

代码片段Python
Person

不需要自己：

代码片段Python
json.loads(...)

14. 为什么 Structured Output 很重要

一种常见但不够稳定的方式：

代码片段Python
response = client.responses.create(
    model=MODEL,
    input="""
分析下面的信息。
 
请只输出 JSON。
"""
)
 
data = json.loads(response.output_text)

模型可能输出：

代码片段Text
当然可以，结果如下：

{
    ...
}

于是 JSON 解析失败。

更好的方式：

代码片段Python
response = client.responses.parse(
    model=MODEL,
    input=input,
    text_format=MySchema,
)

Structured Output 特别适合：

代码片段Text
信息提取
分类
REST API
数据库写入
Agent State
工作流节点输出
表单生成
数据分析

一个实际例子

代码片段Python
from pydantic import BaseModel
 
 
class ArticleAnalysis(BaseModel):
    title: str
    category: str
    keywords: list[str]
    score: int

调用：

代码片段Python
result = client.responses.parse(
    model=MODEL,
    input=article,
    text_format=ArticleAnalysis,
)
 
analysis = result.output_parsed

然后业务代码可以直接：

代码片段Python
save_to_database(
    title=analysis.title,
    category=analysis.category,
    score=analysis.score,
)

15. Function Calling

这是开发 Agent 时最重要的能力之一。

模型本身不会真正：

代码片段Text
查数据库
发邮件
查询订单
获取天气
操作 GitHub
调用内部 API

你可以把自己的函数提供给模型。

整体流程：

代码片段Text
User
 ↓
LLM
 ↓
判断需要调用 get_weather
 ↓
你的 Python 程序
 ↓
执行 get_weather()
 ↓
返回执行结果
 ↓
LLM
 ↓
生成最终回答

最重要的一点：

模型负责决定调用什么工具，你的程序负责真正执行工具。

16. 定义一个 Function Tool

例如：

代码片段Python
tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "获取指定城市当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称"
                }
            },
            "required": ["city"],
            "additionalProperties": False
        },
        "strict": True,
    }
]

调用：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="北京今天天气怎么样？",
    tools=tools,
)

模型可能不直接回答文字，而是返回：

代码片段Text
function_call

其中包含：

代码片段Text
调用哪个函数
参数是什么
call_id 是什么

17. 处理 Function Call

可以遍历：

代码片段Python
import json
 
for item in response.output:
    if item.type == "function_call":
        print(item.name)
        print(item.arguments)
        print(item.call_id)

例如：

代码片段Text
name:
get_weather

arguments:
{"city":"北京"}

解析参数：

代码片段Python
args = json.loads(item.arguments)

执行 Python 函数：

代码片段Python
result = get_weather(**args)

例如：

代码片段Python
def get_weather(city: str) -> dict:
    return {
        "city": city,
        "temperature": 26,
        "condition": "sunny",
    }

18. 把 Tool Result 返回给模型

执行：

代码片段Python
result = get_weather("北京")

之后，还需要把结果交回模型。

代码片段Python
response2 = client.responses.create(
    model="gpt-5.6",
    previous_response_id=response.id,
    input=[
        {
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": json.dumps(result),
        }
    ],
    tools=tools,
)

最后：

代码片段Python
print(response2.output_text)

其中：

代码片段Text
call_id

用于把：

代码片段Text
Function Call

与：

代码片段Text
Function Call Output

对应起来。

整体关系：

代码片段Text
function_call
      │
      │ call_id
      ↓
执行 Python 函数
      │
      ↓
function_call_output
      │
      │ same call_id
      ↓
Model

19. 完整 Function Calling 流程

可以把整个过程记成：

代码片段Text
1. 定义 tools

2. responses.create()

3. 检查 response.output

4. 找到 function_call

5. 解析 arguments

6. 执行 Python function

7. 构造 function_call_output

8. 再次 responses.create()

9. 得到最终回答

这已经是一个最基础的 Agent Loop。

20. 多个 Tools

真实 Agent 通常不会只有一个 Tool。

例如：

代码片段Python
tools = [
    get_weather_tool,
    search_order_tool,
    query_customer_tool,
    send_email_tool,
]

模型可以根据任务决定：

代码片段Text
调用哪个工具
是否需要调用工具
参数是什么
调用一次还是多次
是否需要多个工具配合

例如：

代码片段Text
用户：
帮我检查订单 123，如果已经发货，把物流信息发给客户。

              ↓

           Model
              ↓
       query_order()
              ↓
     get_shipping_info()
              ↓
        send_email()
              ↓
          最终回答

这就是：

代码片段Text
LLM + Tools

构成 Agent 的基础。

21. tool_choice

默认情况下，可以让模型自行决定是否调用工具。

概念上：

代码片段Python
tool_choice="auto"

常见模式包括：

代码片段Text
auto
required
none
指定某个 Tool

auto

模型自己决定：

代码片段Text
是否需要工具

required

要求：

代码片段Text
必须调用工具

none

禁止调用工具。

实际 Agent 系统通常以：

代码片段Text
auto

为主。

Responses API 可以使用 Web Search Tool：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    tools=[
        {
            "type": "web_search"
        }
    ],
    input="最近 AI Agent 领域有什么重要进展？"
)
 
print(response.output_text)

这时不需要自己实现：

代码片段Python
search_google()

模型可以根据请求搜索网络。

可以把它理解为：

代码片段Text
User
 ↓
Model
 ↓
Web Search
 ↓
Internet
 ↓
Search Result
 ↓
Model
 ↓
Answer

适合：

代码片段Text
新闻
最新资料
研究
当前产品信息
事实核查
市场信息

如果希望模型搜索自己的：

代码片段Text
PDF
产品文档
企业知识库
技术资料
规章制度
内部文件

可以使用：

代码片段Text
Files
+
Vector Store
+
File Search

基本流程：

代码片段Text
文件
 ↓
Files API
 ↓
Vector Store
 ↓
File Search Tool
 ↓
LLM

这是一种 OpenAI 托管的知识库检索方案。

24. 上传文件

代码片段Python
file = client.files.create(
    file=open("manual.pdf", "rb"),
    purpose="user_data",
)
 
print(file.id)

常见字段：

代码片段Python
file.id
file.filename
file.bytes
file.status

文件上传之后，可以用于不同功能。

例如：

代码片段Text
File Search
Batch
Fine-tuning
Evals

具体需要使用什么 purpose，应根据对应 API 的要求设置。

25. 创建 Vector Store

代码片段Python
vector_store = client.vector_stores.create(
    name="Product Docs"
)
 
print(vector_store.id)

然后加入文件：

代码片段Python
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file.id,
)

处理文件索引时，还可以使用辅助方法，例如：

代码片段Text
create_and_poll()
upload()
upload_and_poll()
poll()

如果希望：

代码片段Text
上传
+
等待索引完成

通常使用对应的 *_and_poll() 方法更加方便。

26. File Search Tool

知识库准备完成后：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="这个产品支持哪些认证方式？",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": [
                vector_store.id
            ]
        }
    ]
)
 
print(response.output_text)

完整流程：

代码片段Text
User
 ↓
Model
 ↓
File Search
 ↓
Vector Store
 ↓
相关文档
 ↓
Model
 ↓
Answer

这已经可以构成一个非常基础的 RAG 系统。

27. Embeddings

Embedding 会把文本转换成向量。

例如：

代码片段Text
"Python 是一种编程语言"

↓

[0.012, -0.31, 0.82, ...]

调用：

代码片段Python
response = client.embeddings.create(
    model="text-embedding-...",
    input="什么是人工智能？",
)
 
vector = response.data[0].embedding
 
print(len(vector))

Embedding 常用于：

代码片段Text
语义搜索
RAG
相似内容推荐
聚类
去重
文本匹配
异常检测

入口：

代码片段Python
client.embeddings.create(...)

28. 多条 Embedding

可以一次传多条文本：

代码片段Python
response = client.embeddings.create(
    model="text-embedding-...",
    input=[
        "Python 是一种编程语言",
        "Java 是一种编程语言",
        "今天天气很好",
    ],
)

然后：

代码片段Python
for item in response.data:
    print(item.embedding)

不要在大量数据处理中：

代码片段Text
一条文本
调用一次 API

更合理的是进行：

代码片段Text
批量 Embedding

29. File Search 和 Embedding 的区别

这两个概念很容易混淆。

Embedding

你自己得到：

代码片段Text
向量

例如：

代码片段Text
文本
 ↓
Embedding Model
 ↓
Vector

后续：

代码片段Text
存在哪里
怎么搜索
如何计算相似度
怎么切 Chunk

都可以自己控制。

OpenAI 提供更高层的：

代码片段Text
托管检索能力

你主要提供：

代码片段Text
文件
Vector Store

然后模型通过 File Search Tool 使用。

所以：

代码片段Text
Embedding
    ↓
底层能力

File Search
    ↓
更高层的托管检索方案

30. Vision：让模型看图片

Responses API 可以同时传文字和图片：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "分析这张图片。"
                },
                {
                    "type": "input_image",
                    "image_url": "https://example.com/image.jpg"
                }
            ]
        }
    ],
)
 
print(response.output_text)

因此 Responses API 本身就是多模态入口。

可以处理类似：

代码片段Text
图片理解
截图分析
图表解释
UI 检查
照片问答
文档截图分析

31. 本地图片

本地图片可以转成 Base64。

代码片段Python
import base64
 
with open("image.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

构造 Data URL：

代码片段Python
image_url = f"data:image/png;base64,{image_data}"

然后：

代码片段Python
{
    "type": "input_image",
    "image_url": image_url,
}

完整形式：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "这张图里有什么？"
                },
                {
                    "type": "input_image",
                    "image_url": image_url
                }
            ]
        }
    ],
)

32. Images API

图片生成主要通过：

代码片段Python
client.images

常见能力包括：

代码片段Text
生成图片
编辑图片
图片变体

主要方法：

代码片段Python
client.images.generate()
client.images.edit()
client.images.create_variation()

例如：

代码片段Python
result = client.images.generate(
    model="gpt-image-...",
    prompt="一座未来城市，清晨，极简科技风",
)

注意区分：

代码片段Text
理解图片
    ↓
Responses API

生成 / 编辑图片
    ↓
Images API

33. Audio API

入口：

代码片段Python
client.audio

主要分为：

代码片段Text
audio.transcriptions
audio.translations
audio.speech

可以简单理解为：

代码片段Text
Audio
├── Speech → Text
├── Translation
└── Text → Speech

34. Speech to Text

音频转文字：

代码片段Python
with open("meeting.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="...",
        file=audio_file,
    )
 
print(transcription.text)

用途：

代码片段Text
会议转录
语音助手
视频字幕
客服录音
Podcast 转写

35. Text to Speech

文字转语音：

代码片段Python
response = client.audio.speech.create(
    model="...",
    voice="...",
    input="你好，欢迎使用我们的应用。",
)

记住入口：

代码片段Python
client.audio.speech.create()

典型应用：

代码片段Text
AI 语音助手
有声内容
辅助阅读
实时语音应用
客服系统

36. Moderation

用于检测内容：

代码片段Python
result = client.moderations.create(
    model="omni-moderation-latest",
    input="..."
)

例如：

代码片段Python
result.results[0].flagged

可以用于：

代码片段Text
UGC
聊天系统
评论系统
AI 产品输入检查
模型输出检查

可以把流程理解为：

代码片段Text
User Input
 ↓
Moderation
 ↓
允许 / 阻止 / 进一步处理
 ↓
Model

37. 多轮对话：previous_response_id

Responses API 可以通过：

代码片段Text
previous_response_id

继续之前的响应。

第一轮：

代码片段Python
response1 = client.responses.create(
    model="gpt-5.6",
    input="我的名字叫 Alex。"
)

第二轮：

代码片段Python
response2 = client.responses.create(
    model="gpt-5.6",
    previous_response_id=response1.id,
    input="我的名字是什么？"
)
 
print(response2.output_text)

关系：

代码片段Text
response1
    ↓
response2
    ↓
response3

它非常适合简单的连续对话。

38. previous_response_id 的本质

它并不代表：

代码片段Text
模型永久记住用户

而是在告诉 API：

代码片段Text
这次请求继续之前那个 Response。

即：

代码片段Python
previous_response_id=response.id

可以理解为：

代码片段Text
conversation lineage

它减少了手动管理历史消息的工作。

但上下文依然会影响：

代码片段Text
Token 使用
上下文长度
调用成本

39. Conversation

复杂场景可以使用 Conversation。

概念上：

代码片段Text
Conversation
│
├── User Message
├── Assistant Message
├── Tool Call
├── Tool Result
├── User Message
└── Assistant Message

适合：

代码片段Text
长期聊天
Agent Session
客服 Session
多轮工作流

可以把几个概念这样区分：

代码片段Text
单次任务
    ↓
Response

连续 Response
    ↓
previous_response_id

长期会话状态
    ↓
Conversation

40. Structured Output 和 Function Calling 的区别

这两个概念不要混淆。

Structured Output

解决：

代码片段Text
模型最终回答应该是什么结构？

例如：

代码片段Python
class Article(BaseModel):
    title: str
    summary: str

结果：

代码片段JSON
{
  "title": "...",
  "summary": "..."
}

Function Calling

解决：

代码片段Text
模型应该调用哪个外部能力？

例如：

代码片段Text
search_database()
send_email()
get_weather()

对比：

能力主要用途
Structured Output控制模型输出结构
Function Calling调用业务函数或外部系统
Web Search查询互联网
File Search查询知识库

41. Tool 与 Structured Output 可以一起使用

真实应用经常是：

代码片段Text
User
 ↓
Model
 ↓
Tool
 ↓
获取数据
 ↓
Model
 ↓
Structured Output
 ↓
Python Object

例如股票分析：

代码片段Text
User
 ↓
查询股票
 ↓
获取行情
 ↓
查询新闻
 ↓
模型分析
 ↓
StockAnalysis

其中：

代码片段Text
查询行情 / 新闻
    ↓
Tools

StockAnalysis
    ↓
Structured Output

这是现代 Agent 后端非常常见的组合。

42. AsyncOpenAI

Web 服务通常应该熟悉：

代码片段Python
from openai import AsyncOpenAI
 
client = AsyncOpenAI()

完整示例：

代码片段Python
import asyncio
from openai import AsyncOpenAI
 
client = AsyncOpenAI()
 
 
async def main():
    response = await client.responses.create(
        model="gpt-5.6",
        input="解释 async/await。"
    )
 
    print(response.output_text)
 
 
asyncio.run(main())

核心区别：

同步：

代码片段Python
response = client.responses.create(...)

异步：

代码片段Python
response = await client.responses.create(...)

43. 并发调用

Async 最大价值之一是并发。

例如：

代码片段Python
import asyncio
 
responses = await asyncio.gather(
    client.responses.create(
        model="gpt-5.6",
        input="分析方案 A"
    ),
    client.responses.create(
        model="gpt-5.6",
        input="分析方案 B"
    ),
    client.responses.create(
        model="gpt-5.6",
        input="分析方案 C"
    ),
)

适合：

代码片段Text
并行 Agent
批量分析
多文档摘要
多个候选方案比较
同时查询多个独立任务

例如 Multi-Agent：

代码片段Text
                ┌→ Research Agent
User → Router ──┼→ Code Agent
                └→ Review Agent

三个 Agent 可以在适合的情况下并发运行。

44. Pydantic Response

SDK 返回的数据通常不是普通 dict，而是带类型的模型。

例如：

代码片段Python
response = client.responses.create(...)

可以访问：

代码片段Python
response.output
response.output_text
response.id

也可以转换：

代码片段Python
response.to_dict()

或：

代码片段Python
response.to_json()

因此通常不要写：

代码片段Python
response["output"]

而是：

代码片段Python
response.output

这也意味着 IDE 可以获得比较好的：

代码片段Text
类型检查
自动补全
字段提示

45. Files

Files 的常用操作：

代码片段Python
client.files.create(...)
client.files.retrieve(file_id)
client.files.list()
client.files.delete(file_id)
client.files.content(file_id)

结构：

代码片段Text
Files
│
├── create
├── retrieve
├── list
├── delete
└── content

例如列出文件：

代码片段Python
files = client.files.list()
 
for file in files.data:
    print(file.id, file.filename)

46. Vector Stores

常见方法：

代码片段Python
client.vector_stores.create()
client.vector_stores.retrieve()
client.vector_stores.update()
client.vector_stores.list()
client.vector_stores.delete()
client.vector_stores.search()

子资源：

代码片段Text
vector_stores.files
vector_stores.file_batches

基本结构：

代码片段Text
Vector Store
│
├── Files
├── File Batches
└── Search

它主要服务于：

代码片段Text
知识库
File Search
语义检索

47. Models API

查看当前账户能够访问的模型：

代码片段Python
models = client.models.list()
 
for model in models:
    print(model.id)

查询模型：

代码片段Python
model = client.models.retrieve("...")

常见方法：

代码片段Text
models.list()
models.retrieve()
models.delete()

其中删除操作并不是：

代码片段Text
删除 OpenAI 官方模型

而是针对支持删除的自定义模型资源。

48. Batch API

大量非实时任务可以使用 Batch API。

例如：

代码片段Text
10 万条商品分类
大量文本审核
批量 Embedding
离线数据生成
数据集处理

基本流程：

代码片段Text
JSONL
 ↓
Files API
 ↓
Batch
 ↓
后台批量处理
 ↓
Output File

主要方法：

代码片段Python
client.batches.create()
client.batches.retrieve()
client.batches.list()
client.batches.cancel()

Batch 适合：

代码片段Text
量大
不要求立即响应
适合离线处理

而不适合：

代码片段Text
实时聊天
实时 Agent
用户正在等待的请求

49. Fine-tuning

入口：

代码片段Python
client.fine_tuning.jobs

常用操作：

代码片段Python
client.fine_tuning.jobs.create(...)
client.fine_tuning.jobs.retrieve(...)
client.fine_tuning.jobs.list(...)
client.fine_tuning.jobs.cancel(...)

还可能包括：

代码片段Text
pause
resume
checkpoints
events

Fine-tuning 不等于知识库

如果需求是：

代码片段Text
让模型知道我的产品文档

一般先考虑：

代码片段Text
RAG / File Search

而不是 Fine-tuning。

Fine-tuning 更偏向：

代码片段Text
行为模式
输出风格
固定任务
格式稳定性
领域任务适配

可以简单记成：

代码片段Text
知识
    ↓
RAG / File Search

行为
    ↓
Fine-tuning

50. 错误处理

不要只写：

代码片段Python
except Exception:
    ...

至少应该认识：

代码片段Python
import openai

然后：

代码片段Python
try:
    response = client.responses.create(
        model="gpt-5.6",
        input="Hello"
    )
 
except openai.RateLimitError:
    print("触发 Rate Limit")
 
except openai.APIConnectionError:
    print("无法连接 OpenAI")
 
except openai.APIStatusError as e:
    print(e.status_code)
    print(e.response)

常见异常：

代码片段Text
APIError
├── APIConnectionError
├── APIStatusError
│   ├── BadRequestError
│   ├── AuthenticationError
│   ├── PermissionDeniedError
│   ├── NotFoundError
│   ├── UnprocessableEntityError
│   ├── RateLimitError
│   └── InternalServerError
└── APITimeoutError

51. 常见 HTTP 错误

可以大概这样理解：

代码片段Text
400
    ↓
Bad Request

401
    ↓
API Key / Authentication

403
    ↓
Permission

404
    ↓
Resource Not Found

429
    ↓
Rate Limit

500+
    ↓
Server Error

生产环境不要把错误简单显示成：

代码片段Text
请求失败

最好至少记录：

代码片段Text
状态码
错误类型
Request ID
模型
业务请求 ID

52. Request ID

生产环境推荐记录：

代码片段Python
response._request_id

例如：

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="hello"
)
 
print(response._request_id)

失败时：

代码片段Python
except openai.APIStatusError as exc:
    print(exc.request_id)

Request ID 对排查 API 问题很重要。

日志中可以记录：

代码片段Text
request_id
model
latency
status
token_usage
business_request_id

53. Timeout

全局设置：

代码片段Python
client = OpenAI(
    timeout=30.0
)

或者只设置某次请求：

代码片段Python
client.with_options(
    timeout=10.0
).responses.create(
    model="gpt-5.6",
    input="..."
)

超时异常：

代码片段Python
openai.APITimeoutError

生产系统一定要考虑：

代码片段Text
网络慢
模型生成时间长
上游请求取消
用户已经离开页面

54. Retry

全局：

代码片段Python
client = OpenAI(
    max_retries=5
)

单次调用：

代码片段Python
client.with_options(
    max_retries=5
).responses.create(
    model="gpt-5.6",
    input="..."
)

关闭重试：

代码片段Python
max_retries=0

不过需要注意：

代码片段Text
不是所有业务操作都应该盲目重试。

例如 Tool 调用了：

代码片段Text
支付
发送邮件
创建订单

就要额外考虑：

代码片段Text
幂等性

55. Chat Completions

还会经常看到：

代码片段Python
client.chat.completions.create(...)

例如：

代码片段Python
completion = client.chat.completions.create(
    model="gpt-5.6",
    messages=[
        {
            "role": "user",
            "content": "Hello"
        }
    ]
)
 
print(
    completion.choices[0].message.content
)

它仍然存在，也有大量项目正在使用。

但是对于新项目，优先掌握：

代码片段Python
client.responses.create()

56. Responses 和 Chat Completions

可以这样理解：

代码片段Text
Chat Completions
        ↓
经典聊天调用方式

Responses
        ↓
更统一的现代模型调用入口

Responses 更自然地整合：

代码片段Text
Text
Vision
Tools
Function Calling
Web Search
File Search
Structured Output
Reasoning
Conversation
Agent 工作流

因此：

代码片段Text
新项目
    ↓
优先 Responses

维护旧项目
    ↓
需要认识 Chat Completions

57. 旧的 Completions API

还可能看到：

代码片段Python
client.completions.create()

或者老教程中的：

代码片段Python
openai.Completion.create(...)

这些属于更早期的调用方式。

新手学习时不需要把精力放在这里。

重点学习：

代码片段Text
Responses API

即可。

看到旧教程时，要能够判断：

代码片段Text
这是不是当前应该继续采用的写法？

58. 推荐项目结构

实际项目中，不建议把 OpenAI 调用散落在所有业务代码中。

可以使用：

代码片段Text
app/
├── main.py
├── config.py
├── ai/
│   ├── client.py
│   ├── models.py
│   ├── prompts.py
│   ├── schemas.py
│   ├── tools.py
│   └── service.py
└── services/

client.py

代码片段Python
from openai import OpenAI
 
client = OpenAI()

config.py

代码片段Python
MODEL = "gpt-5.6"

prompts.py

代码片段Python
SYSTEM_PROMPT = """
你是一名专业技术助手。
回答准确、清晰、简洁。
"""

service.py

代码片段Python
from .client import client
from .config import MODEL
from .prompts import SYSTEM_PROMPT
 
 
def ask(prompt: str) -> str:
    response = client.responses.create(
        model=MODEL,
        instructions=SYSTEM_PROMPT,
        input=prompt,
    )
 
    return response.output_text

这样比整个项目中反复：

代码片段Python
OpenAI()

更容易维护。

59. 一个最小 Agent

理解 Agent，可以从这个公式开始：

代码片段Text
Agent
=
Model
+
Instructions
+
Tools
+
State
+
Agent Loop

最简单调用：

代码片段Python
response = client.responses.create(
    model=MODEL,
    instructions=AGENT_PROMPT,
    input=user_input,
    tools=TOOLS,
)

接下来判断：

代码片段Text
response.output
       ↓
有没有 function_call？
       ↓
   ┌───┴───┐
   │       │
  有       没有
   │       │
   ↓       ↓
执行 Tool  返回答案
   │
   ↓
Tool Result
   │
   ↓
再次调用 Model

这就是 Agent Loop。

60. Tool Loop 伪代码

最核心的结构可以写成：

代码片段Python
while True:
 
    response = client.responses.create(...)
 
    tool_calls = [
        item
        for item in response.output
        if item.type == "function_call"
    ]
 
    if not tool_calls:
        return response.output_text
 
    results = []
 
    for call in tool_calls:
        result = execute_tool(call)
 
        results.append({
            "type": "function_call_output",
            "call_id": call.call_id,
            "output": result,
        })
 
    # 把 Tool Result 再交给模型

真正实现时还需要考虑：

代码片段Text
上一轮 Response
Tool Schema
多 Tool Call
失败重试
超时
最大循环次数
权限
日志
Tracing

但核心机制就是这一段。

61. 为什么先理解 Tool Loop

理解：

代码片段Text
Model
 ↓
Tool Call
 ↓
Tool Execution
 ↓
Tool Result
 ↓
Model

之后，再学习：

代码片段Text
OpenAI Agents SDK
LangGraph
LangChain
AutoGen
CrewAI

就容易很多。

因为各种 Agent Framework 虽然抽象层不同，但很多核心概念都建立在：

代码片段Text
Model
Tools
State
Loop
Routing

这些基础机制上。

62. OpenAI SDK 和 Agents SDK 不要混淆

OpenAI Python SDK：

代码片段Bash
pip install openai

主要负责：

代码片段Text
模型调用
Responses
Embeddings
Files
Vector Stores
Images
Audio
Batch
Fine-tuning
...

而 Agent Framework / Agents SDK 通常会进一步提供：

代码片段Text
Agent
Runner
Session
Handoff
Tracing
Guardrails
Multi-Agent

建议学习顺序：

代码片段Text
openai SDK
    ↓
Responses API
    ↓
Structured Output
    ↓
Function Calling
    ↓
Tool Loop
    ↓
Agent
    ↓
Agents SDK / LangGraph

这样不会只会“调用框架”，却不知道底层发生了什么。

63. 一个完整 Tool Calling 示例

需求：

用户询问某个城市天气，模型自己判断并调用天气工具。

定义业务函数

代码片段Python
def get_weather(city: str) -> dict:
    return {
        "city": city,
        "temperature": 26,
        "condition": "sunny",
    }

定义 Tool

代码片段Python
weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "查询指定城市当前天气",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string"
            }
        },
        "required": ["city"],
        "additionalProperties": False,
    },
    "strict": True,
}

第一次请求

代码片段Python
response = client.responses.create(
    model="gpt-5.6",
    input="北京天气怎么样？",
    tools=[weather_tool],
)

执行 Tool

代码片段Python
import json
 
tool_outputs = []
 
for item in response.output:
 
    if item.type != "function_call":
        continue
 
    args = json.loads(item.arguments)
 
    if item.name == "get_weather":
        result = get_weather(**args)
 
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(
                result,
                ensure_ascii=False
            ),
        })

把结果交回模型

代码片段Python
final_response = client.responses.create(
    model="gpt-5.6",
    previous_response_id=response.id,
    input=tool_outputs,
    tools=[weather_tool],
)
 
print(final_response.output_text)

完整流程：

代码片段Text
用户
 │
 ▼
Responses API
 │
 ▼
Model
 │
 │ function_call
 ▼
get_weather()
 │
 │ result
 ▼
function_call_output
 │
 ▼
Responses API
 │
 ▼
Model
 │
 ▼
最终回答

掌握这个例子，就基本理解了 Agent Tool Calling 的核心。

64. 主要类和 Resource 速查

类 / Resource用途
OpenAI同步客户端
AsyncOpenAI异步客户端
client.responses主要模型交互 API
ResponseResponses API 返回对象
client.chat.completionsChat Completions
client.embeddings文本向量
client.files文件管理
client.vector_stores向量知识库
client.images图片生成与编辑
client.audio音频相关
client.moderations内容审核
client.models模型查询
client.batches批量异步处理
client.fine_tuningFine-tuning
client.evalsAI 应用评估
client.realtime实时交互
client.webhooksWebhook 相关能力

65. 主要方法速查

代码片段Python
# 模型调用
client.responses.create()
 
# Structured Output
client.responses.parse()
 
# Streaming
client.responses.create(
    stream=True
)
 
# Chat Completions
client.chat.completions.create()
 
# Embedding
client.embeddings.create()
 
# 上传文件
client.files.create()
 
# 获取文件列表
client.files.list()
 
# 创建 Vector Store
client.vector_stores.create()
 
# Vector Search
client.vector_stores.search()
 
# 图片生成
client.images.generate()
 
# 图片编辑
client.images.edit()
 
# Speech to Text
client.audio.transcriptions.create()
 
# Text to Speech
client.audio.speech.create()
 
# Moderation
client.moderations.create()
 
# 模型列表
client.models.list()
 
# Batch
client.batches.create()
 
# Fine-tuning
client.fine_tuning.jobs.create()

66. 一张 SDK 调用关系图

代码片段Text
                         OpenAI()
                            │
             ┌──────────────┼──────────────┐
             │              │              │
         Responses        Files        Embeddings
             │              │              │
        ┌────┼────┐         │              │
        │    │    │         ▼              ▼
      Text Tools Vision  Vector Store     Vector
        │    │    │         │
        │    │    │         ▼
        │    │    └───── File Search
        │    │
        │    ├── Function
        │    ├── Web Search
        │    ├── File Search
        │    └── Other Tools
        │
        ▼
     Response
        │
        ├── output
        ├── output_text
        ├── usage
        └── id

67. 新手最容易犯的错误

继续从旧教程学习 Completions

看到：

代码片段Python
openai.Completion.create(...)

要知道这是旧写法。

新项目优先学习：

代码片段Python
client.responses.create()

把 API Key 写进代码

不要：

代码片段Python
API_KEY = "sk-..."

优先：

代码片段Text
环境变量
Secrets Manager
部署平台 Secret

把 Response 当 dict

不要：

代码片段Python
response["output"]

通常使用：

代码片段Python
response.output

为 JSON 输出只写 Prompt

不要只依赖：

代码片段Text
请只输出 JSON

优先考虑：

代码片段Python
client.responses.parse()

配合：

代码片段Text
Pydantic

认为 Function Calling 会自动执行函数

模型只会：

代码片段Text
请求调用 Tool

真正执行的是：

代码片段Text
你的程序

把 File Search 和 Embedding 混为一谈

Embedding：

代码片段Text
生成向量

File Search：

代码片段Text
托管的文件检索 Tool

手动维护所有聊天历史

简单多轮场景可以考虑：

代码片段Text
previous_response_id

复杂会话可以进一步使用：

代码片段Text
Conversation

所有任务都用最高推理等级

要同时考虑：

代码片段Text
效果
成本
延迟

68. 推荐学习路线

第一阶段：基础调用

学习：

代码片段Text
OpenAI
↓
responses.create()
↓
response.output_text

目标：

可以完成最基础的模型调用。

第二阶段：控制模型

学习：

代码片段Text
instructions
input
model
reasoning
max_output_tokens

目标：

可以控制模型的任务和行为。

第三阶段：真实应用体验

学习：

代码片段Text
Streaming
AsyncOpenAI

目标：

可以开发聊天界面和 Web 服务。

第四阶段：可靠数据输出

学习：

代码片段Text
Pydantic
responses.parse()
Structured Output

目标：

可以让模型输出业务代码能够直接使用的数据。

第五阶段：Agent 基础

学习：

代码片段Text
Function Calling
Tool Result
Tool Loop

目标：

可以自己实现最基础的 Agent。

第六阶段：外部知识

学习：

代码片段Text
Web Search
File Search
Vector Store
Embedding

目标：

可以让模型获取外部信息和私有知识。

第七阶段：多模态

学习：

代码片段Text
Vision
Audio
Images

目标：

可以处理文字之外的数据。

第八阶段：生产能力

学习：

代码片段Text
Conversation
Batch
Fine-tuning
Evals
Realtime

目标：

可以构建更完整的生产级 AI 系统。

69. 新手最需要记住的代码

如果只能记住一个调用模板：

代码片段Python
from openai import OpenAI
 
client = OpenAI()
 
response = client.responses.create(
    model="gpt-5.6",
    instructions="你是一名专业助手。",
    input="你好",
)
 
print(response.output_text)

然后再记住几个核心能力：

代码片段Text
Structured Output
    ↓
responses.parse()

Streaming
    ↓
stream=True

Function Calling
    ↓
tools=[...]

多轮对话
    ↓
previous_response_id

知识库
    ↓
File Search + Vector Store

语义向量
    ↓
embeddings.create()

异步调用
    ↓
AsyncOpenAI

70. 最终心智模型

可以把 OpenAI Python SDK 记成：

代码片段Text
OpenAI
  │
  ▼
Responses
  │
  ▼
Model
  ├── Text
  ├── Vision
  ├── Reasoning
  ├── Structured Output
  │
  └── Tools
       ├── Function Calling
       ├── Web Search
       ├── File Search
       └── Other Tools
  │
  ▼
Response

而一个现代 AI 应用通常可以抽象成：

代码片段Text
Input
  │
  ▼
Model
  │
  ├──────► Reasoning
  │
  ├──────► Tools
  │
  └──────► Knowledge
  │
  ▼
Structured Result
  │
  ▼
Application

如果进一步发展为 Agent：

代码片段Text
                 ┌──────────────┐
                 │     User     │
                 └──────┬───────┘
                        │
                        ▼
                 ┌──────────────┐
                 │    Model     │
                 └──────┬───────┘
                        │
                  判断下一步
                        │
             ┌──────────┴──────────┐
             │                     │
             ▼                     ▼
       ┌───────────┐         ┌───────────┐
       │   Tools   │         │  Answer   │
       └─────┬─────┘         └───────────┘
             │
             ▼
       ┌───────────┐
       │Tool Result│
       └─────┬─────┘
             │
             └──────────────► Model

掌握：

代码片段Text
Responses
Structured Output
Function Calling
Streaming
Async
File Search
Embedding

之后，就已经具备使用 OpenAI Python SDK 开发大多数 LLM 和 Agent 应用所需要的核心基础。