📚 课程目录第1章环境搭建与基础工具链验证

1. 环境搭建与基础工具链验证

任务目标

本案例完成边缘AI语音唤醒场景的本地开发环境搭建，并验证基础工具链可用。最终要求：Python虚拟环境可创建、PyTorch可完成CPU张量运算、sounddevice可枚举音频输入设备、以及一个最小录音脚本能采集到非静音数据。全部验证通过即视为环境就绪，可进入后续关键词识别案例。

环境依赖

操作系统：Ubuntu 20.04/22.04 或 Windows 10/11（均需支持Python 3.9+）
Python 3.9～3.11（推荐3.10）
音频硬件：任意可用麦克风（板载或USB均可）
磁盘空间：约3GB（含PyTorch CPU版）

安装步骤

# 1. 创建虚拟环境
python3 -m venv ~/wake_env
source ~/wake_env/bin/activate   # Windows: wake_env\Scripts\activate

# 2. 安装依赖（CPU版PyTorch）
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install sounddevice numpy

# 3. 验证安装版本
python -c "import torch, sounddevice; print('torch', torch.__version__); print('sd', sounddevice.__version__)"

关键完整代码

将以下内容保存为 env_check.py，用于一次性验证全部工具链环节：

import torch
import sounddevice as sd
import numpy as np
import sys

def check_torch():
    """验证PyTorch CPU张量运算"""
    a = torch.rand(2, 3)
    b = torch.matmul(a, a.T)
    assert b.shape == (2, 2), "张量运算异常"
    print(f"[OK] PyTorch {torch.__version__} 张量运算正常")
    print(f"    示例结果均值: {b.mean().item():.4f}")

def check_audio_device():
    """枚举音频输入设备"""
    devices = sd.query_devices()
    input_devices = [d for d in devices if d['max_input_channels'] > 0]
    assert len(input_devices) > 0, "未找到任何输入设备"
    print(f"[OK] 检测到 {len(input_devices)} 个输入设备:")
    for i, dev in enumerate(input_devices):
        print(f"    [{i}] {dev['name']} (channels: {dev['max_input_channels']})")
    return input_devices[0]['index']

def record_sample(duration=1.0, samplerate=16000):
    """录制1秒音频并检查是否为有效信号"""
    print(f"[..] 正在录音 {duration} 秒，请对着麦克风说话...")
    recording = sd.rec(int(duration * samplerate), samplerate=samplerate,
                       channels=1, dtype='float32')
    sd.wait()
    rms = np.sqrt(np.mean(recording**2))
    peak = np.abs(recording).max()
    print(f"[OK] 录音完成: RMS={rms:.4f}, Peak={peak:.4f}")
    assert rms > 0.001, "信号过弱，请检查麦克风连接或系统音量"
    assert peak < 1.0, "信号削波，请降低输入增益"
    return recording

if __name__ == "__main__":
    print("=== 边缘AI语音唤醒 - 环境验证 ===\n")
    try:
        check_torch()
        dev_idx = check_audio_device()
        sd.default.device = (dev_idx, None)  # 设置默认输入设备
        record_sample()
        print("\n=== 全部验证通过，环境就绪 ===")
    except Exception as e:
        print(f"\n[FAIL] {e}", file=sys.stderr)
        sys.exit(1)

运行与验证

python env_check.py

运行后观察输出：

PyTorch检查：打印版本号与一个2×2矩阵的均值，无报错即通过。
设备枚举：列出至少1个输入设备及其索引号。
录音测试：程序会录音1秒，需在录音期间正常说话。输出中RMS值应大于0.001（典型值0.01～0.3），Peak值应小于1.0。
最终状态：出现“全部验证通过，环境就绪”即表示工具链完整可用。

若录音RMS过低，依次检查：系统输入音量、麦克风是否被静音、pavucontrol（Linux）或“声音设置”（Windows）中的默认输入设备选择。

常见问题

PyTorch安装缓慢：确认使用了--index-url .../cpu参数，CPU版约200MB，GPU版数GB且需要CUDA。
sounddevice报PortAudio错误：Linux需安装libportaudio2（sudo apt install libportaudio2）；Windows通常无需额外操作。
录音全零或RMS极小：检查麦克风阵列中是否选对了设备索引，部分笔记本有多个输入源（内置麦克风/耳机麦克风）。