Semantic Search是一款编辑器插件,可为内容浏览器添加人工智能(AI)搜索模式。 它不会按字面意思匹配资产名称和标签,而是根据视觉和上下文含义对资产进行排序。
例如,搜索 " rusted metal barrel " 可以返回名为 M_OldOilDrum 的资产,即使这些词没有出现在资产名称中。
运行方式
该插件通过创建内容浏览器资产的内存向量搜索索引来工作。 当对资产进行索引时,该插件会构建AI生成的该资产的简短描述,将该描述嵌入为向量,并将结果存储在混合关键字加向量索引中。 然后,内容浏览器搜索查询使用该索引显示语义匹配项。
概括来说:
该插件会收集支持的资产数据,通常包括缓存的缩略图、资产路径、资产类和选定的元数据。
配置好的兼容OpenAI的聊天补全端点,用于为资产生成标签和描述
配置好的兼容OpenAI的嵌入端点会为说明创建向量嵌入。
该插件将说明文字、标签和嵌入存储在派生数据缓存中,并将资产添加到内存搜索索引中。
文本搜索嵌入搜索查询,并将其与索引资产嵌入进行比较。 如果启用混合搜索(默认行为),则基于关键字的精确匹配将与语义匹配融为一体。
启用插件
打开编辑(Edit) > 插件(Plugins)。
搜索Semantic Search。
在实验插件列表下启用该插件。
重启编辑器。
编辑器重启后,每个内容浏览器搜索栏的右侧都有一个AI开关。 点击它即可为内容浏览器启用AI搜索模式。 AI模式激活时,按钮会变成青色。
主用户界面
该插件添加了以下编辑器用户界面:
| UI | 位置 | 用途 |
|---|---|---|
AI切换 | 每个内容浏览器搜索栏的右侧 | 开启或关闭语义搜索模式。 |
索引状态 | 内容浏览器导航栏,在AI模式开启时可见 | 显示已编入索引、未索引和失败的计数,并带有内联刷新、重试和取消按钮。 |
统计对话框 | 工具(Tools) > Semantic Search | 显示索引统计信息,并允许你在Flat索引和量化索引之间切换索引类型。 |
设置(Settings) | 编辑(Edit)> 编辑器偏好设置(Editor Preferences)> 插件(Plugins)> 语义搜索(Semantic Search) | 配置提供程序、索引、HTTP、向量索引和搜索行为。 |
查找相似 | 在AI模式开启时,右键单击内容浏览器中的单个资产 | 搜索与所选资产相似的资产。 |
配置提供程序
提供程序是插件调用的后台服务,用于将资产缩略图和元数据转换为说明文字,并将说明文字或搜索文本转换为嵌入。
打开编辑(Edit) > 编辑器偏好设置(Editor Preferences) > 插件(Plugins) > Semantic Search,并配置提供程序(Provider)部分。
该插件目前仅提供一种提供程序类型:兼容OpenAI的API。
它会调用:
/chat/completions用于资产说明文字/embeddings 用于文本嵌入
| 设置 | 默认 | 说明 |
|---|---|---|
提供程序 | 兼容 OpenAI 的 API | 用于说明文字和嵌入的后端。 |
描述生成基础网址 | 兼容OpenAI的API的基本URL。 该插件向<Captioning Base URL> /chat/completions 发送说明文字请求。 | |
描述生成API密钥 | empty | 在请求中以Authorization: Bearer <key>形式发送。 |
描述生成模型 | gpt-5.4-mini | 用于为资产生成标题和标签的模型。 必须具有视觉功能,因为支持的视觉资产会发送缩略图或屏幕截图。 |
嵌入基础URL | 嵌入请求将发送到<Embedding Base URL> /embeddings。 可能与说明文字URL不同。 | |
嵌入API密钥 | empty | 以Authorization: Bearer <key>形式发送。 可以与说明文字键相同。 |
嵌入模型 | text-embedding-3-small | 用于为资产说明文字和搜索查询创建嵌入的模型。 |
嵌入维度 | 512 | 嵌入的大小。 作为嵌入请求中的维度参数发送。 |
提供程序设置存储在项目编辑器的每用户设置配置中,位于[/Script/SemanticSearch.SemanticSearchSettings]下。
即使编辑器字段显示为密码字段,API密钥仍将以明文形式存储。
更改任何提供程序设置都会重新注册提供程序,取消激活索引,并将向量索引重新构建为Flat,维度为配置的维度。 更改提供程序值后重新编制索引。
构建索引
打开内容浏览器。
点击 AI 按钮,它会变成青色。
查找Semantic Search Index:在内容浏览器导航栏中。
如果资产被列为未索引,请点击未索引计数旁边的刷新按钮。
索引状态栏可以显示:
| 状态 | 含义 |
|---|---|
| 当前在语义索引中的资产。 该计数旁边的刷新按钮会从头开始重新索引所有支持的资产。 |
| 已索引路径中当前未索引的受支持资产。 此计数旁边的刷新按钮仅索引这些资产。 |
| 可重试的提供程序故障,例如HTTP错误或速率限制。 该计数旁边的刷新按钮会重试失败的资产。 |
X按钮 | 索引处于活动状态时可见。 取消排队的索引工作和挂起的提供程序请求。 |
索引在后台运行并显示进度通知。 它运行时,你可以继续在编辑器中工作。
对于每个未缓存的索引资产,预计会向配置的后端发送一个说明文字请求和一个嵌入请求。
支持的资产类型
目前仅支持以下资产类型
静态网格体
骨骼网格体
材质(Material)
材质实例
纹理
蓝图(仅限那些有相关缩略图的蓝图)
对于属于其中一种资产类型的任何资产,我们使用其编辑器缓存的缩略图、资产路径和类别以及一些元数据标签来为该资产创建说明文字请求。
索引过程中会忽略不支持的资产。
对于任何语义搜索查询,未编入索引或不支持的资产不会出现在 AI 搜索结果中,即使它们在内容浏览器中正常可见。
搜索
启用AI模式并填充索引后:
在内容浏览器搜索栏中输入自然语言查询。
按Enter。
当你提交查询时,会提取语义搜索结果。 它们不会像标准内容浏览器搜索那样在每次按键时持续更新。
搜索示例:
wooden crate
rusted metal barrel
glowing neon sign
low-poly rock
red metallic surface
large industrial machine
语义搜索插件与所有内容浏览器筛选兼容。 文件夹、集合和类筛选在应用语义排名之前确定候选集合。 使用普通的内容浏览器过滤器将搜索范围缩小到网格、材质、纹理或特定文件夹。
当AI模式开启但搜索栏为空时,内容浏览器会正常传递项目,因此你仍然可以浏览文件夹。
查找相似
“查找相似” 在嵌入空间中搜索选定参考资产 “附近” 的资产。
在内容浏览器中启用AI模式。
右键单击一项资产。
选择查找相似。
该插件在搜索框中填充了/find-similar <AssetObjectPath>并返回语义上相似的索引资产。
右键单击菜单项仅在AI模式处于活动状态、仅选择了一个资产且索引至少有一个向量时才会显示。 如果所选资产本身未被索引,则搜索不会返回任何结果。
默认情况下,"查找相似"仅在当前文件夹中查找相似资产。 要在整个项目中查找相似资产,请在内容浏览器文件夹选择器中将根文件夹更改为/All。
限制索引路径
默认情况下,索引路径包含/,这意味着该插件会考虑与该前缀匹配的所有内容浏览器包根目录。
要限制索引:
打开编辑(Edit) > 编辑器偏好设置(Editor Preferences) > 插件(Plugins) > Semantic Search。
在索引下,删除/条目。
添加一个或多个包路径,例如
/Game/Props/或Game/Environments/Forest/。从内容浏览器状态栏重新索引。
限制索引路径是减少索引时间、提供程序使用量和成本的最简单方法。
索引类型
打开工具 > 语义搜索以查看索引统计信息并切换索引类型。
| 索引类型 | 行为 |
|---|---|
Flat(精确) | 存储全精度嵌入并给出精确的最近邻向量结果。 它既简单又准确,但内存会随着索引资产数量的增加而线性增长。 |
PQ(压缩) | 使用产品量化来存储压缩的向量代码。 它在大规模时使用的编辑器内存要少得多,但会造成一些召回损失。 |
默认情况下,索引为Flat。 对于中小型项目,Flat通常很好,而且稍微精确一些。 当对数万或数十万个资产进行索引时,PQ会变得更加有用。 从Flat索引切换到PQ索引使用索引中已有的向量执行一次性训练步骤。
除了允许在索引类型之间切换外,统计对话框还显示:
索引类型
向量数
BM25关键字索引计数
嵌入维度
估计的向量内存
估计的BM25内存
当前索引是否已训练
支持、已编入索引、已跳过和失败的计数
其他设置
以下是编辑 > 编辑器偏好设置 > 插件 > Semantic Search中的其他可用设置。
正在索引
| 设置 | 默认 | 说明 |
|---|---|---|
已索引路径 | / | 索引中包含的内容浏览器包路径。 |
启动时自动索引缓存 | 关闭 | 启动时,自动将DDC缓存的嵌入加载到索引中。 |
启动时自动索引未缓存 | 关闭 | 还会在启动时将未缓存的资产发送给提供程序。 仅当缓存的启动索引开启时才有意义。 |
保存时自动索引 | 上 | 如果资产位于索引路径中,则在磁盘上保存或更新资产会重新索引该资产。 |
HTTP
| 设置 | 默认 | 说明 |
|---|---|---|
最大重试次数 | 1 | 在 429 和 5xx 等可重试失败时重试 HTTP 说明文字/嵌入请求。 |
重试超时秒数 | 300 | 单个请求的最大实际时间重试窗口。 |
最大并行描述请求数 | 256 | 限制正在处理的说明文字请求;多余的请求在本地排队。 |
最大并行嵌入请求数 | 256 | 限制正在进行的嵌入请求数量;超出的请求在本地排队。 |
如果你的提供程序返回速率限制错误,请降低并发请求数。
搜索
| 设置 | 默认 | 说明 |
|---|---|---|
启用混合搜索 | 上 | 将向量搜索与关键字BM25排名相结合。 |
RRF常量 | 60 | 倒数排名融合调优。 值越高,排名差距的影响越小。 |
RRF过采样 | 3 | 在融合之前从每个搜索源获取额外的候选。 |
BM25最小应匹配百分比 | 75 | 控制关键字匹配应包含多少查询词。 |
向量距离阈值 | 1.0 | 向量搜索的L2距离阈值。 值越小,越严格。 结果必须超过此语义阈值或具有关键字匹配。 |
相似度距离阈值 | 0.5 | “查找相似项” 使用的L2距离阈值。 值越小,越严格。 |
缓存和持久化
说明文字和嵌入输出存储在派生数据缓存中。 如果你的项目使用共享的远程DDC,则团队可以重复使用生成的数据,而不是每个用户为说明文字付费并再次嵌入相同的资产。
内存中的搜索索引也保存在本地项目的Sav ed/SemanticSearch目录下,并在下次启动编辑器时加载。
费用和隐私说明
索引将资产衍生数据发送到配置的说明文字提供程序。 对于视觉资产类型,通常包括缓存的缩略图以及资产路径、类和选定的元数据。
文本搜索将搜索查询发送到配置的嵌入提供程序。 Find Similar使用现有的索引向量,不会在搜索时将所选资产发送给提供程序。
在为大型项目编制索引之前,请检查你的提供程序定价和速率限制。 对于第一次通过测试的粗略估计,计算一个说明文字请求加上每个未缓存的支持资产的一个嵌入请求。
故障排除
| 症状 | 检查事项 |
|---|---|
没有出现AI按钮 | 确认插件已启用,重新启动编辑器,然后重新打开内容浏览器。 |
刷新后索引保持为 0 | 检查输出日志中的LogSemanticSearch。 常见原因包括缺少API密钥、无法访问的基础 URL 或与 OpenAI 不兼容的服务器。 |
许多资产变为失败 | 检查 HTTP 401、429 或 5xx 错误。 验证说明文字模型是否支持视觉和结构化JSON架构输出,以及嵌入模型是否支持请求的维度。 |
即使使用索引资产,搜索也不会返回任何结果 | 确认AI模式已开启,按回车键提交查询,并检查活动的内容浏览器筛选。 也可以尝试使用不太严格的向量距离阈值。 |
查找相似项不返回任何内容 | 所选资产可能未编制索引,或者相似距离阈值可能过于严格。 |
更改提供程序/型号/维度后,结果似乎已过时 | 使用已索引数量旁边的刷新按钮,从头开始重新索引所有资产。 |
索引太慢或开销太大 | 限制索引路径,如果提供程序限制速率,则降低并发性,或使用更低开销/更快的说明文字和嵌入模型。 |
API密钥出现在配置中 | 这是正常现象。 相应地存储密钥;它们以明文形式写入编辑器每用户设置配置中。 |