CosyVoice 安装 openai-whisper 报错 ModuleNotFoundError: No module named pkg_resources 解决方法

解决方案

推荐使用源码安装，并在安装时禁用构建隔离：

git clone https://github.com/openai/whisper.git
cd whisper
git checkout v20231117
pip install -e . --no-build-isolation

技术原理解析

问题根源分析

问题的关键在于 PEP 517/518 构建隔离机制和你的 setup.py 实现方式。

1. 构建隔离机制 (Build Isolation) 的工作原理

当你执行 pip install -e .（不带 --no-build-isolation）时，pip 会：

1. 创建一个临时的、干净的虚拟环境（在 /tmp/pip-build-env-xxx/）
2. 在这个隔离环境中只安装 pyproject.toml 中 [build-system] 要求的包
3. 在隔离环境中执行构建（运行 setup.py）
4. 将构建产物安装到你的目标环境

2. 为什么你的构建会失败

看你的 setup.py 第 5 行：

import pkg_resources # 这行在构建的早期阶段就需要

问题出在第 30 行附近：

install_requires=requirements +[str(r)for r in pkg_resources.parse_requirements(open(os.path.join(os.path.dirname(__file__),"requirements.txt")))]

关键问题：pkg_resources.parse_requirements() 在模块导入级别就被执行了！

这意味着：

Python 在解析 setup.py 时，立即执行了 import pkg_resources
但在隔离的构建环境中，默认没有安装 setuptools
因此 pkg_resources 不存在，导致 ModuleNotFoundError

3. 构建环境 vs 目标环境的区别

┌─────────────────────┐ ┌─────────────────────┐
│ 目标虚拟环境         │ │ 隔离构建环境         │
│ (cosyvoice)         │ │ (临时)               │
├─────────────────────┤ ├─────────────────────┤
│ ✓ setuptools 81.0.0 │ │ ✗ setuptools 未安装 │
│ ✓ pkg_resources     │ │ ✗ pkg_resources     │
│ ✓ 所有项目依赖      │ │ 只有构建基础包       │
└─────────────────────┘ └─────────────────────┘
↑ ↑
└────── pip install -e . ──────┘
需要同时满足两者

为什么 `--no-build-isolation` 能解决

pip install -e . --no-build-isolation

这个命令告诉 pip：不要创建隔离的构建环境，直接在当前激活的虚拟环境中构建

于是流程变成：

┌─────────────────────┐
│ 目标虚拟环境         │
│ (cosyvoice)         │
├─────────────────────┤
│ ✓ setuptools 81.0.0 │ ←── 直接在同一个环境中执行构建
│ ✓ pkg_resources     │    和安装
│ ✓ 所有项目依赖      │
└─────────────────────┘
↓
pip install -e . (无隔离环境)

因为你的虚拟环境中已经有 setuptools，所以 import pkg_resources 可以成功执行。

更好的修复方式

虽然 --no-build-isolation 解决了问题，但更好的做法是修改 setup.py，使其在隔离环境中也能工作：

import os
import platform
import sys
from setuptools import find_packages, setup

# 延迟导入 pkg_resources，或使用 try/except
def get_install_requires():
    """延迟解析 requirements.txt，避免构建时依赖"""
    requirements = []
    if sys.platform.startswith("linux") and platform.machine() == "x86_64":
        requirements.append("triton>=2.0.0,<3")
    
    # 只在需要时导入 pkg_resources
    try:
        import pkg_resources
        req_file = os.path.join(os.path.dirname(__file__), "requirements.txt")
        with open(req_file, encoding="utf-8") as f:
            requirements.extend([str(r) for r in pkg_resources.parse_requirements(f)])
    except ImportError:
        # 降级方案：简单读取 requirements.txt
        req_file = os.path.join(os.path.dirname(__file__), "requirements.txt")
        with open(req_file, encoding="utf-8") as f:
            requirements.extend([
                line.strip()
                for line in f
                if line.strip() and not line.startswith("#")
            ])
    return requirements

def read_version(fname="whisper/version.py"):
    exec(compile(open(fname, encoding="utf-8").read(), fname, "exec"))
    return locals()["__version__"]

setup(
    name="openai-whisper",
    py_modules=["whisper"],
    version=read_version(),
    description="Robust Speech Recognition via Large-Scale Weak Supervision",
    long_description=open("README.md", encoding="utf-8").read(),
    long_description_content_type="text/markdown",
    readme="README.md",
    python_requires=">=3.8",
    author="OpenAI",
    url="https://github.com/openai/whisper",
    license="MIT",
    packages=find_packages(exclude=["tests*"]),
    install_requires=get_install_requires(),  # 使用函数延迟解析
    entry_points={"console_scripts": ["whisper=whisper.transcribe:cli"]},
    include_package_data=True,
    extras_require={"dev": ["pytest", "scipy", "black", "flake8", "isort"]},
)

总结

问题	原因	解决方案
`ModuleNotFoundError: No module named 'pkg_resources'`	构建隔离环境中没有 setuptools，但 `setup.py` 在模块级别导入 pkg_resources	1. ✅ `--no-build-isolation` 跳过隔离环境 2. 修改 `setup.py` 延迟导入 pkg_resources

你使用的 --no-build-isolation 是完全正确的临时解决方案。对于长期使用，可以考虑向项目提交 PR 修改 setup.py，使其构建时不需要预先存在的 setuptools。