OpenAI Python API 完全指南：从入门到实战
前言
OpenAI Python API 库为开发者提供了便捷访问 OpenAI 强大 AI 模型的能力。本文将详细介绍该库的各项功能，并通过代码示例展示如何使用。
一、OpenAI Python 库概述
OpenAI Python 库是一个官方维护的 Python 客户端，用于与 OpenAI REST API 交互。主要特点包括：
- 支持 Python 3.8+ 版本
- 提供同步和异步客户端
- 内置完整的类型定义
- 基于 httpx 实现网络请求
- 从 OpenAPI 规范自动生成
# 安装命令
pip install openai# 异步增强版（含aiohttp）
pip install openai[aiohttp] 二、基础使用
两种使用 OpenAI Python SDK 与 GPT-4o 模型交互的方式
1. 新版 Responses API（推荐方式）
import os
from openai import OpenAIclient = OpenAI(api_key=os.environ.get("OPENAI_API_KEY")) # 从环境变量读取API密钥response = client.responses.create(model="gpt-4o", # 指定模型instructions="你是一个编程助手", # 设定AI角色，设置AI行为指令input="如何用Python检查对象类型?" # 用户问题
)
print(response.output_text) # 输出响应文本
带有嵌套参数的聊天请求
input: 消息列表（嵌套字典结构）response_format: 要求响应格式为JSON对象
from openai import OpenAIclient = OpenAI()response = client.chat.responses.create(input=[{"role": "user","content": "请给我讲解一下 RAG ?",}],model="gpt-4o",response_format={"type": "json_object"},
)2. 传统 Chat Completions API（仍支持）
from openai import OpenAIclient = OpenAI() # 密钥也可通过环境变量自动加载completion = client.chat.completions.create(model="gpt-4o",messages=[ # 消息历史记录{"role": "developer", "content": "你是一个编程助手"}, # 系统指令{"role": "user", "content": "如何用Python检查对象类型?"} # 用户输入]
)
print(completion.choices[0].message.content) # 输出第一条回复
三、视觉功能
OpenAI 的视觉模型可以分析图片内容
1. 使用图片URL
prompt = "这张图片有什么内容?"
img_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/2023_06_08_Raccoon1.jpg/1599px-2023_06_08_Raccoon1.jpg"response = client.responses.create(model="gpt-4o-mini",input=[{"role": "user","content": [{"type": "input_text", "text": prompt},{"type": "input_image", "image_url": f"{img_url}"},],}],
)2. 使用Base64编码图片
import base64
from openai import OpenAIclient = OpenAI()prompt = "这张图片有什么内容?"
with open("path/to/image.png", "rb") as image_file:b64_image = base64.b64encode(image_file.read()).decode("utf-8")response = client.responses.create(model="gpt-4o-mini",input=[{"role": "user","content": [{"type": "input_text", "text": prompt},{"type": "input_image", "image_url": f"data:image/png;base64,{b64_image}"},],}],
)四、异步处理
以下展示了如何使用 OpenAI Python 库的异步客户端 (AsyncOpenAI)，以及如何配置不同的 HTTP 后端 (httpx 或 aiohttp)。
两者主要区别在于 HTTP 库的选择，API 功能完全相同。aiohttp 在特定高并发场景下可能表现更好。
1. 基础异步用法
使用 `AsyncOpenAI` 替代同步的 `OpenAI` 客户端
每个 API 调用需配合 `await` 关键字
功能与同步客户端完全一致
import os
import asyncio
from openai import AsyncOpenAIclient = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"), # 从环境变量获取 API 密钥
)async def main() -> None:response = await client.responses.create( # 异步调用 APImodel="gpt-4o", input="向一个非开发人员解释什么叫 RAG")print(response.output_text) # 打印响应结果asyncio.run(main()) # 运行异步主函数
2. 使用 aiohttp 后端
默认使用 `httpx`，但可切换至 `aiohttp` 提升并发性能
需通过 `http_client=DefaultAioHttpClient()` 参数启用
推荐在上下文管理器 (`async with`) 中使用
pip install openai[aiohttp] # 安装 aiohttp 支持
import asyncio
from openai import DefaultAioHttpClient
from openai import AsyncOpenAIasync def main() -> None:async with AsyncOpenAI(api_key="My API Key",http_client=DefaultAioHttpClient(), # 显式指定 aiohttp 后端) as client:chat_completion = await client.chat.completions.create(messages=[{"role": "user","content": "Say this is a test",}],model="gpt-4o",)asyncio.run(main())