Back to Details

foundation-models

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Foundation Models

Foundation Models

Apple's on-device AI framework providing access to a 3B parameter language model for summarization, extraction, classification, and content generation. Runs entirely on-device with no network required.
Apple的端侧AI框架，可调用一个30亿参数的语言模型，支持摘要、信息提取、分类和内容生成功能。完全在设备本地运行，无需网络连接。

Overview

概述

Foundation Models enable intelligent text processing directly on device without server round-trips, user data sharing, or network dependencies. The core principle: leverage on-device AI for specific, contained tasks (not for general knowledge).
Foundation Models 可在设备端直接实现智能文本处理，无需与服务器交互、共享用户数据或依赖网络。核心原则：利用端侧AI处理特定、限定范围的任务（而非通用知识类任务）。

Reference Loading Guide

参考文档加载指南

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.
ReferenceLoad When
Getting StartedSetting up LanguageModelSession, checking availability, basic prompts
Structured OutputUsing 
@Generable
for type-safe responses, 
@Guide
constraints
Tool CallingIntegrating external data (weather, contacts, MapKit) via Tool protocol
StreamingAsyncSequence for progressive UI updates, PartiallyGenerated types
TroubleshootingContext overflow, guardrails, errors, anti-patterns
只要有极小概率需要用到相关内容，就务必加载参考文件。 宁可提前准备好上下文，也不要遗漏模式或出现错误。
参考文档加载场景
快速入门设置LanguageModelSession、检查可用性、基础提示词编写
结构化输出使用
@Generable
实现类型安全的响应、
@Guide
约束
工具调用通过Tool协议集成外部数据（天气、联系人、MapKit）
流式输出使用AsyncSequence实现渐进式UI更新、PartiallyGenerated类型
故障排查上下文溢出、安全护栏、错误处理、反模式规避

Core Workflow

核心工作流

  1. Check availability with 
    SystemLanguageModel.default.availability
  2. Create 
    LanguageModelSession
    with optional instructions
  3. Choose output type: plain String or @Generable struct
  4. Use streaming for long generations (>1 second)
  5. Handle errors: context overflow, guardrails, unsupported language
  1. 通过
    SystemLanguageModel.default.availability
    检查可用性
  2. 创建带有可选指令的
    LanguageModelSession
  3. 选择输出类型：普通String或@Generable结构体
  4. 针对生成时间超过1秒的内容使用流式输出
  5. 处理错误：上下文溢出、安全护栏限制、不支持的语言

Model Capabilities

模型能力

Use CaseFoundation Models?Alternative
SummarizationYes-
Extraction (key info)Yes-
ClassificationYes-
Content taggingYes (built-in adapter)-
World knowledgeNoChatGPT, Claude, Gemini
Complex reasoningNoServer LLMs
使用场景是否适用Foundation Models?替代方案
文本摘要是-
关键信息提取是-
文本分类是-
内容打标签是（内置适配器）-
通用知识查询否ChatGPT, Claude, Gemini
复杂推理否云端大语言模型

Platform Requirements

平台要求

  • iOS 26+, macOS 26+, iPadOS 26+, visionOS 26+
  • Apple Intelligence-enabled device (iPhone 15 Pro+, M1+ iPad/Mac)
  • User opted into Apple Intelligence
  • iOS 26+, macOS 26+, iPadOS 26+, visionOS 26+
  • 支持Apple Intelligence的设备（iPhone 15 Pro及以上、M1及以上芯片的iPad/Mac）
  • 用户已开启Apple Intelligence

Common Mistakes

常见错误

  1. Using Foundation Models for world knowledge — The 3B model is trained for on-device tasks only. It won't know current events, specific facts, or "who is X". Use ChatGPT/Claude for that. Keep prompts to: summarizing user's own content, extracting info, classifying text.
  2. Blocking the main thread — LanguageModelSession calls must run on a background thread or async context. Blocking the main thread locks UI. Always use 
    Task { }
    or background queue.
  3. Ignoring context overflow — The model has finite context. If the user pastes a 50KB document, it will fail silently or truncate. Check input length and trim/truncate proactively.
  4. Forgetting to check availability — Not all devices support Foundation Models. Check 
    SystemLanguageModel.default.availability
    before using. Graceful degradation is required.
  5. Ignoring guardrails — The model won't answer harmful queries. Instead of fighting it, design prompts that respect safety guidelines. Rephrasing requests usually works.
  1. 将Foundation Models用于通用知识查询——30亿参数的模型仅针对端侧任务训练，无法知晓当前事件、特定事实或"X是谁"这类信息。这类场景请使用ChatGPT/Claude。请将提示词限定在：总结用户自有内容、提取信息、文本分类。
  2. 阻塞主线程——LanguageModelSession调用必须在后台线程或异步上下文执行。阻塞主线程会导致UI冻结。务必使用
    Task { }
    或后台队列。
  3. 忽略上下文溢出——模型的上下文长度有限。如果用户粘贴了50KB的文档，模型会静默失败或截断内容。请主动检查输入长度并进行修剪/截断。
  4. 忘记检查可用性——并非所有设备都支持Foundation Models。使用前请检查
    SystemLanguageModel.default.availability
    ，并实现优雅降级方案。
  5. 忽略安全护栏——模型不会响应有害请求。不要试图绕过它，而是设计符合安全准则的提示词。通常重新表述请求即可解决问题。