VirtualWife：本地化Live2D+LLM虚拟人直播框架

简介：VirtualWife是一个开源的虚拟数字人项目，面向AI开发者、直播技术实践者及AIGC应用探索者，旨在降低B站虚拟直播的技术门槛，提供可快速部署、可定制的本地化数字人交互方案。资源包共246个文件，涵盖97个Python核心逻辑脚本（含LLM对接、语音驱动、动作合成模块）、40个TypeScript/17个TSX前端交互组件（直播控制台、VRM渲染界面）、16个FBX/8个VRM三维模型资源，以及Dockerfile、多套Nginx配置（chatbot.conf/chatvrm.conf等）、启动/停止脚本（start.bat/stop.bat）和环境配置模板（.env_example），整体压缩包130.2MB，结构清晰、模块解耦。目前已有653人学习下载，读者可直接获取完整可运行的B站直播数字人系统，包含OpenAI与Ollama双后端支持、VRM模型驱动链路、实时语音响应流程及容器化部署方案，适合希望深入理解虚拟人直播架构、复现端到端AI交互流程的中高级开发者。

1. VirtualWife 是什么：一个可开箱即用的本地化虚拟数字人直播框架，专为 B 站实时互动场景设计

这不是一个“AI 换脸玩具”，也不是调用几个 API 就完事的 Demo。VirtualWife.zip 是一个结构完整、路径清晰、依赖收敛的工程包——它把「语音驱动口型 + 姿态微动 + 文本流响应 + B 站弹幕接入」这四块硬骨头，全打包进一个 Windows 可执行环境（含 Python 3.10 运行时）里。我拿它在某高校数字媒体实验室跑通过连续 72 小时的无人值守测试：弹幕触发关键词 → LLM（Ollama 本地模型）生成回复 → TTS 合成语音 → 驱动 Live2D 模型口型与眨眼 → 同步推流至 B 站。整个链路不依赖公网大模型 API（OpenAI 仅作可选回退），核心推理全部走本地 Ollama（实测 Qwen2-1.5B-Chat / Phi-3-mini 在 RTX 3060 笔记本上延迟 < 800ms）。适合三类人直接上手：想快速验证虚拟人直播可行性的小团队、需要离线部署的教育/展厅场景开发者、以及正在啃 Live2D+LLM 联动逻辑的算法工程师。它不解决“怎么训练口型同步模型”，但彻底绕开了“怎么让弹幕和嘴动对上节奏”这个最耗时间的黑匣子。

2. 项目结构拆解：从 zip 包到可运行服务的六层目录逻辑

拿到 VirtualWife.zip 后别急着双击。先解压，你会看到一个严格分层的文件树。这不是随手扔的脚本集合，而是按「输入→处理→输出→调度」划分的工业级组织方式。下面逐层说明每个目录存在的技术必要性，以及你改哪一行会影响什么。

2.1 /config：配置中枢，所有外部可调参数集中地

这里不是放几个 .ini 就完事。它包含三个关键文件：

• live2d_config.json：控制 Live2D 模型行为边界。重点字段motion_fade_time_ms（默认 300）决定动作过渡缓和度，设太小会抖，太大则响应迟滞；mouth_open_threshold（默认 0.35）是语音振幅触发口型张合的阈值，实测中文播音腔需调高到 0.42 才不漏字。
• ollama_config.yaml：定义本地 LLM 调用策略。model_name必须与你ollama list输出的 NAME 完全一致（注意大小写）；system_prompt不是装饰，它被硬编码进/core/llm_handler.py的build_messages()函数里，直接影响上下文压缩逻辑。
• bilibili_config.toml：B 站接入凭证唯一入口。room_id和access_key必须填，heartbeat_interval_sec（默认 25）必须 ≤ B 站要求的 30 秒心跳上限，否则会被踢下线。

提示：所有配置文件都经过jsonschema校验。启动时报ValidationError，一定是某个字段类型或范围错了，不是缺文件。

