Windows下mediapipe-model-maker安装报错分析与WSL解决方案

1. 当你在Windows上安装mediapipe-model-maker时，到底发生了什么？

如果你正在尝试在Windows电脑上，通过一个简单的pip install mediapipe-model-maker命令来搭建一个AI模型训练环境，结果却被满屏的红色错误日志当头一棒，那么恭喜你，你绝对不是一个人。我刚开始接触这个库的时候，也在这个坑里挣扎了好几个小时。那个经典的“Getting requirements to build wheel ... error”报错，就像一堵墙，把很多想在Windows原生环境下玩转MediaPipe Model Maker的开发者挡在了门外。

简单来说，mediapipe-model-maker是Google推出的一套神器，它能让你用很少的代码，就基于MediaPipe框架训练出定制化的视觉模型，比如图像分类、手势识别什么的，对想快速入门AI应用开发的朋友特别友好。但问题就出在它的“出生环境”上。这个库，以及它依赖的庞大生态（尤其是TensorFlow），在Linux系统下被“养育”得最好，对Windows的支持则充满了各种隐形的“坑”。你看到的那个报错，表面上是构建wheel包（一种Python安装包格式）时获取依赖失败，但根子里，是Windows的Python环境、编译工具链和这个库的底层依赖之间的一场“水土不服”的混战。

我们来看看你贴出来的错误日志里藏着的几个关键“罪犯”。首先，日志里提到了PyYAML和setuptools的警告和问题。PyYAML是一个用来解析YAML配置文件的库，很多项目用它来管理配置。在Windows上，某些版本的PyYAML在编译时可能会遇到问题。而setuptools是Python打包和分发工具的核心，它的版本不兼容或某些已弃用的功能（比如日志里警告的License分类器）有时会触发意想不到的构建流程中断。

但最致命的线索藏在最后几行：AttributeError: cython_sources。Cython是一个将Python代码转换成C代码的工具，能极大提升性能。很多底层库（包括MediaPipe和TensorFlow的某些部分）都用到了它。在Windows上，pip安装某些包时，如果这个包包含Cython扩展，系统会尝试从源代码编译。这个过程需要一套完整的C/C++编译环境（比如Visual Studio Build Tools），并且对路径、环境变量、依赖库版本极其敏感。你的错误表明，在构建过程的某个环节，系统找不到或者无法正确处理Cython相关的源代码文件，导致整个构建链条崩溃。

所以，这不仅仅是“这个包装不上”的问题，而是Windows环境下Python生态与深度学习底层库原生编译需求之间的结构性矛盾。你尝试升级、降级setuptools、PyYAML，或者安装特定版本的Cython，可能偶尔会解决一次，但下次更新，或者换一台电脑，问题很可能卷土重来。这种不稳定性，对于需要稳定环境进行开发和实验的项目来说，是难以接受的。

2. 为什么WSL成了Windows玩家的“救命稻草”？

既然在Windows原生环境里“修修补补”这么痛苦，有没有一种一劳永逸的解决方案呢？有，而且它几乎是目前Windows上进行Python AI开发的最佳实践之一，这就是Windows Subsystem for Linux，简称WSL。你可以把它理解成在你Windows电脑内部，合法合规地运行的一个完整的、轻量级的Linux系统。它不是一个虚拟机（虽然效果类似），所以性能损耗非常小，却能让你直接使用Linux的命令行、软件包管理工具（如apt）和文件系统。

为什么WSL能解决mediapipe-model-maker的安装问题？核心原因有三点，这三点直指Windows原生环境的痛点：

第一，原生的Linux内核与环境。 mediapipe-model-maker及其依赖的TensorFlow等库，其官方构建、测试和持续集成环境首要目标就是Linux。在WSL的Linux环境（比如Ubuntu）里安装，pip调用的是为Linux平台预编译好的wheel包，或者利用Linux下成熟稳定的GCC编译工具链进行源代码编译，避开了Windows MSVC编译器可能带来的各种诡异问题。那个困扰你的cython_sources错误，在Linux原生编译环境下出现的概率会大大降低，因为工具链是匹配的。

第二，精准的Python版本控制。 错误提示里虽然没有明说，但一个关键信息是：“因为这个依赖 Tensorflow，Tensorflow不支持太高版本的 Python”。这是一个非常重要的背景知识。TensorFlow作为一个庞大的框架，其对Python版本的支持是有严格窗口期的。例如，TensorFlow 2.10可能最高只支持到Python 3.10，而你的Windows环境里如果已经装了Python 3.11或3.12，就会导致不兼容。在WSL里，你可以非常干净地安装一个指定的Python版本（比如Python 3.10），并用python3.10和pip3.10来精确管理这个环境，不会和你Windows主机上其他版本的Python产生任何冲突。

