jev 兼容
内容提要
介绍为 laya-coreml 模型封装类型安全 API：用 Pydantic 定义布尔判断与多分类的输入输出结构，封装本地推理客户端，在 Apple Silicon 上约 5 毫秒完成推理；再用 FastAPI 包装为 HTTP 服务并自动生成 OpenAPI 文档，供前端生成类型安全的请求代码。默认模型限 96 token，长文本需换用支持 1024 token 的版本。
延伸解读
类型安全封装的实际价值
文章用 Pydantic 定义输入输出结构，把模型返回的概率锁死在明确类型里。这样做的好处是：IDE 能实时提示字段，参数不匹配时在运行前就会报错，减少调试成本。对于布尔判断和多分类任务，这种强类型约束让前端和后端对接更可靠，尤其适合需要稳定接口的工程场景。
本地推理的性能与硬件门槛
模型在 Apple Silicon 的神经引擎上运行，M3/M4 上单次推理约 5 毫秒。但前提是必须使用 Apple Silicon Mac 且系统为 macOS 15 及以上。这意味着该方案目前只适合苹果生态的本地部署，其他平台无法直接受益。低延迟特性适合对响应速度敏感的交互式应用。
96 token 限制与长文本替代方案
默认模型为追求加速，总 token 预算限制在 96 以内，包括输入文本和指令。如果输入过长，模型会抛出容量错误。文章建议改用支持 1024 token 的通用版本。实际使用时需要预估文本长度，或提前做截断处理，否则请求会失败。
HTTP 服务化与前端类型生成
用 FastAPI 包装后，服务自动生成 OpenAPI 文档，前端可基于 openapi.json 用工具生成 TypeScript 请求代码，实现端到端的类型安全。模型在服务启动时加载为单例，避免重复初始化。这种模式适合将本地模型能力以标准 HTTP 接口暴露给其他系统调用。
Q&A
laya-coreml 模型在 Apple Silicon 上的推理速度有多快？
在 M3/M4 等 Apple Silicon 芯片上，laya-coreml 模型利用 Neural Engine 进行本地推理，单次推理仅需约 5 毫秒。
如何为 laya-coreml 模型定义类型安全的输入输出结构？
可以使用 Pydantic 定义强类型 Schema，例如 BooleanQuestion 和 ChoiceQuestion 分别对应布尔判断和多分类，再通过 InferenceRequest 和 InferenceResponse 封装请求与响应，确保类型安全。
laya-coreml 默认模型的 token 限制是多少？输入过长怎么办？
默认模型 aac6fef/laya-coreml 的总 token 预算限制为 96（包括文本和指令）。如果输入超过此限制，会抛出容量错误，此时应改用支持 1024 token 的通用版本 aac6fef/laya-multilingual-coreml。
如何将 laya-coreml 封装成 HTTP API 服务？
可以使用 FastAPI 封装。定义 Pydantic 请求/响应模型，在 lifespan 中加载模型单例，创建 POST 路由 /ai/run 执行推理，并自动生成 OpenAPI 文档。
封装成 HTTP API 后，前端如何生成类型安全的请求代码？
FastAPI 会自动生成 OpenAPI 文档（如 /docs 页面），前端可以下载 openapi.json，并使用 openapi-typescript 等工具生成完全类型安全的 TypeScript 请求代码。
laya-coreml 模型支持哪些类型的决策任务？
模型原生支持布尔判断（noul）和多分类选择（choice），通过定义相应的 Pydantic 模型（如 BooleanQuestion 和 ChoiceQuestion）来指定任务类型和选项。
