fm CLI と Python SDK で AI 搭載スクリプトを作る

ハイライト

macOS 27 では fm コマンドラインツールと Foundation Models Python SDK が追加され、開発者は端末や Python 環境から Apple のデバイス上モデルとクラウドモデルを API キーなしで直接呼び出せます。自動化スクリプトやモデル評価に利用できます。

主要内容

WWDC25 で Apple は Foundation Models Framework（基盤モデルフレームワーク）を発表し、Swift 開発者が app 内でデバイス上の Apple Foundation Model を呼び出せるようにしました。このフレームワークは、構造化データを出力する Guided Generation と、モデルが app のコンテキストとやり取りする Tool Calling をサポートします。

macOS 27 と iOS 27 は、このフレームワークに新機能をもたらします。prompt に画像を渡せるようになり、サーバー側モデルにもアクセスできるため、app は同じ Swift API で任意の大規模言語モデルを呼び出せます。

しかし今年までは、これらのモデルは Swift コードからしか呼び出せませんでした。機械学習エンジニアやデータサイエンティストにとって、Python はより一般的な作業言語です。また、単に prompt を素早く試したいだけのときに、Xcode を開いてプロジェクトを再コンパイルしたくない場合もあります。

Apple は今年、fm コマンドラインツールと Foundation Models Python SDK という 2 つの新しい選択肢を提供しました。

fm コマンドラインツールは macOS 27 にプリインストールされ、Terminal で直接 prompt を試したり、自動化スクリプトに組み込んだりできます。Python SDK は Python コードからデバイス上モデルを呼び出せるようにし、同時にツール呼び出しと guided generation というフレームワークの中核機能もサポートします。Python には豊かな機械学習とデータサイエンスのエコシステムがあるため、Python SDK を使えば評価 pipeline を書き、モデル出力の品質を定量化できます。

詳細

fm コマンドラインツール (03:23)

fm コマンドラインツールは macOS 27 から Mac にプリインストールされています。Terminal を開いて fm と入力すると、利用できるコマンドが表示されます。

• respond: モデルへ prompt を送り、応答を返す
• chat: インタラクティブな対話インターフェイスを起動する
• schema: 出力構造の定義を作成する

$ fm respond "Swift でメールアドレスを解析する基本的な正規表現を提示してください"
# Swift でメールアドレスを解析する基本的な正規表現はこちらです: [...]

ポイント: fm respond はモデルの応答を直接出力するため、スクリプト内での利用に向いています。

インタラクティブな対話

fm chat は ChatGPT のような端末上の対話インターフェイスを提供します。

$ fm chat
> [ユーザーが最初の質問を入力]
> [モデルが回答]
> [ユーザーが追加質問を入力]
> [モデルが回答]

対話インターフェイスにはいくつかの組み込みコマンドがあります。

• /model: Private Cloud Compute モデルへ切り替える
• /save: 現在の会話を保存し、後で再開できるようにする

ポイント: fm chat は新しいアイデアを探索しながら prompt を素早く試すのに向いており、プロジェクトを再コンパイルする必要はありません。

構造化出力

fm は schema による出力構造の定義をサポートします。

$ fm schema object --name AppsIdentified --string app_names --array > schema.json

$ fm respond "このスクリーンショットでユーザーが実際に使っているアプリは何ですか？" \
    --image Screenshot.png --model pcc --schema schema.json
# {"app_names": ["Messages", "Mail", "Calendar"]}

ポイント:

• fm schema object は JSON schema 定義を作成します。
• --image で画像を渡し、視覚理解を行います。
• --model pcc は Private Cloud Compute の大規模モデルを使います。
• --schema は出力形式を JSON に制約します。

ファイル分類の自動化スクリプト (05:58)

講演では、プロジェクトフォルダ内の下書きファイルと最終ファイルを整理する実用例が示されました。

# 出力構造を定義する schema を作成する
fm schema object --name "TriagedFileList" \
    --string 'final_files' --array \
    --string 'draft_files' --array > /tmp/schema.json

# モデルでファイル一覧を分類する
output=$(fm respond \
    --instructions "プロジェクトを完了したので、以前のバージョンから最新バージョンのファイルを仕分けする手助けが必要です。ファイル一覧を渡します。一覧の名前から最新バージョンだと推測できるファイルを latest files として返し、final と見なされなかったすべての draft files を別に返してください。" \
    "すべてのファイル一覧です:\n\n${files_list}" \
    --schema /tmp/schema.json
)

# 最終ファイルをバックアップディレクトリへ移動する
echo "${output}" | jq -r '.final_files[]' | while read -r file; do
    cp "${DIRECTORY_TO_TRIAGE}/${file}" "${FINAL_FILES_STORAGE_DIRECTORY}"
done

