OpenAI Python SDK：安装、设置与实用集成

OpenAI Python SDK（PyPI 上的 openai）是 OpenAI API 的官方 Python 客户端。它负责处理认证、请求格式化、响应解析、流式传输和重试——因此您无需自行实现这些功能。本指南涵盖安装、核心 OpenAI 类、聊天补全、流式传输、函数调用、异步用法、JavaScript SDK 对应项、Azure OpenAI 集成，以及如何将同一 SDK 指向 Novita AI 的 OpenAI 兼容端点，以使用开放权重模型而无需重写代码。

安装 OpenAI Python 包

需要 Python 3.8 或更高版本：

pip install openai

对于开发环境，将其添加到 requirements.txt 或 pyproject.toml：

pip install openai>=1.0.0

1.x 版本（于 2023 年底发布）与 0.x API 的接口有显著变化。如果您要迁移旧代码，请注意 openai.ChatCompletion.create() 已不再使用；请改用 client.chat.completions.create()。

将 API 密钥设置为环境变量。不要将其放入源代码中：

export OPENAI_API_KEY="sk-..."

OpenAI 客户端类

OpenAI 类是主要入口点。默认情况下，它会从 OPENAI_API_KEY 环境变量中读取 API 密钥，或者您可以显式传递它：

import os
from openai import OpenAI

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

该客户端管理连接池、重试和超时。您应创建一个实例并在整个应用程序中重复使用它，而不是每次请求都实例化。

初始化时可配置的选项：

参数	默认值	描述
api_key	OPENAI_API_KEY 环境变量	认证凭据
base_url	https://api.openai.com/v1	覆盖以用于代理或兼容 API
timeout	600 秒	每次请求的超时时间
max_retries	2	遇到速率限制错误时自动重试
http_client	无	用于代理或证书配置的自定义 httpx 客户端

聊天补全：基本请求

聊天补全是最常见的用例。messages 列表遵循与 API 相同的格式：一个表示对话的角色/内容字典列表：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个有用的编程助手。"},
        {"role": "user", "content": "Python 中列表和元组有什么区别？"},
    ],
    temperature=0.3,
    max_tokens=512,
)

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

响应是一个 ChatCompletion 对象。关键字段：

• response.choices[0].message.content — 文本响应
• response.usage.prompt_tokens — 输入消耗的 token 数
• response.usage.completion_tokens — 输出消耗的 token 数
• response.model — 处理请求的模型版本

对于生产环境，使用 max_tokens 以避免失控的生成成本，并在需要确定性输出时使用 temperature=0 或较低值。

流式响应

对于用户希望看到 token 逐个到达的交互式界面，请使用 stream=True：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "用通俗语言解释 Python 生成器。"},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

使用上下文管理器（with 语句）可确保迭代后正确关闭连接。.text_stream 属性生成纯文本字符串；.stream 生成原始事件对象（如果您需要每个块的元数据，如使用统计信息）。

如果需要在没有上下文管理器的情况下进行流式传输：

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "列出 5 条 Python 最佳实践。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

函数调用

函数调用允许模型决定何时调用函数并返回 JSON 参数对象。您的应用程序执行该函数，然后将结果发送回模型，以便模型将其纳入响应：

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "返回某个城市的当前天气。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，例如 'San Francisco'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "东京的天气怎么样？"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    # 在此处执行您的实际函数
    result = {"city": args["city"], "temperature": "18°C", "condition": "cloudy"}

    messages.append(choice.message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

当模型想要调用函数时，它会返回 finish_reason="tool_calls"。您运行该函数，将结果添加到消息列表中，然后发出第二个请求。这个两步循环是标准模式。

使用 AsyncOpenAI 进行异步操作

对于 FastAPI、基于 asyncio 的服务或任何受益于非阻塞 I/O 的代码，请使用 AsyncOpenAI：

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def get_response(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256,
    )
    return response.choices[0].message.content

async def main():
    result = await get_response("Python 中的 asyncio 是什么？")
    print(result)

asyncio.run(main())

AsyncOpenAI 是同步客户端的直接异步对应项；所有方法都是可等待的。这比使用 asyncio.to_thread 包装同步客户端更可取。

OpenAI JavaScript SDK

OpenAI JavaScript SDK（npm 上的 openai）与 Python 接口非常相似。安装它：

npm install openai

在 Node.js 中执行基本的聊天补全：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "你是一个有用的助手。" },
    { role: "user", content: "解释 JavaScript 中 promises 与 async/await 的区别。" },
  ],
  max_tokens: 512,
});

console.log(response.choices[0].message.content);

JavaScript 中的流式传输：

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "用三句话总结 fetch API。" }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(text);
}

JavaScript SDK 支持 Node.js 18+、Deno 和浏览器环境（尽管在浏览器中暴露 API 密钥是不安全的——请改用服务器端代理）。指向兼容 API 的 base_url 选项与 Python 中完全相同。

Azure OpenAI Python 集成

如果您使用的是 Azure OpenAI 服务而非直接 OpenAI API，请使用同一包中的 AzureOpenAI 客户端：

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

response = client.chat.completions.create(
    model="gpt-4o",  # 您在 Azure 中的部署名称
    messages=[
        {"role": "user", "content": "如何使用 Azure OpenAI 和 Python？"},
    ],
)

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

Azure 所需的环境变量：

• AZURE_OPENAI_API_KEY：您的 Azure 资源 API 密钥
• AZURE_OPENAI_ENDPOINT：您的端点 URL，例如 https://your-resource.openai.azure.com/

在 Azure OpenAI 中，model 参数指的是您的 部署名称，而不是底层模型名称。将 api_version 设置为您部署使用的 Azure API 版本（请查阅 Azure OpenAI 文档 了解当前支持的版本）。

