OpenAI Python SDK 实战：responses.create 和 responses.parse 到底怎么选？🤖

最近使用 OpenAI Python SDK，很多同学都会遇到一个问题。

以前我们熟悉的是：

1
client.chat.completions.create(...)

现在文档和示例里，越来越多地方开始出现：

1
client.responses.create(...)

然后又冒出来一个：

1
client.responses.parse(...)

再加上消息里的角色，也不只是 system / user / assistant了。

现在还经常看到：

1
{"role": "developer", "content": "..."}

第一次看到的时候，脑子大概是这样的：

又改接口了？
create 和 parse 到底差在哪？
developer 又是啥？
我项目里到底该用哪个？😭

今天这篇，就从实战角度讲清楚。

不绕弯子。

一、为什么会有 Responses API？

先说结论：

Responses API 是 OpenAI 新一代统一生成接口。

以前的 Chat Completions 更像“聊天接口”。

输入是 messages。
输出是 choices。
取结果要这样写：

1
result = response.choices[0].message.content

能用。

但写多了你会发现：

这套接口比较偏“对话”。

而现在的 AI 应用，不只是聊天。

它还要：

• • 读文本
• • 读图片
• • 读文件
• • 调工具
• • 生成结构化数据
• • 做 Agent 工作流
• • 接企业系统

所以 Responses API 的思路更像：

统一入口。

不管你是普通问答、工具调用、多模态输入，还是结构化输出，都尽量往一个体系里收。

这对工程项目比较友好。

少一点历史包袱。
多一点统一抽象。

（SDK 终于开始像个“系统”了，不再像接口考古现场🐛）

二、先看 responses.create：普通生成就用它

responses.create()可以理解成最常用的生成接口。

适合：

• • 普通问答
• • 文案生成
• • 摘要总结
• • RAG 回答
• • 解释代码
• • 生成自然语言内容

如果你的结果主要是给人看的文本，大概率用它就够了。

示例 1：最简单的 create 用法

下面这段代码，用 Responses API 生成一段解释文本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from openai import OpenAI
import os
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL"))

response = client.responses.create(
    model="gpt-5.5",
    input="用通俗的话解释一下什么是 RAG，不要超过 100 字。"
)

print(response.output_text)

这里最舒服的是：

1
response.output_text

不用再写：

1
response.choices[0].message.content

对新项目来说，代码更干净。

三、messages 里为什么出现 developer？

以前很多人习惯这样写：

1
2
3
4
messages = [
    {"role": "system", "content": "你是一个严谨的技术助手。"},
    {"role": "user", "content": "解释一下 RAG。"}
]

现在在 Responses API 里，你也可以看到：

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你是一个严谨的技术助手，回答要简洁，避免编造。"
    },
    {
        "role": "user",
        "content": "解释一下 RAG。"
    }
]

那 developer是什么？

简单理解：

developer 是开发者给模型的应用级指令。

它通常用来放：

• • 产品规则
• • 输出风格
• • 安全边界
• • 格式要求
• • 业务约束
• • 不希望用户覆盖的系统行为

比如：

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你是一个技术文档助手。回答必须准确、简洁，不要输出未经确认的 API 参数。"
    },
    {
        "role": "user",
        "content": "介绍 responses.create 的用法。"
    }
]

这样写的好处是：

把“应用规则”和“用户问题”分开。

用户问什么，是 user。

你的产品要求模型怎么答，是 developer。

这对工程项目很重要。

四、developer 和 system 怎么理解？

很多人会问：

那 developer和 system到底怎么选？

实战里可以这样理解：

system

更像底层系统级指令。

比如：

• • 模型身份
• • 基础行为约束
• • 高优先级安全规则

developer

更像应用开发者指令。

比如：

• • 当前产品的回复风格
• • 当前业务的输出格式
• • 当前功能的约束条件
• • 当前接口的处理策略

在实际项目里，我更建议：

业务应用规则优先放 developer。

比如你做一个合同审核助手：

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你是合同审核助手。必须只基于用户提供的合同内容分析，不要编造法律条文。"
    },
    {
        "role": "user",
        "content": "帮我看看这段合同有什么风险：..."
    }
]

这样结构更清楚。

不是所有规则都往 system里塞。

system像地基。
developer像产品说明书。
user像用户现场提问。

别混成一锅粥。
不然后期维护会想哭。😭

五、再看 responses.parse：结构化输出就用它

responses.parse()是这篇文章的重点。

一句话：

parse 适合让模型直接返回 Python 对象。

