> 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/quick-start.md).

# 场景元数据快速入门

设置场景元数据，使 Convai 角色能够感知场景中已命名的对象。完成后，角色将知道有哪些对象存在，并能在对话中引用它们——全部操作均可在 Inspector 中完成。

### 前提条件

开始前，请确认：

* [ ] 一个 `ConvaiCharacter` 位于场景中，并且会在播放模式下响应语音

{% stepper %}
{% step %}

#### 向场景对象添加 ConvaiObjectMetadata

在场景中选择任意一个 AI 角色应当了解的 GameObject——一件设备、灭火器、一扇门或一个展品。在 Inspector 中，点击 **添加组件**，然后浏览至 **Convai → 世界对象** 或搜索 `Convai 对象元数据`.

“ **对象名称** ”字段会根据 GameObject 的名称自动填充。如果 GameObject 名称不够描述性，请将其编辑为清晰、易读的标签——例如，将 `Prop_FireExt_01` 更改为 `灭火器`.

也可以选择性地填写 **对象描述** ，用一到两句事实性描述说明对象是什么、位于何处以及任何关键属性。请将其控制在 200 个字符以内。

{% hint style="warning" %}
**对象名称** 为必填项。若留空，该对象将不会包含在负载中—— `已注册` 会显示 `true`，但该对象不会发送到 Convai。
{% endhint %}
{% endstep %}

{% step %}

#### 向其余对象添加 ConvaiObjectMetadata

添加 `ConvaiObjectMetadata` 到 AI 应了解的每个其他对象。无需将其添加到每个 GameObject——只需添加到与 AI 对话相关的对象。

每个组件都会自行向 `ConvaiMetadataRegistry` 自动注册（在启用时）。无需手动连接或调用注册方法。
{% endstep %}

{% step %}

#### 添加 ConvaiSceneMetadataCollector 并启用自动收集

已注册的对象会在角色准备就绪后自动发送给角色，即使没有此组件也是如此—— `ConvaiSceneMetadataCollector` 是可选的。现在添加它，以便使用 **记录统计信息** 确认下一步中使用的结果，并方便日后手动重新收集；请参阅 [场景元数据的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/how-scene-metadata-works.md) 以了解完整的传递流程。

在场景中的任意 GameObject 上，点击 **添加组件** 并搜索 `Convai 场景元数据收集器`。将其放置在与 `ConvaiManager` 相同的 GameObject 上，是一种有用的组织约定。

在 Inspector 中，启用 **启动时收集**。这会指示收集器在房间会话连接时自动发送完整的元数据负载。

保持 **记录统计信息** 启用状态——它会在每次收集时写入一条 Console 日志，显示对象数量和耗时，从而确认一切正常运行。

`ConvaiSceneMetadataCollector` 会在启动时通过查找自动解析其依赖项 `ConvaiManager` 在场景中——无需手动连接。
{% endstep %}

{% step %}

#### 进入播放模式并验证

按下播放按钮。房间连接后，收集器会自动触发。检查 Console 中是否有类似以下的调试日志：

```
[ConvaiSceneMetadataCollector] 在 0.0010 秒内收集了 4 个元数据对象。注册表统计：共 4 个，4 个有效，0 个无效
```

这确认负载已组装并发送到 Convai。通过询问需要场景感知的问题来测试角色——例如：“这一层有哪些可用设备？”或“你能描述一下出口附近有什么吗？”
{% endstep %}
{% endstepper %}

{% hint style="success" %}
角色会根据你输入的名称和描述作出回应。场景元数据正在正常工作。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/b55fe13afe8f10f3ca27eec09be22c5bd975a884" %}
[场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/component-reference.md)
{% endcontent-ref %}

{% 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 %}


---

# 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/features/scene-metadata/quick-start.md?ask=<question>&goal=<endgoal>
```

`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.