深入了解 Foundation Models 框架

深入了解 Foundation Models 框架

使用 Foundation Models 框架提升性能。深入了解引导式生成的工作方式，并使用指南、正则表达式和生成方案来获取自定的结构化响应。我们将向你展示如何使用工具调用让模型自动访问外部信息并执行操作，从而实现个性化体验。为了充分从这个视频中获益，建议你先观看“了解 Foundation Models 框架”。

章节
- 0:00 - 简介
- 0:49 - 会话
- 7:57 - Generable
- 14:29 - 动态模式
- 18:10 - 工具调用
资源
相关视频

WWDC25
嗨我叫 Louis 今天我们来了解如何充分利用 Foundation Models 框架
大家可能都知道 Foundation Models 框架能让你直接访问设备上的大语言模型以及便捷的 Swift API 它适用于 macOS、iPadOS、 iOS 和 visionOS 由于它在设备端运行你只需简单导入就可以在自己的项目中使用在本视频中我们将了解会话如何与 Foundation 模型配合使用如何使用 Generable 获得结构化输出如何获取在运行时定义的动态架构的结构化输出以及使用工具调用让模型调用自定义函数让我们从简单的开始通过会话生成文本
现在我一直在制作这款咖啡店像素艺术游戏我认为会非常有趣的是通过 Foundation 模型来生成游戏对话和其他内容让游戏感觉更生动！
我们可以提示模型回答玩家的问题所以我们的咖啡师会给出独特的对话为此我们将通过自定义指令创建 LanguageModelSession 这样就能告诉模型它在这个会话中的用途对于提示我们将采用用户的输入这就是非常有趣的新游戏元素所需的一切让我们来问咖啡师 “你在这里工作多久了？” 让它回答我们的问题
这完全是在设备端生成的真是很神奇它实际上是如何运作的呢？我们来更好地了解一下 Foundation 模型的文本生成方式以及注意事项在会话中调用 respond(to:) 时首先需要会话的指令和提示在本例中就是用户的输入它会将这个文本转换为令牌令牌就是小字符串有时是个单词但通常只是几个字符大语言模型采用一系列令牌作为输入然后生成一个新的令牌序列作为输出你不必操心 Foundation 模型采用的具体令牌 API 能很好地为你将这个抽离但重要的是要了解令牌不是没有代价的你的指令和提示中的每个令牌都会额外增加延迟在模型开始生成响应令牌之前首先需要处理所有输入令牌而生成令牌也会产生计算成本这就是输出越长生成时间也越长的原因
LanguageModelSession 是有状态的每次调用 respond(to:) 都会记录在脚本中
脚本包含给定会话的所有提示和回复
这对于调试很有用甚至可以显示在你的 UI 中
但是会话的增长规模是有限制的如果你提出很多请求或者给出一个很大的提示或是得到较大的输出就可能达到上下文限制
如果会话超出可用的上下文大小就会抛出错误你要准备好抓住这种错误回到游戏中当我们与某个角色交谈并遇到错误时对话就这样结束了真不凑巧我才刚刚认识这个角色！所幸的是有办法能从这个错误中恢复
你可以捕捉 exceededContextWindowSize 错误
完成后你就可以开始全新的会话没有任何历史记录但在我的游戏中这意味着角色突然忘记了整个对话
你也可以从当前会话中选择部分脚本并带到新会话中
你可以从某个会话的脚本中获取条目将它压缩为新的条目数组
因此对于游戏对话我们可以使用会话脚本的第一个条目也就是指令以及最后一个条目也就是最后一个成功的响应将这些传到新会话中后我们的角色就很适合再聊一会儿但请记住会话脚本包括作为第一个条目的初始指令在为游戏角色转移脚本时我们当然希望包括这些指令
只包括脚本中的几个相关片段也可能是个简单而有效的解决方案但有时事情并没有那么简单让我们设想一个包含更多条目的脚本你肯定总是希望以转移指令来开场但脚本中的很多条目可能具有相关性因此对于这个用例你可以对脚本进行归纳
为此你可以使用一些外部库甚至通过 Foundation 模型本身归纳部分脚本
以上就是你对会话脚本可以进行的操作现在让我们简要了解一下响应实际上是如何生成的在我们的游戏中当你走到咖啡师面前时玩家可以提出任何问题但是如果你开始两个新游戏并在每个游戏中问完全相同的问题你可能会得到不同的输出这是怎么做到的呢？这就是抽样的作用
模型生成输出时一次生成一个令牌为此它会针对既定令牌的概率创建一个分发版本 Foundation 模型默认在某个概率范围内选择令牌有时它可能会以“啊”开头有时它也可能会选择“嗯” 作为第一个令牌每个生成的令牌都会这样选择令牌就是我们所说的抽样默认行为是随机抽样获得不同的输出非常适合游戏等用例但有时你可能想要确定性输出比如当你编写应该可重复的演示时 GenerationOptions API 可让你控制采样方法你可以将它设置为贪婪来获得确定性输出这样设置后对于相同的提示你将得到相同的输出假设你的会话也处于相同状态不过请注意这只适用于给定版本的设备端模型当模型作为系统更新的一部分更新时提示可以确定地给出不同的输出即使在使用贪婪采样时也是如此你还可以调整温度来进行随机抽样比如将温度设置为 0.5 就可以获得仅略有不同的输出或者设置较高值同一提示就可以获得截然不同的输出另外请记住如果提示使用的是用户输入语言可能不受支持
有个专门的 unsupportedLanguageOrLocale 错误会在这种情况下出现这是在 UI 中显示自定义消息的好方法还有一个 API 用于检查模型是否支持某种语言比如检查用户的当前语言是否受支持如果不受支持就会显示免责声明以上就是对会话的概述你可以给它提示将历史记录存储在脚本中你还可以选择设置抽样参数来控制会话输出的随机性但我们可以做得更精彩！当玩家四处走动时我们可以生成 NPC 也就是非玩家角色同样是使用 Foundation 模型做到这一点然而这一次我们想要更复杂的输出我们想要的不仅仅是纯文本而是 NPC 的名字和咖啡订单 Generable 可以在这方面帮助我们要从大语言模型获取结构化输出可能并不容易你可以通过预期的特定字段来提示它并使用一些解析代码来提取它但这很难维护而且非常脆弱它可能并不总是给出有效的密钥这样整个方法就失败了所幸的是 Foundation 模型有个好用得多的 API 称为 Generable 你可以在结构体上应用 @Generable 宏那么什么是 Generable 是个单词吗？是的是个单词
Generable 是让模型生成结构化数据的一种简单方法使用 Swift 类型宏会在编译时生成架构模型可以用它来生成预期的结构宏还会生成一个构造器在向会话发出请求时系统会自动为你调用这个构造器
然后我们可以生成结构体实例和之前一样我们将在会话中调用响应方法但这次是传递生成参数告诉模型要生成哪种类型 Foundation 模型甚至会在提示中自动包含有关 Generable 类型的详细信息采用模型训练所依据的特定格式你不必告诉它 Generable 类型有哪些字段在游戏中我们现在将与 NPC 有不少精彩偶遇！
Generable 实际上比看起来更强大它在低级别使用约束解码这是让模型遵循特定架构生成文本的一种技术请记住这是宏生成的架构正如我们之前看到的 LLM 会生成令牌令牌稍后转换为文本而借助 Generable 这个文本甚至会以类型安全的方式自动为你解析令牌在循环中生成通常称为解码循环如果没有约束解码模型可能会产生一些无效的字段名称比如“firstName”而不是名字这样就无法解析为 NPC 类型
但通过约束解码可防止模型出现这样的结构性错误对于生成的每个令牌模型词汇表中所有的令牌都会有自己的分发版本约束解码的工作原理是屏蔽无效令牌这样模型就不会随便选择任意令牌而只能根据架构选择有效令牌
这样就不用操心手动解析模型输出你就可以把时间花在真正重要的事情上比如与咖啡店里的虚拟客人交谈！ Generable 确实是从设备端 LLM 获取输出的最佳方式它的功能还远不止于此你不仅可以将它用于结构体还可以用于枚举！因此让我们用它来让偶遇更加充满活力！在这里我添加了一个 Encounter 枚举其中包含两种情境枚举在情境中甚至可以包含关联值因此让我们用它来生成咖啡订单或者创建一个想和经理交谈的角色
现在来看看我们在游戏中遇到了什么！
哇真的有人需要一杯咖啡
显然并不是每个客人都那么容易伺候所以让我们由此给 NPC 添加关卡 Generable 支持大多数开箱即用型 Swift 类型包括 Int 我们来添加一个关卡属性但我们不想生成任何整数如果希望关卡处在特定范围内可以用 Guide 来指定可以在属性上使用 Guide 宏并传递一个范围同样模型将使用约束解码以保证值在这个范围内
与此同时我们还为 NPC 添加一系列属性
我们可以再次使用 Guide 这次是指定我们想要的 NPC 这个数组的属性正好三个请记住 Generable 类型的属性是按照源代码中声明的顺序生成的在这里将首先生成名称然后生成关卡然后是属性最后是偶遇
这个顺序可能很重要如果你期望某个属性的值受到另一个属性影响你甚至可以对属性逐个进行流式传输而不必等到全部输出生成完毕游戏现在很有趣！差不多可以与朋友们分享了但我注意到 NPC 的姓名和我想的不太一样我更喜欢名字加姓氏
为此我们可以使用 Guide 但这次只提供自然语言描述
我们可以说姓名应该是“全名” 这实际上是另一种提示方式你不必在提示中描述不同的属性在 Generable 类型中可以直接做到这一点这样一来模型与这些描述的关系更密切如果现在在游戏中四处走动我们会检查这些新姓名的实际应用下面简要介绍可应用于不同类型的所有 Guide
对于常见的数值类型比如 int 可以指定最小值、最大值或范围对于数组可以控制计数或指定数组元素类型的 Guide
对于字符串可以让模型从 anyOf 数组中挑选甚至限制为正则表达式模式
正则表达式模式 Guide 特别强大你可能熟悉用正则表达式来匹配文本但是对于 Foundation 模型你可以使用正则表达式模式来定义要生成的字符串的结构例如可以将姓名约束为一组前缀你甚至可以使用正则表达式构建器句法！
如果这让你对正则表达式重燃兴趣请务必观看永恒的经典之作几年前的讲座“了解 Swift Regex” 总之 Generable 是可以用于结构和枚举的宏它为你提供了一种可靠的方法从模型获取结构化输出你无需操心任何解析为了获得更具体的输出你可以将 Guide 应用于属性因此如果你在编译时就知道结构 Generable 将非常有用这个宏会为你生成架构你会得到一个类型实例作为输出但有时你只是在运行时知道结构这就是动态架构发挥作用的地方我要在游戏中添加一个关卡创建器玩家可以动态定义在游戏中走动时会偶遇的实体比如玩家可以创建一个谜语架构谜语就是一个问题以及多项选择答案如果我们在编译时知道这个结构就只需为它定义一个 Generable 结构体但是关卡创建器允许创建玩家能想到的任何结构
在运行时我们可以用 DynamicGenerationSchema 创建架构就像编译时定义的结构一样动态架构也有一个属性列表我们可以添加能接受玩家输入的关卡创建器
每个属性都有自己的名称和定义所属类型的架构你可以将架构用于任何 Generable 类型包括内置类型如字符串
动态架构可以包含一个数组然后为数组元素指定架构重要的是动态架构可以引用其他动态架构因此在这里我们的数组可以引用同样是在运行时定义的自定义架构
根据用户的输入我们可以创建一个具备两个属性的谜语架构第一个是问题这是字符串属性其次是数组属性一个名为 Answer 的自定义类型然后创建答案它具有字符串和布尔属性请注意谜语的答案属性按名称引用答案架构然后我们可以创建 DynamicGenerationSchema 实例每个动态架构都是独立的也就是说谜语动态架构实际上并不包含答案的动态架构在进行推理之前我们首先必须将动态架构转换为经过验证的架构这可能会抛出错误如果动态架构中存在不一致例如不存在某些类型引用
一旦有了经过验证的架构就可以像往常一样提示会话但这一次输出类型是 GeneratedContent 实例其中包含动态值你可以使用动态架构中的属性名称进行查询同样 Foundation 模型将采用引导式生成来确保输出与架构匹配绝不会编造出意外的字段！因此尽管是动态的你仍然无需担心要手动解析输出
所以现在当玩家遇到 NPC 时模型可以生成这个动态内容我们将在动态 UI 中加以展示让我们来看看遇到了什么我是深色或是浅色苦涩抑或甜蜜我将你唤醒带来热量我是什么？咖啡或热巧克力我认为答案是咖啡没错！我想玩家会从创造各种趣味关卡中获得很多乐趣总结一下利用 Generable 宏我们可以从编译时定义的 Swift 类型轻松生成结构化输出在后台 Foundation 模型负责架构并将 GeneratedContent 转换为你自己的类型的实例动态架构的工作原理非常相似但为你提供了更多的控制权你可以在运行时完全控制架构并直接访问 GeneratedContent 接下来我们来探讨工具调用它可以让模型调用你自己的函数我正在考虑创建一个 DLC 也就是可下载内容让我的游戏更具个性通过工具调用我可以让模型自主获取信息我认为集成玩家的通讯录和日历可能会非常有趣对于服务器模型我通常不会这样做玩家不会喜欢游戏上传这类个人数据但是由于使用了 Foundation 模型这些都在设备端我们就能这样做同时还能保护隐私
使用 Tool 协议来定义工具非常简单你首先要给它一个名称和描述这是 API 会自动放入提示中的内容用于让模型决定调用工具的时间和频率
工具名称最好要简短同时还要是易懂的英文文本避免使用缩写描述不要太长也不要解释任何实现方式因为请记住这些字符串是逐字逐句放在提示中的所以字符串越长意味着令牌越多就会增加延迟相反请考虑在名称中使用动词比如 findContact 描述应该大约是一句话长度与以往一样务必尝试不同的版本来找出最适合你的特定工具
接下来我们可以定义工具的输入我想让工具从特定年龄段获取联系人比如千禧一代模型将能够根据游戏状态选择有趣的用例我可以添加 Arguments 结构体并让它成为 Generable 当模型决定调用这个工具时它会生成输入参数通过 Generable 这样可以保证你的工具始终获得有效的输入参数所以不会编造出不同的世代比如 Gen Alpha 因为游戏不支持这个年龄段
然后就可以实现调用函数模型决定调用工具时将调用这个函数在本例中我们将调用 Contacts API 并返回这个查询的联系人姓名
要使用我们的工具我们将它传递到会话构造器中然后当模型需要额外信息时就会调用我们的工具相比我们自己去获取联系人这个功能更强大因为模型只会在需要特定 NPC 时调用这个工具而且它可以根据游戏状态选择有趣的输入参数比如 NPC 的年龄段
请记住这是使用常规的 Contacts API 你可能对此很熟悉第一次调用我们的工具时它将请求玩家提供通常的许可即使玩家不想授予通讯录访问权限 Foundation 模型仍能像以前一样生成内容但如果它们确实提供了访问权限我们会让游戏更加个性化
让我们在游戏中四处走走直到遇到另一个 NPC 这一次我将从自己的通讯录中抽取一个名字！哦嗨 Naomy！我们来看看她是怎么说的
我不知道你喜欢咖啡请注意 LanguageModelSession 接受了一个工具实例这意味着你在控制工具的生命周期这个工具的实例在整个会话期间将保持不变现在这个例子中因为我们只是使用 FindContactsTool 随机获取角色有时可能会得到同样的联系人在游戏中现在有多个 Naomy 这是不对的只能有一个 Naomy 要解决这个问题我们可以跟踪游戏使用过的联系人我们可以在 FindContactTool 中添加状态为此首先将 FindContactTool 转换为一个类别这样一来它就能从调用方法更改状态然后我们就可以跟踪选取的联系人在我们的调用方法中我们不会再次选择相同的人
现在 NPC 姓名都来自我的通讯录！但与他们交谈的感觉还是不对让我们用另一个工具来完成这个工作这次是访问我的日历
对于这个工具我们将从游戏中正在进行的对话传入联系人姓名模型调用这个工具时我们会让它生成年月日用来获取与这个联系人有关的事件我们将在 NPC 对话的会话中传递这个工具
现在如果我们问我朋友 Naomy 的 NPC “发生什么事了？” 她就可以用我们一起计划的真实事件来作答
哇现在就像在和真正的 Naomy 说话一样
我们来详细了解一下工具调用的工作原理首先在会话开始时传递这个工具以及相关指令在本例中我们提供了今天的日期等信息然后当用户提示会话时模型可以分析文本在本例中模型理解提示是在询问事件因此调用日历工具就合情合理
要调用工具模型首先生成输入参数在本用例中模型需要生成日期来获取当日事件模型可以联系指令和提示中的信息并了解如何根据这些信息填写工具参数因此在本例中模型可以根据指令中今天的日期来推断明天会发生什么工具的输入生成后将启用调用方法这是你大放异彩的时候你的工具可以随心所欲了但请注意会话会等待工具返回然后才能生成更多输出
之后工具的输出将放在脚本中就像模型输出一样而且根据工具输出模型可以生成对提示的响应请注意单个请求可以多次调用工具在这种情况下工具会被并行调用因此通过工具调用方法访问数据时请记住这一点好吧这很有趣！我们的游戏现在会随机生成内容依据是我的个人通讯录和日历而且我的数据并没有离开我的设备简而言之工具调用可以让模型调用你的代码在请求期间访问外部数据这可以是隐私信息如通讯录甚至可以是来自网络来源的外部数据请记住在给定请求中可以多次调用工具模型根据上下文确定这一点工具也可以并行调用可以存储状态这真的很棒！也许在做其他任何事情之前先喝杯咖啡再说要进一步了解你可以观看关于提示工程的专门视频包括设计和安全技巧另外如果你想见见真正的 Naomy 请观看 code-along 视频我希望你能像我一样从 Foundation 模型中获得不少乐趣谢谢观看！

