使用 Core Spotlight 支持语义搜索

了解如何使用 Core Spotlight 在 App 中提供语义搜索结果。探索如何让自己 App 的内容出现在用户的设备端私有索引中，以便用户可以使用自然语言来搜索项目。我们还将介绍如何安排索引编制活动来优化 App 的性能。为了充分利用好本次讲座，我们建议你先查阅 Apple Developer 网站上的 Core Spotlight 文档。

章节

0:00 - Introduction
1:37 - Searchable content
5:05 - Demo: Creating an index delegate extension
6:56 - Results and suggestions
9:18 - Ranking
10:17 - Wrap-up

资源

相关视频

WWDC24

利用 App Intents 为用户奉上 App 的核心功能

WWDC21

在聚焦中展示 app 数据

下载

大家好我叫 Jennifer 是聚焦团队的工程师我们非常关注搜索今天我非常高兴能向大家介绍聚焦中的所有新 API 它们可帮助你在自己的 App 中打造强大的搜索体验 CoreSpotlight 框架可让你的 App 向聚焦提供可搜索内容然后通过查询来检索这些内容这是增强 App 的搜索持久存储解决方案的绝佳方式你的 App 提供的可搜索内容存储在一个私有的本地索引中这个索引永远不会离开设备用户可以在聚焦中搜索你的内容但其他 App 将无法看到这些数据借助 CoreSpotlight 你可以轻松地在 App 中根据搜索栏中输入的自然语言搜索词提供搜索结果和建议今年 CoreSpotlight 支持通过语义搜索理解查询在这之前聚焦可以搜索你的 App 中的内容但搜索词必须完全匹配有了语义搜索用户能够以自己的方式在 App 中搜索内容并且搜索词只需含义相似即可借助聚焦的查询理解模型无论你使用什么搜索方式都能找到正确的结果今天我们将了解如何在 App 内打造全方位的搜索体验首先是向搜索索引提供内容并遵循数据迁移和恢复的最佳实践我们将了解如何检索结果和建议以及如何提升与用户最相关的搜索结果的排名我们将构建一个 App 可让用户搜索自己撰写的手记条目你可以在下面的链接中找到这个示例 App 的完整代码

构建出色搜索体验的第一步是向聚焦提供可搜索内容这些内容代表了用户想要在 App 中搜索的内容在手记 App 中用户可以搜索所有手记条目每个手记条目都是一个可搜索项目为此你需要为项目建立索引使项目能够通过查询进行检索并直接填充用户界面的视图目前语义搜索最适合文本或媒体资源例如图像和视频为了获得最佳结果你需要确保可搜索项目具有恰当的内容类型并且尽可能使用系统定义的属性要创建 CSSearchableItem 请提供唯一标识符、可选的域标识符和属性集唯一标识符应存储在 App 的持久存储解决方案中以便能够恢复完整的项目数据接下来创建 CSSearchableAttributeSet 并务必设置有效的内容类型查看我们的文档获取支持的 UT 类型的完整列表或了解如何创建你自己的自定内容类型提供可搜索的文本项目时务必要设置 title 和 textContent 这些属性会在语义索引中进行处理如果你的项目代表图像或视频资源务必将 contentURL 设置为资源的路径这可确保资源可从 App 的沙盒化容器的语义索引中进行处理

如果项目引用附件或网页内容请考虑将它们作为单独的项目提供给索引并设置它们自己的内容类型和属性你可以使用 relatedUniqueIdentifier 来维持与源项目的关系

设计好可搜索项目后你需要在聚焦中创建可搜索索引并提供这些索引我们新推出了一些好用的 API 可让你通过 App 的设计更高效地提供索引包括使用客户端状态和项目更新来批量建立索引首先创建一个命名的 CSSearchableIndex 获取并验证你发送到聚焦的最后一个客户端状态然后为可搜索项目建立索引这里注意索引调用包围在开始一批提供的项目的调用和结束一批提供的项目的调用中这里可以发送下一个客户端状态

