py-xiaozhi Python 语音客户端本地部署与配置指南

理解配置文件结构

核心配置文件位于 src/constants/constants.py，包含应用的所有可配置参数。主要配置区域包括：

# 音频配置示例（带详细注释）
AUDIO_CONFIG = {
    # 采样率：音频信号的"帧率"，越高音质越好但资源消耗越大
    "sample_rate": 16000,
    # 唤醒词灵敏度：0-1 之间，越高越灵敏但可能误触发
    "wake_word_sensitivity": 0.8,
    # 回声消除开关：是否启用背景噪音过滤
    "echo_cancellation": True,
    # 语音超时时间：无操作后自动退出对话模式（秒）
    "speech_timeout": 5
}

多设备音频配置

py-xiaozhi 支持多设备音频输出，特别适合家庭多房间部署。

通过 src/utils/volume_controller.py 可以进一步精细化控制各设备音量：

# 调整特定设备音量示例
from src.utils.volume_controller import VolumeController
# 创建音量控制器实例
vc = VolumeController()
# 设置"卧室扬声器"音量为 70%
vc.set_device_volume("卧室扬声器", 70)

高级网络配置

对于高级用户，可以修改 src/network/mqtt_client.py 配置 MQTT 连接参数，实现与智能家居系统的深度集成：

# MQTT 服务器配置
MQTT_CONFIG = {
    "host": "your_mqtt_server_ip", # MQTT 服务器地址
    "port": 1883, # MQTT 端口
    "username": "your_username", # 认证用户名
    "password": "your_password", # 认证密码
    "keepalive": 60 # 心跳间隔（秒）
}

目录结构速查

核心功能目录

• src/application.py - 应用入口，协调所有组件工作
• src/audio_processing/ - 音频处理中心，负责语音识别和声音优化
• src/mcp/ - 服务集成模块，连接各类第三方功能
• src/plugins/ - 插件系统，可扩展应用功能
• src/utils/ - 工具函数库，提供各类辅助功能

资源与配置目录

• assets/ - 静态资源，包含界面图标和表情动画
• libs/ - 第三方依赖库，如音频编解码器
• scripts/ - 辅助脚本，用于系统维护和配置
• documents/ - 项目文档和使用指南

扩展功能目录

• src/iot/ - IoT 设备管理，控制智能家电
• src/views/ - 用户界面组件，定制交互体验
• src/protocols/ - 通信协议实现，支持多种网络连接方式

常见问题解决

问题 1：麦克风无法访问

症状：应用启动后提示"无法访问麦克风" 解决方案：

1. 检查系统设置，确保 Python 拥有麦克风访问权限
2. 运行 sudo apt-get install portaudio19-dev 安装音频驱动
3. 验证麦克风是否被其他应用占用

问题 2：唤醒词无响应

症状：说出唤醒词后没有任何反应 解决方案：

1. 降低环境噪音，在安静环境测试
2. 调整唤醒词灵敏度（wake_word_sensitivity）
3. 检查音频输入电平，确保麦克风正常收音

问题 3：多设备音频不同步

症状：多扬声器播放时声音有延迟差异 解决方案：

1. 在音频设置中启用"漂移校正"
2. 调整主时钟源为性能更稳定的设备
3. 尝试降低采样率至 44100Hz

问题 4：应用启动后闪退

症状：启动后立即退出，无错误提示 解决方案：

1. 删除配置目录 ~/.py-xiaozhi 后重试
2. 使用 python main.py --debug 查看详细日志
3. 检查系统是否安装了所有依赖库

问题 5：语音识别准确率低

症状：识别结果与语音内容差异大 解决方案：

1. 检查网络连接，确保在线识别服务正常
2. 在嘈杂环境启用"回声消除"功能
3. 尝试靠近麦克风说话，保持清晰发音

通过以上指南，你已经掌握了 py-xiaozhi 的核心使用方法和配置技巧。这款 Python 语音客户端不仅提供了丰富的功能，还允许深度定制以满足个人需求。无论是家庭自动化控制还是个人助理应用，py-xiaozhi 都能成为得力的智能工具。