基础模型框架示例

探索基础模型

该项目包含按章节组织的实验性示例，旨在帮助您全面了解苹果的基础模型框架。

本项目是 探索基础模型 一书的一部分。

系统要求

• iOS 26.0+ 或 macOS 26.0+（Xcode 26.0+）
• 必须使用官方 Xcode 26
• 启用 Apple Intelligence
• 兼容 Apple Silicon 的 Apple 设备

在 TestFlight 上试用

现在您可以在 TestFlight 上试用 Foundation Lab！加入测试版：https://testflight.apple.com/join/JWR9FpP3

自动化 TestFlight 上传

该仓库包含一个本地 ASC 工作流文件 .asc/workflow.json，以及一个 GitHub Actions 工作流文件 .github/workflows/foundation-lab-testflight.yml，每当 main 分支有代码变更时，都会将 iOS 应用程序上传到外部 TestFlight 测试组。

GitHub Actions 需要以下仓库密钥：

• ASC_KEY_ID
• ASC_ISSUER_ID
• ASC_PRIVATE_KEY_B64

此外，还需要以下仓库变量：

• FOUNDATION_LAB_APP_ID
• FOUNDATION_LAB_EXTERNAL_GROUP_ID
• FOUNDATION_LAB_BUNDLE_ID
• FOUNDATION_LAB_TEAM_ID

开始使用

• 克隆仓库
• 在 Xcode 中打开 FoundationLab.xcodeproj
• 确保您有一台启用了 Apple Intelligence 的设备
• 构建并运行项目
• 通过示例探索各种功能！

命令行界面

该仓库还包含 fm，这是一个独立的命令行界面，由 FoundationLabCore 中的共享功能代码支持。

• 本地开发：cd FoundationLabCLI && swift run fm --help
• 一次性响应：cd FoundationLabCLI && swift run fm session respond --dry-run --json --prompt "推荐一本振奋人心的科幻小说"
• Xcode 开发：从 FoundationLab.xcodeproj 中构建 fm 方案
• Homebrew 发布准备：使用 ./Scripts/generate-homebrew-formula.sh <tag> 并按照 FoundationLabCLI/README.md 操作

内容概览

该应用包含四个主要部分：

聊天

多轮对话，具备上下文管理、流式响应和反馈系统。必要时会自动进行会话摘要以管理上下文窗口。

工具

九种系统集成工具，扩展了模型的功能：

• 天气 - 任意地点的当前天气（OpenMeteo API）
• 网页搜索 - Keyless Search1API（免费，有限制）
• 通讯录 - 搜索和访问系统联系人
• 日历 - 创建和管理日历事件
• 提醒事项 - AI 辅助创建带有优先级的提醒
• 位置 - 当前位置和地理编码
• 健康 - HealthKit 集成，用于查询健康数据
• 音乐 - Apple Music 搜索（需订阅）
• 网页元数据 - 提取元数据并生成社交媒体摘要

语音界面

通过语音与模型交流：

• 实时语音转文字
• 文字转语音回复
• 语音创建提醒
• 音频反应式可视化
• 自动处理所有权限

健康仪表盘

基于 HealthKit 的 AI 驱动健康追踪：

• 个性化健康教练，提供情境洞察
• 趋势分析和相关性研究
• 预测性分析
• 每周总结和个性化健康计划
• 多项健康指标跟踪

集成中心

三个部分用于探索高级功能：

• 工具 - 所有九个系统集成示例
• 模式 - 从基础到专家级别的动态模式示例
• 语言 - 多语言功能和语言检测

示例

十种不同类型的示例展示了框架的能力：

• 单次提示
• 日记记录
• 创意写作
• 结构化数据生成
• 流式响应
• 模型可用性检查
• 生成指南
• 生成选项（温度、标记数、适应度）
• 健康仪表盘
• RAG 聊天，结合文档索引和语义搜索

功能特点

核心能力

• 聊天：具备上下文管理的多轮对话
• 流式传输：实时响应流式传输
• 结构化生成：使用 @Generable 进行类型安全的数据生成
• 生成指南：使用 @Guide 控制约束输出
• 工具调用：系统集成以扩展功能
• RAG：结合 LumoKit/VecturaKit 进行文档索引和语义搜索
• 语音：语音转文字和文字转语音
• 健康：HealthKit 集成与 AI 派生见解
• 多语言：支持 10 种语言（英语、德语、西班牙语、法语、意大利语、日语、韩语、葡萄牙语、中文）

动态模式

该应用包含 11 个从基础到专家级别的动态模式示例：

• 基础模式
• 数组和集合
• 枚举和联合类型
• 嵌套对象
• 模式引用
• 表单生成器
• 发票处理
• 错误处理模式

实验性示例

四个章节提供了动手实践的示例：