2.2 /models：模型资产仓库，含预置 Live2D 与轻量 LLM 适配包

该目录下有两个不可删的子目录：

• /models/live2d/：必须含model3.json、texture_00.png、moc3.moc3三件套。这是 Live2D Cubism 导出的标准格式。如果你换自己的模型，不要只丢 moc3 文件——model3.json里硬编码了motion_groups名称（如"idle"、"talk"），而/core/live2d_renderer.py的play_motion()函数正是靠这个字符串匹配来触发动画。实测某国产模型因model3.json缺talk分组，导致全程只有待机动画。
• /models/ollama/：存放.gguf模型文件。项目默认带phi-3-mini.Q4_K_M.gguf（1.8GB），已做量化适配。若换 Qwen2-1.5B，必须确认其tokenizer_config.json中chat_template字段存在且格式为 Jinja2（Ollama 0.3.0+ 强制要求），否则llm_handler.py会卡在tokenizer.apply_chat_template()报KeyError: 'messages'。

2.3 /core：业务逻辑心脏，四个核心模块职责分明

这是你未来要改代码的地方，但先得知道每块管什么：

• bilibili_client.py：封装 B 站 Websocket 协议。它不处理登录，只管连接wss://broadcastlv.chat.bilibili.com:443/sub、解析DANMU_MSG和SEND_GIFT二进制包、并把弹幕文本塞进队列。关键点：recv_loop()里self._ws.recv()是阻塞调用，若网络抖动超 10 秒未收包，会抛websocket._exceptions.WebSocketTimeoutException—— 但项目没做重连，需自己加while True:循环兜底。
• llm_handler.py：LLM 响应引擎。它用subprocess.Popen启动ollama run，而非requests.post。原因很实在：避免 HTTP 头部开销导致长文本响应超时。generate_response()方法返回的是 raw stdout 流，所以response = response.strip().split('\n')[-1]这行代码，本质是在取最后一行（Ollama 流式输出的 final chunk）。
• tts_engine.py：语音合成模块。调用的是edge-tts（微软 Edge 浏览器 TTS 引擎），非本地模型。--voice zh-CN-XiaoxiaoNeural是硬编码，若你的系统没装中文语音包（Windows 设置 → 语音 → 下载语言包），会静音。实测发现--rate=+20%参数能显著改善语速拖沓感。
• live2d_renderer.py：渲染中枢。它用pyglet窗口托管 Live2D，但关键帧更新逻辑在update()方法里：每 33ms（≈30fps）读一次audio_level（来自tts_engine.py的音频缓冲区 RMS 值），再查表映射到 mouth_open_ratio。这个查表函数get_mouth_ratio()是线性的，但真实语音频谱非线性，所以config/live2d_config.json里的mouth_curve字段其实是预留的非线性校正接口（当前为空，需手动补[[0,0],[0.2,0.1],[0.5,0.6],[1.0,1.0]]这样的折线点）。

2.4 /assets：资源加载区，字体与音效影响体验下限

• /assets/fonts/：必须含NotoSansCJKsc-Regular.otf。Live2D 文字渲染用freetype-py加载此字体，若缺失，live2d_renderer.py初始化时会报FT_Exception: cannot open resource并退出。别用 Windows 自带simhei.ttf——它缺 CJK 统一汉字扩展 B 区字符，弹幕出现生僻字直接乱码。
• /assets/sounds/：含notification.wav（弹幕触发音）和error.wav（LLM 超时音）。这两个 WAV 文件采样率必须是 44100Hz/16bit，否则playsound库在某些 Win10 版本会静音。实测用 Audacity 转码时勾选 “Resample to 44100 Hz” 即可。

2.5 /utils：工具集，藏着三个救命函数

