Apple Foundation Models 怎么做首个 SwiftUI 功能？2026 新手教程

先做一个能输入文本、调用系统模型并显示回答的最小 SwiftUI 功能；动手前检查 Xcode、运行系统和模型可用性，只有目标设备支持并且模型状态可用，才能验收真实调用。你这周可以先搭好页面，再按设备条件决定是否测试模型；首课先别扩展成 Agent 或工具调用。

适合刚开始学习 SwiftUI、想把 AI 文本功能加进练习项目的学生；也适合会做简单页面、但还没写过模型请求的新手。如果你没有本地兼容 Mac，正考虑用远程 Mac 完成课程练习，也可以按下面的环境检查步骤先确认条件。

开始前：编译环境和模型环境不是一回事

Apple Foundation Models SwiftUI 入门的第一道检查，不是先敲代码，而是把“项目能不能编译”和“设备能不能调用模型”分开判断。Apple 的 Xcode 系统要求页列出了 Xcode 27 对应的 macOS 要求；但符合 Xcode 系统要求，只能说明开发工具有运行条件，不代表目标设备已经能使用系统模型。(developer.apple.com)

Foundation Models 使用的是与 Apple Intelligence 相关的系统模型。Apple 官方说明，实际可用性还取决于设备与地区支持情况；所以“项目编译成功”不能代替运行时检查。(developer.apple.com)

如果你准备通过远程桌面操作 Mac，先确认被分配的主机是否满足模型调用条件。模型不是在你手上的 Windows 电脑里运行；远程连接只能让你操作那台 Mac，不能把本机设备的能力传给远端，也不能替代官方的可用性状态检查。

第一段里程碑：先做只会变化的练习页面

先创建一个只包含输入框、操作按钮和回答区域的页面。暂时用固定文字代替模型输出，检查输入内容能否显示、点击按钮后页面能否变化。这样能把 SwiftUI 页面问题和模型环境问题分开排查。

你可以把 @State 想成课程作业的当前进度：输入、加载提示和回答都是进度记录；记录改变后，SwiftUI 会更新依赖这些状态的界面。Apple 对 State 的说明是，它用于保存由 SwiftUI 管理的值。(developer.apple.com)

先准备这几项状态即可：

@State private var prompt = ""
@State private var answer = "回答会显示在这里。"
@State private var isLoading = false
@State private var errorMessage: String?

用 TextField 绑定 prompt，按钮负责触发操作，Text 显示 answer 或错误提示。此时按钮可以先把 answer 改成固定句子。验收标准很直接：你输入的字能显示，点击后回答区域发生可见变化。没通过这一步，先不要加入模型调用。

⚠️ 课程验收时，把“页面可操作”“请求已执行”“模型确实可用”分成不同记录。混成一个“成功”标签，会让你很难判断问题到底出在界面、代码还是运行设备。

第二段里程碑：用最短路径发出文本请求

Apple 的框架流程是先创建 LanguageModelSession，再把文本提示交给会话，请求生成回答。可以把 session 理解为一张连续的课堂对话记录：同一会话会保留请求之间的上下文；prompt 则是你递交给模型的题目。首个练习只需普通文字问答，不必加入图片、工具调用或自定义模型。(developer.apple.com)

下面的代码展示最小调用链。它使用 SwiftUI 状态显示加载中、回答或错误；把代码放进你自己的视图时，记得根据项目结构调整按钮和文本控件。

import SwiftUI
import FoundationModels

struct ContentView: View {
    @State private var prompt = ""
    @State private var answer = ""
    @State private var errorMessage: String?
    @State private var isLoading = false

    var body: some View {
        VStack(spacing: 16) {
            TextField("输入一个简单问题", text: $prompt)
                .textFieldStyle(.roundedBorder)

            Button("生成回答") {
                Task { await askModel() }
            }
            .disabled(isLoading || prompt.trimmingCharacters(
                in: .whitespacesAndNewlines
            ).isEmpty)

            if isLoading {
                Text("正在请求模型……")
            } else if let errorMessage {
                Text(errorMessage)
            } else {
                Text(answer.isEmpty ? "回答会显示在这里。" : answer)
            }
        }
        .padding()
    }

