FlagOS 模型迁移向导

要解决什么问题

把 HuggingFace / vLLM upstream 里的新模型接到 FlagOS（vLLM FL 插件） 上，往往不是「拷几份 Python 文件」就完事：0.13.0 的 API 差异、相对导入、model_type 与 _CONFIG_REGISTRY 对齐、TP 分片下的 MergedColumnParallelLinear、自定义 op 注册路径等，都会在 import、benchmark、serve 或 E2E 阶段暴露。

本技能把迁移当成可重复执行的流程，而不是一次性笔记。

技能如何工作

执行时先解析参数：model_name（必填）、upstream_folder（默认 /tmp/vllm-upstream-ref）、plugin_folder（默认当前目录），并校验路径；上游目录不存在时会询问是否 clone。

随后加载技能内的参考文档：

• references/procedure.md — 逐步迁移主流程
• references/compatibility-patches.md — 面向 0.13.0 的补丁目录
• references/operational-rules.md — 沟通、TaskList、bash 与排错约定

再从 upstream 与 HuggingFace config.json 解析占位符（如 {{ModelClassName}}、{{model_type}}、{{ConfigClassName}} 等），禁止凭命名习惯猜测，必须以源码与 HF 配置为准。

按 procedure 顺序执行「拷贝再补丁」，并在关键节点调用 scripts/ 下的工具：

• Step 6：validate_migration.py — import / API / 注册检查
• Step 9：benchmark.sh — dummy weights 吞吐基准
• Step 10–11：serve.sh、request.sh、e2e_eval.py — 本地服务与相对上游 GT 的 token 级对比（可配合 e2e_remote_serve.sh 管理远端 GT）

运行中应在各步骤边界汇报进度；遇错优先按 operational-rules 的 Upstream-First 原则对照 upstream 与插件差异。

适用边界与注意点

• 默认假设目标环境为 vLLM 0.13.0 与 FlagOS 插件布局；上游 API 变更需同步补丁表（如 P1 相对导入、P3 缺失 API、P8/P11/P12 等典型坑）。
• E2E 上前几个 token 不一致通常指向权重加载或 TP 分片；中后期轻微漂移可能是算子实现差异，需在报告中说明是否可接受。
• Benchmark / Serve 因 GPU 被占用 OOM 时，应先释放占用进程再重试，不要跳过校验与 E2E 步骤。