OpenAI Python SDK 完全指南

OpenAI Python SDK 简介

OpenAI Python SDK是OpenAI官方提供的Python库,用于方便地访问OpenAI的REST API。该SDK支持Python 3.7及以上版本,提供了同步和异步两种客户端,并包含了所有请求参数和响应字段的类型定义。

OpenAI Python SDK基于httpx库构建,提供了便捷的API访问方式。它是根据OpenAI的OpenAPI规范使用Stainless自动生成的。

安装

要安装OpenAI Python SDK,只需使用pip执行以下命令:

pip install openai

值得注意的是,SDK在v1版本(2023年11月6日发布)进行了重写。如果你正在从旧版本升级,可以参考v1迁移指南,其中包含了自动更新代码的脚本。

基本用法

使用OpenAI Python SDK的基本流程如下:

导入OpenAI类
创建客户端实例
调用API方法

以下是一个简单的示例:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "你好,请介绍一下自己。",
        }
    ],
    model="gpt-3.5-turbo",
)

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

在这个例子中,我们首先创建了一个OpenAI客户端实例,然后使用chat.completions.create()方法发送了一个聊天请求。API密钥可以通过环境变量设置,也可以在创建客户端时直接传入。

高级特性

流式响应

OpenAI Python SDK支持使用服务器端事件(SSE)进行流式响应。这对于需要实时输出的应用场景非常有用。以下是一个示例:

from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "讲一个关于人工智能的故事"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

异步支持

SDK提供了异步客户端AsyncOpenAI,使用方法与同步客户端类似,只需在API调用前加上await:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    chat_completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Python中如何实现异步编程?",
            }
        ],
        model="gpt-3.5-turbo",
    )
    print(chat_completion.choices[0].message.content)

asyncio.run(main())

分页

对于返回列表的API方法,SDK提供了自动分页的迭代器,无需手动请求后续页面:

from openai import OpenAI

client = OpenAI()

all_jobs = []
for job in client.fine_tuning.jobs.list(limit=20):
    all_jobs.append(job)
print(all_jobs)

文件上传

SDK支持多种文件上传方式,包括字节流、路径对象或元组:

from pathlib import Path
from openai import OpenAI

client = OpenAI()

client.files.create(
    file=Path("input.jsonl"),
    purpose="fine-tune",
)

错误处理

SDK定义了多种异常类型,以便于处理不同的错误情况:

import openai
from openai import OpenAI

client = OpenAI()

try:
    client.fine_tuning.jobs.create(
        model="gpt-3.5-turbo",
        training_file="file-abc123",
    )
except openai.APIConnectionError as e:
    print("无法连接到服务器")
except openai.RateLimitError as e:
    print("超出API调用限制")
except openai.APIStatusError as e:
    print(f"API返回了非200状态码: {e.status_code}")
    print(e.response)

最佳实践

使用环境变量存储API密钥: 推荐使用python-dotenv库将API密钥存储在.env文件中,而不是直接硬编码在源代码中。
利用类型提示: SDK提供了完整的类型定义,可以在编辑器中获得自动补全和文档提示。
合理使用重试机制: SDK默认对某些错误进行自动重试,你可以通过max_retries选项自定义重试行为。
注意超时设置: 默认请求超时时间为10分钟,可以通过timeout选项进行调整。
使用流式响应: 对于生成大量文本的场景,使用流式响应可以提供更好的用户体验。
异步编程: 在需要处理大量并发请求的场景中,使用异步客户端可以提高性能。
合理管理HTTP资源: 使用上下文管理器或手动调用close()方法来及时释放HTTP连接。

Azure OpenAI 支持

OpenAI Python SDK也支持Azure OpenAI服务,只需使用AzureOpenAI类替代OpenAI类:

from openai import AzureOpenAI

client = AzureOpenAI(
    api_version="2023-07-01-preview",
    azure_endpoint="https://example-endpoint.openai.azure.com",
)

completion = client.chat.completions.create(
    model="deployment-name",
    messages=[
        {
            "role": "user",
            "content": "如何使用Python处理JSON数据?",
        },
    ],
)
print(completion.choices[0].message.content)