> 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/web-plugins/convai-embody/use-your-own-3d-model.md).

# 使用你自己的 3D 模型

使用你托管的 MetaHuman GLB 模型渲染一个 Convai 角色，包括 Full 和 Lite 文件以及你自己的动画片段。

使用您自行托管的 3D 模型来渲染 Convai 角色，而不是使用 Convai 为角色提供的身体模型。如果您有导出为 GLB 的自有 MetaHuman，请参阅本页。完成后，您的模型将替代默认身体模型加载，并通过角色常规的 Convai 连接实现语音、口型同步、注视和眨眼。

### 前提条件

* 已渲染角色的页面。请参阅 [将 3D 角色添加到 React 应用](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md) 或 [将 3D 角色添加到 three.js 场景](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-three-js-scene.md).
* 基于 Unreal Engine MetaHuman 骨架构建的 GLB 格式模型。下一节将列出文件必须包含的内容。
* 用于托管文件的位置，页面可从该位置获取文件；如果托管位置与页面不同，还需设置允许页面访问的 CORS 标头。

### 模型要求

Convai Embody 通过骨骼和混合形状的名称驱动身体。它针对 `convai-mha-1`（Unreal Engine MetaHuman 骨架）实现了全部功能；如果文件中的 MetaHuman 名称与 Unreal Engine 导出的名称完全一致，就能实现口型同步、眨眼、眼球运动、注视和呼吸。其他面部模型和骨架会根据其包含的内容加载（请参阅下文的 [其他工具生成的模型](#models-from-other-tools) ）。

| 部分       | 名称                                                               | 用途                                        |
| -------- | ---------------------------------------------------------------- | ----------------------------------------- |
| 头部和脊柱骨骼  | `head`, `neck_01`, `neck_02`, `spine_02`, `spine_04`             | 注视和呼吸。缺少某根骨骼时，由它驱动的动作会被禁用。                |
| 身体骨骼     | MetaHuman 骨架中的其余骨骼，从 `pelvis` 和 `spine_01` 一直到 `spine_05` 以及四肢骨骼 | 动画片段，按名称指定目标骨骼。                           |
| 面部混合形状   | MetaHuman 表情变形目标， `CTRL_expressions_*`                           | 口型同步、眨眼和眼球运动。                             |
| 面部材质（可选） | 名称为 `Eyes*`, `Teeth*`和 `Eyeocclusion*`                           | 的材质。控制眼睛和牙齿的着色。使用 `faceMaterials: false`. |

Draco 压缩文件会照常加载；解码器从 `dracoDecoderPath`.

#### 其他来源的模型

其他工具生成的模型可以加载，并会在加载时接受检查。Convai Embody 会读取模型包含的内容，并报告其支持和不支持的功能，以及每个问题的修复方法：

* **ARKit 面部模型** （Ready Player Me、Apple 面部捕捉、大多数 VRM 和 Character Creator 导出模型）以及 **重命名过的 MetaHuman 面部模型** 会自动映射，因此口型同步、眨眼和眼球运动都能正常工作。映射表位于 `character.report.face.morphMap`；将其作为 `morphMap` 传入即可固定映射或修正某个条目。
* **没有混合形状的模型** 无法活动面部。报告会说明这一点；身体动画仍会正常运行。
* **动画** 会从 Mixamo、Unreal mannequin 和 Rigify 重定向到身体骨架。如果未声明动画，则会使用模型文件中包含的动画。若某个片段在其文件中缺失、无法加载，或没有驱动身体的任何骨骼，报告会列出其名称。
* **凝视与呼吸** 需要使用 MetaHuman 的头部、颈部和脊柱骨骼名称；在其他骨架上，这些功能会关闭，报告会指出缺少哪些骨骼。

将模型接入对话前，先检查模型：

```typescript
import { inspectModel, formatReport } from '@convai/embody'

const report = await inspectModel('https://assets.example.com/my-model.glb', {
  animations: { Idle: 'https://assets.example.com/idle.fbx' },
})
console.log(formatReport(report))
```

### 使用解析器描述模型

Convai Embody 通过解析器来获知身体模型文件的位置：解析器是一个带有单个 `resolve` 方法的对象，该方法会返回身体模型的清单。默认解析器会向 Convai 查询。你也可以提供自己的解析器，指向你自己的文件。

{% code title="src/myModel.ts" %}

```typescript
import type { CharacterResolver } from '@convai/embody'

export const myModel: CharacterResolver = {
  async resolve(characterId) {
    return {
      characterId,
      avatarId: 'my-model',
      representations: [
        {
          rig: 'convai-mha-1',
          model: [{ url: 'https://assets.example.com/my-model.glb' }],
          clips: {
            Idle: { url: 'https://assets.example.com/my-animations.glb' },
            Talk: { url: 'https://assets.example.com/my-animations.glb' },
          },
        },
      ],
    }
  },
}
```

{% endcode %}

| 字段                        | 说明                                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characterId`             | 需要解析的角色 ID。请原样返回。                                                                                                                                                          |
| `avatarId`                | 此模型的任意稳定标识符。它会显示为 `character.bundle.avatarId`.                                                                                                                             |
| `representations`         | 每种骨架对应的模型。列出一个模型，并设置 `rig: 'convai-mha-1'`.                                                                                                                                |
| `representations[].model` | 模型文件。一个条目就足够；若需两个，请参阅 [提供 Full 和 Lite 文件](#ship-a-full-and-a-lite-file) 。                                                                                                  |
| `representations[].clips` | 动画片段，名称对应 `{ url }`。每个名称都必须与文件中的动画名称一致。此项为可选；请参阅 [添加自定义动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md). |

### 使用你的模型渲染角色

传入解析器，并使用你已有的角色 ID 和凭据。模型由你的解析器提供，对话仍来自角色的 Convai 连接，因此角色会保留其声音、知识和记忆。

{% tabs %}
{% tab title="React" %}
{% code title="src/App.tsx" %}

```tsx
import { ConvaiCharacter } from '@convai/embody/react'
import { myModel } from './myModel'

export default function App() {
  return <ConvaiCharacter token={token} characterId="YOUR_CHARACTER_ID" resolver={myModel} />
}
```

{% endcode %}
{% endtab %}

{% tab title="three.js" %}
{% code title="src/character.ts" %}

```typescript
import { createCharacter } from '@convai/embody'
import { myModel } from './myModel'

const character = await createCharacter({
  token,
  characterId: 'YOUR_CHARACTER_ID',
  resolver: myModel,
})
```

{% endcode %}
{% endtab %}
{% endtabs %}

在 React 中，请在组件外定义解析器，或将其包装在 `useMemo`中。新的解析器对象会重新加载模型，因此在组件中内联编写解析器会导致每次渲染时都重新加载模型。只有在需要更换模型时才更改解析器。

### 让你的模型使用 Convai 动画

若要将你的模型与 Convai 为角色提供的动画搭配使用，请让默认解析器获取角色的清单，然后只替换其中的模型文件。

```typescript
import { httpResolver, type CharacterResolver } from '@convai/embody'

const convai = httpResolver({ authToken: token })

export const myModelWithConvaiClips: CharacterResolver = {
  async resolve(characterId) {
    const bundle = await convai.resolve(characterId)
    for (const rep of bundle.representations) {
      rep.model = [{ url: 'https://assets.example.com/my-model.glb' }]
    }
    return { ...bundle, avatarId: 'my-model', fallback: false }
  },
}
```

这些动画片段是为 MetaHuman 骨架制作的，因此适用于任何使用相同骨架的模型。

### 同时提供 Full 和 Lite 文件

许多手机总共只支持 256 个顶点着色器 uniform，而 three.js 会为每个混合变形占用一个，因此包含全部 251 个 MetaHuman 混合变形的头部无法在这些设备上绘制。一个角色身体可以提供两个文件： **Full**，包含所有混合变形；以及 **Lite**，包含精简后的混合变形集合。将两个文件都列出，并将 `lod` 分别设为 Full 的 0 和 Lite 的 1，同时将任意单个网格上的最大混合变形数设为 `morphTargets`.

```typescript
model: [
  { lod: 0, url: 'https://assets.example.com/my-model.glb', morphTargets: 251 },
  { lod: 1, url: 'https://assets.example.com/my-model-lite.glb', morphTargets: 103 },
],
```

Convai Embody 会在手机和平板电脑上加载 Lite；对于任何无法处理 Full 混合变形的小型 GPU，也会加载 Lite，其他情况下则加载 Full。Lite 的混合变形数量应保持在 192 个或以下，这样在仅有 256 个 uniform 的手机上，着色器的其他部分也有足够空间。 `character.model` 会报告实际加载的文件，而 `modelVariant: 'full'` 或 `'lite'` 则可强制使用其中一个版本，例如在桌面设备上检查 Lite。

### 预览模型而不建立对话连接

若要渲染不连接 Convai 的模型，例如在资产审核页面中，请传入 `connect: false`。使用解析器和 `connect: false`时，无需提供凭据。

```typescript
const character = await createCharacter({ characterId: 'preview', resolver: myModel, connect: false })
```

模型会播放片段、呼吸、眨眼并跟随摄像头，但没有语音，也没有口型同步。 `character.client` 为 `null`.

### 验证模型

运行应用并向角色发送一条消息。

{% hint style="success" %}
你的模型会出现在场景中， `character.model.url` 指向你的文件， `character.rig.missing` 为空，并且角色说话时嘴部会动。
{% endhint %}

### 故障排查

| 症状                                                                                       | 原因与解决方法                                                                                            |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `no supported representation: character offers [<rigs>], embody supports [convai-mha-1]` | 解析器中的 representation 指定了另一个骨架。对于 MetaHuman 模型，请设置 `rig: 'convai-mha-1'` 。                          |
| 控制台警告 `rig "convai-mha-1": missing required bone(s) — …`                                 | 模型缺少警告中列出的头部或脊柱骨骼，因此这些骨骼无法实现注视或呼吸动作。请导出完整的 MetaHuman 骨架，并保留其 Unreal Engine 骨骼名称。                   |
| 身体模型加载了，但角色说话时脸部没有动作                                                                     | 模型的混合形状没有采用 MetaHuman 的 `CTRL_expressions_*` 命名方式。请从 MetaHuman 导出面部表情变形目标。                         |
| 部分手机上不会渲染头部                                                                              | 模型的混合形状数量超过了手机 GPU 的处理上限。请像 [提供 Full 和 Lite 两种文件](#ship-a-full-and-a-lite-file).                   |
| 模型尺寸不正确或位于地面以下                                                                           | 模型加载时会缩放到 `targetHeight` （1.7 米），并将脚底放置在 `groundY`处。设置任一选项即可更改这些值。                                 |
| 文件始终无法加载，或 Draco 解码器发生故障                                                                 | 查看浏览器的网络面板。托管在其他主机上的文件需要配置 CORS；如果页面的内容安全策略阻止访问 `gstatic.com` ，则需要将 `dracoDecoderPath` 指向自行托管的解码器。 |

### 后续步骤

{% content-ref url="/pages/0afbd5007a23e54b6db0d1d71d05955fd870633e" %}
[为角色添加你自己的动画](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-your-own-animations.md)
{% endcontent-ref %}

{% content-ref url="/pages/b60906ed5049da52cc6ddb85571a9101f1eacdb4" %}
[createCharacter 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/createcharacter-reference.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/use-your-own-3d-model.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
