AI 内容创作 / 系统课时

Python 与深度学习环境配置

Python 与深度学习环境配置

数字人项目同时依赖 Python 包、GPU 驱动和系统级音视频工具。本课建立一套可复现的 Python 3.11 环境,完成 PyTorch、CUDA 可用性、FFmpeg 与关键包的统一验证,并记录可追踪的环境快照与安装来源。

学习目标

  • 使用虚拟环境隔离数字人项目依赖
  • 安装并验证 PyTorch、GPU 后端与音视频工具
  • 通过同平台依赖快照与检测脚本复现开发环境

环境基线与依赖边界

数字人流水线通常同时处理张量、图像、音频和视频。Python 虚拟环境负责隔离包版本,PyTorch 负责模型推理,FFmpeg 与 ffprobe 负责媒体转码和信息探测;NVIDIA 驱动属于操作系统层,不应被简单等同于 Python 环境中的 CUDA 运行时。

Python、深度学习与音视频依赖的分层关系

选择 Python 3.11 作为本课程基线,可以使用标准库 tomllib,同时兼顾多数深度学习与音视频包。GPU 机器应先确认显卡驱动正常;预构建 PyTorch 安装通常通过 wheel 或其依赖提供所需用户态运行库;系统仍需兼容的 NVIDIA 驱动。源码构建、编译 CUDA 扩展等任务才按对应文档另装 Toolkit。

层级 关键组件 验证重点
Python 运行时 Python 3.11、venv、pip 解释器路径与版本正确
深度学习 PyTorch、TorchVision、TorchAudio 张量计算与设备后端可用
音视频 FFmpeg、ffprobe、OpenCV、SoundFile 命令可发现,文件可读写
版本记录 requirements-snapshot.txt 与安装来源说明 在相同平台和后端验证可重装

安装、隔离与环境快照

先在空目录中创建虚拟环境。macOS 或 Linux 使用以下命令;激活后,python 与 pip 都应指向项目内的 .venv。

bash
mkdir digital-human-dev
cd digital-human-dev
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python --version
python -m pip --version

预期结果如下,路径和补丁版本会因机器而不同。

text
Python 3.11.<PATCH>
pip <PIP_VERSION> from <PATH>/digital-human-dev/.venv/lib/python3.11/site-packages/pip (python 3.11)

Windows PowerShell 使用对应的激活脚本,并继续通过 python -m pip 调用当前解释器中的包管理器。

powershell
New-Item -ItemType Directory -Force digital-human-dev | Out-Null
Set-Location digital-human-dev
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python --version
python -m pip --version

预期结果中应出现 Python 3.11,且 pip 路径位于当前项目的 .venv 目录。

text
Python 3.11.<PATCH>
pip <PIP_VERSION> from <PATH>\digital-human-dev\.venv\Lib\site-packages\pip (python 3.11)

先从 PyTorch 官方安装页面选择操作系统、Pip 和计算平台。Linux 或 Windows 若要做 CPU 基线,应选择 CPU 构建,而不是假定默认发行包只含 CPU。macOS 按官方 macOS 命令安装,再检测 CPU 或 MPS。若后续课时需要 TorchVision 或 TorchAudio,检查官方版本匹配表,并确认所选版本发布了对应平台的包。随后安装以下通用依赖并记录环境。

bash
python -m pip install numpy opencv-python soundfile
python -m pip check
python -m pip freeze | python -c "import sys; from pathlib import Path; Path('requirements-snapshot.txt').write_text(sys.stdin.read(), encoding='utf-8')"

依赖关系正常时,pip check 会输出以下内容。快照记录已安装包,不记录完整的求解环境或所有 wheel 来源;另行保存操作系统、Python 补丁版本、CPU 或 GPU 构建、PyTorch 安装命令及索引、驱动和 FFmpeg 版本。不同平台分别生成。

text
No broken requirements found.

FFmpeg 属于系统工具。macOS 可使用 brew install ffmpeg,Ubuntu 可使用 sudo apt install ffmpeg,Windows 可通过可信的软件包管理器安装。安装后必须确保 ffmpeg 与 ffprobe 都能从终端直接执行。

编写统一环境验证脚本

