AI 内容创作 / 系统课时
Python 与深度学习环境配置
Python 与深度学习环境配置
数字人项目同时依赖 Python 包、GPU 驱动和系统级音视频工具。本课建立一套可复现的 Python 3.11 环境,完成 PyTorch、CUDA 可用性、FFmpeg 与关键包的统一验证,并记录可追踪的环境快照与安装来源。
学习目标
- 使用虚拟环境隔离数字人项目依赖
- 安装并验证 PyTorch、GPU 后端与音视频工具
- 通过同平台依赖快照与检测脚本复现开发环境
环境基线与依赖边界
数字人流水线通常同时处理张量、图像、音频和视频。Python 虚拟环境负责隔离包版本,PyTorch 负责模型推理,FFmpeg 与 ffprobe 负责媒体转码和信息探测;NVIDIA 驱动属于操作系统层,不应被简单等同于 Python 环境中的 CUDA 运行时。

选择 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。
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预期结果如下,路径和补丁版本会因机器而不同。
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 调用当前解释器中的包管理器。
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 目录。
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,检查官方版本匹配表,并确认所选版本发布了对应平台的包。随后安装以下通用依赖并记录环境。
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 版本。不同平台分别生成。
No broken requirements found.FFmpeg 属于系统工具。macOS 可使用 brew install ffmpeg,Ubuntu 可使用 sudo apt install ffmpeg,Windows 可通过可信的软件包管理器安装。安装后必须确保 ffmpeg 与 ffprobe 都能从终端直接执行。
编写统一环境验证脚本
将以下程序保存为 verify_environment.py。脚本不只打印版本,还会创建张量、选择可用设备,并检查两个音视频命令是否已进入 PATH;任一关键条件失败时,程序会返回非零退出码。
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()运行验证脚本。
python verify_environment.py --device cpuCPU 机器的预期输出如下;版本号、处理器名称和命令路径属于动态值。检验 GPU 时请显式改为 --device cuda 或 --device mps。目标后端不可用时脚本退出,不会静默改用 CPU。ROCm 构建也使用 PyTorch 的 cuda 设备接口。
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配合同平台安装来源、驱动和系统工具版本,可作为复现和排错的基线
下一课预告
下一课将搭建数字人工程骨架,把配置、日志、资源目录和模块接口固定下来,使后续语音、口型与渲染模块能够在同一工程约定下协作。