场景元数据使用示例

适用于医疗培训、分阶段工业演练、博物馆导览以及运行时对象包含/排除的完整 Scene Metadata 设置。

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

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

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

设置

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

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

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

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

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

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

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

设置

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

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 应立即知道它。

排除已清除的对象

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

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

在运行时添加新对象

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();
}

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

下一步

排查场景元数据问题动态上下文