Python3 OpenAI详解

OpenAI 提供了一系列强大的 AI 模型（如 GPT 系列、DALL-E、Whisper 等），并通过官方 Python 库 openai 开放 API 接口，方便开发者在 Python 中集成这些能力。本文将详细讲解 openai 库的安装、核心功能、常用 API 调用及高级用法，帮助你快速上手。

一、环境准备

1. 安装 openai 库

OpenAI 官方 Python 库已更新至 v1 版本（2023 年底发布），与旧版本（v0.x）接口差异较大，推荐使用最新版本：

pip install openai --upgrade  # 确保安装最新版（v1+）

 

2. 获取 API 密钥

使用 OpenAI API 需先获取 API 密钥，步骤如下：

 

1. 注册 / 登录 OpenAI 账号
2. 进入 API 密钥页面
3. 点击 "Create new secret key" 生成密钥（注意：密钥仅显示一次，需妥善保存）

 

3. 初始化客户端

在代码中通过 API 密钥初始化 OpenAI 客户端，推荐将密钥存储在环境变量中（避免硬编码泄露）：

 

import os
from openai import OpenAI# 从环境变量读取 API 密钥（推荐）
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"),  # 环境变量中设置 OPENAI_API_KEY=你的密钥# 若使用代理，需指定 base_url（如国内代理）# base_url="https://api.openai-proxy.com/v1"
)

 

 

若临时测试，也可直接传入密钥（不推荐生产环境）：

client = OpenAI(api_key="sk-你的API密钥")

 

二、核心功能：调用 GPT 系列模型（对话接口）

GPT-3.5-turbo、GPT-4 等模型是 OpenAI 最常用的对话模型，通过 chat.completions.create 接口调用，支持多轮对话。

1. 基础对话（单轮）

发送一个用户问题，获取模型回复：

 

# 构造对话消息（列表形式，每个元素是一个角色的消息）
messages = [{"role": "user", "content": "解释一下什么是机器学习？用通俗的话来说"}
]# 调用 GPT-3.5-turbo 模型
response = client.chat.completions.create(model="gpt-3.5-turbo",  # 模型名称（可选 gpt-4、gpt-4-turbo 等）messages=messages,temperature=0.7,  # 随机性（0-2，值越低越确定，0 接近标准答案）max_tokens=500    # 最大生成 tokens（输入+输出总和不超过模型上限，如 gpt-3.5-turbo 是 4096）
)# 提取回复内容
reply = response.choices[0].message.content
print(reply)

 

 

输出示例：

 

机器学习简单说就是让电脑自己"学习"怎么做事情，而不是我们一步一步教它。比如，你想让电脑认出照片里是不是猫，不用告诉它"猫有尖耳朵、长胡须"，而是给它看成千上万张猫的照片和不是猫的照片，电脑会自己总结出"猫的特征"，之后再看到新照片，就能判断是不是猫了。

 

2. 多轮对话

通过在 messages 列表中追加历史消息，实现上下文连贯的多轮对话：

 

# 初始对话消息
messages = [{"role": "system", "content": "你是一个数学老师，用简单的例子讲解知识。"},  # system 角色：设定模型行为{"role": "user", "content": "什么是质数？"},{"role": "assistant", "content": "质数就是大于1的自然数中，除了1和它自己，不能被其他数整除的数。比如2、3、5、7。"},  # 模型历史回复{"role": "user", "content": "那10以内的质数有哪些？"}  # 新的用户问题
]# 调用模型
response = client.chat.completions.create(model="gpt-3.5-turbo",messages=messages,temperature=0.5
)# 追加新回复到消息列表（为下一轮对话准备）
messages.append({"role": "assistant", "content": response.choices[0].message.content})
print("模型回复：", response.choices[0].message.content)

 

 

输出示例：

 

模型回复：10以内的质数有2、3、5、7。注意1不是质数哦，因为它只有1一个因数~

 

关键参数说明

• model：模型名称，常用选项：
  • gpt-3.5-turbo：性价比高，适合日常对话、简单任务（支持 4k tokens）。
  • gpt-3.5-turbo-1106：支持 16k tokens，上下文更长。
  • gpt-4：更强的推理能力，适合复杂任务（支持 8k/128k tokens）。
• temperature：控制生成随机性（0-2）：
  • 0：生成内容固定、确定（适合事实性问答）。
  • 1：中等随机性（适合创意生成）。
  • 2：高度随机（可能生成离奇内容）。
• max_tokens：限制生成内容长度（输入 tokens + 输出 tokens 不能超过模型上限）。
• stream：是否流式返回（stream=True 时，内容会逐字生成，适合实时聊天界面）。

三、其他常用 API

1. 图像生成（DALL-E）

通过 images.generate 接口调用 DALL-E 模型生成图像：

 