import FoundationModels

func respond(userInput: String) async throws -> String {
  let session = LanguageModelSession(instructions: """
    You are a friendly barista in a world full of pixels.
    Respond to the player’s question.
    """
  )
  let response = try await session.respond(to: userInput)
  return response.content
}

3:37 - Handle context size errors

var session = LanguageModelSession()

do {
  let answer = try await session.respond(to: prompt)
  print(answer.content)
} catch LanguageModelSession.GenerationError.exceededContextWindowSize {
  // New session, without any history from the previous session.
  session = LanguageModelSession()
}

3:55 - Handling context size errors with a new session

var session = LanguageModelSession()

do {
  let answer = try await session.respond(to: prompt)
  print(answer.content)
} catch LanguageModelSession.GenerationError.exceededContextWindowSize {
  // New session, with some history from the previous session.
  session = newSession(previousSession: session)
}

private func newSession(previousSession: LanguageModelSession) -> LanguageModelSession {
  let allEntries = previousSession.transcript.entries
  var condensedEntries = [Transcript.Entry]()
  if let firstEntry = allEntries.first {
    condensedEntries.append(firstEntry)
    if allEntries.count > 1, let lastEntry = allEntries.last {
      condensedEntries.append(lastEntry)
    }
  }
  let condensedTranscript = Transcript(entries: condensedEntries)
  // Note: transcript includes instructions.
  return LanguageModelSession(transcript: condensedTranscript)
}