• 第 2 章：会话入门（16 个示例）
• 第 3 章：生成选项与采样控制（5 个示例）
• 第 8 章：基础工具使用（9 个示例）
• 第 13 章：语言与国际化（7 个示例）

这些示例可以直接在 Xcode 中使用 #Playground 指令运行。

使用示例

基本聊天

let session = LanguageModelSession()
let response = try await session.respond(
    to: "为一家新的咖啡店建议一个朗朗上口的名字。"
)
print(response.content)

结构化数据生成

let session = LanguageModelSession()
let bookInfo = try await session.respond(
    to: "推荐一本科幻小说。",
    generating: BookRecommendation.self
)
print("书名：\(bookInfo.content.title)")
print("作者：\(bookInfo.content.author)")

工具调用

// 单个工具
let weatherSession = LanguageModelSession(tools: [WeatherTool()])
let response = try await weatherSession.respond(
    to: "新德里和库比蒂诺哪个更热？"
)

// 多个工具
let multiSession = LanguageModelSession(tools: [
    WeatherTool(),
    Search1WebSearchTool(),
    ContactsTool()
])
let multiResponse = try await multiSession.respond(
    to: "查看天气、上网搜索，并找到我朋友约翰的联系方式"
)

流式响应

let session = LanguageModelSession()
let stream = session.streamResponse(to: "写一首关于科技的小诗。")

for try await partialText in stream {
    print("部分内容：\(partialText)")
}

语音交互

// 语音识别
let recognizer = SpeechRecognizer()
try recognizer.startRecognition()

// 文本转语音
try await SpeechSynthesizer.shared.synthesizeAndSpeak(text: "你好，我能帮你什么吗？")

健康数据

let session = LanguageModelSession(tools: [HealthDataTool()])
let response = try await session.respond(
    to: "给我看看我这周的步数趋势"
)

数据模型

该应用包含多种用于不同场景的 @Generable 数据模型：

通用用途

@Generable
struct BookRecommendation {
    @Guide(description: "书籍的标题")
    let title: String

    @Guide(description: "作者姓名")
    let author: String

    @Guide(description: "书籍的类型")
    let genre: Genre
}

@Generable
struct ProductReview {
    @Guide(description: "产品名称")
    let productName: String

    @Guide(description: "评分，范围从1到5")
    let rating: Int

    @Guide(description: "主要优点和缺点")
    let pros: [String]
    let cons: [String]
}

@Generable
struct StoryOutline {
    let title: String
    let protagonist: String
    let conflict: String
    let setting: String
    let genre: StoryGenre
    let themes: [String]
}

@Generable
struct JournalEntrySummary {
    let prompt: String
    let upliftingMessage: String
    let sentenceStarters: [String]
    let summaryBullets: [String]
    let themes: [String]
}

健康相关模型

@Generable
struct HealthAI {
    let greeting: String
    let mood: HealthAIMood
    let motivationalMessage: String
    let focusMetrics: [String]
    let suggestions: [String]
}

@Generable
struct HealthAnalysis {
    let healthScore: Int
    let trends: HealthTrends
    let insights: [HealthInsightDetail]
    let correlations: [MetricCorrelation]
    let predictions: [HealthPrediction]
    let recommendations: [String]
}

@Generable
struct PersonalizedHealthPlan {
    let title: String
    let overview: String
    let currentStatus: String
    let weeklyActivities: [String]
    let nutritionGuidelines: NutritionPlan
    let sleepStrategy: String
    let milestones: [String]
}

聊天上下文

@Generable
struct ConversationSummary {
    let summary: String
    let keyTopics: [String]
    let userPreferences: [String]
}

工具详情

天气工具

• 使用 OpenMeteo API 获取实时天气信息
• 包括温度、湿度、风速和天气状况
• 自动地理编码
• 无需 API 密钥

网络搜索工具

• 使用 Search1API 的无密钥端点
• 返回带有摘要的搜索结果
• 无需 API 密钥（免费层级有限制）

联系人工具

• 搜索系统联系人
• 支持自然语言查询
• 需要联系人权限

日历工具

• 创建和管理日程事件
• 能够感知时区和本地化设置
• 支持相对日期（如“今天”、“明天”）
• 需要日历权限

提醒工具

• 使用 AI 创建提醒
• 具有优先级等级：无、低、中、高
• 可设置截止日期和备注
• 需要提醒权限

定位工具

• 提供当前位置信息
• 支持地理编码
• 需要定位权限

健康工具

• 集成 HealthKit
• 查询健康指标
• 提供 AI 驱动的洞察
• 需要 HealthKit 权限

音乐工具

• 搜索 Apple Music 内容
• 支持歌曲、艺术家和专辑
• 需要 Apple Music 订阅
• 需要音乐权限

网页元数据工具

