企业官网建设流程全解析

MediaPipe 安装与上手指南：跨平台人脸、手势与分割，一条命令装好

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe

MediaPipe 是 Google 开源的跨平台机器学习框架，主打实时媒体处理：在一张图片上定位人脸 468 个 3D 关键点、检测手势、分割前景。对绝大多数读者，整个安装过程只有一条命令：pip install mediapipe。当前仓库版本为1.1.0，依据是 mediapipe/version.bzl 中的MEDIAPIPE_FULL_VERSION声明。

先定路线：pip 装好还是源码编译？

本节解决什么问题：30 秒判断你该走哪条路，避免走错返工。

一句话分支：不改源码 → 走主线；要改 → 见备选路线。

动手前体检：四张表查完再装

本节解决什么问题：装之前确认环境和依赖没有硬伤，把报错挡在发生之前。

主线操作：三步装好，十分钟验证

本节解决什么问题：在 Python 场景下用最少的命令完成安装，每步都有可观察的成功信号。

第 1 步：建一个干净的虚拟环境（虚拟环境 = 互相隔离的独立 Python 包空间）。

python3 -m venv mp_env && source mp_env/bin/activate

检查点：命令行提示符前出现(mp_env)前缀；没有它说明环境没激活，后面装的东西会进错地方。

第 2 步：安装 MediaPipe 核心包。

pip install mediapipe

检查点：pip 结尾打印Successfully installed mediapipe-x.x.x ...，且依赖（numpy、opencv-contrib-python 等）一并装完，无红色 ERROR。

第 3 步：确认模块能导入、版本号正常。

python3 -c "import mediapipe as mp; print(mp.__version__, mp.solutions)"

检查点：终端打印一个版本号加solutions模块对象，全程没有 Traceback。若报No matching distribution found，直接跳到下文故障定位第 1 条。

第 4 步：把模型文件放到手边。验收用的 FaceLandmarker 需要一个.task模型文件（MediaPipe 的可执行模型包），官方提供下载入口，放到你准备运行脚本的目录即可；文件名按示例命名为face_landmark.task。

检查点：脚本所在目录下能看到face_landmark.task。

第 5 步：跑验收脚本。脚本见下一节，把它保存到本地任意目录后运行。

检查点：脚本按预期打印判定结果（标准见下一节）。

十分钟验证：最短脚本确认装好了

本节解决什么问题：用一段最短可运行脚本，把"装好了"从感觉变成事实。

把下面内容存为check_mediapipe.py（与face_landmark.task放在同一目录），再运行python3 check_mediapipe.py：

import mediapipe as mp image = mp.Image.create_from_file("test.jpg") options = mp.tasks.vision.FaceLandmarkerOptions( base_options=mp.tasks.BaseOptions(model_asset_path="face_landmark.task"), num_faces=1) with mp.tasks.vision.FaceLandmarker.create_from_options(options) as det: result = det.detect(image) print("OK: 检测到", len(result.face_landmarks), "张脸") if result.face_landmarks else print("NO_FACE")

判定标准：

• 图里有人脸且打印OK: 检测到 1 张脸→ 安装成功；
• 打印NO_FACE但无异常 → 模块可用，换一张含人脸的图再跑一次；
• 报找不到模型文件 →face_landmark.task没就位，下载后放到脚本同目录；也可以先用内置模型的mp.solutions.face_detection验证导入是否正常。

test.jpg可以用仓库里现成的测试图（如 mediapipe/examples/desktop/autoflip/quality/testdata/google.jpg）复制到本地代替。

备选路线：源码编译（不定制可跳过本节）

不定制、不贡献、不改图的话，跳过本节即可；官方文档的明确建议是"没有本地改动时，强烈建议直接pip install mediapipe，更快更省事"（见 docs/getting_started/python.md）。只有本地有改动、必须重建 Python 包时才走这条路。

第 1 步：克隆仓库并进入根目录。

git clone --depth 1 https://gitcode.com/GitHub_Trending/med/mediapipe mediapipe cd mediapipe

检查点：当前目录下能看到 BUILD.bazel（顶层 Bazel 构建文件）、setup.py、WORKSPACE 等文件。

第 2 步：装系统依赖（Debian/Ubuntu 示例；macOS 对应brew install protobuf cmake）。

sudo apt install python3-dev python3-venv protobuf-compiler sudo apt install cmake

检查点：python3-config --includes与bazel --version都能正常输出。

第 3 步：虚拟环境里装 Python 依赖，然后编译安装。

python3 -m venv mp_env && source mp_env/bin/activate pip install -r requirements.txt python3 setup.py install --link-opencv

检查点：命令正常退出后，python3 -c "import mediapipe"不再报错。

⚠️ 为什么别在你改代码的目录里直接编译：setup.py 构建时会临时改写mediapipe/__init__.py和 third_party/BUILD（不带--link-opencv时会把 OpenCV 规则换成静态源码构建），并留下.backup文件。如果你同时用这份克隆提交贡献，先确认编译结束、文件已还原，或者另开一份干净克隆，避免把临时改动带进补丁。

--link-opencv表示链接你系统里已装好的 OpenCV；首次 Bazel 构建耗时较长，属正常现象。

故障定位：四个高频报错的根因与修法

本节解决什么问题：报错不再逐字 Google，按"原文 → 根因 → 修复"三段对号入座。

1.ERROR: Could not find a version that satisfies the requirement mediapipe

• 根因：PyPI 上没有匹配你系统的轮子，典型是 32 位 Python、Python 版本超出 3.9–3.14，或平台在 aarch64 Linux 上；官方支持的只有 64 位 x86_64 Linux、x86_64 macOS 10.15+ 与 amd64 Windows（见 docs/getting_started/troubleshooting.md 同目录 troubleshooting 文档的 "Python pip install failure" 一节）。
• 修复：换 64 位 Python 3.9–3.14 并确认pip --version指向它；仍不行就改走备选路线源码编译。

2.ERROR: An error occurred during the fetch of repository 'local_execution_config_python'

• 根因：Bazel 找不到本地 Python 解释器。
• 修复：在 Bazel 命令后追加--action_env PYTHON_BIN_PATH=$(which python3)，官方排错文档给了同样示例。

3.undefined reference to 'cv::String::deallocate()'（后面跟一串cv::符号）

• 根因：Bazel 没按你的 OpenCV 版本配好头文件路径；OpenCV 2/3 默认配置开箱可用，OpenCV 4 需要按 docs/getting_started/install.md 修改third_party/opencv_linux.BUILD，按gcc -print-multiarch的输出取消对应多架构头文件行的注释。
• 修复：按上述文档调整opencv_linux.BUILD（在自己的本地克隆中操作）后重新编译。

4. Windows 上ImportError: DLL load failed: The specified module could not be found

• 根因：系统缺少 Visual C++ 运行时。
• 修复：安装微软官方vc_redist.x64.exe；或先pip install msvc-runtime临时补上运行时库。

接下来去哪：三条延伸路径

本节解决什么问题：装好之后，按目标找到正确的下一步文档。

• 想在 Python 里搭建自己的计算图：读 docs/getting_started/python_framework.md；
• 想跑 C++ Hello World 验证桌面环境：按 docs/getting_started/hello_world_cpp.md 执行bazel run mediapipe/examples/desktop/hello_world:hello_world，终端连续打印Hello World!即成功；
• 想理解整个项目的编译入口：从 setup.py（驱动 Python 包构建）和 BUILD.bazel（顶层 Bazel 构建文件）读起，排错细节查 docs/getting_started/troubleshooting.md。

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe