python-apple-fm-sdk 是 Apple 官方推出的 Python 绑定库，它直接调用 macOS 上 Apple Intelligence 的核心本地大模型（Foundation Models framework），让你在自己的 Mac 上完成私密、离线、低延迟的本地文本生成。本教程带你走通从安装到首次生成、多轮对话、流式输出与结构化输出的完整流程，核心调用只需几行代码。

为什么选择 python-apple-fm-sdk 🤔

相比调用云端 API，python-apple-fm-sdk 的端侧推理带来四大优势：

核心能力一览：

• 本地推理与批处理评估
• 实时流式文本生成
• 基于 Schema 的结构化生成（guided generation）
• 处理 Swift 应用导出的转录数据

环境要求与一键安装

开始前，请确认你的 Mac 满足以下条件：

• macOS 26.0 及以上
• Xcode 26.0 及以上（建议与系统版本保持一致）
• Python 3.10 及以上
• 已在系统设置中开启 Apple Intelligence

最快安装方法——一条命令即可：

pip install apple-fm-sdk

验证是否就绪（详见 getting_started.rst）：

import apple_fm_sdk as fm model = fm.SystemLanguageModel() is_available, reason = model.is_available() print("SDK ready!" if is_available else f"不可用：{reason}")

三步完成首次本地文本生成

这是整个教程的核心，只需三行代码就能让 Apple Intelligence 在你的 Mac 上生成文本：

import apple_fm_sdk as fm import asyncio async def main(): model = fm.SystemLanguageModel() # 1. 获取系统模型 session = fm.LanguageModelSession() # 2. 创建会话 response = await session.respond("用一句话介绍苹果") # 3. 生成回答 print(response) asyncio.run(main())

三行分别对应：创建模型 → 创建会话 → 发送提示词。完整可运行版本见 simple_inference.py。

💡 提示：正式生成前，建议先调用model.is_available()检查模型可用性，避免在不受支持的设备上空转。

多轮会话：让模型"记住"上下文

LanguageModelSession会维护对话上下文。创建会话时传入instructions可设定助手人设，之后的每次追问都会自动携带历史：

session = fm.LanguageModelSession( instructions="You are a helpful assistant that provides concise answers." ) r1 = await session.respond("What is the capital of France?") r2 = await session.respond("What is its population?") # 自动记得上一句

对应示例见 simple_inference.py。

流式输出：实时看到文字"打字" 📝

需要即时反馈时，用stream_response逐块获取文本：

print("Assistant: ", end="", flush=True) async for chunk in session.stream_response("Tell me a short story about a cat."): print(chunk, end="", flush=True)

完整示例见 streaming_example.py。

结构化生成：直接拿到 Python 对象 📦

用@fm.generable装饰器定义数据类，模型会返回符合约束的真实 Python 对象，而非字符串：

import apple_fm_sdk as fm @fm.generable class Cat: name: str age: int = fm.guide("Age in years", range=(0, 20))

配合generating=Cat调用，即可让模型"按你的结构"输出。相关 API 位于 generable.py。

处理 Swift 转录数据：评估工作流 📊

如果你在 Swift 应用中使用了 Foundation Models，可以用 Python 批量分析它导出的会话转录（transcript），统计角色分布、工具调用、结构化输出占比等指标，帮助评估线上表现：

analysis = analyze_transcript(transcript) # 返回各项统计指标

完整实现见 transcript_processing.py，配套数据结构说明见 transcript.py。

常见问题：模型不可用怎么排查？🔧

若打印出Foundation Models not available，请依次检查：

1. 设备硬件是否支持 Apple Intelligence
2. 系统设置中是否已开启 Apple Intelligence
3. 系统版本是否为 macOS 26.0+
4. Xcode 版本是否与 macOS 版本一致

排查清单整理自 basic_usage.rst 与 getting_started.rst。

延伸阅读与相关文件

• 基本用法与核心概念：basic_usage.rst
• 入门与安装：getting_started.rst
• 会话核心实现：session.py
• 错误类型：errors.py

现在打开终端，输入pip install apple-fm-sdk，三行代码就能让 Apple Intelligence 在你的 Mac 上开始生成文本——数据全程留在本地，隐私与速度兼得。🚀