此页面由 Cloud Translation API 翻译。

问题排查

缺少 Python 二进制文件路径

错误消息：

ERROR: An error occurred during the fetch of repository 'local_execution_config_python':
  Traceback (most recent call last):
       File "/sandbox_path/external/org_tensorflow/third_party/py/python_configure.bzl", line 208
               get_python_bin(repository_ctx)
    ...
Repository command failed

这通常表示 Bazel 找不到本地 Python 二进制文件。要解决此问题，请先找到 Python 二进制文件的位置，然后将 --action_env PYTHON_BIN_PATH=<path to python binary> 添加到 Bazel 命令中。例如，您可以通过以下命令切换为使用系统默认的 python3 二进制文件：

bazel build -c opt \
  --define MEDIAPIPE_DISABLE_GPU=1 \
  --action_env PYTHON_BIN_PATH=$(which python3) \
  mediapipe/examples/desktop/hello_world

缺少必要的 Python 软件包

错误消息：

ImportError: No module named numpy
Is numpy installed?

通常表示未安装某些 Python 软件包。请根据您的 Python 二进制版本运行 pip install 或 pip3 install，以安装这些软件包。

未能提取远程依赖项仓库

错误消息：

ERROR: An error occurred during the fetch of repository 'org_tensorflow':
   java.io.IOException: Error downloading [https://mirror.bazel.build/github.com/tensorflow/tensorflow/archive/77e9ffb9b2bfb1a4f7056e62d84039626923e328.tar.gz, https://github.com/tensorflow/tensorflow/archive/77e9ffb9b2bfb1a4f7056e62d84039626923e328.tar.gz] to /sandbox_path/external/org_tensorflow/77e9ffb9b2bfb1a4f7056e62d84039626923e328.tar.gz: Tried to reconnect at offset 9,944,151 but server didn't support it

or

WARNING: Download from https://storage.googleapis.com/mirror.tensorflow.org/github.com/bazelbuild/rules_swift/releases/download/0.12.1/rules_swift.0.12.1.tar.gz failed: class java.net.ConnectException Connection timed out (Connection timed out)

通常表示 Bazel 无法下载 MediaPipe 所需的必要依赖项代码库。MedaiPipe 有几个由 Google 网站托管的依赖项代码库。在某些区域，您可能需要设置网络代理或使用 VPN 来访问这些资源。您可能还需要将 --host_jvm_args "-DsocksProxyHost=<ip address> -DsocksProxyPort=<port number>" 附加到 Bazel 命令。如需了解详情，请参阅此 GitHub 问题。

如果您认为这并不是网络问题，另一种可能是某些资源暂时不可用，请运行 bazel clean --expunge 并稍后重试。如果仍然无法解决问题，请提交 GitHub 问题并附上详细的错误消息。

MediaPipe OpenCV 配置不正确

错误消息：

error: undefined reference to 'cv::String::deallocate()'
error: undefined reference to 'cv::String::allocate(unsigned long)'
error: undefined reference to 'cv::VideoCapture::VideoCapture(cv::String const&)'
...
error: undefined reference to 'cv::putText(cv::InputOutputArray const&, cv::String const&, cv::Point, int, double, cv::Scalar, int, int, bool)'

这通常表示 OpenCV 未针对 MediaPipe 正确配置。请查看安装中的“安装 OpenCV 和 FFmpeg”部分，了解如何为本地 Opencv 库修改 MediaPipe 的工作区和 linux_opencv/macos_opencv/windows_opencv.BUILD 文件。此 GitHub 问题可能也会有所帮助。

Python pip 安装失败

错误消息：

ERROR: Could not find a version that satisfies the requirement mediapipe
ERROR: No matching distribution found for mediapipe

运行 pip install mediapipe 后，通常表示您的系统没有符合条件的 MediaPipe Python。请注意，MediaPipe Python PyPI 在以下操作系统上正式支持 64 位 Python 3.7 至 3.10 版本：

x86_64 Linux
x86_64 macOS 10.15 及更高版本
amd64 Windows

如果当前支持该操作系统，但您仍然看到此错误，请确保 Python 和 pip 二进制文件都适用于 Python 3.7 至 3.10。否则，请考虑按照此处的说明在本地构建 MediaPipe Python 软件包。

Windows 上的 Python DLL 加载失败

错误消息：

ImportError: DLL load failed: The specified module could not be found

通常表明本地 Windows 系统缺少 Visual C++ 可再分发软件包和/或 Visual C++ 运行时 DLL。这可以通过安装官方 vc_redist.x64.exe 或安装“msvc-runtime”Python 软件包来解决此问题。

$ python -m pip install msvc-runtime

请注意，Microsoft 无法发布或维护“msvc-runtime”Python 软件包。

找不到原生方法

错误消息：

java.lang.UnsatisfiedLinkError: No implementation found for void com.google.wick.Wick.nativeWick

通常表示所需的原生库（例如 /libwickjni.so）尚未加载，或未包含在应用的依赖项中或由于某种原因而找不到。请注意，Java 要求使用函数 System.loadLibrary 显式加载每个原生库。

找不到已注册的计算器

错误消息：

No registered object with name: OurNewCalculator; Unable to find Calculator "OurNewCalculator"

通常表示 CalculatorGraphConfig 中按名称引用了 OurNewCalculator，但 OurNewCalculator 的库目标尚未关联到应用二进制文件。向计算器图表添加新计算器后，您还必须将该计算器添加为使用计算器图表的应用的 build 依赖项。

系统会在运行时捕获此错误，因为计算器图表通过字段 CalculatorGraphConfig::Node:calculator 按名称引用计算器。当计算器库关联到应用二进制文件时，系统会通过 REGISTER_CALCULATOR 宏（使用 registration.h 库）按名称自动注册计算器。请注意，REGISTER_CALCULATOR 可以注册带有命名空间前缀（与其 C++ 命名空间完全相同）的计算器。在这种情况下，计算器图表也必须使用相同的命名空间前缀。

内存不足错误

内存耗尽可能表示正在运行的 MediaPipe 图中累积的数据包过多。导致这种情况的原因可能有很多，例如：

图表中的一些计算器无法跟上实时输入流（例如摄像头）发出的数据包。
有些计算器可能正在等待数据包永远无法送达。

对于问题 (1)，可能需要丢弃一些旧数据包，以便处理较新的数据包。如需了解一些提示，请参阅 How to process realtime input streams。

对于问题 (2)，可能是因为一个输入流因某种原因而缺少数据包。设备或计算器可能配置有误，或者可能偶尔生成数据包。这可能会导致下游计算器等待许多永远不会到达的数据包，进而导致数据包在某些输入流上累积。MediaPipe 使用“时间戳边界”解决了此类问题。如需了解一些提示，请参阅：How to process realtime input streams。

MediaPipe 设置 CalculatorGraphConfig::max_queue_size 通过限制图的输入来限制任何输入流上排队的数据包数量。对于实时输入流，在输入流排队的数据包数量几乎始终应为 0 或 1。如果不是这种情况，您可能会看到以下警告消息：

Resolved a deadlock by increasing max_queue_size of input stream

此外，可以设置 CalculatorGraphConfig::report_deadlock 设置，使图运行失败，并将死锁显示为错误，使 max_queue_size 充当内存用量限额。

图表挂起

许多应用会调用 CalculatorGraph::CloseAllPacketSources 和 CalculatorGraph::WaitUntilDone 来完成或暂停 MediaPipe 图的执行。这样做的目标是允许任何待处理的计算器或数据包完成处理，然后关闭图表。如果一切顺利，图表中的每个数据流都将达到 Timestamp::Done，每个计算器将达到 CalculatorBase::Close，然后 CalculatorGraph::WaitUntilDone 将成功完成。

如果某些计算器或数据流无法达到状态 Timestamp::Done 或 CalculatorBase::Close，则可以调用 CalculatorGraph::Cancel 方法以终止图表运行，而不会等待所有待处理的计算器和数据包完成。

输出时间不均匀

某些实时 MediaPipe 图表会生成一系列视频帧，可作为视频特效或视频诊断进行查看。有时，MediaPipe 图会以聚类的形式生成这些帧，例如，从同一个输入帧聚类中推断出多个输出帧时。如果在生成输出时呈现输出，某些输出帧会立即替换为同一集群中的后续帧，这会导致难以直观地查看和评估结果。在这种情况下，通过以均匀的时间间隔实时呈现帧，可以改进输出可视化。

MediaPipe 通过实时将时间戳映射到时间点，解决了此用例的问题。每个时间戳都表示一个时间（以微秒为单位），计算器（如 LiveClockSyncCalculator）可以延迟数据包的输出来匹配其时间戳。此类计算器可调整输出的时间，以便：

输出之间的时间对应于时间戳之间的尽可能接近的时间。
以尽可能最短的延迟生成输出。

CalculatorGraph 滞后于输入

对于许多实时 MediaPipe 图表来说，低延迟是一个目标。MediaPipe 支持“流水线”式并行处理，以便尽早开始处理每个数据包。通常，可能的最短延迟时间是指每个计算器在连续计算器的“关键路径”上所需的总时间。由于以均匀间隔显示帧时引入了延迟，如输出时间不均匀中所述，MediaPipe 图的延迟时间可能比理想值更差。

如果图表中的某些计算器无法跟上实时输入流的步伐，那么延迟时间将继续增加，并且有必要丢弃一些输入数据包。建议您使用专门为此而设计的 MediaPipe 计算器，例如 FlowLimiterCalculator（如 How to process realtime input streams 中所述）。