• 提取网页元数据
• 生成社交媒体摘要
• 支持特定平台的格式化
• 无需 API 密钥

多语言支持

该应用支持 10 种语言：

• 英语
• 德语
• 西班牙语
• 法语
• 意大利语
• 日语
• 韩语
• 葡萄牙语（巴西）
• 中文（简体）
• 中文（繁体）

语言检测和代码切换示例包含在集成部分中。

权限要求

根据您使用的功能，该应用可能会请求以下权限：

• 麦克风（用于语音输入）
• 语音识别
• 联系人
• 日历
• 提醒
• 定位
• HealthKit
• Apple Music

所有权限均会在适当的时候请求，并且可以在设置中进行管理。

贡献说明

欢迎贡献！请随时提交拉取请求。

许可证

该项目采用 MIT 许可证授权——详细信息请参阅 LICENSE 文件。

Foundation-Models-Framework-Example 快速上手指南

本指南帮助中国开发者快速体验 Apple Foundation Models 框架的核心功能，包括多轮对话、工具调用、结构化数据生成及语音交互等。

环境准备

在开始之前，请确保您的开发环境满足以下严格要求：

• 操作系统：iOS 26.0+ 或 macOS 26.0+
• 开发工具：必须使用 Xcode 26.0+ (官方正式版)
• 硬件要求：配备 Apple Silicon 芯片的兼容设备
• 核心依赖：必须在设备上启用 Apple Intelligence (苹果智能)
• 账号要求：需登录支持 Apple Intelligence 的 Apple ID

注意：由于该框架深度依赖 Apple 最新系统特性，目前暂无国内镜像源或加速方案，请确保网络环境能正常访问 Apple 开发者服务。

安装步骤

1. 克隆项目

打开终端，克隆仓库到本地：

git clone <repository-url>
cd Foundation-Models-Framework-Example

2. 打开项目

使用 Xcode 打开项目文件：

open FoundationLab.xcodeproj

3. 构建与运行

• 在 Xcode 中选择您的物理设备（模拟器可能不支持部分 Apple Intelligence 功能）。
• 确保设备已开启“苹果智能”。
• 点击 Run (⌘R) 构建并启动应用 FoundationLab。

4. CLI 工具可选安装

如果您希望使用命令行界面 (fm) 进行测试：

# 进入 CLI 目录
cd FoundationLabCLI

# 直接运行帮助命令
swift run fm --help

基本使用

启动应用后，您将通过四个主要模块探索框架能力：Chat (对话)、Tools (工具)、Voice Interface (语音) 和 Health Dashboard (健康)。以下是代码层面的核心用法示例。

1. 基础对话 (Basic Chat)

创建会话并获取模型回复：

let session = LanguageModelSession()
let response = try await session.respond(
    to: "Suggest a catchy name for a new coffee shop."
)
print(response.content)

2. 结构化数据生成 (Structured Data Generation)

利用 @Generable 宏定义类型安全的数据结构，让模型直接输出 JSON 对象：

let session = LanguageModelSession()
let bookInfo = try await session.respond(
    to: "Suggest a sci-fi book.",
    generating: BookRecommendation.self
)
print("Title: \(bookInfo.content.title)")
print("Author: \(bookInfo.content.author)")

3. 工具调用 (Tool Calling)

集成系统工具（如天气、搜索、联系人）扩展模型能力：

// 单个工具示例
let weatherSession = LanguageModelSession(tools: [WeatherTool()])
let response = try await weatherSession.respond(
    to: "Is it hotter in New Delhi or Cupertino?"
)

// 多个工具组合
let multiSession = LanguageModelSession(tools: [
    WeatherTool(),
    Search1WebSearchTool(),
    ContactsTool()
])
let multiResponse = try await multiSession.respond(
    to: "Check the weather, search the web, and find my friend John's contact"
)

4. 流式响应 (Streaming Responses)

实现打字机效果的实时文本输出：

let session = LanguageModelSession()
let stream = session.streamResponse(to: "Write a short poem about technology.")

for try await partialText in stream {
    print("Partial: \(partialText)")
}

5. 语音交互 (Voice Interface)

集成语音识别与合成：

// 语音转文字
let recognizer = SpeechRecognizer()
try recognizer.startRecognition()

// 文字转语音
try await SpeechSynthesizer.shared.synthesizeAndSpeak(text: "Hello, how can I help you?")

6. 健康数据查询 (Health Data)

结合 HealthKit 进行个性化健康分析：

let session = LanguageModelSession(tools: [HealthDataTool()])
let response = try await session.respond(
    to: "Show me my step count trends this week"
)

---

提示：项目中包含丰富的 Playground 示例（位于 #Playground 指令下），涵盖会话管理、采样控制、工具使用及多语言支持等章节，建议在 Xcode 中直接运行以深入学习。