使用 fm CLI 和 Python SDK 构建 AI 驱动的脚本

一句话判断

Apple 终于把大模型能力从 Swift 围墙里放出来了，fm CLI 和 Python SDK 让 Mac 变成了原生自带大模型的自动化神器。

这场 Session 讲了什么

以前想用 Apple Foundation Models，你得老老实实建个 Xcode 工程写 Swift。现在 macOS 27 直接预装了 fm 命令行工具，还发布了 apple_fm_sdk Python 包。这俩工具把大模型能力直接塞进了终端和 Jupyter Notebook。

你可以用 fm respond 结合 shell 脚本批量重命名文件、分类草稿，或者用 Python SDK 结合 Pandas 跑几百条数据的 Prompt 评估流水线。这对不想碰 Swift 的 ML 工程师和喜欢写 shell 脚本的 Mac 重度用户来说，绝对是生产力解放。Apple 算是明白了，搞 AI 评估和自动化，Python 和 CLI 才是统治区。

值得深挖的点

把大模型变成 Unix 哲学里的标准管道

Apple 这次对 fm CLI 的设计非常 Unix。fm respond 接收文本或图片，吐出文本或 JSON。结合 fm schema object 定义结构，它就成了一个完美的管道（pipe）组件。官方演示的用 shell 脚本整理文件夹就是典型场景：把 ls 的结果喂给 fm，让它输出 JSON，再用 bash 解析移动文件。

这种设计的 trade-off 很明显。好处是脚本写起来极简，不用管服务生命周期，随调随用；坑在于它不是常驻 Agent，如果是高频小请求，每次调用的冷启动延迟会很难受。另外，Private Cloud Compute (PCC) 模型在 CLI 里调用有严格的速率限制，别指望拿它当免费的无限 API 薅羊毛，老老实实用 on-device 模型跑本地任务。

补齐 Apple Intelligence 的评估短板

搞过 LLM 应用的都知道，写 Prompt 只是一时爽，做 Eval（评估）才是火葬场。以前在 Swift 生态里做大规模数据评估非常痛苦，缺乏好用的数据处理库。现在 Python SDK 镜像了 Swift 的核心 API（如 Tool Calling 和 Guided Generation），ML 工程师可以直接在 Jupyter 里用 Pandas 加载数据集，跑 on-device 模型生成结果，再调 PCC 模型做 Judge（裁判）打分，最后用 matplotlib 画图。

这个决策极其聪明，Apple 不需要自己去造一套评估框架，直接借力 Python 生态。但你要清楚它的边界：这个 SDK 强绑定 Apple Silicon 和 macOS 环境，你没法把它打包到 Docker 里部署到 Linux 服务器上跑 CI/CD。它只能作为本地开发、研究和原型验证的工具，最终的生产代码还是得乖乖写回 Swift。

代码片段

1. 用 Shell 脚本和 fm 结构化输出分类文件

场景：在终端里写个自动化脚本，让大模型帮你把一堆混乱的文件按“最终版”和“草稿”分类，并输出 JSON 供脚本后续处理。

# 定义 JSON 输出的 Schema
fm schema object --name "TriagedFileList" \
    --string 'final_files' --array \
    --string 'draft_files' --array > /tmp/schema.json

# 调用 fm respond 获取结构化结果
output=$(fm respond \
    --instructions "我会给你一个文件列表。请返回最终版文件列表和草稿文件列表。" \
    --schema /tmp/schema.json \
    "这是文件列表:\n\n${file_list}")

# 解析 JSON 并移动文件 (假设有 jq 工具)
echo "$output" | jq -r '.draft_files[]' | xargs -I {} mv {} ./archive/

坑：fm respond 默认走 on-device 模型，如果文件列表特别长或者逻辑特别复杂，记得加 --model pcc 切换到云端大模型，但要注意 PCC 的调用频率限制。

2. Python SDK 定义 Tool 和 Guided Generation

场景：用 Python 写个 grocery app 的原型，让模型调用 Tool 获取历史订单，并严格输出指定结构的推荐商品列表。

import apple_fm_sdk as fm

# 定义模型可以调用的工具
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:
        num = args.value(int, for_property="number_orders")
        return await Orders.load_last_orders(user_id="123", amount=num)

# 定义严格的结构化输出
@fm.generable("推荐商品")
class ItemsSuggestion:
    item_names: list[str] = fm.guide("推荐商品的名称列表")

async def generate_suggested_cart_items():
    session = fm.LanguageModelSession(
        instructions="你是一个生鲜超市助手，根据历史订单推荐商品。", 
        tools=[GetPastOrdersTool()]
    )
    # 强制模型输出 ItemsSuggestion 结构
    result = await session.respond(
        "帮我推荐一下下次可能想买的东西", 
        generating=ItemsSuggestion
    )
    return result.content.item_names

坑：@fm.generable 装饰器虽然好用，但 Python 的类型提示在运行时不如 Swift 严格，如果模型幻觉严重，解析 result.content 时可能会抛出属性错误，记得加 try-catch。

最佳实践

别急着把现有 App 里的 AI 逻辑迁到 Python。Python SDK 的定位是离线评估和原型验证，生产环境的 iOS/macOS App 还是得用 Swift 原生的 Foundation Models Framework。

新项目强烈建议用 fm CLI 接管 Mac 上的本地自动化任务，比如写个 cron job 每天自动总结下载文件夹里的 PDF，或者根据截图内容自动归档图片。

做 Prompt 迭代时，把 Python SDK 和 Jupyter 结合起来，建立一套包含 on-device 生成和 PCC 打分的自动化 Eval 流水线，用数据指导 Prompt 调优，而不是靠拍脑袋。

还有什么值得关注

多模态 CLI：fm respond 支持 --image 参数，你可以直接在终端里传截图让大模型分析，写批量处理 UI 截图的脚本会非常爽。
会话持久化：fm chat 提供了 /save 命令，可以把当前的对话上下文保存下来，下次打开终端接着聊，适合长线思考的复杂任务。
无缝切换模型：在 Python 和 CLI 中，都可以无缝在 on-device 和 Private Cloud Compute 模型之间切换，方便对比小模型和大模型的效果差异。