客户端状态对于管理大量项目非常有用还可用于保持 App 与聚焦之间的数据完整性客户端状态还可用于防止过度提供项目这会影响 App 性能与新的 isUpdate 标记搭配使用时可以确保 App 始终只提供需要的内容为了构建一致的搜索体验迁移和恢复是非常重要的组成部分你的聚焦索引是完全本地和私密的因此你需要采取措施来确保你的可搜索内容在聚焦中保持最新状态当聚焦需要迁移索引时或是需要从数据损坏、中断或其他问题中恢复时它将向你的 App 请求重新建立所有项目的索引或重新建立部分特定项目的索引为了响应这些请求你的 App 可以在 App 正在实时运行时采用代理协议同时实现聚焦可从你的 App 单独调用的代理扩展索引代理扩展允许聚焦将请求安排在在有利的设备条件下比如当设备处于睡眠或空闲状态时这样就可以逐步迁移项目而几乎不改变 App 现有的搜索功能设置索引代理扩展非常简单只要你使用新的 Xcode 文件目标我们来看看具体怎么做首先从手记 App 中开始它已经配置为使用套装 ID 提供可搜索内容：第一步是创建新目标：打开“文件”菜单选择“新建”>“目标”

选择扩展的平台这里我们从 macOS 开始然后搜索新的 CoreSpotlight 代理扩展模板

点击“下一步”配置这个新目标点击“完成” 将这个新目标添加到项目中

添加后激活新扩展

现在我们来看看存根实现

由于聚焦将代表我们启动这一过程我们可以使用一个便捷的命令行工具来进行调试现在我们来试一试

首先在 reindexAll 方法中设置一个断点这样我们就可以尝试在代码中捕捉到这个点确保调用 acknowledgmentHandler 以避免拦截调用方

接下来我们需要重建 App 来添加这个新的 App 扩展选择 App 的目标然后打开“产品”菜单选择“构建”

然后切换回扩展目标在“调试”菜单中选择“附加到流程”

现在我们可以开始调试这时我们需要启动终端 App 来运行工具命令

mdutil 工具让我们能够模拟向套装 ID 发出的请求以便进行调试我们可以运行命令

然后返回 Xcode 中的项目查看是否已到达断点我们现在可以完成相应的实现包括为所有项目重新建立索引、为部分项目重新建立索引、添加拖放支持以及针对关键提供路径的限流场景进行响应你已经为可搜索项目建立了索引现在可以在你的用户界面中支持搜索体验你可以对查询进行配置以便最好地支持你的用户界面需求语义搜索默认启用但也可以配置查询使查询返回采用先进的机器学习模型进行排名的结果而这些模型正是聚焦所使用的你还可以将查询配置为支持 App 中的建议菜单使用 CSUserQueryContext 配置适合用户界面的查询务必设置针对查询返回的每个项目获取的属性列表这些获取的属性通常仅包含需要在用户界面中展示的内容可使用一个标记启用排名结果并且可以限制排名结果的数量这些结果通常显示在单独的“最佳搜索结果”部分中在返回所有结果后必须在 App 中将结果排序可以使用新的 compareByRank 比较运算符来进行排序

建议也可以按数字配置或停用建议会按排名顺序返回但顺序也可在排序时恢复使用元数据语法的结构化查询是根据 App 的用户界面定制搜索结果的最佳方式例如如果用户选择仅显示图像的标签页可以使用像这样的筛选查询来指定结果集仅包含图像筛选查询还可用于你希望仅显示在聚焦中的内容例如可引导至 App 特定部分的路径指引导航查看我们的文档了解如何使用元数据语法构建自定筛选查询

最后一步是创建 CSUserQuery 需要使用搜索栏中的用户查询字符串以及你的查询上下文结果和建议会在异步响应中返回项目结果会以异步方式分批返回因此如果启用了排名请务必在显示之前对项目进行排序建议通常以用户键入的字符串的补全形式返回 CSSuggestion 提供属性字符串可以显示在建议菜单中如果用户选择了某个建议则将搜索栏文本替换为这个字符串以触发新的搜索

