openai python
v1.55.1
OpenAI Python 库可让任何 Python 3.8+ 应用程序方便地访问 OpenAI REST API。该库包含所有请求参数和响应字段的类型定义，并提供由 httpx 提供支持的同步和异步客户端。
它是根据我们的 OpenAPI 规范与不锈钢生成的。
REST API 文档可以在 platform.openai.com 上找到。该库的完整 API 可以在 api.md 中找到。
重要的
SDK 在 v1 中进行了重写，于 2023 年 11 月 6 日发布。请参阅 v1 迁移指南，其中包括自动更新代码的脚本。
# install from PyPI
pip install openai该库的完整 API 可以在 api.md 中找到。
import os
from openai import OpenAI
client = OpenAI (
api_key = os . environ . get ( "OPENAI_API_KEY" ), # This is the default and can be omitted
)
chat_completion = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
)虽然您可以提供api_key关键字参数，但我们建议使用 python-dotenv 将OPENAI_API_KEY="My API Key"添加到您的.env文件，以便您的 API 密钥不会存储在源代码管理中。
使用托管图像：
response = client . chat . completions . create (
model = "gpt-4o-mini" ,
messages = [
{
"role" : "user" ,
"content" : [
{ "type" : "text" , "text" : prompt },
{
"type" : "image_url" ,
"image_url" : { "url" : f" { img_url } " },
},
],
}
],
)将图像作为 base64 编码的字符串：
response = client . chat . completions . create (
model = "gpt-4o-mini" ,
messages = [
{
"role" : "user" ,
"content" : [
{ "type" : "text" , "text" : prompt },
{
"type" : "image_url" ,
"image_url" : { "url" : f"data: { img_type } ;base64, { img_b64_str } " },
},
],
}
],
)与 API 交互时，某些操作（例如启动运行和将文件添加到矢量存储）是异步的，需要一些时间才能完成。 SDK 包含辅助函数，这些函数将轮询状态，直到达到最终状态，然后返回结果对象。如果 API 方法导致可以从轮询中受益的操作，则会有以“_and_poll”结尾的相应方法版本。
例如，要创建一个运行并轮询，直到达到最终状态，您可以运行：
run = client . beta . threads . runs . create_and_poll (
thread_id = thread . id ,
assistant_id = assistant . id ,
)有关运行生命周期的更多信息可以在运行生命周期文档中找到
创建矢量存储并与之交互时，您可以使用轮询助手来监视操作的状态。为了方便起见，我们还提供了批量上传助手，允许您一次同时上传多个文件。
sample_files = [ Path ( "sample-paper.pdf" ), ...]
batch = await client . vector_stores . file_batches . upload_and_poll (
store . id ,
files = sample_files ,
)SDK 还包括处理流和处理传入事件的帮助程序。
with client . beta . threads . runs . stream (
thread_id = thread . id ,
assistant_id = assistant . id ,
instructions = "Please address the user as Jane Doe. The user has a premium account." ,
) as stream :
for event in stream :
# Print the text from text delta events
if event . type == "thread.message.delta" and event . data . delta . content :
print ( event . data . delta . content [ 0 ]. text )有关流式处理助手的更多信息可以在专用文档中找到：helpers.md
只需导入AsyncOpenAI而不是OpenAI ，并在每个 API 调用中使用await ：
import os
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI (
api_key = os . environ . get ( "OPENAI_API_KEY" ), # This is the default and can be omitted
)
async def main () -> None :
chat_completion = await client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
)
asyncio . run ( main ())同步和异步客户端之间的功能在其他方面是相同的。
我们使用服务器端事件 (SSE) 提供对流式响应的支持。
from openai import OpenAI
client = OpenAI ()
stream = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
stream = True ,
)
for chunk in stream :
print ( chunk . choices [ 0 ]. delta . content or "" , end = "" )异步客户端使用完全相同的接口。
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI ()
async def main ():
stream = await client . chat . completions . create (
model = "gpt-4" ,
messages = [{ "role" : "user" , "content" : "Say this is a test" }],
stream = True ,
)
async for chunk in stream :
print ( chunk . choices [ 0 ]. delta . content or "" , end = "" )
asyncio . run ( main ())重要的
我们强烈建议实例化客户端实例，而不是依赖全局客户端。
我们还公开了一个全局客户端实例，可以通过与 v1 之前的版本类似的方式访问该实例。
import openai
# optional; defaults to `os.environ['OPENAI_API_KEY']`
openai . api_key = '...'
# all client options can be configured just like the `OpenAI` instantiation counterpart
openai . base_url = "https://..."
openai . default_headers = { "x-foo" : "true" }
completion = openai . chat . completions . create (
model = "gpt-4o" ,
messages = [
{
"role" : "user" ,
"content" : "How do I output all files in a directory using Python?" ,
},
],
)
print ( completion . choices [ 0 ]. message . content )该 API 与基于标准客户端实例的 API 完全相同。
其目的是在 REPL 或笔记本中使用，以实现更快的迭代，而不是在应用程序代码中使用。
我们建议您始终在应用程序代码中实例化客户端（例如，使用client = OpenAI() ），因为：
嵌套的请求参数是TypedDicts。响应是 Pydantic 模型，它还为以下内容提供辅助方法：
model.to_json()model.to_dict()键入的请求和响应在编辑器中提供自动完成和文档。如果您希望在 VS Code 中查看类型错误以帮助尽早发现错误，请将python.analysis.typeCheckingMode设置为basic 。
OpenAI API 中的列表方法是分页的。
该库为每个列表响应提供自动分页迭代器，因此您不必手动请求连续页面：
from openai import OpenAI
client = OpenAI ()
all_jobs = []
# Automatically fetches more pages as needed.
for job in client . fine_tuning . jobs . list (
limit = 20 ,
):
# Do something with job here
all_jobs . append ( job )
print ( all_jobs )或者，异步：
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI ()
async def main () -> None :
all_jobs = []
# Iterate through items across all pages, issuing requests as needed.
async for job in client . fine_tuning . jobs . list (
limit = 20 ,
):
all_jobs . append ( job )
print ( all_jobs )
asyncio . run ( main ())或者，您可以使用.has_next_page() 、 .next_page_info()或.get_next_page()方法对页面进行更精细的控制：
first_page = await client . fine_tuning . jobs . list (
limit = 20 ,
)
if first_page . has_next_page ():
print ( f"will fetch next page using these details: { first_page . next_page_info () } " )
next_page = await first_page . get_next_page ()
print ( f"number of items we just fetched: { len ( next_page . data ) } " )
# Remove `await` for non-async usage.或者直接处理返回的数据：
first_page = await client . fine_tuning . jobs . list (
limit = 20 ,
)
print ( f"next page cursor: { first_page . after } " ) # => "next page cursor: ..."
for job in first_page . data :
print ( job . id )
# Remove `await` for non-async usage. 嵌套参数是字典，使用TypedDict键入，例如：
from openai import OpenAI
client = OpenAI ()
completion = client . chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "Can you generate an example json object describing a fruit?" ,
}
],
model = "gpt-4o" ,
response_format = { "type" : "json_object" },
)与文件上传相对应的请求参数可以作为bytes 、 PathLike实例或(filename, contents, media type)的元组传递。
from pathlib import Path
from openai import OpenAI
client = OpenAI ()
client . files . create (
file = Path ( "input.jsonl" ),
purpose = "fine-tune" ,
)异步客户端使用完全相同的接口。如果传递PathLike实例，文件内容将自动异步读取。
当库无法连接到 API 时（例如，由于网络连接问题或超时），会引发openai.APIConnectionError的子类。
当 API 返回非成功状态代码（即 4xx 或 5xx 响应）时，会引发openai.APIStatusError的子类，其中包含status_code和response属性。
所有错误都继承自openai.APIError 。
import openai
from openai import OpenAI
client = OpenAI ()
try :
client . fine_tuning . jobs . create (
model = "gpt-4o" ,
training_file = "file-abc123" ,
)
except openai . APIConnectionError as e :
print ( "The server could not be reached" )
print ( e . __cause__ ) # an underlying Exception, likely raised within httpx.
except openai . RateLimitError as e :
print ( "A 429 status code was received; we should back off a bit." )
except openai . APIStatusError as e :
print ( "Another non-200-range status code was received" )
print ( e . status_code )
print ( e . response )错误代码如下：
| 状态码 | 错误类型 |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 第422章 | UnprocessableEntityError |
| 第429章 | RateLimitError |
| >=500 | InternalServerError |
| 不适用 | APIConnectionError |
有关调试请求的更多信息，请参阅这些文档
SDK 中的所有对象响应都提供从x-request-id响应标头添加的_request_id属性，以便您可以快速记录失败的请求并将其报告回 OpenAI。
completion = await client . chat . completions . create (
messages = [{ "role" : "user" , "content" : "Say this is a test" }], model = "gpt-4"
)
print ( completion . _request_id ) # req_123请注意，与使用_前缀的其他属性不同， _request_id属性是公共的。除非另有说明，否则所有其他_前缀属性、方法和模块都是私有的。
默认情况下，某些错误会自动重试 2 次，并具有短暂的指数退避。默认情况下，连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制和 >=500 内部错误都会重试。
您可以使用max_retries选项来配置或禁用重试设置：
from openai import OpenAI
# Configure the default for all requests:
client = OpenAI (
# default is 2
max_retries = 0 ,
)
# Or, configure per-request:
client . with_options ( max_retries = 5 ). chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "How can I get the name of the current day in JavaScript?" ,
}
],
model = "gpt-4o" ,
)默认情况下，请求在 10 分钟后超时。您可以使用timeout选项进行配置，该选项接受浮点数或httpx.Timeout对象：
from openai import OpenAI
# Configure the default for all requests:
client = OpenAI (
# 20 seconds (default is 10 minutes)
timeout = 20.0 ,
)
# More granular control:
client = OpenAI (
timeout = httpx . Timeout ( 60.0 , read = 5.0 , write = 10.0 , connect = 2.0 ),
)
# Override per-request:
client . with_options ( timeout = 5.0 ). chat . completions . create (
messages = [
{
"role" : "user" ,
"content" : "How can I list all files in a directory using Python?" ,
}
],
model = "gpt-4o" ,
)超时时，会抛出APITimeoutError 。
请注意，默认情况下，超时的请求会重试两次。
我们使用标准库日志logging模块。
您可以通过将环境变量OPENAI_LOG设置为info来启用日志记录。
$ export OPENAI_LOG=info或者debug更详细的日志记录。
None是否表示null或缺失在 API 响应中，某个字段可能显式为null或完全缺失；无论哪种情况，它的值在该库中都是None 。您可以使用.model_fields_set区分这两种情况：
if response . my_field is None :
if 'my_field' not in response . model_fields_set :
print ( 'Got json like {}, without a "my_field" key present at all.' )
else :
print ( 'Got json like {"my_field": null}.' )可以通过前缀.with_raw_response.任何 HTTP 方法调用，例如
from openai import OpenAI
client = OpenAI ()
response = client . chat . completions . with_raw_response . create (
messages = [{
"role" : "user" ,
"content" : "Say this is a test" ,
}],
model = "gpt-4o" ,
)
print ( response . headers . get ( 'X-My-Header' ))
completion = response . parse () # get the object that `chat.completions.create()` would have returned
print ( completion )这些方法返回一个LegacyAPIResponse对象。这是一个遗留类，因为我们将在下一个主要版本中对其进行轻微更改。
对于同步客户端来说，这基本上是相同的，除了content和text将是方法而不是属性。在异步客户端中，所有方法都将是异步的。
将提供迁移脚本并且迁移总体上应该是顺利的。
.with_streaming_response当您发出请求时，上面的接口会急切地读取完整的响应正文，但这可能并不总是您想要的。
要流式传输响应正文，请使用.with_streaming_response ，它需要上下文管理器，并且仅在调用.read() 、 .text() 、 .json() 、 .iter_bytes() 、 .iter_text()时读取响应正文， .iter_lines()或.parse() 。在异步客户端中，这些是异步方法。
因此， .with_streaming_response方法返回不同的APIResponse对象，异步客户端返回AsyncAPIResponse对象。
with client . chat . completions . with_streaming_response . create (
messages = [
{
"role" : "user" ,
"content" : "Say this is a test" ,
}
],
model = "gpt-4o" ,
) as response :
print ( response . headers . get ( "X-My-Header" ))
for line in response . iter_lines ():
print ( line )需要上下文管理器才能可靠地关闭响应。
该库的类型是为了方便访问记录的 API。
如果您需要访问未记录的端点、参数或响应属性，仍然可以使用该库。
要向未记录的端点发出请求，您可以使用client.get 、 client.post和其他 http 动词发出请求。提出此请求时，将尊重客户端的选项（例如重试）。
import httpx
response = client . post (
"/foo" ,
cast_to = httpx . Response ,
body = { "my_param" : True },
)
print ( response . headers . get ( "x-foo" ))如果您想显式发送额外参数，可以使用extra_query 、 extra_body和extra_headers请求选项来实现。
要访问未记录的响应属性，您可以访问额外的字段，例如response.unknown_prop 。您还可以使用response.model_extra将 Pydantic 模型上的所有额外字段作为字典获取。
您可以直接重写 httpx 客户端以根据您的用例对其进行自定义，包括：
from openai import OpenAI , DefaultHttpxClient
client = OpenAI (
# Or use the `OPENAI_BASE_URL` env var
base_url = "http://my.test.server.example.com:8083/v1" ,
http_client = DefaultHttpxClient (
proxies = "http://my.test.proxy.example.com" ,
transport = httpx . HTTPTransport ( local_address = "0.0.0.0" ),
),
)您还可以使用with_options()根据每个请求自定义客户端：
client . with_options ( http_client = DefaultHttpxClient (...))默认情况下，只要客户端被垃圾收集，库就会关闭底层 HTTP 连接。如果需要，您可以使用.close()方法手动关闭客户端，或者使用退出时关闭的上下文管理器。
要将此库与 Azure OpenAI 一起使用，请使用AzureOpenAI类而不是OpenAI类。
重要的
Azure API 形状与核心 API 形状不同，这意味着响应/参数的静态类型并不总是正确的。
from openai import AzureOpenAI
# gets the API Key from environment variable AZURE_OPENAI_API_KEY
client = AzureOpenAI (
# https://learn.microsoft.com/azure/ai-services/openai/reference#rest-api-versioning
api_version = "2023-07-01-preview" ,
# https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal#create-a-resource
azure_endpoint = "https://example-endpoint.openai.azure.com" ,
)
completion = client . chat . completions . create (
model = "deployment-name" , # e.g. gpt-35-instant
messages = [
{
"role" : "user" ,
"content" : "How do I output all files in a directory using Python?" ,
},
],
)
print ( completion . to_json ())除了基础OpenAI客户端中提供的选项外，还提供以下选项：
azure_endpoint （或AZURE_OPENAI_ENDPOINT环境变量）azure_deploymentapi_version （或OPENAI_API_VERSION环境变量）azure_ad_token （或AZURE_OPENAI_AD_TOKEN环境变量）azure_ad_token_provider可以在此处找到使用带有 Microsoft Entra ID（以前称为 Azure Active Directory）的客户端的示例。
该包通常遵循 SemVer 约定，尽管某些向后不兼容的更改可能会作为次要版本发布：
我们认真对待向后兼容性，并努力确保您可以获得流畅的升级体验。
我们热切希望得到您的反馈；请提出包含问题、错误或建议的问题。
如果您已升级到最新版本，但没有看到任何您期望的新功能，那么您的 python 环境可能仍在使用旧版本。
您可以通过以下方式确定运行时使用的版本：
import openai
print ( openai . __version__ )Python 3.8 或更高版本。
请参阅贡献文档。
