【BUG已解决】ImportError: cannot import name 'OpenAI' from 'openai' 解决方案

前言

本文主要介绍了 ImportError: cannot import name 'OpenAI' from 'openai' 解决方案，希望能对使用 Python 调用 OpenAI API 进行大模型开发的同学们有所帮助。这是 Python AI 开发中最常见的入门级报错之一，几乎每个刚接触 OpenAI SDK 的开发者都会踩到这个坑。

1. 问题描述

1.1 完整报错信息

在 Python 代码中写下如下导入语句：

from openai import OpenAI

client = OpenAI(api_key="sk-xxxxxxxx")

运行后立刻报错：

Traceback (most recent call last):
  File "test.py", line 1, in <module>
    from openai import OpenAI
ImportError: cannot import name 'OpenAI' from 'openai' (/usr/local/lib/python3.9/site-packages/openai/__init__.py)

1.2 具体现象

1. 按照官方文档或网上教程写代码，使用 from openai import OpenAI
2. 之前能正常运行的代码，某天突然报这个错（可能是环境被重装或依赖被自动更新）
3. pip install openai 明明显示"安装成功"，但导入仍然失败
4. 在 Jupyter Notebook 中导入正常，在终端运行脚本却报错（或反过来）
5. 团队中一个人的代码能跑，换一台电脑就报错

1.3 报错发生的版本对照

这个问题本质上是 OpenAI Python SDK v0.x 和 v1.x 的 API 设计发生了重大变化：

SDK 版本	调用方式	是否支持 from openai import OpenAI
v0.28.x 及更早	模块级函数调用	❌ 不支持（没有 OpenAI 类）
v1.0.0+	客户端实例调用	✅ 支持

如果你的环境中安装的是 v0.x 版本的 openai 包，代码里却用了 v1.x 的语法（from openai import OpenAI），就会触发这个 ImportError。

2. 原因分析

2.1 v0.x 与 v1.x 的 API 设计差异

v0.28.x（旧版）的调用方式：

import openai

openai.api_key = "sk-xxxxxxxx"

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

v1.x（新版）的调用方式：

from openai import OpenAI

client = OpenAI(api_key="sk-xxxxxxxx")

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

可以看到，v1.x 引入了面向对象的 OpenAI 客户端类，取代了 v0.x 的全局模块函数调用方式。这是一次破坏性升级（Breaking Change），两个版本的代码完全不兼容。

2.2 为什么会装到旧版本

原因	说明
requirements.txt 锁定旧版本	项目文件中写死了 openai==0.28.0
pip 缓存了旧版本	网络不好导致下载了缓存的旧包
conda 环境隔离问题	用了错误的 conda 环境，装到了另一个环境
教程/文档过时	网上很多2023年之前的教程仍教 v0.x 用法
requirements.txt 未指定版本	依赖了旧项目的 openai 固定版本

2.3 如何判断自己安装的是哪个版本

pip show openai
# 或
python -c "import openai; print(openai.__version__)"

输出示例：

Name: openai
Version: 0.28.1    ← 这就是旧版本，会触发 ImportError

3. 解决方案

3.1 方案一：升级到最新版 openai SDK（推荐）

# 卸载旧版本
pip uninstall openai -y

# 安装最新版本
pip install --upgrade openai

# 验证版本
python -c "import openai; print(openai.__version__)"
# 应输出 1.x.x

安装完成后，用新版语法：

from openai import OpenAI

client = OpenAI(api_key="sk-xxxxxxxx")

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

3.2 方案二：如果必须使用旧版本，改用旧版语法

有些项目因为历史原因锁定了旧版本（比如依赖了其他也用 openai 的库），不方便随意升级：

# 保持旧版本
pip show openai
# Version: 0.28.1

这种情况下改用旧版语法：

import openai

openai.api_key = "sk-xxxxxxxx"

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

3.3 方案三：使用虚拟环境隔离版本冲突

如果一个项目需要 v1.x，另一个项目需要 v0.x，用虚拟环境隔离：

# 使用 venv
python -m venv project_a_env
source project_a_env/bin/activate    # macOS/Linux
project_a_env\Scripts\activate       # Windows
pip install "openai>=1.0.0"

# 另一个项目
python -m venv project_b_env
source project_b_env/bin/activate
pip install "openai==0.28.1"

或使用 conda：

conda create -n project_a python=3.10
conda activate project_a
pip install openai

3.4 方案四：requirements.txt 明确指定版本

在项目的 requirements.txt 中明确写出版本号，避免团队成员安装不一致的版本：

# requirements.txt
openai>=1.0.0,<2.0.0

团队成员统一安装：

pip install -r requirements.txt

3.5 方案五：使用官方迁移工具自动升级代码

OpenAI 官方提供了从 v0.x 迁移到 v1.x 的自动化工具：

pip install openai==1.* 
openai migrate

这个命令会自动扫描项目代码，把 v0.x 语法转换为 v1.x 语法。

3.6 方案六：检查是否有多个 Python 环境冲突

# 确认当前使用的 Python 和 pip 是否匹配
which python
which pip
python --version
pip --version

# 有时候会出现 python 和 pip 对应不同的环境
# 用 python -m pip 确保操作的是当前 python 环境
python -m pip install --upgrade openai

3.7 方案七：Jupyter Notebook 特殊情况

Jupyter Notebook 使用的 Kernel 可能与终端的 Python 环境不一致：

# 在 Notebook 中检查实际使用的 Python
import sys
print(sys.executable)

# 在 Notebook 中直接安装（确保装到当前 kernel 使用的环境）
!{sys.executable} -m pip install --upgrade openai

4. 版本迁移对照表