# 下書きファイルをアーカイブディレクトリへ移動する
echo "${output}" | jq -r '.draft_files[]' | while read -r file; do
    mv "${DIRECTORY_TO_TRIAGE}/${file}" "${DRAFT_FILES_STORAGE_DIRECTORY}"
done

ポイント:

• --instructions は system prompt を設定し、モデルにタスク背景を伝えます。
• ファイル一覧を渡してモデルに分析させます。
• jq で JSON 出力を解析し、ファイル操作を実行します。
• ファイル名が規則的でなくても処理でき、スクリプトは繰り返し利用できます。

Foundation Models Python SDK (08:52)

Python SDK により、開発者は Python コードから Apple Foundation Models を呼び出せます。インストール要件は次のとおりです。

• Python 3.10 以上
• Apple Silicon Mac
• Xcode がインストール済み

pip install apple_fm_sdk

基本的な使い方 (09:57)

Python SDK の API は Swift 版と非常によく似ています。

import apple_fm_sdk as fm

INSTRUCTIONS = "あなたはアプリ内注文機能を持つ食料品店 Cupertino Mart の AI アシスタントです。"

async def answer_question(prompt: str) -> str:
    session = fm.LanguageModelSession(instructions=INSTRUCTIONS)
    return await session.respond(prompt)

ポイント:

• LanguageModelSession はモデルセッションを作成します。
• instructions 引数は system prompt を設定します。
• respond() はユーザー prompt を受け取る非同期メソッドです。

ツール呼び出し (10:21)

Swift 版と同じく、Python SDK もツール呼び出しをサポートします。

class GetPastOrdersTool(fm.Tool):
    name = "get_past_orders"
    description = "このユーザーの過去の注文に関する情報を取得します。"

    @fm.generable("過去注文の問い合わせパラメータ")
    class Arguments:
        number_orders: str = fm.guide("直近の注文を何件取得するか")

    @property
    def arguments_schema(self) -> fm.GenerationSchema:
        return self.Arguments.generation_schema()

    async def call(self, args: fm.GeneratedContent) -> str:
        number_orders = args.value(int, for_property="number_orders")
        return await Orders.load_last_orders(user_id=user_id, amount=number_orders)

ポイント:

• fm.Tool を継承してツールを定義します。
• @fm.generable デコレータは引数構造を示します。
• fm.guide() は各引数に説明を追加します。
• arguments_schema プロパティは引数 schema を返します。
• call() メソッドはモデルがツールを呼び出したときに実行されます。

Guided generation (10:35)

Guided generation により、モデルは構造化された Python オブジェクトを出力できます。

@fm.generable("提案アイテム")
class ItemsSuggestion:
    item_names: list[str] = fm.guide("提案するアイテム名")

INSTRUCTIONS = "あなたは、ユーザーが関心を持ちそうな食料品候補を返す AI アシスタントです。"

async def generate_suggested_cart_items(user_input: Optional[str]) -> ItemsSuggestion:
    session = fm.LanguageModelSession(instructions=INSTRUCTIONS, tools=load_tools())
    prompt = """ツールを使ってユーザーの過去の注文を読み込み、\
              ユーザーがすでに注文したことがあり、\
              新しい食料品注文を準備している今、再び関心を持ちそうなアイテム一覧を返してください。"""
    if user_input is not None:
        prompt += f"\nユーザーからの次の要望も考慮してください: {user_input}"
    return await session.respond(prompt, generating=ItemsSuggestion)

ポイント:

• @fm.generable デコレータは出力構造を定義します。
• fm.guide() は各フィールドに説明を追加します。
• respond() の generating 引数は出力型を指定します。
• 戻り値は型安全な Python オブジェクトです。

Python 評価 pipeline (10:59)

Python SDK の大きな利点は、Python エコシステムと深く統合できることです。講演では Jupyter Notebook で完全な評価 pipeline を構築する方法が示されました。

場面: 食料品 EC app 向けに、ユーザーの過去注文に基づいて買いたい商品を予測する「スマート補充」機能を開発します。異なる prompt の効果を評価する必要があります。

評価フロー:

1. 大規模モデルで評価データ（入力と期待出力）を生成する
2. 異なる prompt で複数バージョンを実装する
3. 評価データセット上で各バージョンを実行し、出力を収集する
4. judge モデルで各出力を採点する
5. Pandas でデータを保存し、Matplotlib で結果を可視化する

講演では 3 種類の prompt 戦略が比較されました。

• 最小 prompt: 基本指示だけを与える
• 詳細 prompt: タスクを詳しく説明する
• 包括 prompt: 完全なルール一覧を列挙する

評価で分かったこと:

• 詳細 prompt はモデルのコンテキストウィンドウ上限に達しやすく、エラー率が高くなる
• 最小 prompt と詳細 prompt は商品を多く勧めすぎる傾向がある
• 包括 prompt は期待商品をより多く見落とす
• 最小 prompt は幻覚商品をより多く生む

ポイント: Pandas、Matplotlib などの Python 機械学習エコシステムは Foundation Models SDK と滑らかに統合でき、prompt を素早く反復し、効果を定量化できます。

重要な示唆

1. ローカルファイル分類アシスタントを構築する

何を作るか: fm CLI でダウンロードフォルダを自動整理するスクリプトを書きます。schema で分類結果の出力を定義し、find と mv を組み合わせて自動アーカイブします。

なぜ価値があるか: ダウンロードフォルダが散らかるのは普遍的な問題で、手作業の整理は時間がかかり、見落としも起きやすいものです。fm CLI は API キー不要で macOS 27 にプリインストールされ、専用分類モデルを学習するよりずっと簡単に shell スクリプトで知的分類を実現できます。

始め方: fm schema object で出力構造を定義します。たとえば final_files と draft_files の 2 つの配列です。その後 fm respond --schema にファイル一覧を渡して分類させ、jq で JSON 出力を解析してファイル操作を実行します。入口: fm schema object + fm respond --schema。

2. CLI 副操縦士を開発する

何を作るか: Python SDK でコマンドラインアシスタントを構築し、自然言語の指示を理解して対応する shell コマンドを実行できるようにします。

なぜ価値があるか: 開発者は複雑なコマンド引数を思い出せないことがよくあり、意図を自然言語で説明する方がドキュメントを探すより速い場合があります。ツール呼び出しでモデルを事前定義した安全なコマンド集合に制限すれば、誤操作を避けられます。

始め方: Python SDK の fm.Tool 基底クラスを継承して実行可能なコマンドを定義し、fm.generable で引数構造を定義します。LanguageModelSession 作成時に tools リストを渡します。入口: fm.Tool + fm.generable + LanguageModelSession(tools=...)。

3. prompt 評価ワークベンチを作る

何を作るか: Jupyter Notebook と Python SDK で prompt 実験室を構築します。AI 機能向けに複数の prompt バージョンを設計し、自動評価で最適案を見つけます。

なぜ価値があるか: prompt 調整は反復的な試行錯誤です。定量評価がなければ感覚に頼るしかありません。Python エコシステムの Pandas、Matplotlib と Foundation Models SDK を組み合わせれば、異なる prompt 戦略の効果差を素早く比較できます。

始め方: apple_fm_sdk をインストールし、Jupyter Notebook 内で複数の prompt バージョンを定義します。同じテストデータで実行し、judge モデルで出力を採点し、最後に Pandas で集計して Matplotlib で可視化します。入口: pip install apple_fm_sdk + fm.LanguageModelSession。

4. 画像分析 pipeline を構築する

何を作るか: fm の画像理解能力を使ってスクリーンショットを一括処理し、構造化情報を抽出します。たとえばプロダクトモックアップから UI コンポーネント一覧を抽出します。

なぜ価値があるか: 大量のデザイン稿やスクリーンショットを手作業で確認するのは退屈で、細部を見落としがちです。fm CLI は --image 引数で画像を渡せ、--schema で出力形式を制約することで、非構造の画像情報を処理可能なデータへ変換できます。

始め方: fm schema object で抽出したいフィールド（コンポーネント種別、位置、文言など）を定義します。その後 fm respond --image Screenshot.png --schema schema.json でスクリーンショットを一括処理し、構造化 JSON を出力します。入口: fm respond --image + --schema。

5. データクリーニングツールを開発する

何を作るか: Python SDK でスクリプトを書き、モデルにデータセット内の異常値を認識、修正させます。schema でクリーニング後のデータと変更ログを出力します。

なぜ価値があるか: データクリーニングはデータサイエンティストの時間を大きく占めます。形式不一致や明らかに誤った値など、多くの異常パターンはルールで網羅しにくいものです。モデルはコンテキストを理解し、「住所フィールドに電話番号が入っている」のような意味レベルの異常を見つけられます。

始め方: @fm.generable でクリーニング結果の出力構造を定義します。クリーニング後データと変更ログの 2 つのフィールドを含めます。データセットを読み込み、バッチごとにモデルへ渡し、結果を集約して書き出します。入口: @fm.generable + session.respond(prompt, generating=CleanResult)。

関連 Session

• Core AI - Foundation Models フレームワークの中核 API の紹介
• Core AI integration - Swift アプリに Foundation Models を統合する
• Core AI optimization - モデルの性能とコストを最適化する
• Evaluations - Xcode の Evaluations フレームワークで AI 機能をテストする
• Robust evaluations - 信頼できる評価体系を構築する