• audio_utils.py的normalize_audio_buffer()：TTS 输出的 PCM 数据是 int16，但 Live2D 输入要 float32 归一化到 [-1.0, 1.0]。这个函数做了除以 32768.0 的转换，不能跳过，否则口型张合幅度爆炸。
• text_filter.py的filter_sensitive_words()：内置 137 个中文敏感词（如“死”、“杀”、“赌”），匹配后自动替换为*。规则是前缀树（Trie）实现，O(1) 查询。若你要加词，直接往SENSITIVE_WORDS列表 append 字符串即可，无需重启。
• log_manager.py：日志按INFO/WARNING/ERROR三级写入/logs/virtualwife.log，且自动轮转（单个最大 5MB，保留 5 个历史文件）。排查问题时，第一眼盯ERROR行，第二眼查WARNING里LLM timeout after 15s这类提示。

2.6 /scripts：启动与调试脚本，拒绝黑窗口裸奔

• start.bat：主入口。它干三件事：激活venv、设置PYTHONPATH=.、执行python main.py。不要双击运行——必须右键“以管理员身份运行”，否则pyglet窗口在 Win10 上可能被缩放模糊（DPI 感知问题）。
• debug_mode.bat：启动时加--debug参数，会打开两个额外窗口：Audio Monitor（实时显示音频波形）和LLM Debug Console（显示原始 prompt 和 raw response）。这是定位“嘴不动”或“不回弹幕”的第一现场。
• reset_config.bat：一键恢复config/下所有文件为初始状态。当你改崩配置又记不清原值时，比手动 Git checkout 快 10 秒。

3. 本地部署全流程：从安装依赖到首播成功的七步闭环

部署不是复制粘贴命令就完事。每一步背后都有一个必须确认的技术点，漏掉任意一个，你都会卡在“黑屏”“无声”“不回话”这种玄学状态。下面是我在线下陪 A 同学调通时，逐条验证过的路径。

3.1 环境准备：Python 3.10 与 Ollama 的版本锁死

VirtualWife 用到了asyncio.run_coroutine_threadsafe()的新特性，必须 Python ≥ 3.10。低于此版本，bilibili_client.py会报AttributeError: module 'asyncio' has no attribute 'run_coroutine_threadsafe'。
Ollama 要求≥ 0.3.0，因为旧版不支持--format json参数，而llm_handler.py依赖此参数解析流式输出。
验证方法：

# PowerShell 中执行 python --version # 必须输出 Python 3.10.x ollama --version # 必须输出 0.3.0 或更高

若版本不符，去官网下载对应安装包（Python 从 python.org，Ollama 从 ollama.com），不要用 pip install ollama——那是 Python SDK，不是服务端。

3.2 依赖安装：用 requirements.txt 还是手动 pip？

项目根目录有requirements.txt，但直接pip install -r requirements.txt会失败——因为pyglet==2.0.14与pynput==1.7.6在 Windows 上有编译冲突。
正确做法是分两步：

# 先装图形库（需 VS Build Tools） pip install pyglet==2.0.14 # 再装其余（纯 Python） pip install -r requirements.txt --no-deps

--no-deps是关键，避免 pip 自动装pyglet的依赖。实测某次pip install pynput会顺带升级pyglet到 2.1.0，导致 Live2D 渲染窗口白屏（API 变更未适配）。

3.3 模型加载：Ollama 拉取与 Live2D 模型校验

Ollama 模型必须用ollama pull命令拉取，不能手动丢.gguf文件：

# 在项目根目录执行 ollama pull phi:mini # 注意：不是 phi-3-mini，Ollama 的 NAME 是简写的

拉取完成后，检查ollama list输出是否含phi（NAME 列），且SIZE与models/ollama/phi-3-mini.Q4_K_M.gguf大小一致（1.8GB）。
Live2D 模型校验更关键：用文本编辑器打开/models/live2d/model3.json，搜索"moc3"，确认"path": "moc3.moc3"存在；再搜索"textures"，确认"path": "texture_00.png"存在。少一个路径，live2d_renderer.py初始化时就会FileNotFoundError。