response = client.images.generate(model="dall-e-3",  # 模型（dall-e-2 或 dall-e-3）prompt="一只穿着宇航服的柯基犬，在月球上跳，背景是地球，卡通风格",  # 图像描述（越详细效果越好）size="1024x1024",  # 尺寸（dall-e-3 支持 1024x1024、1024x1792 等）quality="standard",  # 质量（standard 或 hd）n=1  # 生成数量（dall-e-3 最多 1 张）
)# 获取图像 URL（有效期 1 小时，可下载保存）
image_url = response.data[0].url
print("图像 URL：", image_url)

 

 

提示：若需要修改已有图像，可使用 images.edit 接口（需提供原始图像和蒙版）。

2. 语音转文字（Whisper）

通过 audio.transcribe 接口调用 Whisper 模型，将音频文件转为文字：

 

# 处理本地音频文件（支持 mp3、wav、m4a 等格式）
with open("test.m4a", "rb") as audio_file:response = client.audio.transcriptions.create(model="whisper-1",  # Whisper 唯一模型file=audio_file,language="zh"  # 可选：指定语言（如 "en" 英文，"ja" 日文）)print("语音转文字结果：", response.text)

 

 

若需要翻译（如将其他语言转为英文），使用 audio.translations.create：

with open("test_spanish.m4a", "rb") as audio_file:response = client.audio.translations.create(model="whisper-1",file=audio_file)
print("翻译结果（英文）：", response.text)

 

四、高级用法

1. 流式响应（实时输出）

当 stream=True 时，模型会逐块返回内容，适合构建实时聊天界面：

 

messages = [{"role": "user", "content": "用 100 字描述春天的景色"}]# 流式调用
stream = client.chat.completions.create(model="gpt-3.5-turbo",messages=messages,stream=True  # 开启流式
)# 逐块打印结果
print("流式输出：")
for chunk in stream:# 过滤空内容（避免打印空字符串）if chunk.choices[0].delta.content is not None:print(chunk.choices[0].delta.content, end="", flush=True)

 

 

输出效果：内容会逐字显示，类似人类打字的过程。

2. 函数调用（Function Calling）

当需要模型调用外部工具（如查天气、调用 API）时，可通过函数调用功能实现。核心步骤：

 

1. 定义函数描述（告诉模型有哪些工具可用）。
2. 模型判断是否需要调用工具，返回调用指令。
3. 执行工具调用，将结果返回给模型，获取最终回答。

 

示例（调用 “查天气” 函数）：

 

# 1. 定义函数描述（JSON 格式）
tools = [{"type": "function","function": {"name": "get_weather","description": "获取指定城市的天气","parameters": {"type": "object","properties": {"city": {"type": "string", "description": "城市名称"}},"required": ["city"]  # 必传参数}}}
]# 2. 用户提问
messages = [{"role": "user", "content": "北京今天的天气怎么样？"}]# 3. 调用模型，让其判断是否需要调用工具
response = client.chat.completions.create(model="gpt-3.5-turbo-1106",  # 需支持函数调用的模型messages=messages,tools=tools,tool_choice="auto"  # 自动判断是否调用工具
)# 4. 解析模型响应：若需要调用工具，则执行函数
if response.choices[0].message.tool_calls:tool_call = response.choices[0].message.tool_calls[0]if tool_call.function.name == "get_weather":# 提取参数（城市名）city = eval(tool_call.function.arguments)["city"]# 模拟调用天气接口（实际中替换为真实 API）weather_result = f"北京今天天气：晴，20-28℃，微风"# 5. 将工具结果返回给模型，获取最终回答messages.append(response.choices[0].message)  # 追加模型的工具调用指令messages.append({"role": "tool","tool_call_id": tool_call.id,"content": weather_result})# 6. 再次调用模型，生成自然语言回答final_response = client.chat.completions.create(model="gpt-3.5-turbo-1106",messages=messages)print("最终回答：", final_response.choices[0].message.content)

 

 

输出示例：

 

最终回答：北京今天天气晴朗，气温在20到28℃之间，伴有微风，适合户外活动~

 

五、错误处理

API 调用可能因密钥错误、网络问题、参数错误等失败，需捕获异常：

 

from openai import OpenAIError, AuthenticationError, RateLimitErrortry:response = client.chat.completions.create(model="gpt-3.5-turbo",messages=[{"role": "user", "content": "Hello"}])
except AuthenticationError:print("API 密钥错误，请检查密钥是否正确")
except RateLimitError:print("超过速率限制，请稍后再试")
except OpenAIError as e:print(f"API 调用失败：{e}")

 

六、最佳实践

1. 保护 API 密钥：避免硬编码在代码中，使用环境变量（os.getenv）或配置文件管理。
2. 控制成本：GPT-4 等模型价格较高，测试时可先用 gpt-3.5-turbo，并通过 max_tokens 限制输出长度。
3. 处理速率限制：OpenAI 对 API 调用频率有限制（如免费账号每分钟 3 次），可通过重试机制（如 tenacity 库）处理。
4. 优化 prompt：清晰描述需求（如 “用 3 句话总结”“以列表形式输出”），提升模型响应质量。