apple-foundation-models

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Operating Rules

操作规则

Consult
```
references/_index.md
```
at the start of every task to navigate the framework's capabilities.
Always check model availability (
```
SystemLanguageModel.default.availability
```
) before attempting to initialize a session; gracefully handle unsupported hardware or missing downloads.
Strictly adhere to Swift 6 concurrency rules:
```
LanguageModelSession
```
must be explicitly isolated (
```
@State
```
,
```
@MainActor
```
, or
```
actor
```
), and
```
Tool
```
conformances must be
```
Sendable
```
.
Respect the strict 4 096-token context limit per session; design proactive recovery strategies for long conversations.
Prefer
```
@Generable
```
for structured output instead of asking the model to write raw JSON.
Never use the model for real-time data retrieval without injecting
```
Tool
```
capabilities, and avoid using it for complex mathematical reasoning or authoritative world-knowledge.
Focus on hardware performance: use
```
prewarm()
```
intelligently during idle time to minimize first-token latency.

每项任务开始时，请查阅
```
references/_index.md
```
以了解框架的功能范围。
在尝试初始化会话前，务必检查模型可用性（
```
SystemLanguageModel.default.availability
```
）；优雅处理不支持的硬件或缺失的下载情况。
严格遵守Swift 6并发规则：
```
LanguageModelSession
```
必须显式隔离（使用
```
@State
```
、
```
@MainActor
```
或
```
actor
```
），且
```
Tool
```
协议实现必须符合
```
Sendable
```
要求。
遵守每个会话严格的4096-token上下文限制；为长对话设计主动恢复策略。
对于结构化输出，优先使用
```
@Generable
```
而非要求模型生成原始JSON。
若未注入
```
Tool
```
能力，切勿使用模型进行实时数据检索；避免将其用于复杂数学推理或权威世界知识查询。
关注硬件性能：在空闲时段智能调用
```
prewarm()
```
以最小化首token延迟。

Task Workflow

任务工作流

Review existing AI integration code

评审现有AI集成代码

Read the code under review and identify which topics apply.
Flag any missing availability checks before
```
LanguageModelSession
```
instantiation.
Validate that
```
.exceededContextWindowSize
```
is explicitly caught and handled.
Ensure
```
LanguageModelSession
```
is not declared locally inside a function or
```
Task
```
(which breaks statefulness).
Check
```
Tool
```
implementations to ensure errors are propagated (
```
throws
```
) and not silenced with
```
try?
```
.

阅读待评审代码并确定适用的主题。
标记
```
LanguageModelSession
```
实例化前缺失的可用性检查。
验证是否显式捕获并处理
```
.exceededContextWindowSize
```
错误。
确保
```
LanguageModelSession
```
未在函数或
```
Task
```
内部本地声明（这会破坏状态性）。
检查
```
Tool
```
实现，确保错误被传播（使用
```
throws
```
）而非通过
```
try?
```
静默处理。

Implement new Foundation Models feature

实现新的Foundation Models功能

Determine the correct model adapter:
```
.default
```
for conversational prose,
```
.contentTagging
```
for classification/extraction.
Design data flow: choose between monolithic
```
respond(to:)
```
or real-time
```
streamResponse(to:)
```
.
Define
```
@Generable
```
structs for structured data extraction, utilizing
```
@Guide
```
to strictly constrain output token by token.
Build instructions safely, keeping them developer-controlled and strictly separated from user input.

确定正确的模型适配器：
```
.default
```
用于对话式文本，
```
.contentTagging
```
用于分类/提取任务。
设计数据流：选择整体式
```
respond(to:)
```
或实时
```
streamResponse(to:)
```
。
为结构化数据提取定义
```
@Generable
```
结构体，利用
```
@Guide
```
逐token严格约束输出。
安全构建指令，确保指令由开发者控制，并与用户输入严格分离。

Implement Tool Calling

实现工具调用

Define the
```
Tool
```
protocol conformance, ensuring a clear, concise
```
description
```
for the model.
Define
```
Arguments
```
using
```
@Generable
```
types.
Implement the
```
call(arguments:)
```
method, ensuring network calls or database queries are properly awaited and errors are correctly thrown back to the model.

定义
```
Tool
```
协议实现，为模型提供清晰简洁的
```
description
```
。
使用
```
@Generable
```
类型定义
```
Arguments
```
。
实现
```
call(arguments:)
```
方法，确保网络调用或数据库查询被正确等待，且错误被正确抛回给模型。

Topic Router

主题路由

Consult the reference file for each topic relevant to the current task:

Topic	Reference
Core Models & Availability	`references/system-language-model.md`
Session & Transcript Lifecycle	`references/session-lifecycle.md`
Structured Output & `@Generable`	`references/guided-generation.md`
Expanding capabilities ( `Tool` )	`references/tool-calling.md`
Temperature & Token Limits	`references/generation-options.md`
Real-time UI & Streams	`references/streaming.md`
Context Overflow & Fallbacks	`references/error-handling.md`
Actor Isolation & Sendable	`references/concurrency.md`
Memory, Prewarming & Optimization	`references/performance.md`
Framework Terminology	`references/glossary.md`

针对当前任务的相关主题，查阅对应的参考文件：