    @available(iOS 26.0, macOS 26.0, *)
    private func askModel() async {
        let model = SystemLanguageModel.default

        guard case .available = model.availability else {
            errorMessage = "当前设备的系统模型暂不可用；页面仍可继续练习。"
            return
        }

        isLoading = true
        errorMessage = nil
        defer { isLoading = false }

        do {
            let session = LanguageModelSession(
                instructions: "请用简洁、适合编程新手的中文回答。"
            )
            let response = try await session.respond(to: prompt)
            answer = response.content
        } catch {
            errorMessage = "请求没有完成。请检查运行环境后重试。"
        }
    }
}

respond(to:) 是异步请求，具体 API 和可用系统版本以你当前使用的 SDK 文档为准；代码示例中的系统版本标注，不代表模型在该设备上必定可用。开始编写前，对照官方的 respond(to:) 方法说明核对调用签名；系统条件则另做运行时检查。

第三段里程碑：把“不可用”变成明确反馈

Apple 提供 SystemLanguageModel.default.availability 检查模型状态。不要只用一个“失败”提示概括所有情况：官方列出的不可用原因包括设备不符合条件、Apple Intelligence 未启用、模型尚未就绪。(developer.apple.com)

实现时可以把这些状态映射到不同提示文字；不要把“暂不可用”无限期表现成加载动画，也不要用预置文字冒充模型输出。模型状态还可能变化，因此请求按钮执行前再检查一次，比只在页面启动时检查更稳妥。

第四段里程碑：按顺序验收真实调用

完成页面与模型代码后，用一条不含私人资料的简单问题做检查，例如“用一句话解释变量是什么”。按下面的顺序记录结果：

• 先看界面：输入内容能否进入文本框，按钮是否会触发状态变化。
• 再看环境：运行时读取的 availability 是什么；如果不可用，记下具体原因，不要猜。
• 再看请求：只有状态允许时才调用 respond(to:)，观察是否进入加载状态。
• 最后看结果：成功时显示 response.content；出错时显示错误提示，并确认加载状态会结束。
• 换环境复测：如使用远程 Mac，记录实际分配环境的系统与 Xcode 版本、模型状态和复测结果。没有真实记录时，不要把单次结果推广成“所有远程 Mac 都支持”。

模拟器适合检查页面布局、按钮逻辑和状态切换，但不能只凭模拟器里页面显示正常，就认定目标设备上的系统模型调用已通过。最终验收应在你计划交付或上课使用的目标环境中，检查实际 availability 并发出请求；具体能力边界以 Apple 文档和设备实测为准。

没有本地 Mac，能继续做 Foundation Models 项目吗？

可以先完成页面和代码练习，但真实调用能否验收，取决于远程分配的 Mac 与其运行环境，而不是“远程”这个连接方式本身。开始租用或安排课程前，先询问并核实具体主机类别、系统版本、Xcode 版本，以及运行时模型可用性；不要仅凭宣传中的芯片系列或远程桌面连通，就推断一定能推理。

你可以先查看 VMSPIN 远程 Mac 环境入口，再根据课程目标核实实际环境。若本地设备只缺一个短期开发与验收环境，按需使用远程 Mac 可以避免为了单次课程立即购置设备；但它不适合需要长期固定硬件、物理接口或完全离线工作的项目。使用前可对照 套餐与计费信息，确认周期与使用方式，再决定是否适合你的课程。

本周建议：把页面练习与设备验收分开

这周先完成一个输入框、一个按钮和一个回答区域，再加入会话请求与状态提示；只有在目标设备报告 available 且请求确实返回内容后，才把模型调用记为通过。页面练习可以继续在不满足模型条件的环境里进行，但不要把它记成真实推理验收。

截至 2026 年 9 月 25 日，本文涉及的 API、状态与 Xcode 系统要求核对自 Apple Developer 官方文档。更新系统或开发工具后，请重新核对 Foundation Models 框架说明、SystemLanguageModel 可用性说明与 Xcode 系统要求。