它通常配合 Pydantic 使用。

也就是说，你先定义好数据结构。

然后让模型按这个结构输出。

SDK 会帮你解析成对象。

这对工程项目非常香。

因为很多 AI 应用，最后不是要一段自然语言。

而是要结构化数据。

比如：

• • 从合同里提取风险点
• • 从简历里提取姓名、技能、年限
• • 从发票里提取金额、税号、日期
• • 从用户输入里识别意图
• • 给 Agent 生成下一步动作
• • 给 PPT 生成页面结构

这些场景，如果只用 create()，你通常会让模型输出 JSON。

然后自己：

1
json.loads(...)

再处理异常。

再兜底。

再修格式。

再骂一句：怎么又少了个逗号。🐛

parse()就是为了减少这类痛苦。

六、示例 2：用 parse 提取结构化信息

下面我们写一个小例子。

假设用户输入一句话：

张三是一名后端工程师，主要做 Python 和 FastAPI，有 5 年经验。

我们希望模型直接解析成对象。

先定义 Pydantic 模型：

1
2
3
4
5
6
7
8
9
10
11
from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()


class DeveloperProfile(BaseModel):
    name: str
    role: str
    skills: list[str]
    years_of_experience: int

然后调用 responses.parse()：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
response = client.responses.parse(
    model="gpt-5.2",
    input=[
        {
            "role": "developer",
            "content": "你负责从文本中提取开发者信息。只提取文本中明确出现的信息。"
        },
        {
            "role": "user",
            "content": "张三是一名后端工程师，主要做 Python 和 FastAPI，有 5 年经验。"
        }
    ],
    text_format=DeveloperProfile,
)

profile = response.output_parsed

print(profile.name)
print(profile.role)
print(profile.skills)
print(profile.years_of_experience)

你拿到的不是一段 JSON 字符串。

而是一个 Pydantic 对象。

类似：

1
2
3
4
5
6
DeveloperProfile(
    name="张三",
    role="后端工程师",
    skills=["Python", "FastAPI"],
    years_of_experience=5
)

这就是 parse()的价值。

模型输出，直接进入程序逻辑。

这里我注意，很多人使用的是国内中转API可能会导致程序失败。这是由于第三方中转站的原因。
这里我推荐使用我们自己的 开发喵API中转服务，真实、有效。

七、create 和 parse 的核心区别

直接看表。

记住一句话：

create 输出文本。parse 输出对象。

再说得更工程一点：

create 适合内容生成，parse 适合数据生成。

八、什么时候用 create？

如果你最终要展示给用户看，优先用 create()。

比如：

1. 聊天机器人

用户问：

“帮我解释一下什么是 MCP。”

你输出一段自然语言回答。

用 create()。

2. RAG 问答

用户问：

“根据知识库，解释一下合同审核流程。”

你检索文档后，让模型生成答案。

用 create()。

3. 公众号文案

比如：

“帮我写一个 AI PPT 技术方案的开头。”

这类内容创作，用 create()。

4. 代码解释

比如：

“解释一下这段 Python 代码在做什么。”

输出自然语言解释。

还是 create()。

九、什么时候用 parse？

如果结果要进入程序处理，优先用 parse()。

比如：

1. 合同审核

你希望输出：

• • 风险类型
• • 风险等级
• • 原文位置
• • 修改建议

这明显是结构化数据。

用 parse()。

2. AI 生成 PPT

你希望输出：

• • 页面标题
• • 页面类型
• • 布局结构
• • 要点列表
• • 图表建议
• • 演讲备注

这也适合 parse()。

因为后面程序要根据这些字段生成 PPTX。

3. 用户意图识别

比如用户说：

“帮我查一下昨天的订单。”

你希望模型输出：

1
2
intent = "query_order"
date = "yesterday"

这种场景，用 parse()。

4. 数据入库

比如简历解析、发票解析、表单提取。

只要后面要写数据库。

就不要让模型随便写文本。

直接上 parse()。

十、一个真实项目里的组合用法

实际项目里，create()和 parse()不是二选一。

经常是混用。

比如做一个 AI PPT 生成系统。

第一步：用 create 生成整体讲稿思路

这一步结果给人看，也方便调试。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "developer",
            "content": "你是一个产品方案顾问，擅长把复杂技术讲成清晰的汇报结构。"
        },
        {
            "role": "user",
            "content": "帮我规划一份 8 页的 AI 合同审核产品介绍 PPT 大纲。"
        }
    ],
)