主题	参考文件
核心模型与可用性	`references/system-language-model.md`
会话与记录生命周期	`references/session-lifecycle.md`
结构化输出与 `@Generable`	`references/guided-generation.md`
扩展能力（ `Tool` ）	`references/tool-calling.md`
温度与Token限制	`references/generation-options.md`
实时UI与流处理	`references/streaming.md`
上下文溢出与回退	`references/error-handling.md`
Actor隔离与Sendable	`references/concurrency.md`
内存、预加载与优化	`references/performance.md`
框架术语	`references/glossary.md`

Correctness Checklist

正确性检查清单

These are hard rules — violations will cause runtime crashes, deadlocks, or broken state:

SystemLanguageModel.default.availability

is checked before creating any session.

```
LanguageModelSession
```
is explicitly owned by
```
@State
```
or an
```
actor
```
(never instantiated locally inside a function).

LanguageModelSession.GenerationError.exceededContextWindowSize

is explicitly caught in all

do/catch

blocks interacting with the session.

A session is never reused after throwing an
```
.exceededContextWindowSize
```
error (a fresh instance must be created).
```
prewarm()
```
is called during idle time (e.g., view
```
.task
```
), never immediately preceding a
```
respond(to:)
```
call.
Errors inside
```
Tool.call(arguments:)
```
are explicitly thrown and never silenced with
```
try?
```
.
Instructions strings are strictly hardcoded or developer-controlled, never built directly from user input.
```
@Generable
```
properties are ordered logically top-to-bottom, with summary/dependent properties placed last.
```
PartiallyGenerated
```
types are never instantiated manually, only consumed from
```
streamResponse
```
.

以下为硬性规则——违反将导致运行时崩溃、死锁或状态损坏：

创建任何会话前必须检查

SystemLanguageModel.default.availability

。

```
LanguageModelSession
```
必须由
```
@State
```
或
```
actor
```
显式持有（绝不能在函数内部本地实例化）。

在所有与会话交互的

do/catch

块中，必须显式捕获

LanguageModelSession.GenerationError.exceededContextWindowSize

错误。

会话抛出
```
.exceededContextWindowSize
```
错误后绝不能复用，必须创建新实例。
```
prewarm()
```
需在空闲时段调用（例如视图的
```
.task
```
），绝不能在
```
respond(to:)
```
调用前立即执行。
```
Tool.call(arguments:)
```
内部的错误必须显式抛出，绝不能通过
```
try?
```
静默处理。
指令字符串必须严格硬编码或由开发者控制，绝不能直接从用户输入构建。
```
@Generable
```
属性需按逻辑从上到下排序，汇总/依赖属性放在最后。
```
PartiallyGenerated
```
类型绝不能手动实例化，只能从
```
streamResponse
```
中获取。

References

参考文件

```
references/_index.md
```
— Read first for quick navigation. Index of all documentation.
```
references/system-language-model.md
```
— Availability states, adapter types (
```
.default
```
,
```
.contentTagging
```
), and hardware requirements.
```
references/session-lifecycle.md
```
— Initialization, system instructions, transcript management, and statefulness.
```
references/guided-generation.md
```
—
```
@Generable
```
macros,
```
@Guide
```
token constraints, and dynamic schema building.

references/tool-calling.md

—

Tool

protocol design,

Sendable

conformance, and

ToolExecutionDelegate

```
references/generation-options.md
```
— Temperature tuning,
```
.greedy
```
vs
```
.random
```
sampling, and response token capping.

references/streaming.md

—

streamResponse(to:)

logic,

PartiallyGenerated

handling for SwiftUI incremental updates.

```
references/error-handling.md
```
— Mandatory recovery strategies for context overflow and unsupported locales.
```
references/concurrency.md
```
— Strict Swift 6 isolation invariants,
```
@MainActor
```
UI patterns, and cross-actor session usage.
```
references/performance.md
```
— KV-cache limits, 4096-token budgets, 1.2 GB RAM footprint, and latency reduction via
```
prewarm()
```
.
```
references/glossary.md
```
— Canonical definitions for terms like "LoRA", "adapter", and "transcript".

```
references/_index.md
```
— 首先阅读以快速导航。所有文档的索引。
```
references/system-language-model.md
```
— 可用性状态、适配器类型（
```
.default
```
、
```
.contentTagging
```
）及硬件要求。
```
references/session-lifecycle.md
```
— 初始化、系统指令、记录管理及状态性。

references/guided-generation.md

—

@Generable

宏、

@Guide

token约束及动态架构构建。

references/tool-calling.md

—

Tool

协议设计、

Sendable

一致性及

ToolExecutionDelegate

。

```
references/generation-options.md
```
— 温度调优、
```
.greedy
```
与
```
.random
```
采样对比及响应token上限设置。

references/streaming.md

—

streamResponse(to:)

逻辑、SwiftUI增量更新的

PartiallyGenerated

处理。

```
references/error-handling.md
```
— 上下文溢出和不支持区域设置的强制恢复策略。
```
references/concurrency.md
```
— Swift 6严格隔离不变量、
```
@MainActor
```
UI模式及跨actor会话使用。
```
references/performance.md
```
— KV缓存限制、4096-token预算、1.2 GB内存占用及通过
```
prewarm()
```
降低延迟。
```
references/glossary.md
```
— 术语的标准定义，如"LoRA"、"adapter"和"transcript"。