尧图网页设计 
开发者指南如何向coreai-models添加一个新模型——从ModelPreset注册到export.py配方【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-modelscoreai-models 是苹果开源的端侧 AI 工具集包含模型导出配方、Python 基元和 Swift 运行时用于把开源模型转换为 Core AI 格式的.aimodel资产。本文面向新手开发者带你完整走通「向 coreai-models 添加一个新模型」的全流程从在 model_registry.py 中注册ModelPreset到为特殊模型编写独立的 export.py 导出配方每一步都给出关键文件路径和验证命令。先认识仓库结构4个目录决定添加模型的方式添加模型前先了解 models/README.md 中定义的仓库分工目录作用添加模型时的用途models/模型目录README 导出配方放置新模型的 README 与export.py配方python/Python 基元与导出工具注册ModelPreset、架构映射swift/Swift 运行时包通常无需改动直接复用skills/编码智能体技能插件辅助智能体理解 Core AI 规则官方在 models/README.md 的 Adding a Model 章节明确了核心原则标准 LLM / 扩散模型 → 在 model_registry.py 添加一条ModelPreset(...)逻辑特殊、无法走标准流程的模型 → 在models/name/export.py编写独立配方第一步注册 ModelPreset——让短名导出生效读懂 ModelPreset 的字段含义ModelPreset是导出系统的模型身份证定义在 model_registry.pyshort_name短名如qwen3-0.6b用户直接用它触发导出hf_idHugging Face 模型 ID如Qwen/Qwen3-0.6Bfamily/type模型家族与类型llm/diffusionvariant平台变体macOS/iOS扩散模型传Nonecompression压缩预设名如4bit可指向 YAML 配方max_context_length上下文长度上限仅 LLM一个真实条目长这样qwen3-0.6b 的 macOS 预设ModelPreset(qwen3-0.6b, Qwen/Qwen3-0.6B, qwen3, llm, macOS, 4bit, float16, 8192)注册到正确的预设表根据模型类型把新条目放进对应的列表语言模型 →LLM_PRESETS扩散模型 →DIFFUSION_PRESETS独立小模型语音、检测、深度估计等→UTILITY_PRESETS使用更轻量的UtilityModel结构体需额外声明model_type、task和export_script路径 同一个模型支持多个平台变体时注册多条预设即可例如 qwen3-4b 的 macOS 与 iOS 版本 就分别指定了不同的压缩策略。第二步注册模型架构——连接 Python 模型类注册ModelPreset只解决了参数从哪来还要告诉导出管线结构怎么建。这一步在 models/registry.py 完成用 ModelEntry 映射平台模型类ModelEntry定义位置把 Hugging Face 的model_type映射到仓库内重写的 PyTorch 模型类macos_classmacOS 变体使用的模型类动态 KV cacheios_classiOS 变体使用的模型类静态形状hf_config_attr/hf_state_dict_prefix多模态检查点的解包钩子新架构只需在_get_registry()返回的字典中增加一项例如qwen3: ModelEntry( macos_classQwen3ForCausalLM, ios_classQwen3ForCausalLMForiOS, ),模型类本身放在 models/macos/ 或 models/ios/ 下可大量复用 primitives/ 中的 SDPA、RoPE、RMSNorm 等构建块。如果模型config.json里的model_type与仓库内部命名不一致如 SmolLM2 报告为llama可以在 MODEL_TYPE_REMAPPING 中添加重映射或在ModelPreset中设置_model_type_override字段第三步选择压缩方案——预设名还是 YAML 配方内置压缩预设一览压缩预设集中定义在 export/presets.py平台预设名说明macOS4bit默认INT4 权重量化块大小 32macOS4bit_weights_8bit_kv_cacheINT4 权重 INT8 KV cachemacOSfp8_weights_fp8_activations_fp8_kv_cacheFP8 全链路macOS 27.2iOS4bit_weight_palettized_group32默认4-bit 调色板压缩组大小 32iOS4bit_weight_palettized_group84-bit 调色板压缩组大小 8双平台none全精度适合调试完整清单见 MACOS_PRESETS 与 IOS_PRESETS默认值在 第 304-305 行 指定。自定义混合精度YAML 压缩配方内置预设覆盖不了的场景如 6-bit 调色板、混合精度用 YAML 文件描述通过--compression-config传入并把路径写进ModelPreset的compression_config字段。参考 qwen3_1_7b_6bit.yamlkmeans_palettization_config: global_config: op_state_spec: weight: n_bits: 6 granularity: type: per_grouped_channel axis: 0 group_size: 8注意 YAML 顶层键与平台的强绑定kmeans_palettization_config仅限 iOSquantization_config仅限 macOS校验逻辑在 export.py 的_load_compression_config_object。第四步编写独立 export.py 配方特殊模型专用当模型无法走标准coreai.llm.export/coreai.diffusion.export管线时语音、视觉、编码器类模型需要写一个自包含的models/name/export.py。以 whisper/export.py 为标准范本PEP 723 内联依赖声明文件头部用注释块声明脚本级依赖uv run会自动创建隔离环境whisper 的写法# /// script # requires-python 3.11 # dependencies [ # coreai-core1.0.0b3, # coreai-torch0.4.3, # transformers4.57.3, # ] # ///配方脚本的四个必备组件封装模型为 torch.nn.Module—— 把 HF 模型包一层只暴露要导出的forward签名参考WhisperModule构造参考输入—— 生成用于torch.export的示例张量并用dynamic_shapes标记动态维度参考 reference_inputs构建.aimodel元数据—— 作者、许可证、描述见_build_aimodel_metadata支持--include-debug-info标志—— 默认以TorchConverter.Mode.RELEASE转换调试时切换为 DEBUG 模式嵌入完整调试信息配方的参数解析可以参考 coreai.llm.export 的 build_parser它展示了这套仓库惯用的完整参数集--output-dir、--overwrite、--num-layers截断层数调试、--dry-run只打印解析结果不导出等。第五步验证与调试——4条命令确认一切正确添加完成后按以下顺序自测# 1. 确认注册表已收录新模型 uv run coreai.model.registry --list-models --type llm # 2. 查看新模型的预设详情支持 --json / --tsv 输出 uv run coreai.model.registry --model-info my-model --type llm # 3. 生成等价的导出参数检查压缩/精度/上下文是否正确 uv run coreai.model.registry --model-info my-model --type llm --as-export-args # 4. 干跑导出只打印解析后的 ExportConfig 不实际转换 uv run coreai.llm.export my-model --dry-run调试技巧 用--num-layers 1 --compression none只导出 1 层全精度快速定位算子转换问题 数值不对时加--include-debug-info重新导出把图映射回 Python 源码 独立脚本路径uv run models/name/export.py --model hf-id--dry-run打印的配置结构对应 ExportConfig 数据类——这是理解整条导出管线加载 → 压缩 → 变体导出 → 打包的关键入口编排逻辑在 export/pipeline.py 的export_model中。收尾清单模型文档与目录规范最后为新模型补齐三件套models/name/README.md—— 参照 qwen3/README.md支持模型表格、导出命令示例、Swift 集成代码、LLM 还需困惑度评测表models/name/export.py—— 独立模型才需要遵循上文四组件规范目录索引—— 在 models/README.md 的 Model Catalog 对应分类下加入链接完成后新用户就能像使用现有模型一样一行命令完成导出uv run coreai.llm.export my-model # 默认 macOS 变体 uv run coreai.llm.export my-model --platform iOS常见坑速查现象可能原因--model-info查不到新模型ModelPreset加错了表或short_name拼写不一致报Unknown model type未在 models/registry.py 注册架构或缺少MODEL_TYPE_REMAPPING条目YAML 配方报requires --platform iOS/macOS顶层压缩键与平台不匹配iOS 导出报缺--max-context-lengthiOS 要求静态形状上下文长度必须显式指定导出产物过大忘了默认 RELEASE 模式确认没误加--include-debug-info 提示仓库 skills/ 提供了模型编写的经验规则算子兼容性、KV cache 模式、精度规则为编码智能体准备的参考资料同样适合人类开发者查阅遇到转换失败时优先检索其中的常见问题分析。掌握「注册ModelPreset→ 映射模型类 → 选定压缩配方 → 可选编写export.py→ 五条命令验证」这条主线你就能把任何新的开源模型接入 coreai-models 的端侧 AI 生态了。【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 开发者指南：如何向coreai-models添加一个新模型——从ModelPreset注册到export.py配方
开发者指南如何向coreai-models添加一个新模型——从ModelPreset注册到export.py配方【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-modelscoreai-models 是苹果开源的端侧 AI 工具集包含模型导出配方、Python 基元和 Swift 运行时用于把开源模型转换为 Core AI 格式的.aimodel资产。本文面向新手开发者带你完整走通「向 coreai-models 添加一个新模型」的全流程从在 model_registry.py 中注册ModelPreset到为特殊模型编写独立的 export.py 导出配方每一步都给出关键文件路径和验证命令。先认识仓库结构4个目录决定添加模型的方式添加模型前先了解 models/README.md 中定义的仓库分工目录作用添加模型时的用途models/模型目录README 导出配方放置新模型的 README 与export.py配方python/Python 基元与导出工具注册ModelPreset、架构映射swift/Swift 运行时包通常无需改动直接复用skills/编码智能体技能插件辅助智能体理解 Core AI 规则官方在 models/README.md 的 Adding a Model 章节明确了核心原则标准 LLM / 扩散模型 → 在 model_registry.py 添加一条ModelPreset(...)逻辑特殊、无法走标准流程的模型 → 在models/name/export.py编写独立配方第一步注册 ModelPreset——让短名导出生效读懂 ModelPreset 的字段含义ModelPreset是导出系统的模型身份证定义在 model_registry.pyshort_name短名如qwen3-0.6b用户直接用它触发导出hf_idHugging Face 模型 ID如Qwen/Qwen3-0.6Bfamily/type模型家族与类型llm/diffusionvariant平台变体macOS/iOS扩散模型传Nonecompression压缩预设名如4bit可指向 YAML 配方max_context_length上下文长度上限仅 LLM一个真实条目长这样qwen3-0.6b 的 macOS 预设ModelPreset(qwen3-0.6b, Qwen/Qwen3-0.6B, qwen3, llm, macOS, 4bit, float16, 8192)注册到正确的预设表根据模型类型把新条目放进对应的列表语言模型 →LLM_PRESETS扩散模型 →DIFFUSION_PRESETS独立小模型语音、检测、深度估计等→UTILITY_PRESETS使用更轻量的UtilityModel结构体需额外声明model_type、task和export_script路径 同一个模型支持多个平台变体时注册多条预设即可例如 qwen3-4b 的 macOS 与 iOS 版本 就分别指定了不同的压缩策略。第二步注册模型架构——连接 Python 模型类注册ModelPreset只解决了参数从哪来还要告诉导出管线结构怎么建。这一步在 models/registry.py 完成用 ModelEntry 映射平台模型类ModelEntry定义位置把 Hugging Face 的model_type映射到仓库内重写的 PyTorch 模型类macos_classmacOS 变体使用的模型类动态 KV cacheios_classiOS 变体使用的模型类静态形状hf_config_attr/hf_state_dict_prefix多模态检查点的解包钩子新架构只需在_get_registry()返回的字典中增加一项例如qwen3: ModelEntry( macos_classQwen3ForCausalLM, ios_classQwen3ForCausalLMForiOS, ),模型类本身放在 models/macos/ 或 models/ios/ 下可大量复用 primitives/ 中的 SDPA、RoPE、RMSNorm 等构建块。如果模型config.json里的model_type与仓库内部命名不一致如 SmolLM2 报告为llama可以在 MODEL_TYPE_REMAPPING 中添加重映射或在ModelPreset中设置_model_type_override字段第三步选择压缩方案——预设名还是 YAML 配方内置压缩预设一览压缩预设集中定义在 export/presets.py平台预设名说明macOS4bit默认INT4 权重量化块大小 32macOS4bit_weights_8bit_kv_cacheINT4 权重 INT8 KV cachemacOSfp8_weights_fp8_activations_fp8_kv_cacheFP8 全链路macOS 27.2iOS4bit_weight_palettized_group32默认4-bit 调色板压缩组大小 32iOS4bit_weight_palettized_group84-bit 调色板压缩组大小 8双平台none全精度适合调试完整清单见 MACOS_PRESETS 与 IOS_PRESETS默认值在 第 304-305 行 指定。自定义混合精度YAML 压缩配方内置预设覆盖不了的场景如 6-bit 调色板、混合精度用 YAML 文件描述通过--compression-config传入并把路径写进ModelPreset的compression_config字段。参考 qwen3_1_7b_6bit.yamlkmeans_palettization_config: global_config: op_state_spec: weight: n_bits: 6 granularity: type: per_grouped_channel axis: 0 group_size: 8注意 YAML 顶层键与平台的强绑定kmeans_palettization_config仅限 iOSquantization_config仅限 macOS校验逻辑在 export.py 的_load_compression_config_object。第四步编写独立 export.py 配方特殊模型专用当模型无法走标准coreai.llm.export/coreai.diffusion.export管线时语音、视觉、编码器类模型需要写一个自包含的models/name/export.py。以 whisper/export.py 为标准范本PEP 723 内联依赖声明文件头部用注释块声明脚本级依赖uv run会自动创建隔离环境whisper 的写法# /// script # requires-python 3.11 # dependencies [ # coreai-core1.0.0b3, # coreai-torch0.4.3, # transformers4.57.3, # ] # ///配方脚本的四个必备组件封装模型为 torch.nn.Module—— 把 HF 模型包一层只暴露要导出的forward签名参考WhisperModule构造参考输入—— 生成用于torch.export的示例张量并用dynamic_shapes标记动态维度参考 reference_inputs构建.aimodel元数据—— 作者、许可证、描述见_build_aimodel_metadata支持--include-debug-info标志—— 默认以TorchConverter.Mode.RELEASE转换调试时切换为 DEBUG 模式嵌入完整调试信息配方的参数解析可以参考 coreai.llm.export 的 build_parser它展示了这套仓库惯用的完整参数集--output-dir、--overwrite、--num-layers截断层数调试、--dry-run只打印解析结果不导出等。第五步验证与调试——4条命令确认一切正确添加完成后按以下顺序自测# 1. 确认注册表已收录新模型 uv run coreai.model.registry --list-models --type llm # 2. 查看新模型的预设详情支持 --json / --tsv 输出 uv run coreai.model.registry --model-info my-model --type llm # 3. 生成等价的导出参数检查压缩/精度/上下文是否正确 uv run coreai.model.registry --model-info my-model --type llm --as-export-args # 4. 干跑导出只打印解析后的 ExportConfig 不实际转换 uv run coreai.llm.export my-model --dry-run调试技巧 用--num-layers 1 --compression none只导出 1 层全精度快速定位算子转换问题 数值不对时加--include-debug-info重新导出把图映射回 Python 源码 独立脚本路径uv run models/name/export.py --model hf-id--dry-run打印的配置结构对应 ExportConfig 数据类——这是理解整条导出管线加载 → 压缩 → 变体导出 → 打包的关键入口编排逻辑在 export/pipeline.py 的export_model中。收尾清单模型文档与目录规范最后为新模型补齐三件套models/name/README.md—— 参照 qwen3/README.md支持模型表格、导出命令示例、Swift 集成代码、LLM 还需困惑度评测表models/name/export.py—— 独立模型才需要遵循上文四组件规范目录索引—— 在 models/README.md 的 Model Catalog 对应分类下加入链接完成后新用户就能像使用现有模型一样一行命令完成导出uv run coreai.llm.export my-model # 默认 macOS 变体 uv run coreai.llm.export my-model --platform iOS常见坑速查现象可能原因--model-info查不到新模型ModelPreset加错了表或short_name拼写不一致报Unknown model type未在 models/registry.py 注册架构或缺少MODEL_TYPE_REMAPPING条目YAML 配方报requires --platform iOS/macOS顶层压缩键与平台不匹配iOS 导出报缺--max-context-lengthiOS 要求静态形状上下文长度必须显式指定导出产物过大忘了默认 RELEASE 模式确认没误加--include-debug-info 提示仓库 skills/ 提供了模型编写的经验规则算子兼容性、KV cache 模式、精度规则为编码智能体准备的参考资料同样适合人类开发者查阅遇到转换失败时优先检索其中的常见问题分析。掌握「注册ModelPreset→ 映射模型类 → 选定压缩配方 → 可选编写export.py→ 五条命令验证」这条主线你就能把任何新的开源模型接入 coreai-models 的端侧 AI 生态了。【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考