Open-LLM-VTuber 报错排查：Live2D 模型文件结构缺失

在部署 Open-LLM-VTuber 时，加载自定义 Live2D 模型容易遇到引擎初始化失败，或者触发表情时报 NoneType 异常的问题。排查物理目录会发现 .moc3 核心文件和 .exp3.json 表情文件都在，但后端依然提示文件丢失。

问题出在主配置文件 .model3.json 的内部索引结构不完整。

1. 解析机制偏差

Open-LLM-VTuber 后端不会主动遍历目录去扫描所有物理文件。它完全依赖模型的主配置文件（.model3.json）来加载资源。如果建模师在导出模型时，没有将表情（Expressions）写入主 JSON，后端引擎就不会注册这些资产。

当 LLM 输出包含特定情绪的文本并触发面部表情时，后端在索引里找不到对应项，就会触发空指针异常，直接拉挂进程。

2. 补齐文件索引

修复方法是手动修改模型主 JSON 文件。使用文本编辑器打开模型目录下的 xxx.model3.json 文件。

找到 FileReferences 节点，检查内部是否包含 Expressions 数组。如果没有，手动加上，并将文件夹里的 .exp3.json 文件映射进去。

代码修改对齐如下：

{
    "Version": 3,
    "FileReferences": {
        "Moc": "魔女.moc3", 
        "Textures": [
            "魔女.8192/texture_00.png",
            "魔女.8192/texture_01.png"
        ],
        "Physics": "魔女.physics3.json",
        "DisplayInfo": "魔女.cdi3.json",
        "Expressions": [
            {"Name": "fz", "File": "fz.exp3.json"},
            {"Name": "cw", "File": "cw.exp3.json"}
        ]
    }
}

Name 字段是代码层调用的内部名称，File 字段对应同级目录下的物理文件相对路径。确保语法结构正确，逗号和括号严格闭合。

3. 动作文件同步关联

如果你的模型目录下存在 .motion3.json 动作文件，同理需要在 FileReferences 内部增加 Motions 节点进行注册。修改并保存 JSON 文件后，重启 Docker 容器。后端会根据完整的映射表重新载入模型资产。

4.再次运行

docker compose down
docker compose up

输入http://127.0.0.1:12393