如果你需要将旧代码迁移到新版本，以下是常用 API 的对照：

功能	v0.x 语法	v1.x 语法
初始化	openai.api_key = "..."	client = OpenAI(api_key="...")
对话补全	openai.ChatCompletion.create(...)	client.chat.completions.create(...)
文本补全	openai.Completion.create(...)	client.completions.create(...)
Embedding	openai.Embedding.create(...)	client.embeddings.create(...)
图片生成	openai.Image.create(...)	client.images.generate(...)
流式响应	stream=True 返回generator	stream=True 返回Stream对象
错误处理	openai.error.OpenAIError	openai.OpenAIError

5. 完整迁移示例

迁移前（v0.x）：

import openai

openai.api_key = "sk-xxxxxxxx"

try:
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "你是一个助手"},
            {"role": "user", "content": "你好"}
        ],
        temperature=0.7,
        stream=False
    )
    print(response.choices[0].message.content)
except openai.error.OpenAIError as e:
    print(f"Error: {e}")

迁移后（v1.x）：

from openai import OpenAI, OpenAIError

client = OpenAI(api_key="sk-xxxxxxxx")

try:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "你是一个助手"},
            {"role": "user", "content": "你好"}
        ],
        temperature=0.7,
        stream=False
    )
    print(response.choices[0].message.content)
except OpenAIError as e:
    print(f"Error: {e}")

6. 常见衍生问题

6.1 AttributeError: module 'openai' has no attribute 'ChatCompletion'

这是相反的情况：装了新版 SDK，却用了旧版语法：

AttributeError: module 'openai' has no attribute 'ChatCompletion'

解决：改用 client.chat.completions.create(...) 新版语法。

6.2 混用第三方库导致的冲突

一些第三方库（如 LangChain 的旧版本）内部依赖 openai==0.28.x：

# 检查依赖冲突
pip check

# 如果 langchain 版本过旧，升级它
pip install --upgrade langchain langchain-openai

7. 常见问题 FAQ

7.1 升级后出现 proxies 参数报错

TypeError: Client.__init__() got an unexpected keyword argument 'proxies'

v1.x 的 OpenAI 类不再直接接受 proxies 参数，需要通过 httpx.Client 传入：

import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    http_client=httpx.Client(proxies="http://127.0.0.1:7890")
)

7.2 异步调用方式的变化

v0.x 异步调用：

response = await openai.ChatCompletion.acreate(...)

v1.x 异步调用：

from openai import AsyncOpenAI

client = AsyncOpenAI(api_key="sk-xxxxxxxx")
response = await client.chat.completions.create(...)

7.3 与 LangChain 集成时的版本对应关系

LangChain 版本	依赖的 openai 版本
langchain < 0.1.0	openai 0.28.x
langchain ≥ 0.1.0 + langchain-openai	openai ≥ 1.0.0

# 如果使用新版 LangChain，需要额外安装适配包
pip install langchain-openai

# 新版 LangChain 中调用 OpenAI 的方式
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4", api_key="sk-xxxxxxxx")

7.4 国产模型使用 OpenAI SDK 兼容接口时的注意事项

许多国产大模型（DeepSeek、月之暗面 Kimi、智谱GLM等）都提供了 OpenAI 兼容的 API 接口，使用新版 SDK 调用时：

from openai import OpenAI

# DeepSeek 示例
client = OpenAI(
    api_key="sk-your-deepseek-key",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

只要目标 API 兼容 OpenAI 的接口规范，直接替换 base_url 和 api_key 即可无缝切换，不需要更换 SDK。

7.5 如何在不确定环境的情况下写出兼容两个版本的代码

如果你的代码需要同时兼容新旧两个版本的环境（例如发布给不同用户使用），可以这样处理：

try:
    # 尝试新版语法
    from openai import OpenAI
    client = OpenAI(api_key="sk-xxxxxxxx")
    USE_NEW_API = True
except ImportError:
    # 降级到旧版语法
    import openai
    openai.api_key = "sk-xxxxxxxx"
    USE_NEW_API = False

def chat(messages):
    if USE_NEW_API:
        response = client.chat.completions.create(model="gpt-4", messages=messages)
        return response.choices[0].message.content
    else:
        response = openai.ChatCompletion.create(model="gpt-4", messages=messages)
        return response.choices[0].message.content

不过这种兼容写法增加了维护成本，长期来看还是建议统一升级到 v1.x，更符合社区主流实践和未来趋势。

8. 排查清单速查表

遇到这个错误时，按以下清单快速自查：

□ 1. pip show openai 确认版本号
□ 2. 如果是 0.x，执行 pip install --upgrade openai
□ 3. 确认虚拟环境/conda环境是否正确激活
□ 4. Jupyter用户检查 sys.executable 对应的环境
□ 5. 检查是否有其他库（如旧版LangChain）依赖了旧版openai
□ 6. requirements.txt 中锁定版本号，避免团队协作时版本不一致
□ 7. 升级后同步修改代码语法（client.chat.completions.create）

9. 总结

ImportError: cannot import name 'OpenAI' from 'openai' 的核心是版本不匹配：

1. 用 pip show openai 确认当前版本
2. 如果是 0.x 版本 → pip install --upgrade openai 升级到 1.x
3. 升级后代码语法要同步改为 from openai import OpenAI + client.chat.completions.create(...)
4. 团队协作项目务必在 requirements.txt 中锁定版本号，避免"我这能跑，你那不能跑"的问题
5. 对接国产模型时，只需替换 base_url 参数，SDK 调用方式完全一致

如果觉得本文对您有帮助，欢迎点赞收藏，让更多遇到同样问题的开发者能够快速找到解决方案。