将以下程序保存为 verify_environment.py。脚本不只打印版本,还会创建张量、选择可用设备,并检查两个音视频命令是否已进入 PATH;任一关键条件失败时,程序会返回非零退出码。

python
from __future__ import annotations

import argparse
import platform
import shutil
import subprocess
import sys
from pathlib import Path

import torch

def select_device(target: str) -> tuple[str, str]:
    if target in ("auto", "cuda") and torch.cuda.is_available():
        return "cuda", torch.cuda.get_device_name(0)

    mps = getattr(torch.backends, "mps", None)
    if target in ("auto", "mps") and mps is not None and mps.is_available():
        return "mps", "Apple Metal Performance Shaders"

    if target not in ("auto", "cpu"):
        raise RuntimeError(f"请求的设备不可用: {target}")
    return "cpu", platform.processor() or "generic CPU"

def require_command(name: str) -> Path:
    path = shutil.which(name)
    if path is None:
        raise RuntimeError(f"未找到命令: {name}")
    subprocess.run([path, "-version"], check=True, capture_output=True, timeout=10)
    return Path(path)

def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--device", choices=("auto", "cpu", "cuda", "mps"), default="auto")
    args = parser.parse_args()
    device, device_name = select_device(args.device)
    tensor = torch.arange(6, dtype=torch.float32, device=device).reshape(2, 3)

    print(f"python: {sys.version.split()[0]}")
    print(f"torch: {torch.__version__}")
    print(f"device: {device} ({device_name})")
    print(f"tensor mean: {tensor.mean().item():.1f}")
    print(f"ffmpeg: {require_command('ffmpeg')}")
    print(f"ffprobe: {require_command('ffprobe')}")
    print("environment: PASS")

if __name__ == "__main__":
    main()

运行验证脚本。

bash
python verify_environment.py --device cpu

CPU 机器的预期输出如下;版本号、处理器名称和命令路径属于动态值。检验 GPU 时请显式改为 --device cuda 或 --device mps。目标后端不可用时脚本退出,不会静默改用 CPU。ROCm 构建也使用 PyTorch 的 cuda 设备接口。

text
python: 3.11.<PATCH>
torch: <TORCH_VERSION>
device: cpu (<DEVICE_NAME>)
tensor mean: 2.5
ffmpeg: <PATH>/ffmpeg
ffprobe: <PATH>/ffprobe
environment: PASS

常见故障与练习

torch.cuda.is_available() 返回 False 时,先检查系统是否能识别显卡和驱动,再确认安装的 PyTorch 构建是否包含目标计算后端。不要通过反复安装不同 CUDA Toolkit 版本碰运气,因为驱动、PyTorch 构建和扩展编译需求属于不同层级。

出现 未找到命令: ffmpeg,通常说明工具未安装或安装目录没有进入 PATH。终端能够执行 ffmpeg -version 后,应重新打开 IDE 或终端,使其继承更新后的环境变量。

当 pip 把包装进全局环境时,常见原因是虚拟环境未激活,或直接使用了其他解释器关联的 pip。统一写成 python -m pip,并在安装前检查 python -m pip --version 中的路径,可以显著降低误装概率。

练习一:在一台新机器上按本课流程建立环境,提交 python --version、python -m pip check 和验证脚本的完整输出。验收条件是解释器来自 .venv,依赖检查通过,脚本最后输出 environment: PASS。

练习二:新建第二个虚拟环境。先按记录的索引安装同一 PyTorch 构建,再以可用的相同包来源安装 python -m pip install -r requirements-snapshot.txt。若有本地引用或 wheel 已下架,先提供可访问的原制品。验收条件是核心包版本与原环境一致,验证脚本仍能运行,并记录 GPU 后端是否发生变化及其原因。

本课总结

  • 虚拟环境隔离 Python 包,系统驱动和 FFmpeg 仍需单独管理
  • 环境是否可用应由张量计算、设备检测和媒体命令共同验证
  • requirements-snapshot.txt 配合同平台安装来源、驱动和系统工具版本,可作为复现和排错的基线

下一课预告

下一课将搭建数字人工程骨架,把配置、日志、资源目录和模块接口固定下来,使后续语音、口型与渲染模块能够在同一工程约定下协作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Python 与深度学习环境配置

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通