3.4 配置填写：B 站房间与密钥的三处校验

B 站接入不是填对room_id就行。bilibili_config.toml有三个必填字段：

• room_id = 1234567：必须是纯数字，不能带https://live.bilibili.com/前缀
• access_key = "abcd1234..."：从 B 站开放平台申请，不是 cookie 里的 SESSDATA
• app_key = "1234567890abcdef"：同上，申请时分配的 16 位 hex 字符串

填完后，运行python -m utils.debug_bilibili_auth（项目自带的调试模块），它会尝试连接 B 站鉴权服务器。成功返回{"code":0,"message":"0","ttl":1}，失败则返回具体错误码（如code=10016是 access_key 过期）。

3.5 首次启动：用 debug 模式捕获第一帧问题

不要直接双击start.bat。用 PowerShell 进入项目根目录，执行：

python main.py --debug

此时会弹出三个窗口：

• 主窗口（Live2D 模型）
• Audio Monitor（绿色波形图，说话时应跳动）
• LLM Debug Console（空白，等弹幕触发）

关键观察点：

• 若 Audio Monitor 无反应：检查tts_engine.py是否调用了edge-tts，运行edge-tts --list-voices | findstr "zh-CN"看是否有中文语音
• 若主窗口黑屏：用任务管理器看python.exe进程 CPU 占用是否 > 90%，若是，大概率pyglet初始化失败，重装pyglet==2.0.14
• 若 LLM Debug Console 一直空：发一条弹幕“你好”，看 console 是否打印PROMPT: ...，没有则bilibili_client.py未收到消息，检查room_id是否填错

3.6 弹幕响应验证：构造最小测试用例

B 站弹幕有审核机制，普通“你好”可能被吞。用以下三句话依次测试：

1. test123（纯字母数字，必过）
2. 虚拟老婆在吗（含关键词，触发默认回复）
3. 讲个笑话（触发 LLM 生成）

每发一句，盯LLM Debug Console：

• 若出现PROMPT: ...但无RESPONSE:：LLM 卡住，检查ollama_config.yaml的timeout_sec（默认 15），调大到 30
• 若出现RESPONSE: ...但嘴不动：检查tts_engine.py是否成功生成temp/output.mp3，用播放器打开听是否真有声
• 若有声但嘴不动：audio_utils.py的normalize_audio_buffer()返回值是否为全 0？用print(np.max(buffer))插桩验证

3.7 推流上线：用 OBS 替代内置推流（推荐方案）

项目自带rtmp_publisher.py，但实测在 B 站推流稳定性差（丢帧率 > 15%）。强烈建议用 OBS 推流：

1. 在 OBS 新建“窗口捕获”，源选择 VirtualWife 主窗口
2. 设置分辨率：1280x720（必须与 Live2D 模型 canvas 一致，否则拉伸变形）
3. 推流地址：rtmp://live-push.bilivideo.com/live-bvc
4. 流名称：{room_id}_{access_key}（B 站要求格式）
   这样做的好处：OBS 有硬件加速、丢帧补偿、码率自适应，比 Python 自研推流稳 3 倍。A 同学第一次用内置推流播了 2 小时，B 站后台显示卡顿率 41%；切 OBS 后降到 1.2%。

4. 避坑指南：六个血泪经验总结，覆盖 92% 的首次翻车场景

部署 VirtualWife 最容易栽在“看起来都对，就是不动”的状态。以下是我在某跨平台系统集成中踩过的坑，按发生频率排序，每条都附可复现现象、根本原因和一招解决法。

4.1 现象：Live2D 模型显示黑屏或白屏，CPU 占用飙高

原因：pyglet版本不兼容。VirtualWife 依赖pyglet==2.0.14的 OpenGL 上下文初始化逻辑，而pip install pyglet默认装最新版（2.1.x），其Window.__init__()方法签名变更，导致live2d_renderer.py的setup_gl()调用失败，但异常被静默吞掉。
解决：

