基于Qwen的OpenAvatarChat服务器部署指南
1. 项目代码获取与子模块初始化
通过SSH克隆项目仓库到本地：
git clone git@github.com:HumanAIGC-Engineering/OpenAvatarChat.git
cd OpenAvatarChat
该项目依赖 Git LFS 管理大模型文件，需确保已安装并启用 LFS 功能：
sudo apt install git-lfs -y
git lfs install
拉取所有子模块内容：
git submodule update --init --recursive --depth 1
2. 安装Python依赖管理工具uv
使用pip全局安装uv以加速后续包安装过程：
pip install uv
3. 虚拟环境配置与依赖安装
建议CUDA版本不低于12.4。实测在CUDA 12.1环境下可正常运行，而13.0可能存在兼容性问题。
虽然原项目推荐使用uv创建虚拟环境，但也可选用conda进行环境管理。此处采用conda方式：
conda create -n avatar_env python=3.11.11
conda activate avatar_env
由于项目未提供requirements.txt，必须通过--uv参数调用pyproject.toml中的依赖列表：
uv pip install setuptools pip
python install.py --uv --config config/chat_with_qwen-omni.yaml
若遇到setuptools新版（如82.0.1）移除pkg_resources导致的构建失败，需单独安装以下组件：
uv pip install wheel
uv pip install openai-whisper==20240930 --no-build-isolation
uv pip install mmcv==2.2.0 --no-build-isolation
网络不稳定时可能超时，可通过设置UV_HTTP_TIMEOUT延长请求等待时间：
export UV_HTTP_TIMEOUT=60000
完成基础依赖后执行后置脚本：
./scripts/post_config_install.sh --config config/chat_with_qwen-omni.yaml
过程中若提示缺少某些模块，直接使用pip补充安装即可。
4. 核心服务配置
当前配置聚焦于qwen-omni方案，主要涉及API密钥和轻量化头像模型的准备。
4.1 配置通义千问API密钥
前往阿里云百炼平台申请API Key：https://bailian.console.aliyun.com。新用户享有百万Token免费额度。
获取Key后，在配置文件config/chat_with_qwen-omni.yaml中更新对应字段：
llm:
api_key: your_actual_api_key_here
4.2 下载LiteAvatar权重文件
运行提供的脚本下载所需的人像生成模型：
bash scripts/download_liteavatar_weights.sh
注意：首次启动demo时系统可能再次触发重复下载，造成路径冲突或文件损坏。建议在初次运行失败后重新执行该脚本覆盖修复。
5. 常见问题修正
5.1 配置项冗余值处理
在chat_with_qwen-omni.yaml中存在两个connection_ttl定义（分别为900和36000），保留较大值以避免连接过早中断：
# connection_ttl: 900
connection_ttl: 36000
5.2 替换视频编码器为软件模式
默认使用硬件编码（NVENC/QSV等）可能导致部分GPU驱动不兼容。修改src/handlers/client/rtc_client/client_handler_rtc.py中的编码配置函数：
def _configure_h264_hardware_encoding():
"""强制使用libx264软件编码器"""
global _selected_h264_encoder, _actual_h264_encoder
_selected_h264_encoder = 'libx264'
_actual_h264_encoder = 'libx264'
h264.DEFAULT_BITRATE = 1500000
h264.MIN_BITRATE = 500000
h264.MAX_BITRATE = 2500000
print("Using software H.264 encoder: libx264")
return
此更改绕过硬件检测逻辑，统一使用FFmpeg的libx264实现编码，提升跨平台兼容性。
6. 启动服务
激活环境后直接运行主程序：
python src/demo.py --config config/chat_with_qwen-omni.yaml
服务启动后可通过Web端或RTC客户端接入，开始语音交互对话。
