FoundationModels: デバイス上の LLM（iOS 18）

Apple のデバイス上言語モデルをアプリケーションに統合するためのパターン。テキスト生成、@Generable を使用した構造化出力、カスタムツール呼び出し、スナップショットストリーミングをカバーしています — すべてデバイス上で実行され、プライバシーを保護し、オフライン使用をサポートします。

いつ使用するか

• Apple Intelligence を使用してデバイス上で AI 機能を構築する
• クラウドに依存せずにテキストを生成または要約する
• 自然言語入力から構造化データを抽出する
• 特定領域の AI 操作のためにカスタムツール呼び出しを実装する
• リアルタイム UI 更新のために構造化レスポンスをストリーミングする
• プライバシーが重要な AI（データがデバイスを離れない）

コアパターン — 利用可能性チェック

セッションを作成する前に、常にモデルの利用可能性を確認します：

struct GenerativeView: View {
    private var model = SystemLanguageModel.default

    var body: some View {
        switch model.availability {
        case .available:
            ContentView()
        case .unavailable(.deviceNotEligible):
            Text("Device not eligible for Apple Intelligence")
        case .unavailable(.appleIntelligenceNotEnabled):
            Text("Please enable Apple Intelligence in Settings")
        case .unavailable(.modelNotReady):
            Text("Model is downloading or not ready")
        case .unavailable(let other):
            Text("Model unavailable: \(other)")
        }
    }
}

コアパターン — 基本的なセッション

// Single-turn: create a new session each time
let session = LanguageModelSession()
let response = try await session.respond(to: "What's a good month to visit Paris?")
print(response.content)

// Multi-turn: reuse session for conversation context
let session = LanguageModelSession(instructions: """
    You are a cooking assistant.
    Provide recipe suggestions based on ingredients.
    Keep suggestions brief and practical.
    """)

let first = try await session.respond(to: "I have chicken and rice")
let followUp = try await session.respond(to: "What about a vegetarian option?")

指示のキーポイント：

• モデルのロールを定義する（「あなたはメンターです」）
• 何をすべきかを指定する（「カレンダーイベントの抽出を支援する」）
• スタイル設定を指定する（「可能な限り簡潔に答える」）
• セーフガードを追加する（「危険なリクエストについては、『お力になれません』と返信」）

コアパターン — @Generable を使用したガイド付き生成

生の文字列ではなく、構造化された Swift 型を生成します：

1. Generable 型を定義する

@Generable(description: "Basic profile information about a cat")
struct CatProfile {
    var name: String

    @Guide(description: "The age of the cat", .range(0...20))
    var age: Int

    @Guide(description: "A one sentence profile about the cat's personality")
    var profile: String
}

2. 構造化出力をリクエストする

let response = try await session.respond(
    to: "Generate a cute rescue cat",
    generating: CatProfile.self
)

// Access structured fields directly
print("Name: \(response.content.name)")
print("Age: \(response.content.age)")
print("Profile: \(response.content.profile)")

サポートされている @Guide 制約

• .range(0...20) — 数値範囲
• .count(3) — 配列要素数
• description: — 生成のセマンティックガイド

コアパターン — ツール呼び出し

モデルにカスタムコードを呼び出させて、領域固有のタスクを実行します：

1. ツールを定義する

struct RecipeSearchTool: Tool {
    let name = "recipe_search"
    let description = "Search for recipes matching a given term and return a list of results."

    @Generable
    struct Arguments {
        var searchTerm: String
        var numberOfResults: Int
    }

    func call(arguments: Arguments) async throws -> ToolOutput {
        let recipes = await searchRecipes(
            term: arguments.searchTerm,
            limit: arguments.numberOfResults
        )
        return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
    }
}

2. ツール付きセッションを作成する

let session = LanguageModelSession(tools: [RecipeSearchTool()])
let response = try await session.respond(to: "Find me some pasta recipes")

3. ツールエラーを処理する

do {
    let answer = try await session.respond(to: "Find a recipe for tomato soup.")
} catch let error as LanguageModelSession.ToolCallError {
    print(error.tool.name)
    if case .databaseIsEmpty = error.underlyingError as? RecipeSearchToolError {
        // Handle specific tool error
    }
}

コアパターン — スナップショットストリーミング

PartiallyGenerated 型を使用して、リアルタイム UI のために構造化レスポンスをストリーミングします：

@Generable
struct TripIdeas {
    @Guide(description: "Ideas for upcoming trips")
    var ideas: [String]
}

let stream = session.streamResponse(
    to: "What are some exciting trip ideas?",
    generating: TripIdeas.self
)

for try await partial in stream {
    // partial: TripIdeas.PartiallyGenerated (all properties Optional)
    print(partial)
}

SwiftUI 統合

@State private var partialResult: TripIdeas.PartiallyGenerated?
@State private var errorMessage: String?

var body: some View {
    List {
        ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
            Text(idea)
        }
    }
    .overlay {
        if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
    }
    .task {
        do {
            let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
            for try await partial in stream {
                partialResult = partial
            }
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

主要な設計決定

決定	理由
デバイス上での実行	プライバシー — データがデバイスを離れない；オフラインで動作
4,096 トークン制限	デバイス上モデルの制約；大きなデータをセッション間で分割処理
スナップショットストリーミング（増分ではない）	構造化出力に適している；各スナップショットは完全な部分状態
@Generable マクロ	構造化生成のためのコンパイル時安全性；PartiallyGenerated 型を自動生成
セッションあたり単一リクエスト	isResponding で並行リクエストを防止；必要に応じて複数セッションを作成
response.content（.output ではなく）	正しい API — 常に .content プロパティを通じて結果にアクセス

ベストプラクティス

• セッションを作成する前に常に model.availability をチェックしてください — すべての利用不可のケースを処理
• instructions を使用してモデル動作を導いてください — プロンプトより優先される
• 新しいリクエストを送信する前に**isResponding をチェック**してください — セッションは一度に 1 つのリクエストを処理
• response.content を通じて結果にアクセスしてください — .output ではなく
• 大きな入力を分割処理してください — 4,096 トークン制限は指示、プロンプト、出力の合計に適用
• 構造化出力に**@Generable を使用**してください — 生の文字列の解析よりも強力な保証を提供
• GenerationOptions(temperature:) を使用して創造性を調整してください（値が高いほどより創造的）
• Instruments を使用して監視してください — Xcode Instruments を使用してリクエストパフォーマンスを分析

避けるべきアンチパターン

• model.availability を最初にチェックせずにセッションを作成する
• 4,096 トークンのコンテキストウィンドウを超える入力を送信する
• 単一セッションで並行リクエストを試みる
• .output ではなく .content を使用して応答データにアクセスする
• @Generable 構造化出力が利用可能な場合に生の文字列レスポンスを解析する
• 複雑なマルチステップロジックを単一プロンプトで構築する — 複数のフォーカスされたプロンプトに分割
• モデルが常に利用可能だと想定する — デバイスの適格性と設定は異なります

使用するケース

• プライバシー重視のアプリ向けのデバイス上テキスト生成
• ユーザー入力（フォーム、自然言語コマンド）から構造化データを抽出
• オフラインで動作する必要がある AI アシスタント機能
• 生成されたコンテンツを段階的に表示するストリーミング UI
• ツール呼び出し（検索、計算、ルックアップ）を通じた領域固有 AI 操作の実行