Python SDK 示例

Python SDK 示例适合脚本、Notebook、数据处理、后端服务、CLI 工具和自动化任务。它比 curl 更适合长期复用，也比直接在业务里拼 HTTP 请求更容易维护。

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。Base URL 使用 https://api.ofapp.cn/v1。具体可用模型、价格、额度、套餐和能力，请以 OfApp.cn 控制台或官方文档为准。

把 Python SDK 接到统一 API 入口

用环境变量管理 OfApp.cn API Key、Base URL 和模型名，让脚本、Notebook、后端服务和自动化任务共用同一套 OpenAI 兼容配置。

查看 OfApp.cn 接入说明

页面摘要

项目	内容
适合人群	Python 脚本、Notebook、数据处理、后端服务、CLI 和自动化任务开发者
阅读时间	约 6 分钟
核心问题	如何用 OpenAI Python SDK 接入 OfApp.cn OpenAI 兼容入口
你会得到	环境变量模板、客户端初始化、模型列表验证、Responses 与 Chat Completions 示例、流式输出、错误处理和上线检查
安全边界	API Key 只放环境变量、Secret 或密钥管理工具；模型、价格、额度和能力请以 OfApp.cn 控制台或官方文档为准

适合谁读

读者	正在做什么	读完能完成什么
Python 初学者	想用几行代码调用 AI	跑通最小 Chat Completions 请求
数据分析师	想批量摘要、分类、提取字段	把 SDK 放进脚本或 Notebook
后端开发者	给服务端加 AI 能力	封装可复用 client、超时、重试和错误处理
运营和内容团队	批量改写、翻译、总结资料	用文件输入和日志记录保持可复核
团队维护者	要把本地脚本上线到服务器或 CI	避免泄露 Key，保留脱敏排查线索

如果你只是想验证 Key 和 Base URL 是否可用，先看 curl 示例。Python SDK 更适合重复调用、批处理和服务端封装。

接入流程图

这张图的重点是顺序。先把最小请求跑通，再加入文件读取、批处理、流式输出、重试和业务逻辑。若最小请求失败，优先排查 API Key、Base URL、模型名和网络。

前置条件

OpenAI Python SDK 面向 Python 应用，建议先确认你正在使用的解释器和 pip 属于同一个环境。

python -V
python -m pip install --upgrade openai

准备三个环境变量：

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="你的 OfApp.cn API Key"
export OPENAI_MODEL="以 OfApp.cn 控制台可用模型为准"

环境变量	作用	注意
OPENAI_API_KEY	请求鉴权	不写进源码、Notebook、日志、截图或公开仓库。
OPENAI_BASE_URL	指向 API 入口	OfApp.cn OpenAI 兼容入口示例为 https://api.ofapp.cn/v1。
OPENAI_MODEL	指定模型	从 OfApp.cn 控制台或官方文档确认，不凭网上示例猜。

初始化客户端

把 SDK 初始化集中放在一个文件里，例如 client.py。这样脚本、Notebook 和服务端代码都能复用同一个配置。

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
    timeout=60.0,
    max_retries=2,
)

配置	建议
api_key	从环境变量读取，避免泄露真实 Key。
base_url	OfApp.cn 示例为 https://api.ofapp.cn/v1。
timeout	给脚本和服务端请求设置上限，避免任务一直挂起。
max_retries	对网络、429、5xx 等临时问题保持有限重试。

如果你在 CI、Docker 或服务器里运行，先在启动脚本里打印“环境变量是否存在”，不要打印真实值。

配置自检脚本

接入排错时，先确认 Python 进程能读到同一组环境变量。下面的脚本只打印状态， 不打印真实 Key。

import os

required = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_MODEL"]

for name in required:
    value = os.environ.get(name, "")
    print(f"{name}: {'set' if value else 'missing'}")

print("base_url_has_v1:", os.environ.get("OPENAI_BASE_URL", "").rstrip("/").endswith("/v1"))

如果本机成功、服务器失败，通常不是代码突然变坏，而是运行进程没有读到相同 的环境变量，或部署后没有重启服务。

查询模型列表

生成请求失败时，先用模型列表验证入口、Key 和网络。OfApp.cn 官方文档提供了 /v1/models 示例；在 SDK 中也可以直接调用模型列表接口。

from client import client

models = client.models.list()

for item in models.data[:10]:
    print(item.id)

如果这里失败，优先检查 OPENAI_BASE_URL 是否包含 /v1、Key 是否正确、当前网络是否能访问 OfApp.cn，以及账号当前可用模型是否以控制台为准。

Python SDK 调用方式选择

同一个 Python SDK 可以用于 Notebook 探索、服务端接口和批处理任务。接入前 先选清楚路径，避免把实验代码直接带进生产。