第三，隔离且干净的依赖管理。 在Windows上，各种Python包全局安装，或者不同项目环境通过Anaconda交织，容易引发依赖地狱（Dependency Hell）。WSL提供了一个全新的、独立的空间。你可以在里面用venv或virtualenv创建纯净的虚拟环境，所有操作都在这个“沙盒”里进行，装坏了删掉环境重来就是，完全不会污染你的Windows主系统。

我自己的经历就是这样，在Windows上折腾了半天setuptools、Cython的版本，甚至重装了Visual Studio Build Tools，问题依旧时断时续。直到切换到WSL下的Ubuntu，一条pip install mediapipe-model-maker命令，几分钟就安静地装好了，那种顺畅感让人如释重负。这不仅仅是解决了一个安装错误，更是为你后续的模型训练、调试铺平了一条稳定得多的道路。

3. 手把手带你从零配置WSL与Python环境

好了，理论说了这么多，咱们直接上干货。如果你还没用过WSL，别担心，跟着下面的步骤走，从启用功能到装好mediapipe-model-maker，大概二三十分钟就能搞定。整个过程就像搭积木，一步一个脚印。

3.1 启用并安装WSL

首先，我们需要在Windows上打开WSL功能。这是微软官方支持的功能，完全合法合规。

1. 以管理员身份打开Windows PowerShell。你可以在开始菜单搜索“PowerShell”，右键选择“以管理员身份运行”。
2. 输入以下命令并回车：

   wsl --install
   

   这个命令会默认安装WSL 2和Ubuntu发行版。如果你的网络顺畅，它会自动下载并安装。安装完成后，系统会提示你重启电脑。
3. 重启电脑后，你会在开始菜单里看到一个新的“Ubuntu”应用图标。点击它，它会完成最后的初始化设置，让你创建一个Linux用户名和密码。这个账号是WSL子系统的管理员（sudo用户），密码输入时是看不见的，正常输入后回车即可。

至此，你的电脑里就拥有了一个完整的Ubuntu Linux环境。你可以通过“Ubuntu”应用访问它的命令行界面。

3.2 在WSL中配置Python 3.10虚拟环境

进入Ubuntu命令行后，我们首先要更新软件包列表，并安装我们需要的Python版本。

1. 更新系统包管理器：

   sudo apt update && sudo apt upgrade -y
   

   这能确保我们接下来安装的软件都是最新版本。

2. 安装Python 3.10和必要的工具： Ubuntu的默认仓库可能已经包含了Python 3.10。我们直接安装它，同时装上Python虚拟环境管理工具python3-venv和pip。

   sudo apt install python3.10 python3.10-venv python3-pip -y
   

   安装完成后，可以用python3.10 --version检查一下版本。

3. 创建一个专用于mediapipe的虚拟环境： 我强烈建议为每个项目创建独立的虚拟环境，这是Python开发的好习惯。

   # 先导航到你打算存放项目的目录，比如家目录下的projects文件夹
   cd ~
   mkdir -p projects/mediapipe_demo
   cd projects/mediapipe_demo
   
   # 创建名为‘mp_env’的虚拟环境
   python3.10 -m venv mp_env
   

4. 激活虚拟环境：

   source mp_env/bin/activate
   

   激活后，你的命令行提示符前面通常会显示(mp_env)，表示你现在已经在这个纯净的“沙盒”里了。接下来所有pip安装的包，都会只存在于这个环境中。

3.3 安装mediapipe-model-maker及其依赖

现在，我们来到了最激动人心的环节。在激活的虚拟环境中，执行安装命令。

1. 首先，升级pip和setuptools到较新版本（这步在Linux下通常很安全，能避免一些基础问题）：

   pip install --upgrade pip setuptools wheel
   

2. 安装mediapipe-model-maker：

   pip install mediapipe-model-maker
   

   静静等待即可。你会看到pip从网络下载各种依赖包，包括tensorflow、mediapipe等等。在WSL的Linux环境下，这个过程绝大多数情况下都会非常顺利，因为它下载的是针对Linux平台预编译好的二进制包（文件后缀为manylinux的whl文件），无需本地编译。

3. 验证安装： 安装完成后，我们可以写一个最简单的脚本来测试。 创建一个Python文件，比如叫test_install.py：

   nano test_install.py
   

   在打开的编辑器里输入：

   import mediapipe as mp
   from mediapipe_model_maker import image_classifier
   
   print("MediaPipe version:", mp.__version__)
   print("Model Maker module imported successfully!")
   

   按Ctrl+X，然后按Y，再回车保存退出。 运行这个脚本：

   python test_install.py
   

   如果输出显示了MediaPipe的版本号和成功导入的信息，那么恭喜你，安装大功告成！

4. 避坑指南与进阶操作

