OpenAvatarChat项目在Windows本地运行指南

发布于：2025-09-07 ⋅ 阅读:(17) ⋅ 点赞:(0)

📋 系统要求

硬件要求

  • 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. 
 
  2. 本地MiniCPM模式 - chat_with_minicpm.yaml
  
      
   
    • 适合高配置显卡用户（20GB+ 显存）
      • 
   
    • 完全本地运行，无需API
      • 
  
    3. 
 
  3. Edge TTS模式 - chat_with_openai_compatible_edge_tts.yaml
  
      
   
    • 不需要百炼API Key
      • 
   
    • 使用免费的Edge TTS
      • 
  
    4. 



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. 
 
  2. 创建环境并安装pynini：
    3. 





bash


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


    
 
  1. 设置uv环境变量：
    2. 





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. 
 
  2. 访问Web界面: 浏览器打开http://localhost:8282
    3. 
 
  3. 测试功能: 
  
      
   
    • 点击"开始对话"
      • 
   
    • 检查麦克风和摄像头权限
      • 
   
    • 测试语音对话功能
      • 
  
    4. 



💡 性能优化建议


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


                        
                        

                        

                            
                            
                        

                        
                        

                            

                            
                        

                            

                                
                            

                        

                    


                



            


            

                
                

    

        

            网站公告
        

    

    

        
        
    



                

    

        

            今日签到
        

    

    

        
点亮在社区的每一天

        
        去签到
    



                

    

        

            热门文章
        

    

    

        
        

        

    

    
    
    


    



                

    

        

            最新发布