6:14 - Sampling

// Deterministic output
let response = try await session.respond(
  to: prompt,
  options: GenerationOptions(sampling: .greedy)
)
                
// Low-variance output
let response = try await session.respond(
  to: prompt,
  options: GenerationOptions(temperature: 0.5)
)
                
// High-variance output
let response = try await session.respond(
  to: prompt,
  options: GenerationOptions(temperature: 2.0)
)

7:06 - Handling languages

var session = LanguageModelSession()

do {
  let answer = try await session.respond(to: userInput)
  print(answer.content)
} catch LanguageModelSession.GenerationError.unsupportedLanguageOrLocale {
  // Unsupported language in prompt.
}

let supportedLanguages = SystemLanguageModel.default.supportedLanguages
guard supportedLanguages.contains(Locale.current.language) else {
  // Show message
  return
}

8:14 - Generable

@Generable
struct NPC {
  let name: String
  let coffeeOrder: String
}

func makeNPC() async throws -> NPC {
  let session = LanguageModelSession(instructions: ...)
  let response = try await session.respond(generating: NPC.self) {
    "Generate a character that orders a coffee."
  }
  return response.content
}

9:22 - NPC

@Generable
struct NPC {
  let name: String
  let coffeeOrder: String
}

10:49 - Generable with enum