pip uninstall pyglet -y pip install pyglet==2.0.14

验证：启动后任务管理器看python.exeCPU 是否回落至 < 10%，且主窗口显示模型轮廓。

4.2 现象：弹幕能收到，LLM 也返回文字，但 TTS 不发声，嘴也不动

原因：tts_engine.py调用edge-tts时，Windows 系统未启用“语音识别”功能。Edge TTS 引擎底层依赖 Windows Speech Platform，若系统设置 → 隐私 → 语音识别 关闭，则edge-tts进程会秒退，subprocess.run()返回码 1，但代码里没检查returncode。
解决：

1. 打开 Windows 设置 → 隐私 → 语音识别 → 开启“在线语音识别”
2. 在 PowerShell 运行edge-tts --text "测试" --write-media temp/test.mp3，看是否生成文件
3. 若仍失败，运行DISM /Online /Enable-Feature /FeatureName:SpeechRuntime /All /NoRestart启用语音运行时

4.3 现象：Ollama 模型加载成功，但每次 LLM 响应都超时（15 秒后报 ERROR）

原因：ollama_config.yaml的model_name与ollama list输出的 NAME 不一致。Ollama 对 NAME 大小写敏感，phi-3-mini和phi:mini是两个模型。项目代码里llm_handler.py的run_ollama()方法用subprocess.Popen(["ollama", "run", model_name])，若 NAME 错，Ollama 会卡在下载界面（无网络时假死）。
解决：

ollama list # 看清楚 NAME 列实际值 # 修改 ollama_config.yaml 的 model_name 为完全一致的字符串 # 例如：model_name: "phi:mini"（不是 phi-3-mini）

4.4 现象：B 站弹幕能收到，但发送“讲个笑话”后，LLM Debug Console 显示RESPONSE: null

原因：llm_handler.py的parse_ollama_stream()函数假设 Ollama 输出 JSON 行，但某些模型（如 Qwen2）在流式输出时，首行是{"model":"qwen2"...}，后续才是{"response":"..."}。而代码只取最后一行json.loads(line)，若最后一行是空或{}，就返回null。
解决：
修改llm_handler.py第 87 行：

# 原代码： response = json.loads(lines[-1]).get("response", "") # 改为： for line in reversed(lines): try: obj = json.loads(line) if "response" in obj and obj["response"].strip(): response = obj["response"] break except: continue else: response = ""

4.5 现象：Live2D 嘴型张合幅度极小，像轻微抽搐，跟不上语音节奏

原因：live2d_config.json的mouth_open_threshold设太高（如 0.5），导致只有爆破音（b/p/t）才能触发张嘴，而中文元音（a/e/i）振幅不足。同时mouth_curve为空，线性映射无法拟合语音频谱特性。
解决：

1. 将mouth_open_threshold从 0.35 降至 0.25
2. 在mouth_curve字段填入非线性校正点：

"mouth_curve": [[0.0,0.0],[0.15,0.05],[0.3,0.25],[0.5,0.6],[0.8,0.9],[1.0,1.0]]

3. 重启程序，用debug_mode.bat观察 Audio Monitor 波形与嘴型同步性

4.6 现象：OBS 推流画面正常，但 B 站观众看到模型卡在第一帧，不眨眼不动作

原因：OBS “窗口捕获” 源默认勾选“捕获透明度”，而 VirtualWife 主窗口使用pyglet的set_alpha(0.0)实现背景透明。开启此选项会导致 OBS 捕获到 alpha 通道，B 站播放器解码异常。
解决：

1. 在 OBS 中右键“窗口捕获”源 → 属性
2. 取消勾选 “Capture transparency”
3. 点击“确定”，重启 OBS 源

5. 进阶技巧：用弹幕关键词触发 Live2D 动作组，实现真正交互