目标	建议路径	适合场景	先验证什么
新脚本生成文本	client.responses.create()	总结、改写、分类、结构化提取探索	OfApp.cn 当前是否支持对应端点和模型
兼容性优先	client.chat.completions.create()	旧项目迁移、OpenAI-compatible API、连通性验证	Key、Base URL、模型名和 messages 格式
长文本或命令行输出	stream=True	CLI 助手、聊天界面、长摘要	非流式请求先成功，终端或网关不缓冲输出
Notebook 探索	小批量单元格	数据分析、资料整理、提示词试验	Key 不进 .ipynb，输出先脱敏
批处理任务	脚本、队列或 Worker	批量摘要、翻译、分类、清洗	失败记录、超时、重试和人工抽检

Responses 最小请求

新项目可以优先了解 Responses 写法。OpenAI Python SDK 支持 client.responses.create()，OfApp.cn 是否支持某个具体能力或模型，请以控制台或官方文档为准。

import os

from client import client

response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="用三句话解释 Python SDK 适合哪些 AI 自动化任务。",
)

print(response.output_text)

如果返回结构与示例不同，先打印对象结构，再回到 OpenAI-compatible API 快速开始 对照端点和响应字段。

Chat Completions 最小请求

很多兼容客户端、旧项目和教程仍使用 Chat Completions。它适合做连通性验证，也适合迁移既有项目。

import os

from client import client

completion = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "生成一句中文测试回复。",
        }
    ],
)

print(completion.choices[0].message.content)

第一次接入时，不要同时加入工具调用、JSON Schema、长上下文、图片和复杂 Prompt。最小请求成功后，再逐项增加能力。

流式输出

流式输出适合聊天界面、CLI 工具和长文本生成。OpenAI Python SDK 的 Responses 可以使用 stream=True 返回事件流。

import os

from client import client

stream = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="分三点说明如何用 Python 自动整理会议纪要。",
    stream=True,
)

for event in stream:
    print(event)

如果你使用 Chat Completions 流式输出，可以按 chunk 读取增量内容：

import os

from client import client

stream = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    stream=True,
    messages=[
        {
            "role": "user",
            "content": "分三点说明 Python SDK 接入步骤。",
        }
    ],
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

现象	排查方向
非流式成功，流式失败	看代理、网关、SSE 转发和客户端读取。
终端一次性输出	检查是否有缓冲，print 是否设置 flush=True。
中途断开	记录已输出内容、状态码、耗时和网络环境。
事件对象看不懂	先打印原始 event，再按当前响应结构解析。

错误处理

OpenAI Python SDK 的错误类型可以帮助你区分网络错误、限流和非成功状态码。排查时记录状态码、请求 ID 和脱敏后的错误摘要，不要把真实 Key 或完整客户数据写进日志。

import os
import openai

from client import client

try:
    completion = client.chat.completions.create(
        model=os.environ["OPENAI_MODEL"],
        messages=[{"role": "user", "content": "ping"}],
    )
    print(completion.choices[0].message.content)
except openai.APIConnectionError as error:
    print("网络连接失败，请检查 DNS、代理、服务器网络或 OfApp.cn 访问状态。")
    print(f"cause={error.__cause__}")
except openai.RateLimitError as error:
    print("请求过快或额度受限，请降低并发并检查控制台额度。")
    print(f"status_code={error.status_code}")
except openai.APIStatusError as error:
    print("API 返回非成功状态码。")
    print(f"status_code={error.status_code}")
    print(f"request_id={error.request_id}")

常见错误对应关系：

类型	常见含义	下一步
APIConnectionError	网络、DNS、代理或连接失败	用 curl 验证同一台机器是否能访问。
AuthenticationError	Key 无效或鉴权头异常	回到控制台复制 Key，确认环境变量已加载。
PermissionDeniedError	当前 Key 或账号无权限	检查账号、项目、模型权限和控制台提示。
NotFoundError	路径或模型名不正确	检查 Base URL、端点和模型名。
RateLimitError	请求过快或额度受限	降低并发，加入退避，检查额度。
APIStatusError	其他非成功状态码	记录 status_code、request_id 和脱敏摘要。

超时和重试

SDK 默认会处理部分临时错误，但生产脚本不应该无限等待，也不应该在失败时无节制重试。

from client import client

short_client = client.with_options(timeout=10.0, max_retries=0)

场景	建议
本地调试	可以把超时设短，快速暴露网络问题。
批处理脚本	给每条输入设置超时，并把失败项写入重试队列。
Web 服务	保持有限重试，避免用户请求被长时间占用。
定时任务	记录输入 ID、状态码、耗时和脱敏错误摘要。

更多退避策略可以看 错误重试示例。

批处理脚本示例

下面的结构适合批量摘要、翻译、分类和资料整理。重点不是一次跑完所有数据，而是每条输入都有可追踪状态。

import os

from client import client

