拓冰网站定制 
导出失败别慌coreai-models 调试工具箱完整指南——include-debug-info、剥离调试信息与 PSNR 数值校验【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-modelscoreai-models 是一套面向 Apple 平台端侧 AI 的模型导出工具集提供导出配方export recipes、Python 原语和 Swift 运行时工具把 PyTorch 模型转换为 Core AI.aimodel格式。当导出失败、数值对不上或产物体积异常时include-debug-info开关、调试信息剥离和 PSNR 数值校验就是三件最实用的调试利器。本文将从零讲清它们的用法帮你在 10 分钟内定位并解决导出问题。1️⃣ 准备工作获取 coreai-models 仓库如需本地运行导出命令先克隆仓库git clone https://gitcode.com/gh_mirrors/co/coreai-models导出前建议先确认支持哪些模型uv run coreai.model.registry --list-models --type llm整体目录结构可以参考仓库主文档 models/README.md各模型家族的导出配方位于models/名称/export.py。2️⃣ 理解导出默认行为为什么你的 .aimodel 信息很少coreai-models 所有导出路径默认使用转换器的RELEASE模式只嵌入最少量调试信息让产出的.aimodel体积最小——这正是发布时想要的状态。这一默认值由全仓库共享的常量锁定常量定义python/src/coreai_models/_constants.py 中的DEFAULT_INCLUDE_DEBUG_INFO False配置落点python/src/coreai_models/export/pipeline.py 中ExportConfig的include_debug_info字段也就是说默认导出 RELEASE 模式 最小调试信息。理解了这一点才能判断调试信息缺失到底是异常还是预期。3️⃣ 一键开启使用 include-debug-info 定位导出失败什么时候该加 --include-debug-info遇到以下三类问题时值得重新导出一份带完整调试信息的资产症状说明❓ 数值不对输出与 PyTorch 参考结果偏差大但说不清哪层出的错 算子降级失败某个 op 无法被 Core AI 降低lowering️ 需要回溯源码要把计算图节点映射回 Python 源码--include-debug-info会让转换器切换到DEBUG模式把完整调试信息嵌入.aimodeluv run coreai.llm.export Qwen/Qwen3-0.6B --include-debug-info全平台统一所有导出入口都支持该开关这个标志不是某个脚本的私货而是贯穿整个工具箱的统一契约coreai.llm.export语言模型coreai.vlm.export视觉-语言模型coreai.diffusion.export扩散模型coreai.segmentation.export图像/视频分割以及每个独立的 models/名称/export.py 配方例如uv run models/whisper/export.py --include-debug-info独立配方如 models/whisper/export.py通过uv run直接执行无需额外安装依赖PEP 723 内联依赖。一个容易踩的坑--verbose 不是调试信息⚠️--include-debug-info与--verbose/-v完全独立。-v只提高控制台日志级别不会改变.aimodel资产里嵌入的任何内容。想看控制台细节用-v想给资产加调试信息必须用--include-debug-info。仓库如何保证每个入口行为一致测试文件 python/tests/test_model_units/test_export/test_include_debug_info.py 对每一条导出路径做了契约检查锁定全仓库默认值必须为FalseRELEASE 模式参数化检查ExportConfig与DiffusionExportConfig是否继承共享常量扫描全部独立models/*/export.py配方确保它们都声明了--include-debug-info且默认 RELEASE 模式并禁止裸构造TorchConverter()那会静默继承库的 DEBUG 默认值4️⃣ 调试完别忘瘦身不重新导出原地剥离调试信息诊断完成后你通常不想带着完整的 DEBUG 信息把资产发出去。好消息是不需要重新导出。models/README.md给出了原地剥离的标准流程models/README.mdfrom coreai.authoring import AIModelAsset from coreai_torch.debugging.debug_info import strip_debug_info source AIModelAsset.load(inputModel.aimodel) metadata source.metadata author, license_, description ( metadata.author, metadata.license, metadata.model_description ) program source.program strip_debug_info(program) # 原地修改 program program.save_asset(Path(outputModel.aimodel))最容易翻车的细节save_asset()只会持久化creationDate、assetVersion和producer三项元数据。如果不把author、license、description重新挂回去发布出去的资产会静默丢失署名和许可证信息AIModelAsset.load(outputModel.aimodel).update_metadata( lambda m: ( setattr(m, author, author), setattr(m, license, license_), setattr(m, model_description, description), ) )剥离后的outputModel.aimodel携带的调试信息量与默认RELEASE导出的产物一致。5️⃣ 数值对不上用 PSNR 定位精度问题PSNR 是什么、仓库怎么算PSNR峰值信噪比单位 dB是 coreai-models 校验模型转换数值正确性的核心指标值越高压缩/转换后的输出与 fp16 参考输出越接近。仓库内置了可直接复用的度量脚本 skills/skills/model-compression-exploration/scripts/quality_metrics.py除了psnr还提供指标适用场景psnr/snr连续输出logits、特征图iou二值/阈值化输出分割掩码、检测热力图判定基准什么 PSNR 算过skills/skills/model-authoring/SKILL.md 给出了清晰的验证门槛建议对照着判断自己的导出结果对比场景门槛含义重写模型 vs 源模型PyTorch 70 dB实现正确Neural Engine 布局 vs GPU 布局 70 dB布局转换正确编译后 vs PyTorch≥ 40 dB编译精度fp16 优化4-bit 调色板压缩后≥ 35 dB压缩可接受压缩位数与 PSNR 的对应关系8-bit 通常 55 dB低于 50 dB 要警惕4-bit 约 40 dB低于 35 dB 要排查2-bit 仅 25–35 dB一般不建议发布。常见 PSNR 异常速查表这些症状→原因→修复来自仓库沉淀的排障手册 skills/skills/model-authoring/references/common_issues.mdPSNR 症状常见原因修复方向SDPA 只有 ~15–30 dB因果掩码方向反了(1, query, 1, key)转置掩码或改用create_ane_causal_mask()M-RoPE 只有 ~18 dBGPU 的 M-RoPE 模式未精确复刻对齐torch.cat([cos, cos])后按::2索引20–30 dB激活函数选错SiLU/QuickGELU/GELU 混用先打印源模型激活函数的type()数值整体错乱张量不连续Neural Engine 按连续内存读取所有张量在包装NDArray前调用.contiguous() 特别注意跨布局直接比较裸张量得到的 PSNR 没有意义先做对应的布局变换再比较。Swift 端也有对应校验导出后的 Swift 运行时同样内置了数值校验工具例如语音识别的对照测试 swift/Sources/Tools/speech-recognizer/SpeechParity.swift 和图像分割的image-segmenterCLI内含 PSNR 比较参数swift/Sources/Tools/image-segmenter/ImageSegmentationRunnerMain.swift。在设备上验证与 Python 侧参考输出的偏差时可以直接使用。6️⃣ 实战排查流程四步走把三件工具串起来形成标准排查链路 复现默认导出失败或输出异常先用-v观察控制台日志记住它不改资产内容 取证加--include-debug-info重新导出用调试信息定位到具体算子/图层 定量用 PSNR/SNR/IoU 对照上面两张表判断是编译精度问题、布局问题还是压缩过头✂️ 收尾问题解决后用strip_debug_info原地剥离调试信息并重新挂回元数据产出最小体积的发布版.aimodel总结coreai-models 的调试工具箱围绕一个朴素原则设计默认产物面向发布RELEASE 最小调试信息诊断时随时可切换诊断后随时可剥离。记住三个要点即可应付绝大多数导出问题--include-debug-info全平台通用且与-v互不干扰剥离调试信息无需重新导出但务必回挂 author/license/description 元数据拿不准数值对不对时用 PSNR 门槛表对照 70 dB 看实现≥ 40 dB 看编译≥ 35 dB 看 4-bit 压缩更多模型细节可继续查看对应模型卡片例如 models/qwen3/README.md 与 models/whisper/README.md压缩探索的完整方法论见 skills/skills/model-compression-exploration/SKILL.md。【免费下载链接】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 调试工具箱完整指南——include-debug-info、剥离调试信息与 PSNR 数值校验
导出失败别慌coreai-models 调试工具箱完整指南——include-debug-info、剥离调试信息与 PSNR 数值校验【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-modelscoreai-models 是一套面向 Apple 平台端侧 AI 的模型导出工具集提供导出配方export recipes、Python 原语和 Swift 运行时工具把 PyTorch 模型转换为 Core AI.aimodel格式。当导出失败、数值对不上或产物体积异常时include-debug-info开关、调试信息剥离和 PSNR 数值校验就是三件最实用的调试利器。本文将从零讲清它们的用法帮你在 10 分钟内定位并解决导出问题。1️⃣ 准备工作获取 coreai-models 仓库如需本地运行导出命令先克隆仓库git clone https://gitcode.com/gh_mirrors/co/coreai-models导出前建议先确认支持哪些模型uv run coreai.model.registry --list-models --type llm整体目录结构可以参考仓库主文档 models/README.md各模型家族的导出配方位于models/名称/export.py。2️⃣ 理解导出默认行为为什么你的 .aimodel 信息很少coreai-models 所有导出路径默认使用转换器的RELEASE模式只嵌入最少量调试信息让产出的.aimodel体积最小——这正是发布时想要的状态。这一默认值由全仓库共享的常量锁定常量定义python/src/coreai_models/_constants.py 中的DEFAULT_INCLUDE_DEBUG_INFO False配置落点python/src/coreai_models/export/pipeline.py 中ExportConfig的include_debug_info字段也就是说默认导出 RELEASE 模式 最小调试信息。理解了这一点才能判断调试信息缺失到底是异常还是预期。3️⃣ 一键开启使用 include-debug-info 定位导出失败什么时候该加 --include-debug-info遇到以下三类问题时值得重新导出一份带完整调试信息的资产症状说明❓ 数值不对输出与 PyTorch 参考结果偏差大但说不清哪层出的错 算子降级失败某个 op 无法被 Core AI 降低lowering️ 需要回溯源码要把计算图节点映射回 Python 源码--include-debug-info会让转换器切换到DEBUG模式把完整调试信息嵌入.aimodeluv run coreai.llm.export Qwen/Qwen3-0.6B --include-debug-info全平台统一所有导出入口都支持该开关这个标志不是某个脚本的私货而是贯穿整个工具箱的统一契约coreai.llm.export语言模型coreai.vlm.export视觉-语言模型coreai.diffusion.export扩散模型coreai.segmentation.export图像/视频分割以及每个独立的 models/名称/export.py 配方例如uv run models/whisper/export.py --include-debug-info独立配方如 models/whisper/export.py通过uv run直接执行无需额外安装依赖PEP 723 内联依赖。一个容易踩的坑--verbose 不是调试信息⚠️--include-debug-info与--verbose/-v完全独立。-v只提高控制台日志级别不会改变.aimodel资产里嵌入的任何内容。想看控制台细节用-v想给资产加调试信息必须用--include-debug-info。仓库如何保证每个入口行为一致测试文件 python/tests/test_model_units/test_export/test_include_debug_info.py 对每一条导出路径做了契约检查锁定全仓库默认值必须为FalseRELEASE 模式参数化检查ExportConfig与DiffusionExportConfig是否继承共享常量扫描全部独立models/*/export.py配方确保它们都声明了--include-debug-info且默认 RELEASE 模式并禁止裸构造TorchConverter()那会静默继承库的 DEBUG 默认值4️⃣ 调试完别忘瘦身不重新导出原地剥离调试信息诊断完成后你通常不想带着完整的 DEBUG 信息把资产发出去。好消息是不需要重新导出。models/README.md给出了原地剥离的标准流程models/README.mdfrom coreai.authoring import AIModelAsset from coreai_torch.debugging.debug_info import strip_debug_info source AIModelAsset.load(inputModel.aimodel) metadata source.metadata author, license_, description ( metadata.author, metadata.license, metadata.model_description ) program source.program strip_debug_info(program) # 原地修改 program program.save_asset(Path(outputModel.aimodel))最容易翻车的细节save_asset()只会持久化creationDate、assetVersion和producer三项元数据。如果不把author、license、description重新挂回去发布出去的资产会静默丢失署名和许可证信息AIModelAsset.load(outputModel.aimodel).update_metadata( lambda m: ( setattr(m, author, author), setattr(m, license, license_), setattr(m, model_description, description), ) )剥离后的outputModel.aimodel携带的调试信息量与默认RELEASE导出的产物一致。5️⃣ 数值对不上用 PSNR 定位精度问题PSNR 是什么、仓库怎么算PSNR峰值信噪比单位 dB是 coreai-models 校验模型转换数值正确性的核心指标值越高压缩/转换后的输出与 fp16 参考输出越接近。仓库内置了可直接复用的度量脚本 skills/skills/model-compression-exploration/scripts/quality_metrics.py除了psnr还提供指标适用场景psnr/snr连续输出logits、特征图iou二值/阈值化输出分割掩码、检测热力图判定基准什么 PSNR 算过skills/skills/model-authoring/SKILL.md 给出了清晰的验证门槛建议对照着判断自己的导出结果对比场景门槛含义重写模型 vs 源模型PyTorch 70 dB实现正确Neural Engine 布局 vs GPU 布局 70 dB布局转换正确编译后 vs PyTorch≥ 40 dB编译精度fp16 优化4-bit 调色板压缩后≥ 35 dB压缩可接受压缩位数与 PSNR 的对应关系8-bit 通常 55 dB低于 50 dB 要警惕4-bit 约 40 dB低于 35 dB 要排查2-bit 仅 25–35 dB一般不建议发布。常见 PSNR 异常速查表这些症状→原因→修复来自仓库沉淀的排障手册 skills/skills/model-authoring/references/common_issues.mdPSNR 症状常见原因修复方向SDPA 只有 ~15–30 dB因果掩码方向反了(1, query, 1, key)转置掩码或改用create_ane_causal_mask()M-RoPE 只有 ~18 dBGPU 的 M-RoPE 模式未精确复刻对齐torch.cat([cos, cos])后按::2索引20–30 dB激活函数选错SiLU/QuickGELU/GELU 混用先打印源模型激活函数的type()数值整体错乱张量不连续Neural Engine 按连续内存读取所有张量在包装NDArray前调用.contiguous() 特别注意跨布局直接比较裸张量得到的 PSNR 没有意义先做对应的布局变换再比较。Swift 端也有对应校验导出后的 Swift 运行时同样内置了数值校验工具例如语音识别的对照测试 swift/Sources/Tools/speech-recognizer/SpeechParity.swift 和图像分割的image-segmenterCLI内含 PSNR 比较参数swift/Sources/Tools/image-segmenter/ImageSegmentationRunnerMain.swift。在设备上验证与 Python 侧参考输出的偏差时可以直接使用。6️⃣ 实战排查流程四步走把三件工具串起来形成标准排查链路 复现默认导出失败或输出异常先用-v观察控制台日志记住它不改资产内容 取证加--include-debug-info重新导出用调试信息定位到具体算子/图层 定量用 PSNR/SNR/IoU 对照上面两张表判断是编译精度问题、布局问题还是压缩过头✂️ 收尾问题解决后用strip_debug_info原地剥离调试信息并重新挂回元数据产出最小体积的发布版.aimodel总结coreai-models 的调试工具箱围绕一个朴素原则设计默认产物面向发布RELEASE 最小调试信息诊断时随时可切换诊断后随时可剥离。记住三个要点即可应付绝大多数导出问题--include-debug-info全平台通用且与-v互不干扰剥离调试信息无需重新导出但务必回挂 author/license/description 元数据拿不准数值对不对时用 PSNR 门槛表对照 70 dB 看实现≥ 40 dB 看编译≥ 35 dB 看 4-bit 压缩更多模型细节可继续查看对应模型卡片例如 models/qwen3/README.md 与 models/whisper/README.md压缩探索的完整方法论见 skills/skills/model-compression-exploration/SKILL.md。【免费下载链接】coreai-modelsModel export recipes, Python primitives, and Swift runtime utilities for on-device AI项目地址: https://gitcode.com/gh_mirrors/co/coreai-models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考