@Generable
struct NPC {
  let name: String
  let encounter: Encounter

  @Generable
  enum Encounter {
    case orderCoffee(String)
    case wantToTalkToManager(complaint: String)
  }
}

11:20 - Generable with guides

@Generable
struct NPC {
  @Guide(description: "A full name")
  let name: String
  @Guide(.range(1...10))
  let level: Int
  @Guide(.count(3))
  let attributes: [Attribute]
  let encounter: Encounter

  @Generable
  enum Attribute {
    case sassy
    case tired
    case hungry
  }
  @Generable
  enum Encounter {
    case orderCoffee(String)
    case wantToTalkToManager(complaint: String)
  }
}

13:40 - Regex guide

@Generable
struct NPC {
  @Guide(Regex {
    Capture {
      ChoiceOf {
        "Mr"
        "Mrs"
      }
    }
    ". "
    OneOrMore(.word)
  })
  let name: String
}

session.respond(to: "Generate a fun NPC", generating: NPC.self)
// > {name: "Mrs. Brewster"}

14:50 - Generable riddle

@Generable
struct Riddle {
  let question: String
  let answers: [Answer]

  @Generable
  struct Answer {
    let text: String
    let isCorrect: Bool
  }
}

15:10 - Dynamic schema

struct LevelObjectCreator {
  var properties: [DynamicGenerationSchema.Property] = []

