
Apple Foundation Models 是苹果提供的生成式 AI 开发框架。开发者可以通过统一的 API 调用端侧模型、Private Cloud Compute(PCC)(苹果私有云模型)或自定义模型,完成文本生成、结构化输出、工具调用和图片理解等任务。
Apple Foundation Models 框架的核心是五个对象:
LanguageModel:决定模型在哪里运行,以及具备哪些能力。LanguageModelSession:管理指令、历史、工具和请求。@Generable输出适合App处理的结构化对象**Tool:让模型能够借助App能力完成任务。DynamicProfile管理工作流。
一、先理解三个核心概念
1. 模型种类
| 模型 | 特点 | 适用场景 |
|---|---|---|
SystemLanguageModel |
在设备本地运行(iOS macOS),注重隐私和响应速度 | 摘要、分类、简单问答 |
PrivateCloudComputeLanguageModel |
在苹果自建数据中心和自研芯片上运行,提供更复杂的能力,并采用可验证的隐私保护机制 | 复杂推理或较大的上下文 |
自定义 LanguageModel |
通过统一协议接入其他推理后端 | 自研模型或第三方模型 |
2. 会话(Session)
LanguageModelSession 是使用模型的主要入口。一次会话通常包含:
- Instructions:模型的角色和行为规则, 就是系统提示词。
- Prompt:用户当前的提示词。
- Transcript:提示词、模型回复和工具调用等历史记录。
- Tools:允许模型请求调用的App工具。
模型收到指令、输入和必要的上下文后,可以生成文本、结构化结果或工具调用。工具由App执行,执行结果再交回模型生成最终答案。
因此,模型不会直接访问 App 数据库或执行任意代码,权限仍由App控制。
3. 为什么需要结构化输出
普通文本适合直接展示,@Generable 则让模型返回可由App使用的 Swift 数据类型。
4. 整体结构一览

