AnyLanguageModel 结构化输出攻略：@Generable 宏让 AI 返回类型安全数据

AnyLanguageModel 结构化输出攻略Generable 宏让 AI 返回类型安全数据【免费下载链接】AnyLanguageModelAn API-compatible, drop-in replacement for Apples Foundation Models framework with support for custom language model providers.项目地址: https://gitcode.com/gh_mirrors/an/AnyLanguageModel在开发 AI 应用时最让人头疼的问题之一就是大模型返回的是自由文本而你的代码需要的是类型安全数据。AnyLanguageModel 是一个 API 兼容的 Swift 框架可作为 Apple Foundation Models 框架的即插即用替代品它内置的Generable 宏能把让 AI 返回结构化数据这件事变得像声明一个 Swift 结构体一样简单。本文将带你从零掌握 AnyLanguageModel 结构化输出告别手写 JSON 解析的痛苦。为什么需要结构化输出传统做法是让模型返回一段 JSON 字符串然后你手动JSONDecoder解码再小心翼翼地处理字段缺失、类型错误。这套流程的问题很明显格式不稳定模型偶尔多一个逗号、少一个引号解析直接崩溃字段名漂移说好的user_name变成了username约束不可控说好的数字范围 0~100它给你返回 9999大量胶水代码定义模型、写解析、写校验重复劳动而**结构化输出Structured Output**直接把约束写死在生成过程中模型在输出时就必须符合你定义的 schema从根本上杜绝了解析失败。AnyLanguageModel 是什么AnyLanguageModel 是一个开源 Swift 包定位是Apple Foundation Models 框架的 drop-in 替代品——你只需把import FoundationModels换成import AnyLanguageModel就能获得几乎一致的 API同时支持接入更多模型提供商类型提供商本地模型Core ML、MLX、llama.cpp (GGUF)、Ollama云端模型OpenAI、Open Responses、Anthropic Claude、Google Gemini系统模型Apple 系统语言模型核心的结构化输出能力由三部分组成全部开源在项目源码中Generable.swift定义Generable协议与Generable宏GenerableMacro.swift宏的实际实现自动生成 schema 与转换代码StructuredGeneration.swift本地模型的约束式 JSON 生成引擎Generable 宏入门三步拿到类型安全数据 ✅第一步声明一个结构体在任意struct或enum上打上Generable框架会自动为你生成 schema、初始化器和双向转换代码Generable(description: 猫咪的基本资料) struct CatProfile { var name: String Guide(description: 猫咪的年龄, .range(0...20)) var age: Int Guide(description: 用一句话描述猫咪的性格) var profile: String }第二步发起结构化输出请求通过respond(generating:)指定目标类型模型就会严格按结构返回let session LanguageModelSession(model: model) let response try await session.respond( to: 生成一只可爱的领养猫咪, generating: CatProfile.self )第三步直接使用强类型结果拿到手的response.content已经是完整的CatProfile实例字段直接访问无需任何手动解析print(response.content.name) // Mochi print(response.content.age) // 3 print(response.content.profile) // 一只喜欢晒太阳的橘猫整个过程零解析代码、零类型转换、零运行时崩溃风险这就是Generable 宏让 AI 返回类型安全数据的价值所在。Guide 宏给 AI 立规矩 光有类型还不够你通常还希望约束取值范围。Guide就是干这个的它支持非常丰富的约束实现见GenerationGuide.swift数字范围约束Generable struct GameCharacter { Guide(description: 角色名字, .minimum(1)) var level: Int Guide(description: 角色星级, .range(1...5)) var star: Int Guide(description: 血量百分比, .range(0.0...100.0)) var health: Double }数组数量约束Generable struct QuizQuestion { Guide(description: 题目内容) var text: String Guide(.count(4)) // 恰好 4 个选项 var choices: [String] Guide(.count(2...5)) // 或 2 到 5 个标签 var tags: [String] }枚举约束枚举也可以直接Generable模型只能在给定 case 中挑选天然适合状态、优先级等场景Generable enum Priority: Equatable { case low case medium case high }测试代码里就有现成的枚举与嵌套结构示例见StructuredGenerationFixtures.swift。实战让天气工具拥有结构化参数 ️把结构化输出和工具调用Tool Calling结合是 AI 应用中最高频的玩法。AnyLanguageModel 官方 README 的示例非常典型struct WeatherTool: Tool { let name getWeather let description 获取某个城市的最新天气信息 Generable struct Arguments { Guide(description: 要查询天气的城市) var city: String } func call(arguments: Arguments) async throws - String { \(arguments.city) 的天气是晴天72°F / 23°C } } let session LanguageModelSession(model: model, tools: [WeatherTool()]) let response try await session.respond { Prompt(Cupertino 的天气怎么样) }模型会自动生成符合Arguments结构的工具调用参数你的call方法拿到的arguments就是类型安全的Arguments实例安全、直观、零解析。高级技巧流式输出与嵌套结构 ⚡PartiallyGenerated流式结构化输出Generable会自动为结构体生成一个PartiallyGenerated类型支持流式生成过程中拿到半成品数据。所有属性都是可选值生成到哪一步就能读到哪一步非常适合做实时 UI 展示。嵌套结构体结构体可以任意嵌套schema 会自动递归构建$defs引用机制例如人 → 地址这种层级结构完全没问题Generable struct StructuredPerson { Guide(description: 姓名) var name: String Guide(description: 年龄) var age: Int var address: Address // 另一个 Generable 结构体 }底层原理如果你好奇宏到底生成了什么可以查看GenerableMacro.swift——它自动合成成员初始化器、init(_ generatedContent:)、generationSchema、generatedContent等一整套代码。生成后的 schema 是标准的 JSON Schema见GenerationSchema.swift云端模型直接用 schema 约束输出本地模型Core ML、MLX、llama.cpp则走约束式 token 采样见StructuredGeneration.swift。快速上手安装与运行 ️在Package.swift中加入依赖即可dependencies: [ .package(url: https://gitcode.com/gh_mirrors/an/AnyLanguageModel, from: 0.8.0) ]也可以直接克隆体验git clone https://gitcode.com/gh_mirrors/an/AnyLanguageModel运行测试验证一切正常swift test常见问题 FAQ QGenerable 支持哪些类型A基础类型 String、Int、Double、Float、Bool、Decimal以及数组、字典、可选值、枚举和任意嵌套结构体都支持。Q云端模型也支持结构化输出吗A支持。OpenAI、Open Responses、Anthropic 和 Gemini 都会把生成的 schema 传给服务端实现真正的输出约束。Q字段解析失败怎么办A得益于生成阶段的约束失败概率极低结构体初始化器是throws的万一失败你可以捕获错误并重试。总结 AnyLanguageModel 的Generable Guide组合把AI 结构化输出从繁琐的 JSON 解析工作流变成了纯粹的 Swift 类型声明体验。无论是本地跑 MLX / llama.cpp还是接 OpenAI / Claude / Gemini你都用同一套类型安全 API。如果你想彻底告别解析 AI 返回的字符串这就是终极方案——快去试试吧【免费下载链接】AnyLanguageModelAn API-compatible, drop-in replacement for Apples Foundation Models framework with support for custom language model providers.项目地址: https://gitcode.com/gh_mirrors/an/AnyLanguageModel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考