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 代理開發指南〕。