VirtualWife 默认只响应弹幕文本生成回复，但 Live2D 模型本身支持多组预设动作（如挥手、点头、生气）。项目预留了接口，只是没在 UI 暴露。下面教你用 3 行代码，让观众发“比心”就触发heart.motion3.json动作，发“鼓掌”就播clap.motion3.json。这才是 B 站直播该有的沉浸感。

5.1 动作组准备：把 motion3.json 放进指定路径

Live2D 动作文件必须是.motion3.json格式（Cubism 导出），且放在/models/live2d/motions/目录下。命名规则：{动作名}.motion3.json，例如：

• heart.motion3.json（比心动作）
• clap.motion3.json（鼓掌动作）
• angry.motion3.json（生气动作）

关键点：打开heart.motion3.json，搜索"motion_groups"，确认存在"group": "gesture"字段。项目代码里live2d_renderer.py的play_motion()方法，只认group值为"gesture"、"idle"、"talk"的动作。若你的动作文件group是"custom"，需手动改为"gesture"。

5.2 弹幕关键词绑定：修改 text_filter.py 的触发逻辑

打开/utils/text_filter.py，找到filter_sensitive_words()函数下方，插入新函数：

def parse_danmu_action(danmu_text: str) -> Optional[str]: """ 解析弹幕关键词，返回对应动作组名 """ danmu_text = danmu_text.strip() if "比心" in danmu_text or "♥" in danmu_text: return "heart" elif "鼓掌" in danmu_text or "👏" in danmu_text: return "clap" elif "生气" in danmu_text or "怒" in danmu_text: return "angry" return None

然后在/core/bilibili_client.py的handle_danmu()方法里（约第 120 行），在self.llm_queue.put(...)之前插入：

# 新增：解析动作关键词 action_name = parse_danmu_action(danmu_text) if action_name: # 直接触发动作，不走 LLM self.live2d_queue.put(("motion", action_name)) return

这样，当弹幕含“比心”时，直接跳过 LLM，向 Live2D 渲染器发指令。

5.3 渲染器指令接收：扩展现有队列协议

/core/live2d_renderer.py的update()方法里，self.command_queue当前只处理("text", str)类型。我们要支持("motion", str)：

# 在 update() 方法开头，command_queue.get_nowait() 后添加 try: cmd_type, cmd_data = self.command_queue.get_nowait() if cmd_type == "motion": # 播放指定动作 self.play_motion(cmd_data) # 此方法已存在 return except queue.Empty: pass

play_motion()方法会自动查找/models/live2d/motions/{cmd_data}.motion3.json并播放。注意：动作播放期间，talk动作会暂停，所以("motion", "heart")和("text", "...")不会冲突。

5.4 效果验证与参数调优表格

改完代码后，不用重启整个服务。live2d_renderer.py支持热重载（pyglet的schedule_interval机制），只需保存文件，3 秒内生效。以下是常用动作的参数调优参考（基于实测 Phi-3-mini + Live2D Cubism 4.4）：

fade_in_sec控制动作淡入时间，priority控制动作抢占权。这些值在play_motion()调用时传入，例如：

self.play_motion("heart", fade_in_sec=0.15, priority=2)

5.5 防刷保护：给动作指令加冷却时间

观众刷“比心”一百次，模型不会疯掉——我们加个 5 秒冷却：
在/core/live2d_renderer.py类顶部加：

from time import time self.last_action_time = {}

在play_motion()方法开头加：

now = time() if now - self.last_action_time.get(action_name, 0) < 5.0: return # 5秒内不重复播同一动作 self.last_action_time[action_name] = now

这样，即使弹幕洪水，每个动作每 5 秒最多触发一次，既保体验又防崩溃。

从那以后我每次给客户部署 VirtualWife，都强制走一遍这五步：先ollama list确认模型名，再edge-tts --list-voices看语音包，接着用debug_mode.bat看三窗口联动，然后发三条测试弹幕，最后才切 OBS 推流。少走一步，后面两小时都在查日志。希望帮到你。

本文还有配套的精品资源，点击获取