iOS 27 中的 Foundation Models：工具调用控制

iOS 26 为 App 带来了设备端的大型语言模型、通过 @Generable 获取类型安全输出的方式，以及让模型在生成过程中调用您代码的 Tool 协议¹。由模型决定何时动用工具，而工具则由您来写。唯一做不到的，是引导调用行为本身；唯一非做不可的，是亲手写下每一个工具，连每个 App 都需要的那些也不例外。iOS 27 补上了这两处缺口。GenerationOptions.ToolCallingMode 让您能以每次请求为单位，控制模型与工具交互的方式²；而 Vision 框架现在也内置了两个现成工具 OCRTool 与 BarcodeReaderTool，您只需把它们挂到会话上，无须自行编写识别代码³⁴。两者合在一起，补全了框架一开始就在铺陈的代理循环：模型决定要做什么，您决定它能多积极地去做，Apple 则提供读取物理世界的感知工具。

接下来要谈的，是叠加在框架参考之上的 iOS 27 那一层。如果您还没接触过 LanguageModelSession、Tool 协议或引导式生成，请先从《Foundation Models 框架讲解》读起，再回到这里。

TL;DR

• GenerationOptions.ToolCallingMode 是 iOS 27 新增的结构，用于描述模型在工具使用上的行为，并通过 GenerationOptions 以每次请求为单位设定²。Apple 记录了三种模式。
• 框架可在首次工具调用后变更其模式，让模型停止调用工具并产生最终响应，从而限定单次请求的工具活动²。
• OCRTool 识别图像中的文字，并返回一个包含所有读取内容的字符串。您只需用 OCRTool 实例配置 LanguageModelSession 即可启用它³。
• BarcodeReaderTool 扫描机器可读的代码，并返回一个 Barcode 结果数组，每个结果都带有解码后的内容与符号体系类型。启用方式相同，用一个实例配置会话即可⁴。
• 这两个 Vision 工具都允许您覆盖默认名称与描述，让您掌控模型如何识别并决定使用各个工具³⁴。
• 此处所谈的一切均为 iOS 27 beta（以及对应的 iPadOS、macOS、visionOS，还有三个符号中的两个所对应的 watchOS beta）²³⁴。

iOS 26 与 iOS 27 之间有何变化

iOS 26 的框架在 API 层面把工具调用视为二元。您交给会话一组工具，从此便由模型独自决定是否调用、调用多少次。对单次查询而言，这没问题；但只要您想在同一个会话内针对不同请求做出不同行为，事情就变得别扭：某个提示需要模型查询工具，另一个提示则宁可让它直接依上下文作答、省下这趟往返。

iOS 27 把这个决定交回到您手中。ToolCallingMode 是您通过 GenerationOptions 传入的值，也就是那个本来就在控制解码的选项对象²⁵，而且这个模式是请求的属性，而非会话的属性。内置的 Vision 工具则改变了等式的另一端：您不必再写一条 OCR 流水线或一个条形码扫描器、再包进自家的 Tool 一致性实现，而是挂上 Apple 的实现，把心力都花在提示上。

GenerationOptions.ToolCallingMode：引导调用

ToolCallingMode 是 GenerationOptions 之下的一个结构，在 iOS 27、iPadOS 27、Mac Catalyst 27、macOS 27、visionOS 27 与 watchOS 27 的 beta 中均可使用²。Apple 的摘要只有一句话：一个用来描述模型在工具使用上行为的值²。其声明再简单不过：

// iOS 27 beta
struct ToolCallingMode

Apple 的文档指出，工具调用模式支持三种模式²。撰写本文之时，原本会逐一指出各模式名称的讨论文字在参考资料中部分被省略，因此与其臆测标识名称，我宁可描述框架就行为所记录的内容——而那才是真正左右您设计的部分。

Apple 确实写明的行为是：框架可在首次工具调用后变更模式，让模型得以产生最终响应²。这一句正是承重所在。它意味着一次请求可以在某种姿态下启动——模型可以（或必须）调用工具——而一旦首次调用返回，框架便切换模式，让模型不再动用工具、转而给出定论。实际效果是为单次请求的工具活动设下界限：您不会任由一个模型在循环里不停调用工具，直到耗尽上下文窗口。

您通过本来就会传给 respond(to:) 的选项对象来设定模式：

import FoundationModels

let session = LanguageModelSession(tools: [FindContacts()])

// A request where you want to govern tool-calling behavior explicitly.
var options = GenerationOptions()
options.toolCallingMode = .someMode   // one of the three documented modes
let response = try await session.respond(
    to: "Draft a dinner invite to three of my contacts.",
    options: options
)

.someMode 的确切写法源自那三个有记录的情形；真正重要的是机制，而机制在于：行为以每次请求为单位、由 GenerationOptions 承载。这个对象正是 iOS 26 那个既掌管解码策略、又左右模型如何挑选输出 token，并提供您仅在防范响应过于冗长时才动用的可选响应 token 上限的结构⁵。工具调用模式是您本就在用的控制界面上的一个新维度，而非另一个得在代码里穿针引线的新对象。