虽然WSL方案已经规避了大部分问题，但在实际使用中，还是有一些细节需要注意，能让你体验更顺畅。

4.1 可能遇到的WSL内安装小问题及解决

• 网络问题导致下载慢或失败：由于默认源可能在海外，pip安装大型包（如TensorFlow）时可能很慢。可以考虑在WSL内配置国内的PyPI镜像源。临时使用可以在pip install时加-i参数，例如：

  pip install mediapipe-model-maker -i https://pypi.tuna.tsinghua.edu.cn/simple
  

  如果想永久更改，可以创建或修改~/.pip/pip.conf文件。

• 磁盘空间不足：WSL默认安装在C盘。如果你C盘空间紧张，在安装大量Python包（尤其是TensorFlow这种大家伙）后可能会告急。你可以考虑将WSL分发版迁移到其他盘符，具体命令可查阅微软官方文档关于wsl --export和wsl --import的用法。

• 与Windows的文件系统交互：你可以在WSL中通过/mnt/c/路径访问Windows的C盘。这意味着你完全可以在Windows下用喜欢的编辑器（如VSCode）写代码，然后在WSL环境里运行。安装VSCode的“Remote - WSL”扩展后，体验会更无缝。

4.2 为什么不用Docker或双系统？

你可能会想，除了WSL，不是还有Docker或者直接装双系统这些选择吗？这里简单分析一下：

• Docker：功能更强大，隔离性更彻底，镜像可以确保环境完全一致。但对于刚入门、只是想快速安装一个库并开始实验的开发者来说，Docker的学习曲线稍陡，需要理解镜像、容器、挂载卷等概念。WSL更像是一个“开箱即用”的轻量级Linux终端，对于Python/pip工作流来说更直接。
• 双系统：彻底的解决方案，性能无损。但缺点是需要重启电脑切换系统，对于需要频繁在Windows（处理文档、沟通）和Linux（开发）之间切换的场景很不方便。WSL实现了两者并存，随时切换。

所以，对于在Windows上进行AI模型快速原型开发的个人或小团队，WSL在易用性、性能和对原生Windows生态的访问性上，取得了非常好的平衡。

4.3 开始你的第一个Model Maker项目

环境搭好了，不跑个例子说不过去。这里给你一个超简单的图像分类器训练流程，感受一下Model Maker的便捷。假设你已经收集了一些图片，分门别类放在不同的文件夹里（例如dataset/train/roses/, dataset/train/tulips/）。

在你的WSL项目目录下（虚拟环境已激活），创建一个训练脚本train.py：

from mediapipe_model_maker import image_classifier
import tensorflow as tf

# 指定数据路径，假设你的数据集在Windows的D盘，在WSL中路径可能是 /mnt/d/dataset/
data_path = "/mnt/d/dataset/"

# 加载数据
data = image_classifier.Dataset.from_folder(data_path)
train_data, rest_data = data.split(0.8)
validation_data, test_data = rest_data.split(0.5)

# 配置模型选项
options = image_classifier.ImageClassifierOptions(
    supported_model=image_classifier.SupportedModels.MOBILENET_V2,
    hparams=image_classifier.HParams(epochs=10, batch_size=32), # 先少训练几轮看看效果
    model_options=image_classifier.ModelOptions(dropout_rate=0.2)
)

# 创建并训练模型
model = image_classifier.ImageClassifier.create(
    train_data=train_data,
    validation_data=validation_data,
    options=options
)

# 在测试集上评估
loss, accuracy = model.evaluate(test_data)
print(f"测试集损失: {loss}, 测试集准确率: {accuracy}")

# 导出模型，可以用于后续推理
model.export_model('my_flower_model.tflite')
print("模型已导出为 my_flower_model.tflite")

运行这个脚本，你就能亲眼看到模型开始训练。整个过程，你几乎不需要关心复杂的神经网络层设计、优化器选择，Model Maker已经把很多最佳实践封装好了。这种“高阶API”的体验，正是它吸引人的地方。

从在Windows原生环境里面对一堆编译错误束手无策，到在WSL里顺畅地安装并跑起第一个训练demo，这个转变的核心，其实就是选择了一个对开发者更友好的底层环境。AI开发的工具链本身已经足够复杂，我们不应该再把时间浪费在解决环境配置这种基础问题上。WSL提供了一条绕过Windows下诸多深坑的捷径。当然，这并不意味着你要完全抛弃Windows，你依然可以享受Windows的图形界面和办公软件，只是在需要运行AI代码时，轻轻点开那个Ubuntu终端。这种混合开发模式，已经成为越来越多Windows平台技术开发者的标准配置。下次当你遇到其他在Windows上难以安装的Python科学计算或AI库时，不妨也先想想：要不，试试WSL？