这张图对应三个要点:LanguageModelSession 是唯一入口;LanguageModel 只负责"模型在哪运行";Tool 的执行权始终在 App 手里,模型只是发起请求。
二、Foundation Models 基础调用
2.1 生成文本
最基础的调用只需创建会话并发送提示词。默认会话使用系统提供的端侧模型。
swift
import FoundationModels
let session = LanguageModelSession(
instructions: "你是一位简洁、准确的中文助手。"
)
let response = try await session.respond(
to: "用一句话解释什么是端侧 AI。"
)
print(response.content)
实际使用前应检查模型的 isAvailable。长文本或长对话还需要关注 contextSize,必要时裁剪或总结历史,避免超出上下文窗口。
2.2 生成结构化结果
@Generable 描述输出结构
@Guide 补充字段语义或约束。调用方可以直接读取类型安全的对象,不必手动解析 JSON 字符串。
swift
@Generable
struct ArticleSummary {
@Guide(description: "一句话概括文章主题")
var summary: String
@Guide(description: "最重要的三个要点")
var keyPoints: [String]
}
let response = try await session.respond(
to: "总结这篇文章:\(article)",
generating: ArticleSummary.self
)
let summary: ArticleSummary = response.content
print(summary.summary)
print(summary.keyPoints)
2.3 调用App工具
工具适合查询实时信息、读取 App 数据或执行明确操作。
模型负责生成参数,App负责真正执行代码。
swift
struct WeatherTool: Tool {
let description = "查询指定城市的当前天气"
@Generable
struct Arguments {
@Guide(description: "需要查询天气的城市名称")
var city: String
}
func call(arguments: Arguments) async throws -> String {
try await WeatherService.currentWeather(city: arguments.city)
}
}
let session = LanguageModelSession(
tools: [WeatherTool()],
instructions: "需要实时天气时使用工具,不要猜测。"
)
let response = try await session.respond(
to: "上海现在的天气怎么样?"
)
这里模型可能生成 city = "上海" 并请求调用工具。WeatherTool 返回结果后,模型再把结果组织成自然语言答案。
完整流程如下:
注意图中第 5 步:模型只产出参数,真正执行的是 Tool.call(arguments:),结果再回灌给模型组织成自然语言。
三、使用 DynamicProfile 编排会话
固定指令适合单一任务。复杂 App 可能需要在"头脑风暴"和"制定计划"等模式之间切换,并为不同模式配置不同的指令、模型和生成参数。
DynamicProfile 会读取App状态并生成对应的会话配置:
swift
struct CraftProfile: LanguageModelSession.DynamicProfile {
var orchestrator: CraftOrchestrator
var body: some DynamicProfile {
switch orchestrator.mode {
case .brainstorming:
Profile {
Instructions {
"为手工项目提出多样、有创意的方案。"
}
BrainstormRecordTool()
}
// 创意阶段使用 PCC,温度能够提高输出的多样性
.model(orchestrator.pccLanguageModel)
.temperature(1)
case .planning:
Profile {
Instructions {
"把选定的方案整理成清晰、可执行的教程。"
}
}
// 规划阶段启用更深入的推理
.model(orchestrator.pccLanguageModel)
.reasoningLevel(.deep)
case .reviewing:
Profile {
Instructions { "回顾项目并提出改进建议。" }
}
// 简单回顾可以回到端侧模型
.model(orchestrator.systemLanguageModel)
}
}
}
let session = LanguageModelSession(
profile: CraftProfile(orchestrator: orchestrator)
)
这个例子体现了会话编排的核心:业务代码仍然调用同一个 session,但会话使用的指令、工具和模型可以随状态变化。
历史记录较多时,可以使用 historyTransform 调整实际送入模型的内容,而不直接修改原始会话历史。
下面的示例保留会话历史中的工具调用与工具输出,再加上最近一次响应,减少普通对话占用的上下文:
swift
struct HistoryManagingProfile: LanguageModelSession.DynamicProfile {
var orchestrator: CraftOrchestrator
var body: some DynamicProfile {
Profile {
Instructions { "结合已有工具结果,回顾项目并提出建议。" }
}
.model(orchestrator.systemLanguageModel)
.historyTransform { history in
// 找不到最近一次响应时,保持原历史不变
guard let latestResponseIndex = lastResponseEntryIndex(history) else {
return history
}
// 从会话历史中只保留工具调用和工具输出
let filteredHistory = history[0..<latestResponseIndex].filter { entry in
isToolCallsOrToolOutput(entry)
}
// 拼接筛选后的早期记录和最近一次响应
return filteredHistory + history[latestResponseIndex...]
}
}
}
historyTransform 只影响本次提供给模型的历史,不等于删除 App 中保存的原始历史会话 Transcript。
四、选择模型与接入自定义模型
4.1 在端侧模型和 PCC 之间切换
会话接口不依赖某个固定模型。更换 model 参数后,提示词、结构化输出和工具调用的写法基本可以保持不变。
swift
// 端侧模型
let localSession = LanguageModelSession(
model: SystemLanguageModel()
)
// Private Cloud Compute 模型
let cloudSession = LanguageModelSession(
model: PrivateCloudComputeLanguageModel()
)
let response = try await cloudSession.respond(
to: "分析这篇文章的论点,并列出关键证据。\(article)"
)
选择模型时,需要综合考虑任务复杂度、隐私要求、上下文大小、响应速度和可用配额,而不是所有请求都使用更强的模型。
4.2 实现自定义 LanguageModel
自定义模型主要分为两部分:
LanguageModel:声明模型能力,并提供执行器配置。LanguageModelExecutor:把统一请求转换成底层推理调用,再通过 Channel 返回文本、用量和元数据。
下面的代码展示基本结构:
swift
public struct MyLanguageModel: LanguageModel {
public typealias Executor = MyLanguageModelExecutor
public var capabilities: LanguageModelCapabilities {
LanguageModelCapabilities(capabilities: [
.toolCalling,
.guidedGeneration,
.reasoning
])
}
public var executorConfiguration: Executor.Configuration {
Executor.Configuration()
}
}
public struct MyLanguageModelExecutor: LanguageModelExecutor {
public typealias Model = MyLanguageModel
public struct Configuration: Hashable, Sendable {
public init() {}
}
public init(configuration: Configuration) throws {
}
public func respond(
to request: LanguageModelExecutorGenerationRequest,
model: MyLanguageModel,
streamingInto channel: LanguageModelExecutorGenerationChannel
) async throws {
// 1. 将 request 中的 Transcript 和生成参数转换为后端API请求
// 2. 执行真正的模型推理
// 3. 将生成的文本增量发送给App上层会话
for try await token in runInference(request) {
await channel.send(.response(action: .appendText(token)))
}
}
}
接入自定义模型时,不仅仅是调用某个后端/SDK API,而是正确完成四项映射:**历史消息、生成参数、流式输出和错误。
五、通过命令行和 Python 使用Apple模型
5.1 使用 fm 命令行工具
fm 适合快速调试提示词、图片输入和结构化输出。下面的示例先生成 JSON Schema,再要求模型按 Schema 返回结果:
bash
# 定义输出结构:一个字符串数组 app_names
fm schema object --name AppsIdentified \
--string app_names --array > schema.json
# 从截图中提取 App 名称,并按 Schema 输出
fm respond "What apps are visible in this screenshot?" \
--model pcc \
--image Screenshot.png \
--schema schema.json
# 输出示例:{"app_names": ["Messages", "Mail", "Calendar"]}
不使用 Schema 时,也可以直接执行 fm respond "你的提示词" 快速验证模型输出。
5.2 使用 Python SDK
Python SDK 的调用流程与 Swift 基本一致:创建会话、发送异步请求、读取结果。结构化输出可以通过 @fm.generable 声明。
python
import apple_fm_sdk as fm
@fm.generable("Article summary")
class ArticleSummary:
summary: str = fm.guide("A one-sentence summary")
key_points: list[str] = fm.guide("The three most important points")
async def summarize(article: str) -> ArticleSummary:
session = fm.LanguageModelSession(
instructions="You are a concise article summarizer."
)
return await session.respond(
f"Summarize this article: {article}",
generating=ArticleSummary
)
安装命令为 pip install apple_fm_sdk。Python 同样支持定义工具,让模型查询业务数据后再生成答案。
六、使用 SpotlightSearchTool 搜索App内容
SpotlightSearchTool 让模型能够搜索 App 已写入 Spotlight 的内容。
swift
import CoreSpotlight
import FoundationModels
let searchTool = SpotlightSearchTool()
let session = LanguageModelSession(
model: SystemLanguageModel(),
tools: [searchTool],
instructions: """
使用搜索工具查找用户的徒步记录。
只根据搜索结果回答,不要编造不存在的记录。
"""
)
let response = try await session.respond(
to: "我去过哪些靠近水边的徒步路线?"
)