控制之所以落在请求层级而非会话层级，是因为工具需求是问题的属性，而非对话的属性。一个聊天会话可能某一轮确实需要查询联系人，下一轮却纯粹是模型凭已有内容就能完成的改写。在第二轮硬要调用工具，等于浪费一趟往返、烧掉共享上下文窗口承担不起的 token⁵。以每次请求为单位的模式，让每一轮各自声明自己的姿态。

内置 Vision 工具：OCRTool 与 BarcodeReaderTool

iOS 27 故事的下半段，来自以 Foundation Models 工具形式公开的 Vision 框架。Apple 现在提供两个工具，挂到 LanguageModelSession 的方式跟挂上自家工具一模一样，区别只在于识别代码完全不必您动手。

在第 241 场会议中，Apple 将 BarcodeReaderTool 与 OCRTool 呈现为内置的系统工具，能以模型原生办不到的方式，增强其对视觉信息的推理能力。⁷

OCRTool

OCRTool 识别图像中的文字。Apple 的摘要正是如此，而讨论段落对其约定相当精确：此工具返回一个包含图像中所有已识别文字的字符串³。要开启它，您用一个 OCRTool 实例配置 LanguageModelSession³。其声明为：

// iOS 27 beta, Vision framework
struct OCRTool

挂上它的形式与任何工具相同，因为对会话而言，它不过是又一个 Tool：

import FoundationModels
import Vision

// Configure the session with an OCRTool instance to enable it.
let session = LanguageModelSession(tools: [OCRTool()])

let response = try await session.respond(
    to: "Pull the total and the date off this receipt image and summarize them."
)

模型判断提示何时需要从图像中取出文字，调用 OCRTool，取回一个包含工具所读全部内容的字符串，再把这个字符串折进它的答案里——就跟它折入您自己所写工具的结果一样³。您没写任何 Vision 请求，也没写任何处理代码。您挂上一个工具，描述了任务。

Apple 允许您覆盖默认名称与描述，以自定义模型如何识别并使用该工具³。这个着力点，是您对「模型何时动用 OCR」唯一的杠杆。如果您的 App 在读小票，把工具描述写成小票的用语，会让模型偏向在小票形态的提示上调用它，而远离图像只是装饰的提示。描述是一份模型会读的函数文档，所以请当成函数文档来写。

BarcodeReaderTool

BarcodeReaderTool 扫描图像中机器可读的代码⁴。OCRTool 返回的是扁平字符串，条形码工具返回的却是结构：当模型遇到含有机器可读代码的图像时，可调用此工具加以解码，工具则返回一个 Barcode 结果数组，每个结果都含有解码后的内容与符号体系类型⁴。其声明与挂接方式与 OCRTool 如出一辙：

// iOS 27 beta, Vision framework
struct BarcodeReaderTool

// Configure the session with a BarcodeReaderTool instance to enable it.
let session = LanguageModelSession(tools: [BarcodeReaderTool()])

let response = try await session.respond(
    to: "Scan this label and tell me what product it is and which standard the code uses."
)

每个 Barcode 结果中的符号体系类型，正是让结构化返回值得一用的细节⁴。QR 码、商品上的 EAN-13 条形码，以及驾照上的 PDF417，都是机器可读的代码，但对您的 App 各有不同含义。由于工具在交回解码后的载荷的同时也附上符号体系，模型（以及您的下游代码）便能依代码的种类分支，而不只是依其中的字节分支。如同 OCRTool，您也可以覆盖默认名称与描述，以引导模型如何识别并使用该工具⁴。

两个工具的 beta 可用范围相同：iOS 27、iPadOS 27、Mac Catalyst 27、macOS 27 与 visionOS 27 两者皆列，而 BarcodeReaderTool 另列入 watchOS 27³⁴。

组合循环：感知加上受控调用

这两项功能各自有趣，合在一起更佳，因为它们分处同一次代理请求的两端。Vision 工具是感知，是模型望向图像的双眼；ToolCallingMode 是治理，是您掌握模型该多倚重那双眼的手。

设想一个补货库存的功能。用户拍下一个货架。会话同时挂上两个 Vision 工具，再加上一个您自家的工具——一个查询 App 目录的 LookUpProduct。单一请求要求模型识别物品并建立补货清单。模型调用 BarcodeReaderTool 解码它能看见的标签，对没有清晰代码的物品用 OCRTool 读取任何印刷文字，再调用您的 LookUpProduct 把每一条解码载荷解析成目录条目。三个工具、一个提示、一个连贯的答案。

import FoundationModels
import Vision

let session = LanguageModelSession(tools: [
    OCRTool(),
    BarcodeReaderTool(),
    LookUpProduct(),     // your own Tool conformance over the app catalog
])

var options = GenerationOptions()
options.toolCallingMode = .someMode   // govern how the model sequences the calls
let response = try await session.respond(
    to: "Identify everything on this shelf and build a reorder list.",
    options: options
)

