Open-LLM-VTuber 本地部署与互动实战指南关键词Open-LLM-VTuber、AI虚拟主播、Live2D、语音交互、本地部署、Ollama、LLM、ASR、TTS、开源AI伴侣文章摘要Open-LLM-VTuber 是一个开源项目把 LLM、语音识别、语音合成、视觉感知和 Live2D 角色动画整合到一起支持完全离线运行。本文从零开始带你完成本地部署全过程——环境准备、依赖安装、LLM/ASR/TTS 模块配置、Live2D 角色导入与互动调试并整理了常见问题的排错方案。一、什么是 Open-LLM-VTuberOpen-LLM-VTuber 是一个开源项目GitHub 上关注度不低。它做的事情很简单把大模型、语音识别、语音合成、视觉感知和 Live2D 角色动画拼到一起让你在笔记本上就能跑一个会说话、有表情、能看屏幕的虚拟角色还能完全离线用。1.1 它解决了什么问题传统 LLM 交互Open-LLM-VTuber 的改进纯文本框对话支持实时语音对话无需打字无表情反馈Live2D 角色通过表情和动作传达情绪无视觉感知可读取摄像头、屏幕截图让角色「看见」环境依赖云端 API完全本地离线运行保护隐私单一模型绑定LLM/ASR/TTS 模块化设计可自由替换1.2 项目核心亮点完全离线运行所有数据留在本地支持语音打断——AI 说话时直接开口就行不用等他讲完Live2D 角色会根据对话内容切换表情被点击还有反馈可以通过 GPT-SoVITS 克隆自己的声音Windows、macOS、Linux 都能跑LLM、ASR、TTS、Live2D 四个模块各自独立想换哪个换哪个二、核心功能与架构设计2.1 功能模块全景Open-LLM-VTuber 在功能模块上可以自由替换各模块可用的方案如下模块支持的方案LLM大语言模型Ollama、OpenAI 兼容 API、Claude、Gemini、DeepSeek、智谱、vLLM、llama.cpp、LM Studio、GGUFASR语音识别sherpa-onnx-asr、FunASR、Faster-Whisper、Whisper.cpp、Whisper、Groq Whisper、Azure ASRTTS语音合成Edge TTS、GPT-SoVITS声音克隆、CosyVoice、MeloTTS、Coqui-TTS、Bark、sherpa-onnx-tts、Fish Audio、Azure TTS视觉感知摄像头输入、屏幕录制、截图输入角色表现Live2D 表情映射、触摸反馈、桌宠模式透明背景 全局置顶2.2 技术架构系统数据流大致是这样的数据处理流程用户语音输入 → ASR语音转文字→ LLM大模型推理→ TTS文字转语音→ Live2D 角色动画 ↑ 摄像头/屏幕截图视觉感知各模块之间通过工厂模式解耦切换 ASR 或 TTS 引擎不需要改核心逻辑改配置就行。2.3 目录结构概览Open-LLM-VTuber/ ├── avatars/ # 角色头像资源 ├── characters/ # Live2D 角色模型文件 ├── config_templates/ # 配置文件模板 ├── frontend/ # Web 前端代码 ├── live2d-models/ # Live2D 模型目录 ├── prompts/ # AI 角色提示词 ├── src/ # 后端核心源码 │ ├── open_llm_vtuber/ │ │ ├── asr/ # 语音识别模块 │ │ ├── llm/ # 大语言模型模块 │ │ ├── tts/ # 语音合成模块 │ │ └── ... ├── conf.yaml # 主配置文件 └── run_server.py # 启动入口三、环境准备3.1 硬件要求运行模式最低要求推荐配置纯云端 API 模式普通电脑即可无需独立显卡本地混合模式ASR 本地 LLM 云端速度正常的 CPU8GB 内存全离线模式全部本地运行支持 Ollama 的 GPUNVIDIA GPU6GB 显存/ Apple M 系列 / AMD GPU支持 ROCm提示如果本地硬件跑不动大模型可以选择更小的量化模型或者将 LLM 切换到云端 API如 DeepSeek、OpenAI 兼容接口ASR 和 TTS 仍可本地运行。3.2 软件依赖Python 环境Python 版本 3.10 3.13推荐使用uv官方推荐的 Python 包管理器# Windows (PowerShell) powershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | shGit# Windows winget install Git.Git # macOS brew install git # Linux (Ubuntu/Debian) sudo apt install gitFFmpeg⚠️ 必需依赖FFmpeg 用于音频处理是项目运行的硬性依赖必须提前安装。# Windows winget install ffmpeg # macOS brew install ffmpeg # Linux (Ubuntu/Debian) sudo apt install ffmpeg验证安装ffmpeg -versionNVIDIA GPU 支持可选如果计划本地运行 LLM建议配置 CUDA 环境# 检查驱动 nvidia-smi # 检查 CUDA推荐 11.8 nvcc --version需安装NVIDIA 显卡驱动CUDA Toolkit推荐 11.8cuDNN需与 CUDA 版本匹配四、本地部署实战4.1 获取项目代码⚠️关键项目路径中不能包含中文必须放在全英文路径下。方法一下载 Release 包推荐从 GitHub Releases 页面 下载Open-LLM-VTuber-v1.x.x.zip并解压。❌不要从 GitHub 主页的 Code → Download ZIP 下载缺少 Git 信息和前端代码。方法二Git 克隆git clone https://github.com/Open-LLM-VTuber/Open-LLM-VTuber --recursive cd Open-LLM-VTuber⚠️必须加--recursive参数自 v1.0.0 起前端代码已拆分为独立仓库作为 Git submodule缺少此参数会导致浏览器显示 Detail Not Found 错误。4.2 安装项目依赖国内用户先配置镜像源非大陆用户可跳过在项目根目录的pyproject.toml文件底部添加[[tool.uv.index]] url https://mirrors.aliyun.com/pypi/simple default true安装依赖# 确认 uv 已正确安装 uv --version # 创建虚拟环境并安装所有依赖 uv sync此步骤会下载约 1-2GB 的 Python 依赖包请耐心等待。4.3 生成配置文件uv run run_server.py # 看到服务启动后立即按 CtrlC 退出⚠️ 如果退出不及时导致模型自动下载被中断需要删除models/目录下的全部文件后重试。v1.1.0 版本注意conf.yaml可能不会自动生成。如果未生成请将config_templates/conf.default.yaml或conf.ZH.default.yaml复制到项目根目录并重命名为conf.yaml。4.4 安装并配置 OllamaLLM 后端Ollama 是一个本地大模型管理工具Open-LLM-VTuber 默认用它作为 LLM 后端。安装 Ollama从 ollama.com 下载并安装对应平台版本。下载并运行模型# 推荐使用 qwen2.5中文能力强资源消耗适中 ollama run qwen2.5:latest # 或者使用更轻量的模型 ollama run qwen2.5:1.5b # 查看已安装的模型列表 ollama list模型选择建议qwen2.5:1.5b— 最轻量适合低配机器qwen2.5:7b— 平衡性能与效果推荐qwen2.5:14b— 效果更好需 8GB 显存模型文件超过显存容量会导致 CPU 运算速度极慢务必将模型大小控制在显存范围内4.5 修改配置文件编辑项目根目录的conf.yaml核心修改如下# 设置 LLM 提供者为 Ollama basic_memory_agent: llm_provider: ollama_llm # 配置 Ollama 连接参数 llm_configs: ollama_llm: base_url: http://localhost:11434 # Ollama 默认端口 model: qwen2.5:latest # 与 ollama list 输出保持一致 temperature: 0.7 # 回答随机性 (0~1)注意model字段的值必须与ollama list显示的名称完全一致包括标签如:latest建议直接复制粘贴避免拼写错误。4.6 启动项目uv run run_server.py首次运行会自动下载 ASR 模型sherpa-onnx-asr 的 SenseVoiceSmall请耐心等待。启动成功后在浏览器中访问http://localhost:12393如果一切顺利你将看到一个带有 Live2D 角色的 Web 界面五、配置详解5.1 LLM 模块配置LLM 模块支持以下几种接入方式Ollama本地llm_provider: ollama_llm ollama_llm: base_url: http://localhost:11434 model: qwen2.5:latest temperature: 0.7OpenAI 兼容 API如 DeepSeekllm_provider: openai_compatible_llm openai_compatible_llm: api_key: sk-your-api-key base_url: https://api.deepseek.com/v1 model: deepseek-chatvLLM高性能推理llm_provider: vllm_llm vllm_llm: base_url: http://localhost:8000/v1 model: qwen2.5-7b-instruct5.2 ASR 语音识别配置默认使用sherpa-onnx-asr(SenseVoiceSmall 模型)中文识别效果不错资源占用也低。如果想换asr_config: asr_type: faster_whisper # 可选: sherpa_onnx, fun_asr, faster_whisper, whisper_cpp, azure_asr faster_whisper: model_size: small # tiny / base / small / medium / large device: cuda # cpu / cuda5.3 TTS 语音合成配置默认使用Edge TTS微软免费在线 TTS无需额外配置。如需使用本地 TTS 或声音克隆tts_config: tts_type: edge_tts # 可选: gpt_sovits, cosy_voice, melo_tts, bark, azure_tts 等 edge_tts: voice: zh-CN-XiaoxiaoNeural # 中文女声GPT-SoVITS 声音克隆配置示例tts_config: tts_type: gpt_sovits gpt_sovits: base_url: http://localhost:98805.4 Live2D 角色配置项目自带若干示例 Live2D 模型。如需导入自定义模型将 Live2D 模型文件.model3.json及相关资源放入live2d-models/目录在conf.yaml中指定模型路径在 Web 界面的设置中选择对应的角色⚠️版权提示项目自带的 Live2D 示例模型遵循 Live2D Inc. 的单独许可不属于 MIT 许可证覆盖范围。商业使用时务必确认模型素材的授权。5.5 AI 角色人设定制编辑prompts/目录下的提示词文件可以定制 AI 的性格、说话风格和背景故事# 示例活泼可爱风格的 AI 助手人设 character_config: name: 小光 personality: 活泼开朗、好奇心强、喜欢帮助别人 speaking_style: 语气亲切、偶尔使用颜文字、喜欢用「呢」「哦」「呀」等语气词 background: 一个来自数字世界的 AI 助手对人类世界充满好奇六、互动实战体验6.1 基础语音对话启动项目后在 Web 界面中授权麦克风权限浏览器会弹出麦克风权限请求点击「允许」开始对话点击麦克风按钮或使用快捷键开始说话观察角色反应AI 会用语音回复Live2D 角色同步做出对应表情和动作语音打断在 AI 说话时直接开口AI 会停止当前回复并开始聆听6.2 视觉感知功能配置摄像头或屏幕捕获后角色能「看见」你的环境vision_config: enabled: true source: camera # camera / screen / screenshot interval: 5 # 截图间隔秒启用后AI 可以描述摄像头中看到的画面对屏幕上的内容做出评论识别场景变化并主动发起话题6.3 桌宠模式下载 Open-LLM-VTuber-Web 的 Electron 桌面客户端Windows 下载.exe安装包macOS 下载.dmg镜像桌宠模式特点透明背景角色悬浮在桌面上全局置顶始终显示在其他窗口之上触摸反馈点击角色有互动反应随意拖拽可以放在屏幕任意位置6.4 调试技巧# 查看 Ollama 是否正常运行 curl http://localhost:11434/api/tags # 查看服务日志 uv run run_server.py 21 | tee server.log # 检查麦克风Windows 在「设置 → 系统 → 声音 → 输入」中确认设备macOS 在「系统偏好设置 → 声音 → 输入」中确认七、常见问题与排错指南7.1 安装部署类问题原因解决方案conf.yaml未生成v1.1.0 版本不再自动生成手动将config_templates/conf.default.yaml复制到根目录并重命名为conf.yaml浏览器显示 Detail Not Found缺少前端 submoduleGit 克隆时必须带--recursive参数或手动执行git submodule update --init --recursive依赖安装慢/失败国内网络限制在pyproject.toml中配置阿里云镜像源ffmpeg未找到未安装或未加入 PATH重新安装 FFmpeg 并确认ffmpeg -version能正常输出中文路径报错项目路径包含中文字符将项目移动至全英文路径下7.2 运行时错误问题原因解决方案Error calling the chat endpointOllama 未运行或模型名不匹配1) 确认ollama serve正在运行2) 用ollama list检查模型名是否与配置完全一致AI 回复速度极慢模型超出显存回退到 CPU 运算使用更小的模型如 1.5B/7B 版本语音识别不工作麦克风权限未授权或设备未选对检查浏览器麦克风权限确认系统默认录音设备正确TTS 无声音输出Edge TTS 网络问题或浏览器静音检查网络连接确认浏览器标签页未静音代理导致本地服务不可用系统代理未绕过 localhost配置代理绕过127.0.0.1和localhost或下载资源后关闭代理7.3 体验优化类问题建议AI 回应太慢减小模型参数量将 LLM 切换到云端 API角色表情不够丰富在提示词中明确描述情绪表达检查 Live2D 模型是否支持对应表情参数语音识别不准换用更大规模的 ASR 模型如 Faster-Whisper medium确保环境安静对话记忆丢失v1.2.0 支持基于 Letta (MemGPT) 的长期记忆可在配置中启用想用声音克隆部署 GPT-SoVITS 并配置 TTS 类型为gpt_sovits八、总结与展望8.1 适用场景什么人适合玩这个想自己搭一个 AI VTuber 或桌面宠物的开发者/爱好者想做直播互动或陪伴型机器人的内容创作者对 ASR、TTS、LLM 和前端角色联动感兴趣的技术人在意隐私希望语音和视觉数据不走云端在探索 AI 角色系统的产品原型开发者8.2 项目现状与未来截至 2026 年中项目还在活跃开发。团队已经宣布 v2.0 会是一次完整重写——架构、性能、可扩展性都会大改。换句话说现在 v1.x 的配置方式未来可能会变用的时候留意官方更新就好。8.3 一句话总结如果你厌倦了对着对话框打字想试试一个有声音、有表情、能看屏幕、还能被打断说话的 AI——Open-LLM-VTuber 可能是目前最接近这个想法的开源方案。参考资源官方文档https://docs.llmvtuber.comGitHub 仓库GitHub - Open-LLM-VTuber/Open-LLM-VTuber: Talk to any LLM with hands-free voice interaction, voice interruption, and Live2D taking face running locally across platforms · GitHubOllama 官网https://ollama.comGPT-SoVITSGitHub - RVC-Boss/GPT-SoVITS: 1 min voice data can also be used to train a good TTS model! (few shot voice cloning) · GitHub本文基于 Open-LLM-VTuber v1.x 版本编写最后更新于 2026 年 6 月。部分配置和功能可能随版本更新而变化请以官方文档为准。