OpenAvatarChat项目在Windows本地运行指南

📋 系统要求

硬件要求

• GPU: 必须配备支持CUDA的NVIDIA GPU
• 显存:
  • 使用MiniCPM-o未量化模型：需要20GB以上显存
  • 使用MiniCPM-o量化版本：需要10GB以下显存
  • 使用云端API：对GPU要求大大降低，LiteAvatar在CPU上也可运行
• 内存: 推荐32GB RAM，多会话场景下建议64GB+
• 处理器: 推荐i9-13900KF或更高

软件要求

• 操作系统: Windows 10/11
• Python: 版本 3.11.7 ~ 3.11.11（必须小于3.12）
• CUDA: 本地NVIDIA驱动程序支持的CUDA版本必须 ≥ 12.4
• Git: 用于克隆项目和管理子模块
• Git LFS: 项目包含大文件，必须安装

🚀 安装步骤

1. 环境准备

安装Git LFS

bash

# 在Git Bash中运行
git lfs install

克隆项目

bash

git clone https://github.com/HumanAIGC-Engineering/OpenAvatarChat.git
cd OpenAvatarChat
git submodule update --init --recursive

2. 安装uv（Python包管理工具）

在PowerShell中运行：

powershell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

或者使用pip安装：

bash

pip install uv

3. 选择配置模式

项目提供多种预设配置，根据您的硬件配置选择：

推荐配置（不同需求）：

1. 云端API模式 - chat_with_openai_compatible_bailian_cosyvoice.yaml
   • 适合显卡配置较低的用户
   • 使用云端API（需要API Key）
   • 对硬件要求最低
2. 本地MiniCPM模式 - chat_with_minicpm.yaml
   • 适合高配置显卡用户（20GB+ 显存）
   • 完全本地运行，无需API
3. Edge TTS模式 - chat_with_openai_compatible_edge_tts.yaml
   • 不需要百炼API Key
   • 使用免费的Edge TTS

4. 依赖安装

方式一：按需安装（推荐）

bash

# 创建虚拟环境
uv venv --python 3.11.11# 激活虚拟环境（Windows）
.venv\Scripts\activate# 安装指定配置的依赖
uv run install.py --uv --config config/chat_with_openai_compatible_bailian_cosyvoice.yaml# 执行后置配置（某些模块需要）
.\scripts\post_config_install.sh --config config/chat_with_openai_compatible_bailian_cosyvoice.yaml

方式二：安装全部依赖

bash

uv sync --all-packages

5. Windows特殊配置

设置环境变量（避免编码问题）

powershell

$env:PYTHONUTF8=1

如果使用CosyVoice本地推理（可选）

由于Windows下pynini包编译问题，需要结合Conda：

1. 安装Miniconda
2. 创建环境并安装pynini：

bash

conda create -n openavatarchat python=3.10
conda activate openavatarchat  
conda install -c conda-forge pynini==2.1.6

1. 设置uv环境变量：

powershell

# PowerShell
$env:VIRTUAL_ENV=$env:CONDA_PREFIX

6. 模型下载

根据选择的配置下载对应模型：

MiniCPM模型（如使用本地MiniCPM）

bash

# 完整版模型（需要20GB显存）
bash scripts/download_MiniCPM-o_2.6.sh# 量化版模型（需要10GB以下显存）  
bash scripts/download_MiniCPM-o_2.6-int4.sh

LiteAvatar模型

bash

bash scripts/download_liteavatar_weights.sh

7. 配置API密钥（如使用云端API）

创建.env文件在项目根目录：

DASHSCOPE_API_KEY=your_api_key_here

或在配置文件中直接设置API密钥。

🏃‍♂️ 运行项目

启动服务

bash

uv run src/demo.py --config config/chat_with_openai_compatible_bailian_cosyvoice.yaml

访问界面

启动成功后，在浏览器中访问：

http://localhost:8282

🔧 常见问题解决

1. CUDA相关问题

• 确保NVIDIA驱动支持CUDA 12.4以上
• RTX 50系列显卡需要CUDA 12.8：

bash

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

2. 编码问题

设置环境变量：

powershell

$env:PYTHONUTF8=1

3. 子模块问题

重新拉取子模块：

bash

git submodule update --init --recursive

4. 依赖安装问题

• 不要使用根目录的requirements.txt，使用uv安装
• 根据实际使用的Handler安装对应依赖

🎯 验证安装

1. 检查日志输出: 启动过程中应无关键错误
2. 访问Web界面: 浏览器打开http://localhost:8282
3. 测试功能:
   • 点击"开始对话"
   • 检查麦克风和摄像头权限
   • 测试语音对话功能

💡 性能优化建议

1. 显存不足时：
   • 使用量化版本模型
   • 改用云端API
   • 调整批处理大小
2. 提高响应速度：
   • 使用SSD存储模型
   • 确保足够内存
   • 优化网络连接（使用API时）

   通过以上步骤，您应该能够在Windows本地成功运行OpenAvatarChat项目。如果遇到具体问题，建议查看项目的FAQ文档或提交issue。