这正是框架一路朝其迈进的循环。iOS 26 提供了运行时模型、引导式生成，以及让设备端模型无须您解析自由文本即可调用您代码的 Tool 协议¹。本系列中那篇谈架构的文章，在运行时模型与开发者在 Claude Code 里跑来写 App 的工具型 LLM 之间划出界线，并主张以单一 Swift 领域函数，通过三个轻薄的适配层，同时支撑一个 Foundation Models Tool、一个 App Intent 与一个 MCP 工具⁶。iOS 27 嵌入的正是这幅图的运行时那一侧：内置的 Vision 工具是 Apple 写好、由您挂载的领域函数，LookUpProduct 是您写的领域函数，模型负责统筹它们全部，而 ToolCallingMode 则是这场统筹上的节流阀。

信任边界并未移动。OCRTool 与 BarcodeReaderTool 在 App 进程内、于设备上、针对用户的图像运行，沙箱与隐私姿态都与您自己所写的工具相同。Apple 提供实现，改变的是由谁维护识别代码，而非由谁为这项功能负责。提示、会话、可用性检查，以及是否把相机摆到用户面前的决定，仍归您所有。

各模式与工具的取舍时机

从上述约定衍生出的几条规则。

当工具需求因请求而异时，动用 ToolCallingMode。 若一个会话中每一轮都需要相同的工具行为，默认值就够了，设模式反而是噪声。当一次请求必须查询工具、而另一次该依上下文作答时，或当您想借框架在首次调用后的模式切换，来限定一个原本可能陷入循环的请求时，这个模式才称得上物有所值²。请在请求上设定它，而非为整个会话设定一次，因为控制就落在请求这一层²。

当答案是困在图像里的文字时，动用 OCRTool。 小票、招牌、手写笔记、文字截图。工具返回一个包含所有读取内容的字符串³，因此适合那些您希望模型针对文字内容、而非版面布局进行推理的提示。若您需要边界框或逐行的置信度分数，那是更底层的 Vision 请求，不是这个工具。

当图像带有机器可读代码、且代码种类至关重要时，动用 BarcodeReaderTool。 商品标签、票券、证件、库存标签。其结构化返回——解码内容加符号体系⁴——正是值得舍「把条形码当成普通文本处理」而就它的理由。请在您自家的工具或后处理中，依符号体系分支。

只要您的 App 对一个通用工具有特定用途，就覆盖名称与描述。 两个 Vision 工具默认都带有通用身份，而模型挑选工具的依据之一便是它们的描述³⁴。一个只读小票的 App，理应在 OCR 工具的描述里言明此事，以免模型对每一张碰巧含有文字的照片都调用它。

FAQ

iOS 27 中的 GenerationOptions.ToolCallingMode 是什么？

它是 iOS 27 beta 新增的结构，用于描述模型针对某次请求在工具使用上的行为。您通过传给 respond(to:) 的 GenerationOptions 来设定它，因此工具调用行为是每次请求的属性，而非整个会话的属性。Apple 记录了三种模式²。

Apple 记录了几种工具调用模式，各叫什么名字？

Apple 的文档指出，工具调用模式支持三种模式²。撰写本文之时，逐一指出各模式名称的参考文字部分被省略，因此我描述的是有记录的行为，而非臆测标识名称。Apple 确实明言的行为是：框架可在首次工具调用后变更模式，让模型产生最终响应，从而限定单次请求的工具活动²。

我该如何启用 Apple 内置的 OCR 工具？

用一个 OCRTool 实例配置您的 LanguageModelSession，方式与您挂上任何工具相同³。当提示需要从图像取出文字时，模型便会调用它，工具则返回一个包含所有已识别文字的字符串。OCRTool 位于 Vision 框架中，并在 iOS 27 beta 中可用³。

BarcodeReaderTool 返回什么？

它返回一个 Barcode 结果数组，每个结果都含有解码后的内容与符号体系类型⁴。符号体系让您能分辨 QR 码、EAN-13 与 PDF417，并依代码的种类分支，而不只是依其载荷分支。您只需用一个 BarcodeReaderTool 实例配置 LanguageModelSession 即可启用它⁴。

我能改变模型决定使用内置 Vision 工具的方式吗？

可以。OCRTool 与 BarcodeReaderTool 都允许您覆盖默认名称与描述，以自定义模型如何识别并使用该工具³⁴。描述是「模型何时动用工具」的杠杆，因此以您 App 自身的用语来写，会让模型偏向做出正确的调用。

内置的 Vision 工具会把图像送出设备吗？

不会。OCRTool 与 BarcodeReaderTool 都是 Foundation Models 工具，在 App 进程内、于设备上运行，沙箱与隐私姿态都与您自己所写的工具相同¹³⁴。Apple 提供识别代码，改变的是由谁维护它，而非它在哪里运行、或由谁为这项功能负责。

完整的 Apple Ecosystem 系列：《Foundation Models 框架讲解》；《设备端 LLM》；《运行时 LLM 与工具型 LLM 之别》；《自定义适配器》；类型化的《App Intents》；全新的《App Intents iOS 27 后台执行与同步》；对上 MCP 工具的《路由问题》；《Vision 框架》；《Core ML 设备端推理》；《三个界面》。枢纽位于《Apple Ecosystem 系列》。若想了解更广泛的「iOS 结合 AI 代理」背景，请参阅《iOS 代理开发指南》。