  mutating func addStringProperty(name: String) {
    let property = DynamicGenerationSchema.Property(
      name: name,
      schema: DynamicGenerationSchema(type: String.self)
    )
    properties.append(property)
  }

  mutating func addArrayProperty(name: String, customType: String) {
    let property = DynamicGenerationSchema.Property(
      name: name,
      schema: DynamicGenerationSchema(
        arrayOf: DynamicGenerationSchema(referenceTo: customType)
      )
    )
    properties.append(property)
  }
  
  var root: DynamicGenerationSchema {
    DynamicGenerationSchema(
      name: name,
      properties: properties
    )
  }
}

var riddleBuilder = LevelObjectCreator(name: "Riddle")
riddleBuilder.addStringProperty(name: "question")
riddleBuilder.addArrayProperty(name: "answers", customType: "Answer")

var answerBuilder = LevelObjectCreator(name: "Answer")
answerBuilder.addStringProperty(name: "text")
answerBuilder.addBoolProperty(name: "isCorrect")

let riddleDynamicSchema = riddleBuilder.root
let answerDynamicSchema = answerBuilder.root

let schema = try GenerationSchema(
  root: riddleDynamicSchema,
  dependencies: [answerDynamicSchema]
)

let session = LanguageModelSession()
let response = try await session.respond(
  to: "Generate a fun riddle about coffee",
  schema: schema
)
let generatedContent = response.content
let question = try generatedContent.value(String.self, forProperty: "question")
let answers = try generatedContent.value([GeneratedContent].self, forProperty: "answers")

