先做一個只有文字輸入、系統模型請求與回答顯示的 SwiftUI 功能；動手前確認開發環境相容，並在執行時檢查模型是否可用。這條 Apple Foundation Models SwiftUI 入門路線適合想完成第一個文字生成練習的你，但真正的模型呼叫只能在符合條件的目標環境中驗收。

適合剛開始學 SwiftUI、想在練習 App 加入 AI 文字功能的學生。
如果你已經能做簡單頁面，卻還沒發起過 Foundation Models 請求，這篇會帶你走完首次實作。
準備使用遠端 Mac 的話，也要先確認實際分配的環境，而不是只看服務名稱或編譯結果。

本週建議動作：先完成一個靜態文字頁面，再依序檢查環境、發送簡單請求、記錄模型狀態。先不要加入 Agent、工具呼叫或其他複雜功能。

動手前：先確認三種條件，而非只看編譯結果

第一次接入模型時，最容易混淆的是「專案可以編譯」和「模型真的能回答」。它們是不同的驗收項目：Xcode 負責建置程式，執行系統負責提供模型，而裝置上的可用性狀態則說明目前能不能呼叫。

官方的 Foundation Models 框架說明介紹系統模型的呼叫方式；SystemLanguageModel 文件則提供檢查可用性的介面。實際支援範圍、API 細節和系統要求，應以這些文件及目前使用的執行環境為準。

檢查項目 你要確認什麼 尚未通過時怎麼做
開發工具 目前 Xcode 是否符合專案及系統的要求 先查閱 Xcode 系統需求，不要只按搜尋結果中的版本名稱判斷
執行環境 實際運行的系統與裝置是否符合官方支援條件 查清楚目標裝置與目前設定；不要推定所有 Apple silicon Mac 或模擬器都能推論
模型狀態 SystemLanguageModel.default.availability 回報什麼 依回報結果顯示可用或不可用提示，再決定是否測試請求

搜尋「Xcode 27」時，也請把它當成需要核對的工具版本名稱，而非模型可用的保證。Xcode 系統需求和模型執行條件是兩件事；工具能開啟專案，不代表目標環境一定能呼叫模型。

如果你準備使用遠端 Mac，先確認實際分配的系統與 Xcode 版本，以及能否在該環境檢查模型狀態。無法取得這些資訊時，先把它當作尚未完成真實呼叫驗收，不要把其他人的測試結果套用到自己的工作階段。

第一個里程碑：做出可操作的 SwiftUI 練習頁

先把頁面縮小為三個部分：輸入文字的欄位、送出請求的按鈕，以及顯示結果或狀態的區域。這不是功能不足，而是把問題拆開；若畫面還沒反應，就不必同時猜測模型、網路或複雜邏輯出了什麼問題。

在 SwiftUI 中，@State 可以存放由畫面管理的狀態；當值改變時，畫面會依新狀態更新。你可以把它想成課程作業的繳交欄位：你改了答案，頁面就要呈現目前保存的內容。Apple 的 SwiftUI State 說明列出狀態的使用方式。

畫面區域 初學階段要完成的事 驗收方式
輸入欄位 能輸入一段普通文字 輸入後文字仍顯示在欄位中
操作按鈕 點擊後改變頁面狀態 出現「準備送出」或載入中的狀態
回答區域 顯示回答、錯誤或不可用提示 不會一直空白，也不會把錯誤說成成功

可以先讓按鈕只將回答區域改成「已收到輸入」。這一步不需要模型，目的是確認輸入綁定、按鈕動作和畫面更新都正常。若此時畫面沒有變化，先修好 SwiftUI 狀態；否則接入模型後，問題會更難定位。

第二個里程碑：建立會話並送出第一個文字請求

頁面驗收後，再加入 Foundation Models。LanguageModelSession 可以理解成一段連續的模型對話；prompt 則是你交給模型的題目。第一次練習只送一般文字，先不加入圖片、工具或動態設定。

以下程式示範基本流程，API 名稱與用法可對照 Apple 的 LanguageModelSession 文件及 respond(to:) 方法說明。若官方文件或專案所用 SDK 有更新，請以目前文件為準。

import SwiftUI
import FoundationModels

struct ContentView: View {
    @State private var prompt = ""
    @State private var answer = ""
    @State private var status = "輸入問題後再送出"
    @State private var isWorking = false

    var body: some View {
        VStack(spacing: 16) {
            TextField("輸入一個簡單問題", text: $prompt)
                .textFieldStyle(.roundedBorder)

            Button("送出") {
                Task {
                    await askModel()
                }
            }
            .disabled(isWorking || prompt.isEmpty)

            Text(status)
            Text(answer)
                .frame(maxWidth: .infinity, alignment: .leading)
        }
        .padding()
    }

