Foundation Models 不可用怎么办？2026 排查指南

先读取 SystemLanguageModel 的 availability，再按不可用原因决定是提示设置、提供替代功能，还是允许稍后重试；生成阶段的资产错误还要单独捕获。本周先补齐状态记录和降级分支，再用目标设备验收；模拟器运行或构建通过，都不能代替目标设备上的模型运行测试。Apple 也建议先检查模型可用性，并为不可用状态准备回退体验。(Foundation Models 使用指南)

这篇指南适合正在为 iOS App 接入 Apple Foundation Models、却遇到模型不可用的独立开发者。
维护 macOS App、需要兼容不同系统版本和模型状态的开发者，也可以按相同的排查逻辑检查。
负责测试或发布验收、需要确认降级路径的小团队，可以直接使用文中的检查清单。

提醒： availability 表示读取时的状态，不是对下一次生成请求的成功保证。用户可能在检查后关闭 Apple Intelligence，模型资产也可能在生成阶段不可用；因此，状态判断与错误捕获必须分别存在。

排查前先记录系统版本、设备型号、设备与 Siri 语言、Apple Intelligence 设置、availability 的完整结果，以及触发操作。这样能把“AI 无法使用”拆成可复现的症状，避免把设置、设备资格、资产状态和 App 代码混成一个问题。

SystemLanguageModel.default.availability 的检查结果，可先按下表分流。状态名称来自 Apple API 文档；具体 API 是否可用以及错误类型如何处理，应结合 App 的目标系统版本复核。(availability 状态定义)

排查时不要只保存 isAvailable 的布尔值。布尔结果可以快速控制界面，但具体的 availability 分支能告诉开发者为什么不可用；对于支持这些状态的部署目标，日志应保留实际原因，而不是统一记成“模型关闭”。(不可用原因枚举)

deviceNotEligible 表示设备不支持 Apple Intelligence，不是提示用户去开启某个开关。应先对照 Apple 当前支持信息确认设备资格；支持范围可能随 Apple 的产品与系统说明更新，发布前应复核官方页面，而不要把某个团队手边设备的结果推断成全部用户的兼容结论。(Apple Intelligence 设备与系统要求)

另外，设备资格与 App 的最低部署版本是两项不同检查。前者回答“这台设备能否使用系统模型”，后者回答“这个 App 能否安装或运行在该系统版本”；调高部署目标不会让不符合条件的设备获得模型资格。

替代功能要对应用户原本要完成的任务，而不是只显示“当前设备不支持 AI”。例如，若生成式功能用于改写文本，可保留手动编辑；若用于提取内容，可让用户继续查看原文或用既有筛选条件完成操作。Apple 的设计指南也建议在生成式功能不可用或用户不使用时，尽可能提供非 AI 回退。(生成式 AI 设计指南)

若 availability 指向 Apple Intelligence 未启用，说明这是用户的系统设置状态，不应误判为设备不支持。App 可以解释开启后可能获得什么功能，并提供前往系统设置的指引；但不能声称 App 能替用户开启系统功能，也不应将启用设为使用核心功能的前提。

若状态是 modelNotReady，可让用户稍后重试，同时继续使用不依赖模型的功能。Apple 说明模型会自动下载，下载过程会受网络状态、电量和系统负载等因素影响；所以适合表达“模型尚未准备好，请稍后再试”，不适合承诺一个固定等待时间。(modelNotReady 说明)

实现上，重试应是明确的用户操作，或有上限的自动恢复流程。每次重试前重新读取 availability；若状态未改变，就返回可用的替代路径，而不是在界面后台无限循环请求。这样可以避免把暂时性状态变成耗电、无提示、无法退出的等待体验。

当状态显示 .available，但 respond 一类生成调用仍失败时，检查范围应转到会话与请求本身。记录触发操作、输入类型、系统版本、调用时的状态和捕获到的错误类型；不要仅凭一次状态检查就断定框架故障，也不要把所有异常都映射成“模型不可用”。

assetsUnavailable 与 availability 阶段的 modelNotReady 不是同一个观察点：前者是生成调用期间所需资产不可用，后者是调用前检查到模型尚未就绪。新旧系统版本的错误 API 也可能不同。Apple 文档说明，在目标为 iOS 26 或 macOS 26 的应用中，相关新错误类型不可用时，需要使用可用性判断并兼容旧的 LanguageModelSession.GenerationError.assetsUnavailable 分支；发布前要按目标系统版本核对处理方式。(新资产错误说明) (旧生成错误说明)