使用 Microsoft Entra ID（前身为 Azure AD）进行身份验证而非 API 密钥：

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

切换到 Novita AI 的 OpenAI 兼容 API

Novita AI 在 https://api.novita.ai/openai 提供了一个 OpenAI 兼容端点。您可以使用相同的 openai Python 或 JavaScript SDK，只需更改 base_url 和 api_key。无需其他代码更改：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "你是一个有用的编程助手。"},
        {"role": "user", "content": "解释 Python 的 GIL 如何影响多线程。"},
    ],
    temperature=0.3,
    max_tokens=512,
)

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

从 novita.ai/settings/key-management 获取 Novita AI API 密钥。同一密钥适用于所有 Novita AI API，包括 OpenAI 兼容端点。

使用 Novita AI 的 JavaScript：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVITA_API_KEY,
  baseURL: "https://api.novita.ai/openai",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-coder-30b-a3b-instruct",
  messages: [{ role: "user", content: "编写一个 Python 类型注解速查表。" }],
  max_tokens: 600,
});

console.log(response.choices[0].message.content);

下游的所有内容——流式传输、函数调用、异步用法、response_format、temperature、max_tokens——都完全相同。Novita AI 端点遵循 OpenAI 聊天补全 API 规范。

通过 Novita AI 使用开源模型

交换 base_url 即可访问一个开放权重模型目录，这些模型在特定任务上已与闭源前沿模型具有竞争力。对于编码工作流、函数调用和长上下文推理，实际差距已显著缩小。

通过 Novita AI 的 OpenAI 兼容端点提供的值得评估的模型：

DeepSeek V4 Pro（deepseek/deepseek-v4-pro）：一个大型 MoE 模型（MIT 近似许可证），在 SWE-Bench 和函数调用基准测试中排名靠前。在编码代理、代码审查和多步骤工具使用任务中表现出色，这些任务中您原本会使用 GPT-4o 或 Claude Opus。

Qwen3 Coder 30B A3B Instruct（qwen/qwen3-coder-30b-a3b-instruct）：来自 Qwen Coder 系列的 30B 稀疏 MoE 模型，针对代码生成、错误分类和拉取请求审查进行了优化。在 Novita AI 上，每 100 万输入 token 收费 0.07 美元，每 100 万输出 token 收费 0.27 美元，对于日常编码辅助，比大多数闭源 API 便宜得多。

Qwen3 235B A22B Instruct（qwen/qwen3-235b-a22b-instruct-2507）：一个大型 MoE 模型（Apache 2.0），具有强大的推理和多语言编码性能。适用于当前使用 GPT-4o 进行创意或复杂响应，但希望在大规模应用中降低每 token 成本的任务。

Novita AI 上的模型 ID 格式为 provider/model-name。您可以直接将其传递给 SDK 中的 model 参数。

一个适用于希望混合使用开源和闭源模型的团队的简单路由模式：

def get_client(use_novita: bool = False) -> OpenAI:
    if use_novita:
        return OpenAI(
            api_key=os.environ["NOVITA_API_KEY"],
            base_url="https://api.novita.ai/openai",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# 对成本敏感、高容量的编码任务使用开放权重模型
coding_client = get_client(use_novita=True)

# 在闭源模型确实更好的任务上使用 OpenAI
openai_client = get_client(use_novita=False)

这使您可以进行输出质量 A/B 测试、按任务性能基准测试，并在不触及请求逻辑的情况下将流量转移到更便宜的模型上。

常见问题解答

OpenAI Python 包的名称是什么？

PyPI 上的包名是 openai。使用 pip install openai 安装。

OpenAI 客户端 Python 类叫什么？

用于同步使用的主类是 OpenAI，用于异步使用的是 AsyncOpenAI。两者都在 openai 模块中：from openai import OpenAI, AsyncOpenAI。

OpenAI Python SDK 是否支持流式传输？

是的。使用 client.chat.completions.stream() 作为上下文管理器，或者将 stream=True 传递给 client.chat.completions.create() 并迭代数据块。

OpenAI JavaScript SDK 的包名是什么？

npm 包是 openai。使用 npm install openai 安装。类和方法签名与 Python SDK 几乎相同。

如何在 Python 中使用 Azure OpenAI？

使用 openai 包中的 AzureOpenAI 类。传递 azure_endpoint、api_key 和 api_version。model 参数指的是您的 Azure 部署名称，而不是底层模型。

我可以将 OpenAI Python SDK 与其他提供商一起使用吗？

可以。任何实现 OpenAI 聊天补全 API 格式的提供商都可以通过设置客户端的 base_url 来使用。Novita AI 在 https://api.novita.ai/openai 的端点就是一个例子；完整的 SDK 功能集——流式传输、函数调用、异步——无需更改即可工作。

如何确保我的 OpenAI API 密钥安全？

将密钥存储在环境变量（OPENAI_API_KEY）中，并使用 os.environ["OPENAI_API_KEY"] 读取它。切勿将其放入源代码、公共仓库、构建日志或客户端 JavaScript 中。

推荐文章

• Novita AI 现已支持 OpenAI Agents SDK！ — 将 Novita AI 模型连接到 OpenAI Agents SDK，实现多代理编排、护栏和追踪。
• Qwen3 Coder 30B A3B Instruct 快速入门 — 此经济高效的编码模型在 Novita AI 上的模型 ID、定价、上下文窗口和 API 示例。
• Vercel AI SDK：构建 AI 应用的完整开发者指南 — 使用 Vercel AI SDK 和 Novita AI 的 OpenAI 兼容端点，在 TypeScript 中实现流式传输、工具调用和代理循环。