print(response.output_text)

第二步：用 parse 生成页面结构

这一步结果给程序用。

所以要结构化。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
from pydantic import BaseModel


class SlidePage(BaseModel):
    page_number: int
    title: str
    layout: str
    key_points: list[str]
    visual_suggestion: str
    speaker_notes: str


class SlideDeck(BaseModel):
    topic: str
    pages: list[SlidePage]


response = client.responses.parse(
    model="gpt-5.2",
    input=[
        {
            "role": "developer",
            "content": "你是PPT结构设计助手。请把用户主题拆成可生成PPT的页面结构。"
        },
        {
            "role": "user",
            "content": "生成一份 8 页的 AI 合同审核产品介绍 PPT 页面结构。"
        }
    ],
    text_format=SlideDeck,
)

deck = response.output_parsed

for page in deck.pages:
    print(page.page_number, page.title, page.layout)

这就是比较稳的工程路线：

create 负责思考和表达。parse 负责结构和落地。

十一、parse 不是万能的，也有坑

parse()很好用。

但不要神化它。

它也有几个注意点。

1. Schema 不要设计太复杂

字段太多。
嵌套太深。
约束太绕。

模型就更容易出错。

建议从简单结构开始。

先跑通，再扩展。

2. 字段描述要清楚

比如：

1
risk_level: str

这就有点模糊。

更好的做法是用枚举。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from enum import Enum
from pydantic import BaseModel


class RiskLevel(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"


class ContractRisk(BaseModel):
    risk_level: RiskLevel
    risk_type: str
    original_text: str
    suggestion: str

这样更稳。

3. 不要把大段正文塞进结构化字段

PPT 场景尤其常见。

你让模型输出：

1
content: str

它可能塞一大段。

后面生成 PPT 直接爆版。

建议拆成：

1
2
3
title: str
bullet_points: list[str]
speaker_notes: str

页面上放 bullet。
详细内容放备注。

这才像 PPT。

4. 失败要有兜底

结构化输出仍然可能失败。

比如：

• • 输出过长
• • 内容被过滤
• • 字段无法满足
• • 上下文不够
• • 用户输入太乱

所以生产环境里要加：

• • 重试
• • 日志
• • 错误提示
• • 降级方案
• • 人工审核入口

别裸奔上线。
AI 会给你惊喜。也会给你惊吓。🐛

十二、developer role 的实战建议

如果你现在写新项目，我建议这样组织输入。

普通问答

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你是一个技术助手。回答要准确、简洁，不要编造 API。"
    },
    {
        "role": "user",
        "content": "responses.create 怎么用？"
    }
]

结构化抽取

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你负责信息抽取。只输出文本中明确出现的信息，不要推测。"
    },
    {
        "role": "user",
        "content": "李雷，产品经理，擅长需求分析和原型设计。"
    }
]

企业业务场景

1
2
3
4
5
6
7
8
9
10
input=[
    {
        "role": "developer",
        "content": "你是企业合同审核助手。必须保守判断，不确定时标记为 needs_review。"
    },
    {
        "role": "user",
        "content": "请审核以下合同条款：..."
    }
]

核心原则：

developer 放规则，user 放任务。

这样后期维护会舒服很多。

十三、我的选择建议

如果你只是写 Demo：

用 responses.create()。

简单。直观。够用。

如果你做真实项目：

认真考虑 responses.parse()。

尤其是结果要进入数据库、流程引擎、PPT 生成器、合同审核系统的时候。

如果你做 Agent：

两个都要会。

Agent 往往需要：

• • 用 create()做解释、总结、对话
• • 用 parse()做计划、分类、动作参数、状态流转

最后给一个实战判断：

小结 💡

今天这篇，我们讲了三个点：

1. 1. Responses API 是更统一的新接口。
   新项目可以优先考虑它。
2. 2. responses.create 适合生成文本。
   结果主要给人看，就用它。
3. 3. responses.parse 适合结构化输出。
   结果要给程序处理，就用它。

再加一句：

developer role 更适合放应用规则，user role 更适合放用户任务。

最后记住这句话：

给人看的，用 create。给程序用的，用 parse。

这基本能解决 80% 的选择问题。🚀

互动问题

你在项目里用 OpenAI SDK 时，最头疼的是哪一类问题？

是接口迁移？
结构化输出？
还是工具调用和 Agent 工作流？

欢迎留言聊聊。🐱

AI喵智能体
通俗讲AI，带你做实战。
关注我，和AI一起成长。