18:47 - FindContactTool

import FoundationModels
import Contacts

struct FindContactTool: Tool {
  let name = "findContact"
  let description = "Finds a contact from a specified age generation."
    
  @Generable
  struct Arguments {
    let generation: Generation
        
    @Generable
    enum Generation {
      case babyBoomers
      case genX
      case millennial
      case genZ            
    }
  }
  
  func call(arguments: Arguments) async throws -> ToolOutput {
    let store = CNContactStore()
        
    let keysToFetch = [CNContactGivenNameKey, CNContactBirthdayKey] as [CNKeyDescriptor]
    let request = CNContactFetchRequest(keysToFetch: keysToFetch)

    var contacts: [CNContact] = []
    try store.enumerateContacts(with: request) { contact, stop in
      if let year = contact.birthday?.year {
        if arguments.generation.yearRange.contains(year) {
          contacts.append(contact)
        }
      }
    }
    guard let pickedContact = contacts.randomElement() else {
      return ToolOutput("Could not find a contact.")
    }
    return ToolOutput(pickedContact.givenName)
  }
}

20:26 - Call FindContactTool

import FoundationModels

let session = LanguageModelSession(
  tools: [FindContactTool()],
  instructions: "Generate fun NPCs"
)

21:55 - FindContactTool with state

import FoundationModels
import Contacts

class FindContactTool: Tool {
  let name = "findContact"
  let description = "Finds a contact from a specified age generation."
   
