> 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/features/scene-metadata/usage-examples.md).

# 场景元数据使用示例

下面的示例涵盖了用于训练模拟和交互式体验的真实设置。每个示例都是自包含的：先说明 Inspector 配置，然后给出完成该行为所需的任何脚本。请从与你当前复杂度相匹配的示例开始。

### 示例 1：医学训练模拟 — 解剖实验室

**场景：** 一个外科训练模拟场景，由一名医护讲师 NPC 引导受训者完成解剖实验室训练。这个角色必须识别并描述房间里的实体模型和设备——受训者会提出诸如“这是什么器官？”或“主动脉在哪里？”之类的问题。

#### 设置

添加 `ConvaiObjectMetadata` 将以下内容添加到每个解剖模型和设备项：

| Object Name | Object Description             |
| ----------- | ------------------------------ |
| 心脏模型        | 放在中央检查台上的等大解剖心脏模型。显示四个心腔和主要血管。 |
| 肝脏模型        | 安装在展示架左侧的成人肝脏模型。肝静脉采用颜色编码。     |
| 手术手术刀       | 放置在器械托盘上的标准手术刀。刀柄为蓝色。          |
| Stethoscope | 听诊器挂在检查台旁的挂钩上。                 |

添加 `ConvaiSceneMetadataCollector` 添加到 `ConvaiManager` GameObject。启用 **Collect On Start**.

无需脚本。讲师角色在会话开始时会接收到所有描述，并且可以回答基于真实场景的解剖问题。

{% hint style="success" %}
受训者问：“有哪些模型可供学习？”讲师回答：“中央桌上有一个等大心脏模型，展示四个心腔；你左侧的展示架上有一个带颜色编码肝静脉的成人肝脏模型。”
{% endhint %}

### 示例 2：工业安全演练——按阶段的元数据

**场景：** 一个包含多个演练阶段的安全培训模块。每个阶段引入不同的危险和设备。AI 讲师应只了解当前阶段相关的道具。

#### 设置

留空 **Collect On Start** 在……上禁用 `ConvaiSceneMetadataCollector`。使用脚本在每个阶段加载后发送元数据。

```csharp
using Convai.Runtime.SceneMetadata;
using UnityEngine;

public class SafetyDrillController : MonoBehaviour
{
    [SerializeField] private ConvaiSceneMetadataCollector _metadataCollector;
    [SerializeField] private ConvaiObjectMetadata[] _phase1Props;
    [SerializeField] private ConvaiObjectMetadata[] _phase2Props;

    private ConvaiObjectMetadata[] _allProps;

    void Awake()
    {
        _allProps = GetComponentsInChildren<ConvaiObjectMetadata>(includeInactive: true);
    }

    public void LoadPhase(int phase)
    {
        // 排除所有道具
        foreach (var prop in _allProps)
            prop.IncludeInMetadata = false;

        // 仅启用当前阶段的道具
        ConvaiObjectMetadata[] activeProps = phase == 1 ? _phase1Props : _phase2Props;
        foreach (var prop in activeProps)
            prop.IncludeInMetadata = true;

        // 发送更新后的有效负载
        if (_metadataCollector.IsReadyToSendMetadata())
            _metadataCollector.CollectAndSendSceneMetadata();
    }
}
```

每个阶段只会向 Convai 发送其相关道具。讲师会根据当前演练上下文调整其知识，而不会了解其他阶段的道具。

### 示例 3：交互式博物馆——展品导览

**场景：** 一个虚拟博物馆导览角色会回答游客关于多个展厅展品的问题。导览应知道每件展品是什么、位于何处，以及它的重要之处。

#### 设置

添加 `ConvaiObjectMetadata` 将以下内容添加到每个展品的根 GameObject。编写包含位置提示和关键信息的描述：

| Object Name | Object Description                           |
| ----------- | -------------------------------------------- |
| 罗塞塔石碑复制品    | 埃及展厅中央、第 2 号房间中央的一块大型石板。包含圣书体、世俗体和古希腊文的相同文本。 |
| 罗马军团士兵盔甲    | 第 3 号房间左侧墙边的人体模型上穿着完整的军团士兵战甲。年代为公元 1 世纪。     |
| 维京长船残片      | 保存在北欧展厅、悬挂在天花板上的一段 9 世纪维京长船船首部分。             |

启用 **Collect On Start**。当游客问“第 2 号房间里有什么？”时，导览会给出准确、以描述为依据的信息。

请从一位知识渊博的导览会说的话的角度来编写描述。包括房间位置、视觉识别特征以及相关背景信息。AI 会将 `Object Description` 该字段逐字作为其回应的依据。

### 示例 4：运行时上下文更新——结合场景元数据和动态上下文

**场景：** 一个仓库培训场景，其中物品可以移动或移除。当危险被清除时，AI 应停止提及它。当新工具到达时，AI 应立即知道它。

#### 排除已清除的对象

```csharp
public void OnHazardCleared(ConvaiObjectMetadata hazardMetadata)
{
    // 从 AI 上下文中移除，而不销毁 GameObject
    hazardMetadata.IncludeInMetadata = false;

    if (_collector.IsReadyToSendMetadata())
        _collector.CollectAndSendSceneMetadata();
}
```

#### 在运行时添加新对象

```csharp
public void OnToolDelivered(GameObject toolObject, string toolName, string toolDescription)
{
    // 在运行时添加元数据组件
    var metadata = toolObject.AddComponent<ConvaiObjectMetadata>();
    metadata.ObjectName = toolName;
    metadata.ObjectDescription = toolDescription;
    // 组件会在 OnEnable 时自动注册

    if (_collector.IsReadyToSendMetadata())
        _collector.CollectAndSendSceneMetadata();
}
```

{% hint style="info" %}
场景元数据和动态上下文是相辅相成的。使用场景元数据告诉 AI 场景中存在什么。使用动态上下文告诉 AI 运行时正在发生什么。配合 `CollectAndSendSceneMetadata()` 其带有 `SetState` 对……的调用 `IConvaiDynamicContext` 可让角色同时具备对象感知和事件感知。
{% endhint %}

### 下一步

{% content-ref url="/pages/f6f3f3d88a3636afea1b0c8774162c2014fba780" %}
[排查场景元数据问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/troubleshooting-and-diagnostics.md)
{% endcontent-ref %}

{% content-ref url="/pages/eb13f9c057b5d7a65a7d8338048c0f7def05d5cf" %}
[动态上下文](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/usage-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.