还要检查 App 自己的会话调用逻辑。例如，同一个 LanguageModelSession 在上一请求仍运行时又收到第二个请求，可能触发并发请求错误；此时应控制调用节奏或检查 isResponding，而不是把它误判成设备资格问题。(会话请求与状态说明)

如果错误日志包含用户输入或生成内容，应先评估隐私影响，只保存排查所需的信息；通常错误类别、系统版本和不含个人内容的复现步骤，比完整保存提示词与回复更适合用于线上问题定位。

仅用一份当前 SDK 编译成功，不能证明所有部署目标都走同一错误处理路径。Apple 的错误文档指出，旧错误类型已经弃用；使用 Xcode 26 构建的应用会继续捕获旧类型，而要捕获新的错误类型则需要使用 Xcode 27 重新构建后提交。因此，维护多个版本分支时，应同时核对编译 SDK、部署目标和运行设备系统，而不是只看工程设置中的一个版本号。(生成错误类型及 Xcode 迁移说明)

具体实现可以把错误处理收敛到一个适配层：新系统分支识别新错误类型，兼容分支识别旧类型，其余错误则进入通用诊断路径。对外界面不必暴露 API 名称，但研发日志应能区分是模型资产不可用、用户设置变化，还是会话代码错误。

发布验收要测试的不只是“模型能生成一次”，还要验证不同状态下用户是否仍能完成主要任务。每种状态都应有对应的界面、可操作的下一步和记录方式；如果无法提供替代体验，也要明确说明受限功能，而不是让按钮无响应。

✅ 发布前可勾选清单

• [ ] 在支持且模型可用的目标设备上，验证功能入口、请求、结果展示和失败提示。
• [ ] 验证 deviceNotEligible 时，模型专属操作退出，但核心非 AI 流程仍可使用。
• [ ] 验证 Apple Intelligence 未启用时，提示由用户自行选择是否前往系统设置。
• [ ] 验证 modelNotReady 时，等待与重试可退出，替代操作不被遮挡。
• [ ] 模拟或捕获生成阶段 assetsUnavailable，确认错误提示、日志和恢复路径都有效。
• [ ] 验证连续点击或并发触发不会把会话错误显示成设备不支持。
• [ ] 按实际部署目标复核 Xcode SDK、API 可用性判断和旧错误兼容分支。
• [ ] 将模拟器与构建结果记为代码路径验证，不将其标注为目标设备模型运行验收。

远程 Mac 可以承担 Xcode 工程构建、依赖检查和代码分支复核，但这些工作只能证明相应的构建或代码路径结果，不能证明模型已在受支持 iPhone 上运行。设备上的模型行为，仍需由真实目标设备测试并保留可核验证据。若项目需要独立的远程 Mac 构建环境，可以先查看 JEXCLOUD 的远程 Mac 方案；这类环境适合补足 macOS 工具链，不应替代设备验收。

deviceNotEligible 是不是 Apple Intelligence 没开启？
不是。先核对设备资格；设置提示只适用于对应的未启用状态。若设备确实不受支持，就提供不依赖模型的替代体验。

Apple Intelligence 已经开启，为什么模型还不可用？
开启状态不等于模型资产已就绪。重新读取 availability，区分 modelNotReady 与生成调用失败，再按对应分支处理。

模型尚未就绪，可以一直重试吗？
不建议无限重试。提供可退出的稍后重试，同时让用户继续使用替代流程；每次发起请求前重新检查状态。

生成运行时出现 assetsUnavailable，和 modelNotReady 有什么不同？
前者发生在生成阶段，后者是 availability 检查返回的未就绪原因。两者应分别记录、捕获，并按目标系统版本适配错误处理。

如果排查结果指向代码分支或构建环境，租用远程 Mac 可以补足本地缺少的 macOS 与 Xcode 工具链；它避免专门购置一台 Mac，也便于按需使用，但仍有网络访问、远程交互和环境管理成本，而且不能完成目标 iPhone 的模型运行验收。若你需要临时构建或复核代码路径，可以查看 JEXCLOUD 的 Mac 租用选项；若项目长期高频构建、必须接入本地物理设备，或需要真实 iPhone 持续测试，自购设备或本地 Mac 可能更合适。本文最后更新于 2026 年 11 月 1 日，排查结论核对自 Apple Foundation Models、availability 与错误类型文档及 Apple Intelligence 支持说明；Apple 文档或支持范围更新后，应重新复核目标系统版本对应的处理方式。

• 远程构建与真实设备测试：iOS 验收时需要注意什么
• Xcode Cloud 与云端 Mac CI：如何选择混合构建方案