Arthur-Ficial/apfel

apfel – 面向 Apple Silicon 的本地运行 LLM

是什么 – apfel 是一个基于 Swift 的命令行工具，封装了 Apple Silicon Mac 上自带的 Apple 提供的 Foundation Models LLM。它允许你从终端查询模型，或运行一个本地 OpenAI 兼容的 HTTP 服务器，使现有的 SDK（Python、Node 等）无需任何云密钥即可与本地模型通信。

主要功能

• 纯本地推理 – 使用内置的 SystemLanguageModel；无需 API 密钥，无网络流量。
• 两种使用模式 – 管道友好的 CLI（apfel "prompt"，apfel -f file …）和即插即用的 OpenAI 服务器（apfel --serve 监听 http://localhost:11434/v1）。
• 工具调用 / MCP – 可调用本地或远程 Model Context Protocol (MCP) 工具，内置计算器示例。
• 丰富的输出选项 – 文本、JSON（-o json）、模式验证的 JSON、流式输出、退出码信号、文件附件处理（文本、PDF、图像，macOS 27 支持 OCR/视觉）。
• 聊天 REPL – apfel --chat 用于交互式会话。
• 无配置 – 所有行为由标志或环境变量控制；可选包装器 apfel-run 提供 TOML 配置支持。

典型工作流

1. 安装 – brew install apfel（或使用 Swift 6.3 从源码构建）。
2. 运行提示 – apfel "Summarise this repo" 或管道文件：cat README.md | apfel。
3. 在脚本中使用 – JSON 输出用于自动化：apfel -o json "Translate to German: hello" | jq .content。
4. 本地服务 – apfel --serve 并将任何 OpenAI 客户端指向 http://localhost:11434/v1。
5. 添加工具 – apfel --mcp ./mcp/calculator/server.py "What is 15×27?"。

限制

• 仅在搭载 macOS 26（Tahoe）或更高版本的 Apple Silicon Mac 上运行；模型大小固定（约 3B 参数）。
• macOS 26 / M1–M2 上上下文窗口为 4096 个标记，macOS 27 且 M3+ 12GB 时为 8192 个标记。
• 无嵌入功能，无大规模并行加速；响应需数秒。
• 安全机制可能阻止某些提示；使用 --permissive 可放宽限制。
• 视觉支持（图像理解）仅在 macOS 27 上可用。

适用人群

• 希望在不支付云服务费用的情况下，为本地脚本、CI 流水线或原型开发快速、私密 LLM 的开发者。
• 已使用 OpenAI 兼容 SDK 并希望在 Mac 工作站上即插即用本地后端的团队。
• 喜欢以 shell 为中心的 AI 助手并希望使用 MCP 实现工具调用的高级用户。

了解更多

• 完整安装指南：docs/install.md。
• CLI 标志参考：docs/cli-reference.md。
• OpenAI 兼容性详情：docs/openai-api-compatibility.md。
• MCP 工具示例：docs/mcp-calculator.md 和捆绑的 demo/ 文件夹。
• 示例提示：docs/EXAMPLES.md。

总结 – apfel 将 Apple 提供的本地 LLM 转换为多功能的 Unix 工具和本地 OpenAI 兼容服务器，使 macOS 上无需外部 API 即可实现以隐私为先的 AI 工作流。