Imported from AXERA-TECH/Magnetar (
AGENTS.md). Install upstream withnpx skills add AXERA-TECH/Magnetar. Copyright stays with the author.
AGENTS.md
本仓库包含 Magnetar 模型部署工具。所有 Agent 回复默认使用中文。
项目目标
将远程或本地浮点模型转换为 AX 芯片客户交付包：
模型 → ONNX → Pulsar2 编译 → AXMODEL → 仿真验证 → Python/C++ SDK → 交付包 → 发布
工具库
Agent 负责编排和决策。magnetar/stages/*.py 提供确定性执行函数：
| 模块 | 函数 | 用途 |
|---|---|---|
magnetar.config |
load_config() |
读取 .magnetarrc + 环境变量 |
magnetar.errors |
MagnetarError/classify_error() |
类型化错误码注册表（与 magnetar.yaml retry_on 对齐，测试强制） |
magnetar.stages.events |
log_event()/log_error() |
追加式事件日志 .magnetar-events.jsonl（可回放审计流，mark_stage 自动写） |
magnetar.pulsar2_util |
ensure_pulsar2_package(), resolve_backend(), run_pulsar2(), config_check() |
Pulsar2 独立包后端（自动获取 ModelScope/HF 最新 *_package.tar.gz，解压即完整运行环境，强制不用 Docker） |
magnetar.proc_util |
run() |
通用子进程执行（限长输出 + 日志落盘） |
magnetar.recipes |
list_recipes(), load_recipe(name), match_recipe(...) |
已验证模型配方（recipes/*.json）；命中则按配方确定性执行，未命中且 ALLOW_EXPLORE=false 时 STOP |
magnetar.board_util |
select_board(), ssh(), scp_to(), scp_from(), ensure_remote_infer(), port_open() |
AX 板端操作（上板前确保 ax-remote-infer 已装，18500 端口可发现板子） |
magnetar.stages.init |
run(config) → task_dir |
创建 TASK_DIR 结构 |
magnetar.stages.acquire |
run(task_dir, source)；write_model_flow(task_dir, flow) |
获取模型到 origin/ 并记录运行流程 |
magnetar.stages.export |
run_mobilenet(task_dir) → sample；run_generic(task_dir, ...) → result |
MobileNet 专用 / 任意模型通用导出（先简后繁自动降级） |
magnetar.stages.toolchain |
run() → pulsar_image |
自动获取/验证 Pulsar2 独立包可用（无 PULSAR2_HOME 时自动下载最新 *_package.tar.gz） |
magnetar.stages.compile |
run(task_dir, target_hw, image) |
Pulsar2 编译 AXMODEL |
magnetar.stages.simulate |
run(task_dir, sample, image, board=board, target_hw=...) → metrics |
精度对分（有板优先上板 ax_run_model，无板才回退 pulsar2 run） |
magnetar.stages.sdk_gen |
run_mobilenet_python(), run_mobilenet_cpp()；run_generic_python(task_dir), run_generic_cpp(task_dir) |
生成 Python/C++ SDK（通用版基于 model_meta + model_flow） |
magnetar.stages.runonboard |
run(task_dir, sample, hw, pwd) → metrics |
板端部署验证 |
magnetar.stages.package |
assemble(task_dir, metrics, image) → pkg, self_test(pkg) → result |
组装面向小白的交付包，含一键脚本 + README + 自测 |
magnetar.stages.publish |
publish(pkg, target, name, token, org, model) → result |
发布到 GitHub（源码）或 HuggingFace（预编译） |
magnetar.stages.llm |
classify(origin, ...) → 路由；llm_build(task_dir, input, chip, image, ...) → model_dir；install_axllm(board) / serve_axllm(board, model_dir) / validate_chat(api_url, ...) |
LLM/自回归模型路由与 ax-llm 部署（llm_build2 编译 + axllm 板端 serve/验证） |
非 MobileNet 模型：优先使用 magnetar.stages.export.run_generic /
scripts/export_onnx.py 通用导出器（load 脚本约定 build() 返回 (model, example_inputs)），
导出失败时依据 export/export_report.md 的诊断报告决定人工处理方向；确需手写导出逻辑时
再自行实现并正确填写 model_meta.json。
LLM/自回归模型（route=llm）：不走通用 ONNX 路径，改用 ax-llm——
pulsar2 llm_build2（Pulsar2 ≥ 6.0）直接编译 HF 权重 → compile/llm_model_dir/
（逐层 axmodel + post axmodel + bf16 embedding + tokenizer + axllm config.json），
板端用 axllm run/serve（AXERA-TECH/ax-llm，axllm 分支）；SDK 为 OpenAI 兼容
HTTP 客户端（Python 依赖仅 requests）。判定函数：magnetar.stages.llm.classify
（config architectures/model_type、pipeline_tag、model_flow task、模型名）。
hybrid 组合模型（MOSS-TTS、NeuTTS-2E 等）需先确认 LLM/AR 子模型拆分方案。
执行流程
严格按以下顺序推进 10 阶段，不可跳过。每阶段完成后更新 task.md 和 analysis.md。
INIT 后先过 model_route gate：route=llm 时 EXPORT/COMPILE/SIMULATE/SDK-GEN/
RUNONBOARD/PACKAGE 按 ax-llm 分支执行（详见 .codex/skills/magnetar/SKILL.md 路由节）。
状态机（回退/重试/循环）由 workflows/magnetar.yaml 控制。日常执行按
workflows/magnetar-summary.md（全局读一次）+ workflows/steps/<阶段>.md（每阶段读对应片段），
仅状态机诊断/排障时才读 yaml 全文。
SIMULATE 有板必上板（ax_run_model 秒级），pulsar2 run 仅无板/板端失败时回退；BOARD 未配置时先 select_board() 找空闲板，找不到才用仿真。
STOP 点
必须暂停等待用户确认：
SOURCE、TARGET_HARDWARE未提供- ONNX 与原模型对分失败（cosine < 0.99）
- 模型含动态 shape 且静态化失败
- Pulsar2 不可用
- 编译失败需改 ONNX → 退回 EXPORT
- SIMULATE 精度不达标（先查
issues/；INT8/U16/混合精度全试过仍不过时，STOP 前先向用户提议上 QAT） - 需要私有凭据
- PUBLISH 需用户确认发布目标、仓库名、凭据
BOARD 缺失不是 STOP：SIMULATE 先用 select_board() 找空闲板上板，找不到才回退 pulsar2 run；RUNONBOARD 无板自动跳过。
配置
优先读取 .magnetarrc（shell 风格 key=value），环境变量可覆盖。详见 .magnetarrc.example。
多任务并发隔离约定：
.magnetarrc只放公共默认（凭据/工具链/镜像/行为选项），任务参数（SOURCE/TARGET_HARDWARE/MODEL_NAME/BOARD/TASK_DIR）不要在里面反复改写- 每个任务 INIT 时把任务参数固化到
TASK_DIR/config.json；之后各阶段一律用magnetar.config.load_task_config(task_dir)读取，禁止并发任务互相改写.magnetarrc
目录约定
TASK_DIR/
origin/ export/ compile/ simulate/
sdk/python/ sdk/cpp/ runonboard/ package/ cache/
task.md analysis.md .magnetar-state.json .magnetar-events.jsonl
产物不得污染原始模型工程。
mark_stage 每阶段收尾自动追加 stage/artifact/metric 事件到 .magnetar-events.jsonl；
错误统一抛 MagnetarError(code)，新错误码先登记 magnetar/errors.py 再进 yaml retry_on。
模型获取
- 模型下载/获取优先 ModelScope（国内 CDN 快，公开模型无需额外凭据），HuggingFace 仅作回退
- 涉及 HF 的任何东西（模型权重、Pulsar2、ModelZoo 等）先查
ModelScope 有没有：
magnetar.net_util.modelscope_available("<org>/<name>")探测 （HF repo id 与 ModelScope 约定一致，如 AXERA-TECH/Pulsar2 两侧都有），有则优先 ModelScope 下载，没有才回退 HF/hf-mirror - HF 大文件（权重等）下载默认用 hf-mirror 的 hfd 工具：
scripts/download_hf.sh <org>/<name> --local-dir origin/<name> -x 8（自动缓存~/.cache/magnetar/hfd.sh，端点默认 hf-mirror，aria2c 多线程； 小文件如 tokenizer.json 仍可直接单线走 HF_ENDPOINT） - 默认国内镜像：HuggingFace
HF_ENDPOINT=https://hf-mirror.com；GitHub 克隆/下载经GH_PROXY=https://gh-proxy.com；uv/pip 默认PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/（海外用户可在.magnetarrc置空字符串禁用，恢复直连） - 大权重可用 ModelScope CDN 分片并行下载（参考
issues/013_moss-tts-realtime_ax650_pipeline_pitfalls.md） - SOURCE 支持 ModelScope / HuggingFace / Git URL / HTTP URL / 本地文件或目录
关键技术点
校准归一化对齐
Pulsar2 用 (img - mean) / std，libdet 用 (input - mean) * std。必须反向对齐：
| 组件 | 配置 | 输入范围 |
|---|---|---|
| Pulsar2 校准 | calibration_std = 255 |
uint8/255 = [0,1] |
| libdet 推理 | std = 1/255 |
uint8 × (1/255) = [0,1] |
常见错误：calibration_std = 0.004（即 1/255）→ 校准输入 [0,65025] → 板端全零。
量化
默认 INT8。U16 仅 INT8 cosine < 0.99 时尝试。highest_mix_precision 必须为 false。
校准集尽量用真实业务数据（真实输入/中间特征），随机/扰动数据仅兜底——可能在标定集上好看，真实业务上崩；
真实数据入口：run_generic(calibration_data=...) 或 scripts/export_onnx.py --calib-dir。
INT8 / U16 / 混合精度（layer_configs、SmoothQuant、Brecq、Percentile 等）全部尝试仍 cosine < 0.99 时，
STOP 前先向用户提议上 QAT（量化感知训练）；QAT 的框架选型/实现通道/注意事项见
docs/ax-knowledge.md §QAT（官方 QAT.axera、QAT→QDQ 通道、toy sanity、成本与进入条件）。
环境复用（避免重复装大包）
- 大包只装一次：
python -m magnetar.env_util base（默认~/.cache/magnetar/base-venv，MAGNETAR_BASE_VENV可覆盖；依赖清单requirements/base.txt变化才自动重建） - 每个任务用
magnetar.env_util.create_task_venv(task_dir, extra_packages=...)建薄 venv （.pth 链接 base，任务本地包优先），路径固化到 TASK_DIR/config.json 的 VENV_PATH； 禁止每个模型重建完整 torch/transformers 大环境 - 后续阶段解释器统一取
magnetar.env_util.resolve_task_python(task_dir) - BSP/交叉工具链也走公共目录：
magnetar.bsp_util.ensure_bsp(target_hw, cfg)自动 下载/解压到MAGNETAR_BSP_HOME（默认~/.cache/magnetar/bsp）；SDK/runtime 下载地址按芯片从 ax-pipelinescripts/build_common.sh解析（MSP_URL_DEFAULT/TOOLCHAIN_URL_DEFAULT；AX650 为 msp_50_3.10.2.zip + Arm GNU 9.2 aarch64， AX630C / AX620Q（AX620E NPU）为 msp_20e + build_common.sh 对应编译器 （AX620Q 为 ax620q_bsp_sdk uclibc）；CXX_BSP_URL/CXX_TOOLCHAIN_URL可覆盖，BUILD_COMMON_SH_URL可换清单源），探测AX_RUNTIME_ROOT与交叉编译器； C++ SDK 编译一律magnetar.bsp_util.build_cpp_sdk(task_dir, cfg)，禁止再手动找 ax_engine 头文件/库
编译
ONNX 必须静态 shape。编译前用 ONNX Runtime 验证。
临时文件与残留清理（防 /tmp 塞满）
- 本机临时目录一律放
TASK_DIR/cache/scratch/<用途>/（magnetar.scratch.scratch_dir）， 禁止往 /tmp 散落大文件；任务收尾调magnetar.scratch.cleanup_scratch(task_dir)。 package.self_test(pkg, model_name, task_dir=task_dir)：自测目录进任务 scratch， 通过即删、失败保留在result["scratch_dir"]供排查。- 板端临时文件一律进租约命名空间
/tmp/magnetar-lease/<token>/；acquire_board_lease获取前无条件先扫过期租约（mtime 心跳，活租约不受影响）。 - 新任务开始前执行
./magnetar cleanup（只读报告）确认"该不该清"， 确认后--force才删；板端用--board root@host[:port]查看/清理过期租约。
LLM / 自回归模型（ax-llm）
- 入口：
pulsar2 llm_build2（Pulsar2 ≥ 6.0，支持 AX650A/N、AX630C，其他芯片以--chip支持与 ax-llm 实际验证为准）；产物逐层 axmodel + post axmodel + bf16 embedding，自带逐层 decode/prefill cosine 校验。 - 板端运行：AXERA-TECH/ax-llm
axllm分支（axllm run <model_dir>/axllm serve <model_dir> --port 8000，OpenAI 兼容 API）；安装curl -fsSL https://raw.githubusercontent.com/AXERA-TECH/ax-llm/axllm/install.sh | bash。 - 辅助工具：AXERA-TECH/ax-llm-build（embed_process.sh 提取/转换 embedding； config/*.json 为 llm_build 配置样例）。
- axllm 模型目录 config.json 必填字段：model_name、tokenizer_type、 url_tokenizer_model（本地 tokenizer 文件）、template_filename_axmodel（含 %d）、 axmodel_num、filename_post_axmodel、filename_tokens_embed、 tokens_embed_num、tokens_embed_size。
- 精度验收：逐层 cosine min ≥ 0.99 + 板端语义验证（≥3 组 prompt 全非空）； 不达标先调 weight_type（s8→s4）/hidden_state_type/context，仍失败 STOP 提议 QAT。
输入/输出格式（成功案例固化）
- 校准数据、pulsar2 run、ax_run_model、axengine 输入格式一律按
docs/input-format-cheatsheet.md，禁止反复试格式 - 代码层单一来源：
magnetar/io_format.py；python magnetar/pulsar2_ref.py --cases打印成功案例 - 高频坑：U8 校准
calibration_std=255、Numpy 校准 npy 带 batch 维、tensor_name与 ONNX 输入名一致、bin 文件名必须等于 tensor 名
板端 ax-remote-infer
- 上板（SIMULATE 板端通道 / RUNONBOARD）前检查 TCP 18500：daemon 已跑则直接复用；未装则用官方 release 的
remote_install.sh静默安装（缓存~/.cache/magnetar/ax-remote-infer） - release 下载默认经
GH_PROXY（AX_REMOTE_INFER_URL可覆盖） - 装好后可通过扫描 18500 端口发现板子：
select_board()在 dashboard 不可用/无空闲板时回退扫描MAGNETAR_SCAN_SUBNET（默认 dashboard 所在 /24）
PUBLISH 发布
- 进入 PUBLISH 阶段时暂停，询问用户：发布到哪里（GitHub/HuggingFace）、仓库名、凭据位置
- GitHub：推送完整源码 + model_convert（客户可复现编译流程）
- HuggingFace：仅上传预编译模型 + SDK 产物（客户直接用），不含 model_convert/ 复现脚本
- HF README 自动添加 YAML frontmatter
- 凭据通过 GITHUB_TOKEN / HF_TOKEN 环境变量或 .magnetarrc 提供
验证期望
- ONNX 导出可复现，Torch/ONNX 对分 cosine ≥ 0.99
- Pulsar2 配置
highest_mix_precision为 false - Python SDK
import <sdk>通过，默认AxEngineExecutionProvider - C++ SDK cmake configure 通过
- SDK 前后处理对齐原版模型（
model_flow.json的 preprocess/postprocess 来自原版管线，ACQUIRE 阶段验证过），调用方式尽量对齐原版入口（sdk_interface记录入参顺序/输入格式/输出结构），禁止为省事改成直通/自定义 ax_run_model仅用于 smoke check，不能替代 SDK 验证- PACKAGE 产出独立 git 项目，板端自验证通过
- 交付包 Python/C++ 尽量减少依赖：端到端 NPU 跑通后 SDK 仅依赖 numpy + pyaxengine， 不含 onnxruntime/torch/transformers 等回退；CPU fallback 尽量不做，能端到端 NPU 就端到端 （RUNONBOARD 通过即强制 NPU-only 交付，package 装配时会校验无回退依赖）
爱芯开发知识
完整资源清单见 docs/ax-knowledge.md（仅查证 URL/版本时按需读取，不随每轮全量加载；
SDK/BSP 下载地址除外——按芯片查 ax-pipeline build_common.sh，ax-knowledge 不再收录）。
Token 效率约定
本工作流面向长流程（10 阶段 + 重试 + 回退），上下文是稀缺资源，遵守以下约定：
- 大日志只读尾部 + 关键指标，完整日志落盘不读入
- Pulsar2/SSH 大输出默认截断返回尾部（≤400 行），完整日志落盘（compile.log / pulsar2_run.log），异常也只带尾部 + 日志路径
- shell 检索用
rg -l/head/tail限长输出，禁止整段 dump - 进度/恢复读
.magnetar-state.json，不读 task.md 全文 - 禁止读取二进制产物（.npy/.bin/.axmodel/.onnx/.pt）
- compile 日志用
summarize_compile_log()取指标，不读全文 - 查
issues/先读INDEX.md，只读命中的文件 - 每阶段只读一次对应 hidden SKILL.md 与
workflows/steps/<阶段>.md，全局只读一次workflows/magnetar-summary.md，不重复通读workflows/magnetar.yaml全文 - 对齐按批确认，缺失项一次列清单带推荐答案
- 优先
stages/*.py现成函数与export_onnx.py通用导出器 - 每阶段一句话更新
task.md/analysis.md，详细报告只落盘 - 汇报/答复只给结论 + 指标，不贴大段日志
完整约定见 .codex/skills/magnetar/SKILL.md 与 docs/ax-knowledge.md。