Apple Foundation Models:Apple AI核心框架

Apple Foundation Models 是苹果提供的生成式 AI 开发框架。开发者可以通过统一的 API 调用端侧模型、Private Cloud Compute(PCC)(苹果私有云模型)或自定义模型,完成文本生成、结构化输出、工具调用和图片理解等任务。

Apple Foundation Models 框架的核心是五个对象:

  1. LanguageModel:决定模型在哪里运行,以及具备哪些能力。
  2. LanguageModelSession:管理指令、历史、工具和请求。
  3. @Generable 输出适合App处理的结构化对象**
  4. Tool:让模型能够借助App能力完成任务。
  5. 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 返回结果后,模型再把结果组织成自然语言答案。

完整流程如下:

sequenceDiagram autonumber participant U as 用户 participant A as App participant S as Session participant M as 模型 participant T as Tool rect rgb(234, 242, 255) Note over U,A: ① 发起请求 U->>A: 提出需求 A->>S: respond(to:) S->>S: 组装 Instructions + Transcript + Prompt S->>M: 发起生成请求 end rect rgb(255, 244, 229) Note over M,T: ② 模型只产出参数,App 真正执行 M-->>S: 生成工具参数 city = "上海" S->>T: call(arguments:) T-->>S: 返回工具执行结果 end rect rgb(233, 251, 240) Note over S,M: ③ 结果回灌,生成最终答案 S->>M: 带上工具结果继续生成 M-->>S: 最终答案 / 结构化对象 end S-->>A: response.content A-->>U: 渲染结果

注意图中第 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: "我去过哪些靠近水边的徒步路线?"
)
相关推荐
IT_陈寒17 分钟前
Redis那个过期删除策略,差点让我线上崩了
前端·人工智能·后端
ServBay23 分钟前
Cursor披露恶意扩展,怎么守住本地 API Key
后端·ai编程·cursor
阿里云大数据AI技术36 分钟前
AI 原生大数据服务 ADA 快速入门:完成首次对话式数据分析
大数据·人工智能
字节跳动开源44 分钟前
小红书/抖音图文排版利器——一个杂志风skill
人工智能·开源·设计
IT规划师1 小时前
热点速递 | Agent 交付没人敢合?GitHub 榜在补验收
agent·ai编程
Bacon1 小时前
我把 Codex 塞进了 Touch Bar:一个 30pt 高的额度与对话面板
人工智能
衡石科技1 小时前
企业级 BI 的安全治理:衡石如何贯通认证、数据权限与审计
大数据·人工智能·安全·商业智能
慧都小项1 小时前
MyEclipse Inline Diff 实用指南:逐处核对 AI 修改再提交
git·ai编程·myeclipse·java 代码审查·ai 代码修改
码间留白1 小时前
AI 给的两个方案都被我否了:把 startIcon 与启动遮罩做成同一张图,鸿蒙 APP 冷启动零白屏
性能优化·uni-app·ai编程·harmonyos