items = [
    {"id": "note-001", "text": "这里放会议记录。"},
    {"id": "note-002", "text": "这里放客户反馈。"},
]

for item in items:
    try:
        completion = client.chat.completions.create(
            model=os.environ["OPENAI_MODEL"],
            messages=[
                {
                    "role": "system",
                    "content": "你是严谨的中文摘要助手，只基于用户材料总结。",
                },
                {
                    "role": "user",
                    "content": item["text"],
                },
            ],
        )
        print(item["id"], completion.choices[0].message.content)
    except Exception as error:
        print(item["id"], type(error).__name__)

真实业务里还要补输入长度限制、失败重试队列、结果人工复核和敏感数据脱敏。

Notebook 使用建议

Notebook 适合探索，但也很容易泄露 Key 或把临时输出混进版本库。

做法	原因
从环境变量读取 Key	避免把真实 Key 写进 .ipynb。
单独保留最小请求单元格	出错时能快速确认配置是否仍然有效。
大批量任务拆成小批次	便于恢复、复核和控制成本。
输出前先脱敏	避免客户内容、账号信息或内部文件名进入共享报告。

上线前检查清单

检查项	通过标准
Key 管理	只来自环境变量、Secret 或密钥管理工具。
Base URL	https://api.ofapp.cn/v1 只配置一次，没有重复拼接。
模型名	来自 OfApp.cn 控制台或官方文档。
最小请求	Responses 或 Chat Completions 至少有一个可稳定返回。
错误处理	能区分连接、鉴权、限流、404 和 5xx。
日志	记录状态码、耗时、请求 ID 和脱敏摘要。
超时重试	有上限，不会无限等待或无限重试。
人工复核	输出进入业务前有抽检或审批机制。

常见问题

Python SDK 里的 base_url 和 JavaScript SDK 的 baseURL 是一回事吗？

含义相近，写法不同。Python SDK 使用 base_url，JavaScript SDK 使用 baseURL。如果把字段名写混，SDK 不会按预期请求 OfApp.cn 入口。

可以只设置 OPENAI_API_KEY 不设置 OPENAI_BASE_URL 吗？

如果你要接入 OfApp.cn 这类 OpenAI-compatible 入口，应显式设置 base_url 或 OPENAI_BASE_URL，让请求发往 https://api.ofapp.cn/v1。否则 SDK 可能使用默认 OpenAI 入口。

应该先用 Responses 还是 Chat Completions？

新脚本可以了解 Responses；迁移旧项目或排查兼容工具时，Chat Completions 往往更贴近现有代码。关键是先跑通一个最小请求，再扩展复杂能力。

为什么 curl 成功但 Python SDK 失败？

常见原因是 Python 进程没有读到同一组环境变量、虚拟环境装错包、base_url 拼错、代理配置不同，或模型名来自不同环境。先在 Python 里打印变量是否存在，不打印真实值。

Notebook 里为什么不建议直接写 Key？

Notebook 经常会被提交到仓库、发给同事或导出成 HTML。真实 Key 一旦写进去，很容易被复制、缓存或泄露。建议从环境变量或密钥管理工具读取。

max_retries 越大越好吗？

不是。重试适合临时网络、429 或 5xx，但过多重试会放大延迟和成本。批处理任务更适合把失败项记录下来，稍后分批重跑。

如何记录错误又不泄露敏感信息？

记录状态码、错误类型、请求 ID、耗时和脱敏摘要即可。不要记录真实 API Key、完整客户内容、账号邮箱、账单信息或未脱敏文件名。

生产环境需要把 SDK 再封装一层吗？

建议封装。把 client 初始化、超时、重试、日志、输入长度限制和错误映射集中管理，业务函数只负责传入任务和处理结果。

相关文章

• curl 示例
• JavaScript SDK 示例
• OpenAI Compatible API 快速调用
• OpenAI 兼容 API 快速开始
• 如何用 OpenAI SDK 接入
• Streaming 示例
• 错误重试示例
• invalid API key
• API 错误排查中心

资料来源

• OfApp.cn 官方文档：核对 API Key、Base URL、Bearer 鉴权和 /v1 入口相关信息。
• OfApp.cn 官网：核对 OfApp.cn 面向 OpenAI、Codex、GPT Image、Claude 和 AI 客户端的入口语境。
• 天才游乐场：核对普通用户从网页入口体验模型、图片和 Key 配置的上下文。
• OpenAI Python SDK README：参考 OpenAI 客户端、Responses、Chat Completions、错误类型、超时和重试写法。
• OpenAI API 文档：参考 API Key、认证、SDK 和兼容 API 的通用边界。

带走什么

Python SDK 接入 OfApp.cn 的关键不是多写几段代码，而是把配置、最小请求、错误处理、日志脱敏和人工复核做成稳定流程。只要最小请求能稳定返回，后续批处理、Notebook、后端服务和自动化脚本都会更容易排查和维护。