OpenAI 知识点

OpenAI Python API 库

OpenAI Python 库提供了从任何 Python 3.7+ 应用程序方便访问 OpenAI REST API 的功能。该库包括所有请求参数和响应字段的类型定义，并提供由 httpx 支持的同步和异步客户端。

它是从我们的 OpenAPI 规范 使用 Stainless 生成的。

文档

REST API 文档可以在 platform.openai.com 上找到。该库的完整 API 可以在 api.md 中找到。

安装

[!重要] SDK 在 v1 中进行了重写，发布日期为 2023 年 11 月 6 日。请参阅 v1 迁移指南，其中包括自动更新代码的脚本。

# 从 PyPI 安装
pip install openai

使用方法

该库的完整 API 可以在 api.md 中找到。

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": "Say this is a test",
        }
    ],
    model="gpt-3.5-turbo",
)

虽然你可以提供一个 api_key 关键字参数，但我们建议使用 python-dotenv 将 OPENAI_API_KEY="My API Key" 添加到你的 .env 文件中，这样你的 API 密钥就不会存储在源代码控制中。

轮询助手

在与 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:
        # 打印文本从文本增量事件
        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"),
)

async def main() -> None:
    chat_completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Say this is a test",
            }
        ],
        model="gpt-3.5-turbo",
    )

asyncio.run(main())

同步和异步客户端的功能是相同的。

流式响应

我们提供对使用服务器端事件（SSE）的流式响应的支持。

from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Say this is a test"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

异步客户端使用完全相同的接口。

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

# 可选；默认为 `os.environ['OPENAI_API_KEY']`
openai.api_key = '...'

# 所有客户端选项都可以像 `OpenAI` 实例化对应项一样配置
openai.base_url = "https://..."
openai.default_headers = {"x-foo": "true"}

completion = openai.chat.completions.create(
    model="gpt-4",
    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 模型，它们还提供了用于诸如：

• 重新序列化回 JSON 的 model.to_json()
• 转换为字典的 model.to_dict()

类型化的请求和响应在编辑器中提供自动完成和文档。如果你想在 VS Code 中看到类型错误以帮助更早地捕获错误，请将 python.analysis.typeCheckingMode 设置为 basic。

分页

OpenAI API 中的列表方法是分页的。

该库为每个列表响应提供了自动分页迭代器，因此你不必手动请求后续页面：

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)

或者，异步：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main() -> None:
    all_jobs = []
    # 通过项目遍历所有页面，根据需要发出请求。
    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"将使用这些详细信息获取下一页：{first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"我们刚刚获取的项目数量：{len(next_page.data)}")

# 对于非异步使用，请删除 `await`。

或者直接使用返回的数据：

first_page = await client.fine_tuning.jobs.list(
    limit=20,
)

print(f"下一页光标：{first_page.after}")  # => "下一页光标：..."
for job in first_page.data:
    print(job.id)

# 对于非异步使用，请删除 `await`。

嵌套参数

嵌套参数是字典，使用 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-3.5-turbo-1106",
    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-3.5-turbo",
        training_file="file-abc123",
    )
except openai.APIConnectionError as e:
    print("无法访问服务器")
    print(e.__cause__)  # 一个底层异常，可能在 httpx 中引发。
except openai.RateLimitError as e:
    print("收到 429 状态码；我们应该稍微退后一点。")
except openai.APIStatusError as e:
    print("收到另一个非 200 范围的状态码")
    print(e.status_code)
    print(e.response)

错误代码如下：

状态码	错误类型
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

重试

默认情况下，某些错误会自动重试 2 次，并带有短暂的指数退避。连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制和 >=500 内部错误默认情况下都会重试。

你可以使用 max_retries 选项来配置或禁用重试设置：

from openai import OpenAI

# 为所有请求配置默认值：
client = OpenAI(
    # 默认值为 2
    max_retries=0,
)

# 或者，每个请求配置：
client.with_options(max_retries=5).chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "How can I get the name of the current day in Node.js?",
        }
    ],
    model="gpt-3.5-turbo",
)

超时

默认情况下，请求在 10 分钟后超时。你可以使用 timeout 选项进行配置，该选项接受浮点数或 httpx.Timeout 对象：

from openai import OpenAI

# 为所有请求配置默认值：
client = OpenAI(
    # 20 秒（默认值为 10 分钟）
    timeout=20.0,
)

# 更细粒度的控制：
client = OpenAI(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# 每个请求覆盖：
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-3.5-turbo",
)

超时时，将抛出 APITimeoutError。

请注意，默认情况下会重试两次超时的请求。

高级

日志记录

我们使用标准库 logging 模块。

你可以通过将环境变量 OPENAI_LOG 设置为 debug 来启用日志记录。

$ export OPENAI_LOG=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}.')

访问原始响应数据（例如标头）

可以通过在任何 HTTP 方法调用前添加前缀 .with_raw_response. 来访问“原始”响应对象，例如

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-3.5-turbo",
)
print(response.headers.get('X-My-Header'))

completion = response.parse()  # 获取 `chat.completions.create()` 将返回的对象
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-3.5-turbo",
) 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 请求选项。

未记录的响应属性

要访问未记录的响应属性，你可以访问 Pydantic 模型上的额外字段，例如 response.unknown_prop。你还可以使用 response.model_extra 将 Pydantic 模型上的所有额外字段作为字典获取。

配置 HTTP 客户端

你可以直接覆盖 httpx 客户端，以根据你的用例对其进行自定义，包括：

• 支持代理
• 自定义传输
• 其他高级功能

from openai import OpenAI, DefaultHttpxClient

client = OpenAI(
    # 或者使用 `OPENAI_BASE_URL` 环境变量
    base_url="http://my.test.server.example.com:8083",
    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 资源

默认情况下，当客户端被垃圾回收时，库会关闭底层的 HTTP 连接。如果需要，你可以使用 .close() 方法手动关闭客户端，或者使用在退出时关闭的上下文管理器。

Microsoft Azure OpenAI

要将此库与 Azure OpenAI 一起使用，请使用 AzureOpenAI 类而不是 OpenAI 类。

[!重要] Azure API 形状与核心 API 形状不同，这意味着响应/参数的静态类型不总是正确的。

from openai import AzureOpenAI

# 从环境变量 AZURE_OPENAI_API_KEY 获取 API 密钥
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",  # 例如 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_deployment
• api_version（或 OPENAI_API_VERSION 环境变量）
• azure_ad_token（或 AZURE_OPENAI_AD_TOKEN 环境变量）
• azure_ad_token_provider

使用 Microsoft Entra ID（以前称为 Azure Active Directory）的客户端示例可以在此处找到。

版本控制

该软件包通常遵循 SemVer 约定，尽管某些向后不兼容的更改可能作为次要版本发布：

1. 仅影响静态类型的更改，而不破坏运行时行为。
2. 对库内部的更改，这些内部技术上是公开的，但不是为外部使用而设计或记录的。（如果你依赖于这些内部，请开一个 GitHub issue 告诉我们）。
3. 我们不认为会影响大多数用户的更改。

我们非常重视向后兼容性，并努力确保你可以依赖平滑的升级体验。

我们期待你的反馈；请开一个 issue 提出问题、错误或建议。

要求

Python 3.7 或更高版本。