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. 选择配置模式

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

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：

安装Miniconda
创建环境并安装pynini：

复制代码

bash

复制代码

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

设置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安装对应依赖

🎯 验证安装

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

💡 性能优化建议

显存不足时 ：
- 使用量化版本模型
- 改用云端API
- 调整批处理大小
提高响应速度 ：
- 使用SSD存储模型
- 确保足够内存
- 优化网络连接（使用API时）
通过以上步骤，您应该能够在Windows本地成功运行OpenAvatarChat项目。如果遇到具体问题，建议查看项目的FAQ文档或提交issue。

OpenAvatarChat项目在Windows本地运行指南

📋 系统要求

硬件要求

软件要求

🚀 安装步骤

1. 环境准备

安装Git LFS

克隆项目

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

3. 选择配置模式

推荐配置（不同需求）：

4. 依赖安装

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

方式二：安装全部依赖

5. Windows特殊配置

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

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

6. 模型下载

MiniCPM模型（如使用本地MiniCPM）

LiteAvatar模型

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

🏃‍♂️ 运行项目

启动服务

访问界面

🔧 常见问题解决

1. CUDA相关问题

2. 编码问题

3. 子模块问题

4. 依赖安装问题

🎯 验证安装

💡 性能优化建议