如何在带有macOS伴生应用的Web应用中使用Apple的基础模型
内容提要
本文介绍如何构建Vision Bridge：一个结合React前端与Swift macOS伴生应用的本地AI图像分析工具。它利用Apple Vision进行OCR文字识别，再通过Foundation Models生成摘要、标签等结构化JSON数据，全程在设备端运行，无需云端，保护隐私。文章详细说明了架构、代码实现及运行方法。
延伸解读
架构核心：本地桥接模式
Vision Bridge 的核心思路是：浏览器无法直接调用 Apple 原生框架，因此通过一个本地 Swift 伴生应用作为桥梁，将 React 前端与 Apple Vision、Foundation Models 连接起来。这种模式不仅适用于 AI 功能，任何 Web 平台不暴露的原生能力（如文件系统、硬件访问）都可以通过类似方式实现。理解这一点，有助于你在其他项目中复用此架构。
模型不直接“看”图
Foundation Models 目前不支持直接输入图像，因此本教程将图像交给 Apple Vision 进行 OCR，提取文本、置信度和边界框，再将这些结构化文本作为提示词输入模型。模型基于文本推理，而非原始像素。这种分工发挥了两者优势：Vision 擅长提取机器可读信息，模型擅长生成摘要和标签。但这也意味着模型输出受限于 OCR 的准确性，可能遗漏图像中的非文本信息。
设备端运行的优势与限制
全程在设备端运行，无需云端，保护隐私且无按 token 计费。但依赖 Mac 硬件和系统版本，需支持 Apple Intelligence 且模型可用。伴生应用会检查模型可用性，并在不可用时返回状态信息，前端可据此提示用户。这种本地处理适合敏感数据，但模型能力可能不如云端大模型，且受限于设备性能。
输出数据的层次与用途
返回的 JSON 包含四部分：support 表示能力状态，image 为元数据，vision 是 OCR 的“事实”数据（文本、置信度、归一化边界框），model 是模型生成的“解释”数据（摘要、标签等）。理解这种区分很重要：vision 数据可用于精确的搜索或高亮，而 model 数据适合作为草稿或辅助信息，但需注意其可能继承 OCR 错误。
Q&A
什么是Vision Bridge？
Vision Bridge是一个结合React前端与Swift macOS伴生应用的本地AI图像分析工具。它利用Apple Vision进行OCR文字识别，再通过Foundation Models生成摘要、标签等结构化JSON数据，全程在设备端运行，无需云端，保护隐私。
为什么需要macOS伴生应用？
因为浏览器无法直接使用Apple的Foundation Models框架，而原生macOS应用可以使用任何Apple框架。伴生应用作为本地桥接，使Web应用能够利用原生能力，如Vision和Foundation Models。
Foundation Models如何处理图像？
Foundation Models本身不能直接读取图像，因此Vision Bridge通过Apple Vision提取图像中的文本和元数据，然后将这些结构化文本信息作为提示词输入给Foundation Models，模型基于这些文本生成摘要、标签等，而不是直接处理原始像素。
如何检查Foundation Models的可用性？
伴生应用通过检查SystemLanguageModel.default的availability属性来判断模型是否可用。如果可用，返回foundationModelAvailable为true；如果不可用，会返回具体原因，如appleIntelligenceNotEnabled。
Vision Bridge的API端点有哪些？
伴生应用提供两个端点：GET /v1/health用于健康检查，返回支持状态；POST /v1/analyze-image用于分析图像，接收包含文件名、MIME类型和base64图像数据的JSON，返回分析结果。
如何运行Vision Bridge？
首先启动伴生应用，运行命令npm run companion；然后在另一个终端启动Web应用，运行npm run dev；最后打开Vite提供的URL（通常是http://127.0.0.1:5173）即可使用。
Vision Bridge的响应中包含哪些信息？
响应包含四个部分：support（支持状态）、image（图像元数据）、vision（OCR检测到的文本、置信度和边界框）、model（模型生成的摘要、描述、标签和可能用途）。
如何处理模型返回的JSON解析失败？
即使要求模型返回JSON，也可能出现Markdown代码块或格式错误。示例应用会去除简单的Markdown代码围栏，如果解析失败则回退到原始文本，确保不丢失信息。
