> 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 中完成。

### 先决条件

开始前，请确认：

* [ ] A `ConvaiCharacter` 已在场景中，并且在 Play Mode 中能对语音作出响应

{% stepper %}
{% step %}

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

在场景中选择任何你希望 AI 角色了解的 GameObject——例如一件设备、一个灭火器、一扇门或一个展品。在 Inspector 中，点击 **添加组件** 并搜索 `Convai 对象元数据`.

该 **Object Name** 该字段会根据 GameObject 的名称自动填充。如果 GameObject 名称不够直观，请将其编辑为清晰、易读的标签——例如，将 `Prop_FireExt_01` 到 `灭火器`.

可选填写 **Object Description** ，写一到两句事实性描述：该对象是什么、位于哪里以及任何关键属性。请控制在 200 个字符以内。

{% hint style="warning" %}
**Object Name** 是必填项。留空则该对象会从有效负载中排除—— `Is Registered` 显示 `true`，但该对象不会传送到 Convai。
{% endhint %}
{% endstep %}

{% step %}

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

添加 `ConvaiObjectMetadata` 到每个你希望 AI 了解的额外对象上。你不需要将它添加到每个 GameObject——只需添加到与 AI 对话相关的对象即可。

每个组件都会自动向 `ConvaiMetadataRegistry` 注册，在启用时自动完成。无需手动连接或调用注册。
{% endstep %}

{% step %}

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

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

在 Inspector 中启用 **Collect On Start**。这会告诉收集器在房间会话连接时自动发送完整的元数据有效负载。

留空 **日志统计** 已启用——它会在每次收集时向 Console 写入一条记录，显示对象数量和耗时，用于确认一切正常。

`ConvaiSceneMetadataCollector` 会在启动时通过查找 `ConvaiManager` 场景中的相关依赖——无需手动连接。
{% endstep %}

{% step %}

#### 进入 Play Mode 并验证

按下 Play。房间连接后，收集器会自动触发。请检查 Console 中类似以下内容的调试记录：

```
[ConvaiSceneMetadataCollector] Collected 4 metadata objects in 0.0010s. Registry stats: 4 total, 4 valid, 0 invalid
```

这表明有效负载已组装并发送到 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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/quick-start.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.