    @MainActor
    private func askModel() async {
        let model = SystemLanguageModel.default

        switch model.availability {
        case .available:
            isWorking = true
            status = "正在送出"
            defer { isWorking = false }

            do {
                let session = LanguageModelSession()
                let response = try await session.respond(to: prompt)
                answer = response.content
                status = "已收到模型回應"
            } catch {
                status = "請求失敗，請檢查錯誤並稍後重試"
            }

        case .unavailable(let reason):
            answer = ""
            status = "目前無法使用模型：\(reason)"
        }
    }
}

程式將狀態分開保存：prompt 是輸入內容，answer 是結果，status 用來呈現進度或失敗原因。按鈕停用條件也能避免輸入空白或請求尚未完成時重複操作。

第一次測試時，不必追求回答特別聰明。你要確認的是：按鈕有觸發、程式有進入可用性判斷、請求有成功或清楚失敗，以及畫面如實呈現結果。這比先設計複雜提示詞更能幫你定位問題。

第三個里程碑：把「不可用」變成可理解的回饋

模型不可用，不等於整個頁面不能做，也不應以無限載入或空白畫面掩蓋問題。Apple 的 不可用原因說明提供狀態原因的資訊；依實際回報，你可以顯示「目前裝置不符合條件」、「請確認相關系統功能設定」或「模型尚未準備好」等適合使用者理解的訊息。

不要自行假設每個原因都能靠同一個操作排除。先依官方回報辨識狀態，再採取相應動作：環境不符合時換到已確認支援的執行環境；設定問題則檢查系統設定；模型尚未就緒時保留介面，稍後再測。若狀態無法判斷，就如實標示「目前無法確認」，不要宣稱請求成功。

實際結果 頁面應呈現 下一步
模型狀態可用 顯示送出中，接著顯示回應或錯誤 以簡單文字驗證完整流程
模型回報不可用及原因 說明目前不能呼叫，保留輸入內容 根據官方原因檢查環境或設定
頁面可操作但模型不能呼叫 清楚標示目前只完成介面練習 先驗收畫面，之後再找可用環境測試

完整驗收：把介面、請求和模型結果分開記錄

用一條不含個人資料的簡單問題完成測試。按下送出後，觀察頁面狀態是否改變；再確認程式是否進入模型可用性判斷，最後確認畫面顯示的是實際回應，還是清楚的錯誤與不可用訊息。

驗收紀錄可用這三欄：

  • 介面已驗收：文字能輸入，操作後頁面有狀態變化。
  • 請求流程已驗收：程式依可用性結果執行請求，失敗時有回饋。
  • 真實模型已驗收：目標環境回報可用，並收到模型回應。

三者不要合併成一句「程式跑成功了」。例如，頁面在模擬器中能打開，只能證明目前已驗收的畫面和執行流程；是否能完成真實模型推論，仍要看目標環境的可用性回報與實際請求結果。先按 Xcode 系統需求檢查工具，再依模型文件驗收，比單看建置成功更可靠。

最後更新於 2026 年 9 月 25 日；API 與環境說明核對自 Apple Foundation Models 文件、SystemLanguageModel 可用性文件及上述 Xcode 系統需求頁。若官方 API、系統版本或工具要求有變，請以連結中的最新文件重新確認。

新手常見問題

Apple Foundation Models 要怎麼接進 SwiftUI？

先建立輸入、按鈕和結果區域，再於操作動作中檢查 SystemLanguageModel.default.availability。可用時建立 LanguageModelSession 並呼叫 respond(to:)；不可用時顯示原因。這樣你能分辨介面問題和模型問題。

第一次發出請求前要檢查哪些環境？

分別檢查 Xcode 與專案是否相容、實際執行的裝置和系統是否符合官方要求，以及執行時的模型可用性。特別是遠端 Mac，不要預設所有分配環境都能呼叫模型；要以你實際連線後檢查到的資料為準。

模型暫時不可用，頁面練習可以繼續嗎？

可以。先完成輸入、按鈕狀態、載入提示和錯誤顯示，並在紀錄中註明尚未驗收真實模型推論。等取得符合條件的裝置或執行環境，再補做可用性檢查和文字請求。

沒有本地 Mac，還能做這項練習嗎？

你可以先準備 SwiftUI 頁面與請求程式碼，但真實呼叫是否可行，要看遠端環境實際提供的系統、Xcode 和模型狀態。先確認課程所需條件，再決定是否使用遠端 Mac；可先查看 VMSPIN 方案資訊，並確認環境細節，不要只憑「遠端 Mac」名稱推斷相容性。

下一步：先驗環境，再決定是否使用遠端 Mac

如果你目前的做法是等借到 Mac、反覆重裝工具，或只在不確定支援狀態的環境中測試，常見問題是課程進度受設備安排影響、實際系統條件不透明，以及編譯結果容易被誤認為模型已成功。若本地設備無法完成相容性驗收，可先閱讀 遠端 Mac 環境與方案資訊，確認實際分配環境能否滿足課程需求，再決定要不要租用 VMSPIN。若你需要長期固定使用、特定實體介面，或必須保證某一套尚未確認相容的環境，自購或使用手邊設備可能更適合；短期完成課程練習時，則先核實條件再租，避免為未確認的模型能力付費。