OpenAI 应用入门一：用 Responses API 做一次可检查的学习辅导

这个三课系列从 OpenAI Cookbook 的真实接口例子出发，依次完成文字辅导、结构化学习卡和课程资料查询。本课对应 Responses 示例中的基础请求、读取结果和上下文管理。它是面向会一点 Python 的读者的中文案例改编，不是全部 Cookbook 的翻译，也不涉及 Codex 宣传或自动开发网站。

适用层级：Python 进阶，需要已有 API 账号与基础脚本操作经验，不是无代码入门。完成后，你应能区分聊天界面和 API，运行或阅读一个完整请求，解释返回对象中的状态与文字，并知道怎样避免把密钥写进前端。本文使用虚构教学内容；接口与字段完成官方资料核对，未调用真实模型，示范答案不是实测记录。

1. 先确定程序负责哪一小段工作

我们的目标很小：给出一道方程，让模型写一段适合初学者的解释，然后由程序或教师检查。这里的应用还不负责登录、班级管理、学生画像或自动评分。把范围缩小后，第一次调用失败时更容易知道该检查哪里。

在网页聊天中，产品替你管理了很多事情。通过 API 开发时，你需要自己决定输入、行为规则、调用时机、结果显示和失败处理。一个 HTTP 请求成功返回，也不等于解释内容已经正确，更不表示可以直接给真实学生发布。

本课采用 Responses API。原 Cookbook 的入门 Notebook 使用过早期示例模型，并通过数组下标取得文本；本课按当前官方文档采用 SDK 的 output_text 汇总文本，模型名由环境变量配置，不把历史型号写死为今天的推荐。

2. 准备环境，但不要把凭据放进示例

你需要 Python 环境、OpenAI API 项目中可用的密钥，以及支持 Responses 文字输入的可用模型。API 使用可能产生费用，网页聊天套餐不能被当作已自动包含 API 额度。若只想理解流程，可以阅读代码和教学输出，不必创建收费调用。

本系列以 Windows PowerShell 为操作基线。在你自己的练习目录打开 PowerShell，依次执行以下两条命令。第二条明确调用虚拟环境解释器，不依赖激活步骤，也不需要修改执行策略：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install openai

后续安装和运行均使用这个显式路径，避免依赖装在一个环境、程序却由另一个环境执行。其他常见系统需相应改用 .venv/bin/python，下文的会话配置命令则是 PowerShell 专用，不要直接粘贴到其他 shell。

在同一个 PowerShell 窗口执行以下配置。按提示输入自己的项目密钥，不会在终端回显；模型标识从你 API 项目当前可用模型中确认，必须支持本课接口，不能输入网页聊天里显示的任意昵称：

$lessonSecret = Read-Host '输入你的 API 密钥（不回显）' -AsSecureString
$env:OPENAI_API_KEY = [System.Net.NetworkCredential]::new('', $lessonSecret).Password
Remove-Variable lessonSecret
$env:OPENAI_MODEL = Read-Host '输入账号可用且支持 Responses 的模型标识'

这只配置当前 PowerShell 进程及它启动的子进程，不把密钥写入脚本或永久用户设置。环境变量仍由程序以明文读取，不应在该会话运行不可信程序。不要把密钥粘到公开代码、截图、浏览器前端或聊天记录，也不要打印整个环境变量。练习完成后可关闭这个窗口，或分别执行 Remove-Item Env:OPENAI_API_KEY 与 Remove-Item Env:OPENAI_MODEL 清除当前会话中的值。新开窗口需要重新配置。

3. 第一个完整请求

保存为 lesson_text.py，使用刚才的同一个窗口运行 .\.venv\Scripts\python.exe .\lesson_text.py：

import os
from openai import OpenAI, APIConnectionError, APIStatusError

model = os.environ.get("OPENAI_MODEL")
if not os.environ.get("OPENAI_API_KEY") or not model:
    raise SystemExit("请先配置 OPENAI_API_KEY 和 OPENAI_MODEL。")

client = OpenAI(timeout=30.0, max_retries=0)

try:
    response = client.responses.create(
        model=model,
        instructions=(
            "你是面向成年初学者的数学辅导助手。"
            "用中文给出简短、可核查的解题说明。"
            "不要声称已经评估学生能力；只处理提供的题目。"
        ),
        input="请解释怎样求解 8x + 7 = -23，并把答案代回原式检查。",
        max_output_tokens=1200,
        store=False,
    )
    if response.status != "completed":
        raise SystemExit(f"响应尚未完整完成：{response.status}")
    if not response.output_text.strip():
        raise SystemExit("本次没有可显示的文字，请检查响应类型或拒答信息。")
    print(response.output_text)
    if response.usage:
        print("输入 token：", response.usage.input_tokens)
        print("输出 token：", response.usage.output_tokens)
