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 OpenAI

client = 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 OpenAI

client = 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 OpenAI

client = 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 OpenAI

client = 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 AsyncOpenAI

client = AsyncOpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # 从环境变量获取 API 密钥
)

async def main() -> None:
    response = await client.responses.create(  # 异步调用 API
        model="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 AsyncOpenAI


async 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())