语义搜索需要使用必须下载到设备上的机器学习模型这个模型将在你的 App 的进程中运行这些模型可以随时载入或退出以便在运行时保留 App 的存储空间这就是为什么你每次都需要在搜索界面显示前调用这个类方法这样才能确保在用户开始搜索时所有资源都可用现在搜索可以正常使用你需要开始考虑不断改善搜索体验为此你可以提供信号来改善用户最关心的内容的排序在提供自适应的排序体验时互动和新鲜度是非常重要的信号用户可能会浏览与可搜索项目相关的内容或者主动进行搜索然后滚动浏览结果集中的各个项目最后选择一个结果来查看详细信息在每种情况下你的 App 都可以向聚焦发出互动信号从而改善它在未来搜索中的排名

当用户浏览与 CSSearchableItem 相关的内容时在项目属性集上设置 lastUsedDate 属性并将它提供给索引作为更新当用户选择某个查询结果或某个查询建议你可以将交互标记为与这个查询相关联这样就可以了用户现在可以获得成熟的搜索体验能够流畅处理多个平台和语言区域的多样化搜索内容我们了解了如何向完全私密的设备端搜索索引提供内容如何检索结果和建议以及如何不断提升最相关的搜索结果采用 Core Spotlight 能够很好地帮助用户在你的 App 中查找内容有了语义搜索它变得前所未有的强大

如果想要进一步了解其他类型的聚焦集成请观看我们的其他讲座包括如何利用 App Intents 如何使用 CoreData 免费获得 CoreSpotlight 提供感谢观看期待在聚焦里见到你

2:14 - Creating CSSearchableItem

// Creating searchable items for donation


let item = CSSearchableItem(uniqueIdentifier: uniqueIdentifier, domainIdentifier: domainIdentifier, attributeSet: attributeSet)

2:28 - Creating CSSearchableAttributeSet

// Creating searchable content for donation


let attributeSet = CSSearchableItemAttributeSet(contentType: UTType.text)
attributeSet.contentType = UTType.text.identifier

2:40 - Searchable items with type

// Searchable items with text


attributeSet.title
attributeSet.textContent


// Searchable items with media


attributeSet.contentType
attributeSet.contentURL


// Searchable items with links


attributeSet.contentURL
attributeSet.relatedUniqueIdentifier

3:31 - Batch indexing with client state

// Batch indexing with client state


let index = CSSearchableIndex(name: "SpotlightSearchSample")        
index.fetchLastClientState { state, error in         
    if state == nil {
        index.beginBatch()
        index.indexSearchableItems(items)
        index.endIndexBatch(expectedClientState: state, newClientState: newState) { error in
        }
    }
}

3:56 - Avoid overwriting existing attributes

// Make it an update to avoid overwriting existing attributes


item.isUpdate = true

7:19 - Configure a query

// Configure a query


let queryContext = CSUserQueryContext()
queryContext.fetchAttributes = ["title", "contentDescription"]

7:33 - Ranked results

// Ranked results


queryContext.enableRankedResults = true
queryContext.maxRankedResultCount = 2

7:47 - Suggestions

// Suggestions


queryContext.maxSuggestionCount = 4

7:55 - Filter queries

// Filter queries


queryContext.filterQueries = ["contentTypeTree=\"public.image\""]

8:23 - Query for searchable items and suggestions

// Query for searchable items and suggestions


let query = CSUserQuery(userQueryString: "windsurfing carmel", userQueryContext: queryContext)
for try await element in query.responses {
    switch(element) {
        case .item(let item):
            self.items.append(item)
            break
        case .suggestion(let suggestion):
            self.suggestions.append(suggestion)
            break
    }
}

8:40 - Suggestions

// Suggestions


suggestion.localizedAttributedSuggestion

8:56 - Preparing for queries

// Preparing for queries


CSUserQuery.prepare
CSUserQuery.prepareWithProtectionClasses

9:50 - Set the lastUsedDate

// Set the lastUsedDate when the user interacts with the item


item.attributeSet.lastUsedDate = Date.now
item.isUpdate = true

10:00 - Interactions with items and suggestions from a query

// Interactions with items and suggestions from a query


query.userEngaged(item, visibleItems: visibleItems, interaction: CSUserQuery.UserInteractionKind.select)

query.userEngaged(suggestion, visibleSuggestions: visibleSuggestions, interaction: CSUserQuery.UserInteractionKind.select)

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。