except APIConnectionError:
    raise SystemExit("连接失败或超时，请检查网络，不要打印密钥。")
except APIStatusError as error:
    raise SystemExit(f"接口返回状态码 {error.status_code}，请核对权限、模型和额度。")

代码中的 instructions 定义本次调用的行为规则，input 是待处理题目。max_output_tokens 限制输出预算，但不是最终字数承诺，也不是货币预算；某些推理模型还会在这一预算中使用推理 token，额度太小可能让可见答案不完整。这里不设置模型未必支持的温度等可选参数。

store=False 表示不为后续按响应 ID 取回而存储这次响应，不应被解释为已经满足所有数据保留或合规要求。学习中仍然只传虚构题目，不传真实学生隐私。连接超时后也不要无限重试；一次请求可能已经被服务端处理，重复提交有成本和重复结果的风险。

4. 检查的对象不只是“有没有文字”

一种教学参考答案如下：

把等式两边同时减去 7，得到 8x = -30。
两边再除以 8，得到 x = -15/4，也就是 -3.75。
代回检查：8 × (-15/4) + 7 = -30 + 7 = -23，与原式右边相同。

验收时看三件事：是否对等式两侧做相同操作；最终值是否是负四分之十五；代回是否等于负二十三。格式可以不同，但把答案写成正四分之十五，或检查时算错符号，都应判为失败。程序显示了文字只是技术层面的一个检查点。

Responses 的 output 可以包含不同类型的项目，不保证第一个永远是带文字的消息。SDK 的 output_text 适合这个纯文字练习；下一课需要机器读取字段，就不应该再靠切字符串猜结构。将来加入工具时，没有可见文本还可能意味着模型正在请求工具，而不是接口出错。

5. 多轮上下文不是自动读懂过去所有事

原 Cookbook 演示了使用前一个响应 ID 继续对话。本课的最小程序明确使用非存储方式，所以不要直接再拿它的 ID 假设可以继续。要做多轮，先选择一种策略：自己维护需要的消息，或在允许存储时使用服务端的响应关联能力。

不论采用哪一种，新的请求都要清楚知道当前规则和材料。官方文档说明，使用 previous_response_id 时，前一次的 instructions 不会自动作为本次规则继承，因此应在需要的每次调用中重新发送。更换题目后，还应避免把上一名学习者的内容带给下一名学习者。

对初学应用，可以先每题开一个独立请求。这样会失去连续对话的便利，但状态边界更简单。等单题的输入、结果和失败处理都验收通过，再逐步增加对话状态，而不是一开始就把无限历史全部传入。

6. 练习与故障排查

练习一：把问题改成“只解释为什么两边都要减去 7，不继续给最后答案”。只改 input，保留规则和代码结构。预期输出聚焦保持等式平衡的操作，而不是自动替你完成下一课的所有题目。记录提示与输出，以后可以比较不同版本。

练习二：暂时取消 OPENAI_MODEL 配置。程序应在调用前停止，并提示缺少配置。这是你可以不用付费调用就检查的错误分支。不要把真正密钥改成假字符串发起网络请求来凑测试次数。

练习三：如果显示“没有可显示的文字”，先看响应状态和类型，不要马上加上“请一定输出”。如果是输出预算不足，需要调整预算或缩小问题；如果是权限错误，应检查项目与模型权限；如果是网络问题，先检查连接。不同失败原因对应不同修复措施。

本课得到的是一个可阅读、可运行的后端脚本和一份明确的人工核验标准，还不是生产辅导系统。下一课会把解释转换为固定字段，让页面能分步展示，同时保留拒答、不完整响应和数学校验的边界。

来源说明：OpenAI Cookbook 的 Responses API 基础示例，中文案例改编；仓库 MIT 许可。数学输入取自同仓库 Structured Outputs 教学例子，以便三课衔接；按当前官方文档改用 output_text 并补充环境、状态、预算和非存储说明。2026 年 9 月 4 日完成资料核对，未调用真实 API，不代表官方认证课程。

原教材许可声明

MIT License

Copyright (c) 2025 OpenAI

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.