> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/troubleshooting.md). # 排查具身化问题 诊断 Convai 具身化系统中的骨骼检测、预设槽位、模块 Tick 和面部合成问题，并提供修复与验证步骤。 当角色的 Rig 无法被正确检测、某个具身预设没有按预期生效、某个模块似乎从不更新，或者两个模块看起来在争夺同一个面部表情时，请使用此页面。先从 [具身编辑器窗口](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-editor.md) ——它的 `设置` 选项卡和 `预设` 选项卡表面会直接处理大多数这些问题，并在可用时提供一键修复。 ### 故障排查表 | 症状 | 可能原因 | 修复方法 | 验证 | | ------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | 具身编辑器中的 Rig 部分显示为 `未设置` | 未选择角色，或者所选 `游戏对象` 没有 `ConvaiCharacter` 组件 | 在 Hierarchy 中选择该角色，或者将 `ConvaiCharacter` 添加到其 `游戏对象` | “ `设置` 选项卡的 `Rig` 部分标题会变为 `就绪` 或 `需要注意` | | Rig 部分显示为 `需要注意`："没有 Animator（可选）" 或 "Rig 不是 Humanoid" | 该角色没有 `Animator`，或者其 Rig 未设置为 `Humanoid` | 如果角色不需要骨骼身体运动，则跳过此项；否则请将模型的 Rig 类型在 `Humanoid` 其导入设置中 | 该发现项会被一个 `正常` 发现项替代，或者替换为针对以下骨骼解析的发现项： `头部`/`左眼`/`右眼` | | Rig 部分显示为 `需要注意`："Face rig 未被识别" | `StandardRigBinding.DetectedConvention` 解析为 `未知` ——面部网格不符合已知的 blendshape 命名约定 | 设置 `约定覆盖` 在 `StandardRigBinding` 组件手动设置，或者指定一个 `CustomRigConventionMap` | 该发现项会被一个 `正常` 发现项会命名该约定 | | Rig 部分显示为 `需要注意`: `……但勉强` | `DetectionConfidence` 低于 `50%` | 检查表情和口型同步是否正确；如果不正确，请手动设置该约定，而不要相信自动检测 | `DetectionConfidence` 由 `StandardRigBinding` 升至高于 `50%`，或者该约定是手动设置的 | | "Head"、"Left eye" 或 "Right eye" 骨骼发现项显示警告 | 该 Rig 的 Humanoid Avatar 中没有为该语义映射骨骼，或者该 Rig 不是 Humanoid | 将模型的 Rig 类型设置为 `Humanoid` 在其导入设置中，或者在上显式指定骨骼覆盖 `StandardRigBinding` | `StandardRigBinding.TryGetBone` 对该骨骼返回 `是`，相应警告就会停止在 Console 中出现 | | 每次你碰到角色时，Console 都会重复一条 Rig 骨骼或 blendshape 警告 | 第一次未命中属于正常情况——这是 Rig 缺失，不是 bug | 补上缺失项（见上面两行），或者如果需要它的功能未在使用中，则忽略它 | 该警告在组件生命周期内只会记录一次，而不是每帧一次，因此在没有状态变化的情况下不应再次出现 | | 一个 `ConvaiEmbodimentPreset` 显示 `未设置` 在具身编辑器的 `预设` 选项卡 | 该预设包含重复的模块 ID、一个未选择模块的槽位，或者一个指向错误配置文件类型的槽位 | 打开预设并使用该发现项的修复按钮，例如 `移除重复项` 或 `清除设置` | 该预设在 `预设` 选项卡中的状态会变为 `就绪` 或 `需要注意` | | 某个模块的设置与所分配预设所要求的不一致 | `保留缺失槽位` 已启用，并且预设中没有该模块的槽位，因此该模块保留了其在 Inspector 中分配的自身配置文件 | 在预设中为该模块添加一个槽位，或者禁用 `保留缺失槽位` 如果你希望所有未列出的模块都改为回退到其默认配置文件 | 该角色的 Console 预设诊断消息不再将该模块列在“Active receivers without a preset slot”下 | | 某个模块似乎从不更新——它在运行时状态从不变化 | 该组件不在相同的 `游戏对象` 层级中，和 `ConvaiCharacter`，因此它已自行禁用 | 将该组件移动到角色的 `游戏对象` 或其某个子对象上 | Console 中提到该组件并指出“is not on a Convai character”的错误不再出现，并且组件在进入 Play 模式后仍保持启用 | | 某个模块先是能正常更新一段时间，然后悄无声息地停止 | 该模块的 tick 抛出了异常，这会被报告一次，然后该模块会被跳过 | 检查 Console 中的“threw during its embodiment tick”消息，并修复该模块中的底层异常 | 一旦引发异常的代码被修正并重新进入场景，该模块就会恢复更新 | | 两个模块看起来在争夺同一个面部表情 | 两个模块正在同一面部区域驱动 blendshape，且权重相互冲突 | 检查角色上的按区域权重 `ConvaiFacialCompositionProfile` ，而不是禁用任一模块——面部输出是按区域将 Emotion、LipSync 和 Custom 图层进行加权混合，而不是独占锁 | 该区域的 blendshape 会稳定成一个一致的表情，而不是明显地来回震荡 | ### 未检测到 Rig 或置信度过低 具身编辑器的 `设置` 选项卡会报告角色的 `StandardRigBinding` 在 `Rig` 部分下。如果角色还没有 `StandardRigBinding` 组件，该选项卡会显示“Rig will be worked out automatically”——Convai 会在角色启动的那一刻解析它，所以这本身不是问题。 一旦 `StandardRigBinding` 存在（无论是手动添加还是通过 **Set Up This Character** 按钮添加），其 `DetectedConvention` 和 `DetectionConfidence` 来自检查角色的面部网格。检测置信度低于 `50%` 会被视为值得检查的猜测： ``` Face rig 被检测为 ，但只是勉强达到 ``` 如果完全没有已知约定匹配， `DetectedConvention` 保持 `未知` 并且选项卡会报告： ``` Face rig 未被识别 ``` 在这两种情况下，请设置 `约定覆盖` 在 `StandardRigBinding` 组件，或者提供一个 `CustomRigConventionMap` 用于不匹配任何内置约定的 Rig。参见 [角色 Rig 设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) 以了解完整的检测模型。 缺少骨骼或 blendshape 时，会在组件生命周期内通过 Console 记录一次警告： ``` [] 该 Rig 没有 '' 骨骼，因此任何需要它的内容都会保持未激活。请在 Character Rig 组件的 Custom Rig Setup 下为其分配，或使用其 humanoid avatar 映射了该骨骼的 Rig。 ``` ``` [] 该角色上的任何网格都没有 '' blendshape，因此任何驱动它的内容都会保持未激活。请将该 blendshape 添加到面部网格，或在 Custom Convention Map 下映射其实际名称。 ``` 这两条消息都来自 `StandardRigBinding.TryGetBone` 和 `TryGetBlendshape`。一旦相应的骨骼或 blendshape 得到解析，或者你分配了显式覆盖，它们就会停止重复。 ### 预设槽位不匹配 一个 `ConvaiEmbodimentPreset` 将模块 ID 映射到配置文件资源。问题有两个来自预设资源本身： * **重复的模块 ID。** 如果某个预设把同一个模块列了两次，则只会使用第一个匹配的槽位。Console 会记录： ``` 重复的模块配置文件槽位：。将使用第一个匹配槽位。 ``` 在具身编辑器的 `预设` 选项卡中打开预设并移除重复项。 * **某个槽位命名了项目未安装的模块**、一个未选择模块的槽位，或者一个为该模块分配了错误类型配置文件的槽位。这些都会在 `预设` 选项卡中各自显示为单独的发现项，并带有一个可移除或清除有问题槽位的修复按钮。 另外， `ConvaiEmbodimentPresetBinding` 会将预设与角色上实际存在的模块进行比较，并在有任何异常时记录一条合并诊断消息： ``` [ConvaiEmbodimentPresetBinding] 预设 '' 在 '' 上的诊断： ``` “ `` 部分可包含以下任意内容： * `没有活动接收器的配置文件槽位：。` ——预设配置了角色没有的模块。 * `具有空配置文件的槽位：。` ——槽位存在，但未分配配置文件资源。 * `没有预设槽位的活动接收器；将保留 Inspector 配置文件：。` ——在以下情况下显示： `保留缺失槽位` 已启用：没有匹配槽位的模块会保留其自身组件上分配的配置文件。 * `没有预设槽位的活动接收器；将应用空配置文件：。` ——在以下情况下显示： `保留缺失槽位` 已禁用：没有匹配槽位的模块会回退到 `null`，它会解析为其内置默认配置文件。 * `空白配置文件槽位索引：。` ——某个槽位条目根本没有模块 ID。 如果某个模块的行为与您从预设中预期的不一致，请先检查 `保留缺失槽位` 时 `ConvaiEmbodimentPresetBinding` ——它决定未列出的模块是保留自身设置还是重置为默认值。 ### 某个模块没有在 tick 每个具身模块都会在以下位置向角色的 tick 调度器注册： `OnEnable` 通过 `EmbodimentContext.RegisterTickable`。两种不同的故障看起来相似，但原因不同。 **该组件根本没有注册。** 当该组件不在相同的 `游戏对象` 层级中，和 `ConvaiCharacter`。该组件会自行禁用，并且 Console 会记录： ``` [] '' 不在 Convai 角色上，因此它没有可驱动的内容。请将此组件移动到带有 Convai Character 组件的对象（或其子对象）上。 ``` 将该组件移动到角色的 `游戏对象` 或其子对象上，然后重新启用它。 **该组件已注册，但其 tick 抛出异常。** 调度器会捕获任一单个模块 tick 中的异常，只报告一次，并继续正常 tick 其他所有模块： ``` [EmbodimentTickScheduler] '' 上的 在其 embodiment tick 期间抛出了异常，并且只会被报告一次。该角色上的其他模块不受影响。 ``` 由于这只会在每次会话中每个模块报告一次，因此如果某个模块看起来“停止工作”而 Console 不再输出任何内容，这通常就是这种情况的标志。修复源头处的异常并重新进入 Play 模式——模块就会在修复后恢复。 如果两种消息都没有出现，而模块仍然看起来没有反应，请确认场景处于 Play 模式：tick 调度器只会在运行时创建，因此在 Edit 模式下，除具身编辑器的 `实时` 选项卡。 ### 模块之间的面部输出冲突 面部 blendshape 并不由单个模块独占。相反，每个 blendshape 区域（嘴、眉、眼、脸颊/鼻子、下巴以及其他所有部分）都会根据角色上的按区域权重，将 Emotion、LipSync 和 Custom 图层混合在一起 `ConvaiFacialCompositionProfile`，并分别对应静止和说话状态。 可见的冲突——表情闪烁或过冲而不是稳定下来——通常意味着两个图层以相近权重向同一区域贡献了冲突值，而不是某个模块坏了。请检查 `ConvaiFacialCompositionProfile` 该区域在上的权重，而不是禁用其中一个模块：降低该区域中某一图层的权重，或者通过调整其名称模式将某个 blendshape 移到不同区域，可以在不丢失模块其他输出的情况下解决冲突。参见 [面部组合](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md) 以了解完整的按区域加权模型。 ### 下一步 {% content-ref url="/pages/526da9bf1ae481254ffde1d02128e23947af7af5" %} [具身化编辑器窗口](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-editor.md) {% endcontent-ref %} {% content-ref url="/pages/dddb9a87015e6befbe3c15caf6aa6b2df224fa33" %} [角色骨架设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) {% endcontent-ref %} {% content-ref url="/pages/260c8f480c6e05ba6ea9db729322298e970606cc" %} [具身化预设](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-presets.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.