  var pickedContacts = Set<String>()
    
  ...

  func call(arguments: Arguments) async throws -> ToolOutput {
    contacts.removeAll(where: { pickedContacts.contains($0.givenName) })
    guard let pickedContact = contacts.randomElement() else {
      return ToolOutput("Could not find a contact.")
    }
    return ToolOutput(pickedContact.givenName)
  }
}

22:27 - GetContactEventTool

import FoundationModels
import EventKit

struct GetContactEventTool: Tool {
  let name = "getContactEvent"
  let description = "Get an event with a contact."

  let contactName: String
    
  @Generable
  struct Arguments {
    let day: Int
    let month: Int
    let year: Int
  }
    
  func call(arguments: Arguments) async throws -> ToolOutput { ... }
}

- 0:00 - 简介
- 了解面向 Apple 设备的 Foundation Models 框架，它提供了一个可通过 Swift API 访问的设备端大语言模型。该框架涵盖了如何使用 Generable 获取结构化输出、动态架构和可调用自定义函数的工具调用。
- 0:49 - 会话
- 在本例中，Foundation Models 通过生成动态游戏对话和内容来提升像素艺术咖啡店游戏的体验。通过创建“LanguageModelSession”，向模型提供自定说明，从而让模型能够回应玩家提出的问题。该模型将用户输入和会话说明处理成令牌、小子字符串，然后生成一个新的令牌序列作为输出。 “LanguageModelSession”是有状态的，会将所有提示和回应保留在对话记录中。你可以利用这份记录进行调试，并在游戏的用户界面中展示对话历史记录。但是，会话的大小是有限制的，称为上下文限制。默认情况下，响应的生成具有不确定性。模型会使用采样功能，为每个令牌生成一个概率分布，从而引入一定的随机性。这种随机性可以通过使用 GenerationOptions API 来控制，让你能够调整采样方法、温度值，甚至将其设置为“贪婪”以获得确定性输出。除了简单的对话之外，还可以使用 Foundation Models 来生成更复杂的输出，例如为不可玩角色 (NPC) 生成名字和咖啡订单。这一功能为游戏世界增添了层次感和多样性，让游戏更生动逼真、更引人入胜。你还必须考虑并妥善处理不受支持的语言等潜在问题，以保障用户体验的流畅性。
- 7:57 - Generable
- Foundation Models 的 Generable API 是一款强大的工具，可简化从大语言模型中提取结构化数据的过程。通过将 @Generable 宏应用于 Swift 结构体或枚举，编译时会生成架构，从而引导模型的输出。 Generable 会自动生成构造器，并通过约束解码技术将模型生成的文本解析为类型安全的 Swift 对象。这项技术可确保模型的输出符合指定的架构，避免出现幻觉和结构错误。你可以使用“指南”进一步自定义生成流程，这些指南可为特定属性提供约束条件、范围或自然语言描述。这样就可以更精细地控制生成的数据，例如指定名称格式、数组数量或数值范围等。Generable 可实现高效且可靠的数据生成，让开发者能够专注于应用程序中更复杂的部分。
- 14:29 - 动态模式
- 在游戏的关卡创建器中，动态架构让玩家能够在运行时定义自定实体。这些架构类似于编译时的结构体，其属性包含名称和类型，支持数组以及对其他动态架构的引用。根据玩家的输入，可创建一个谜语架构，其中包含问题 (字符串类型) 和答案数组 (自定类型，包含字符串和布尔属性)。这些动态架构经过验证，然后由 Foundation Models 用于生成内容，确保输出与定义的结构相匹配。这种动态方法让游戏能够在动态 UI 中显示玩家创建的谜语及其他实体，在保持结构化数据处理的同时，为玩家提供了高度的灵活性与创造力。
- 18:10 - 工具调用
- 借助 Foundation Models，游戏开发者可以使用工具调用功能创建个性化的 DLC。这使得模型能够自主从玩家设备上获取通讯录和日历等信息，同时由于数据始终保留在设备本地，隐私也得到了保障。定义工具需要指定名称、描述和输入参数。模型会根据这些信息来判断何时以及如何调用该工具。然后，该工具的实现会与外部 API (如 Contacts API) 进行交互，以检索数据。

章节

资源

相关视频

WWDC25