用 MAX `max serve` 启动/托管模型：环境…

当你要把 Hugging Face 或本地 checkpoint 通过 MAX 起成 OpenAI 兼容 HTTP 服务，或排查 `max serve` 启动失败时使用。

适用场景

解决思路

1. 若 MAX 已安装且已有可工作的自定义架构包，先走快路径；不要手动读 `arch.py` 和 `config.json` 推理 flags，使用 bundled inspector 打印可运行命令和理由。
2. 运行 `python <skill>/scripts/suggest_serve_command.py --custom-architectures /abs/path/to/my_arch --model <hf-repo-or-path>` 获取推荐命令和 `# notes:`（它会读取 `arch.py` + `config.json`）。
3. 启动推荐命令：pixi 项目加 `pixi run`；远程主机用 `setsid ... </dev/null` 使其在 SSH 会话后存活：`setsid <the suggested command> </dev/null > /tmp/max-serve.log 2>&1 &`。
4. 用一次调用等待就绪（崩溃时快速失败；冷编译约 10 分钟预算，推进的 `Still compiling` 心跳正常）：`timeout 600 bash -c 'until grep -qE "Server ready|Uvicorn running" /tmp/max-serve.log; do grep -qiE "Traceback|CRASHED|Error building|cannot be found|not found in registry" /tmp/max-serve.log && { echo SERVE_FAILED; tail -30 /tmp/max-serve.log; exit 1; }; sleep 3; done' && echo SERVE_READY`。
5. 用一个请求确认（`model` 字段必须等于 `--served-model-name`）：`curl -s http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"my_arch","messages":[{"role":"user","content":"The capital of France is"}],"max_completion_tokens":32}'`。
6. 阅读 inspector 的 `# notes:`，这是陷阱出现处（`default_encoding` 与 checkpoint 不一致、`name` 与内置冲突、GPU-only 编码、MoE）。如果命令工作且输出连贯，完成；只有 note 或失败才进入详细步骤。
7. 按任务读取参考文件，不要一开始全读：服务自定义架构读 `references/custom-arch.md`；选择除 `--model`、`--devices`、`--quantization-encoding`、`--max-length` 之外的任何 serve flag 读 `references/flags.md`；`max serve` 启动失败或 cryptic error 读 `references/troubleshooting.md`。
8. 先判断是否已安装 MAX nightly：运行 `max serve --help`；若在 pixi 项目内运行 `pixi run max serve --help`。如果已有可用 `max serve` 就不要重装；该命令要求项目包含 `max[serve]` 或 `max-serve` extra 依赖。
9. 若 `max serve` 不可用，使用 pixi 默认方案：若未安装 pixi，按 https://pixi.prefix.dev/latest/#installation 安装；然后 `pixi init my-max-project -c https://conda.modular.com/max-nightly/ -c conda-forge && cd my-max-project`，再 `pixi add max-serve`。
10. 若已有 `pixi.toml`，确保 channels 行精确为 `channels = ["https://conda.modular.com/max-nightly/", "conda-forge"]`（新版用 `[workspace]`，旧版用 `[project]`）。
11. 若偏好 uv：若未安装 uv，按 https://docs.astral.sh/uv/getting-started/installation/ 安装；然后 `uv init my-max-project && cd my-max-project`，`uv venv && source .venv/bin/activate`，`uv add "max[serve]" --index https://whl.modular.com/nightly/simple/ --prerelease allow`。
12. pixi 安装后，在 pixi 项目中给命令加 `pixi run` 前缀，或进入 `pixi shell`；uv 安装后激活 venv 并直接调用 `max`。
13. 判断内置还是自定义架构：运行 `max list` 查看已注册架构和示例 repo ID。
14. 将 checkpoint 的 `config.json::architectures[0]`（如 `LlamaForCausalLM`、`Qwen2ForCausalLM`）与 `max list` 匹配。
15. 若架构已列出：属于内置模型，跳到构建 serve 命令步骤，并省略 `--custom-architectures`。
16. 若架构未列出：需要自定义架构包。如果用户还没有该包，不要在本技能中制造；这是 bring-up 任务，需实现 `arch.py`、`model.py`、计算图和权重适配器，指向模型 bring-up 工作流并停止。
17. 自定义架构包是 Python 包（含 `__init__.py` 的目录），暴露顶层 `ARCHITECTURES` 列表，元素为 `SupportedArchitecture` 实例；用 `--custom-architectures` 传入，MAX 会导入并按 `name` 注册，每个请求用 checkpoint 的 `config.json::architectures[0]` 匹配注册的 `name`。
18. 写命令前先读架构包，不要猜 flag：打开 `arch.py`，查看 `SupportedArchitecture(...)` 调用；`default_encoding` 是要服务的编码，`supported_encodings` 是 `--quantization-encoding` 必须所属集合，`name` 必须匹配 checkpoint，`multi_gpu_supported` 决定能否分片，包内 `chat_template.jinja` 意味着需要 `--chat-template`。
19. 打开 checkpoint 的 `config.json`：`architectures[0]` 必须等于 `arch.py` 的 `name`；`max_position_embeddings` 限制 `--max-length`；`torch_dtype`/`quantization_config` 应与 `default_encoding` 一致；MoE 字段（如 `num_experts`）提示可能需要 `--device-graph-capture`。
20. 服务自定义架构时读取 `references/custom-arch.md`：其中包含逐字段的 `arch.py` 到 flags 映射、编码到设备表，以及 serve-time 陷阱（overlap-scheduler 与 logprobs、8001 端口 metrics 冲突、`trust-remote-code`）。
21. 将 `--custom-architectures` 指向包目录（脚本和远程主机最安全用绝对路径）；`IMPORT_PATH:MODULE_NAME` 冒号形式也可用，但多数工具使用目录路径：`max serve --model <hf-repo-or-path> --custom-architectures /abs/path/to/my_arch`。
22. 运行三项前置检查以避免看堆栈：① `SupportedArchitecture` 的 `name=` 精确等于 `config.json::architectures[0]`；② `supported_encodings` 包含 checkpoint 实际发布的编码（bf16 checkpoint 需要 `bfloat16`，GPTQ checkpoint 需要 `gptq` 等）；③ `weight_adapters` 有针对 checkpoint 权重格式的条目（`.safetensors` 用 `WeightsFormat.safetensors`，`.gguf` 用 `WeightsFormat.gguf`）。
23. 如果模型还不是可工作的自定义架构包（计算图、权重适配器、配置尚未实现），这是 bring-up 而非 serving；本技能只服务已有包，不编写包。
24. 默认优先构建最小命令并运行：`max serve --model <hf-repo-or-path> [--custom-architectures ...]`，让 MAX 自动检测其余项。
25. 该最小命令已绑定 `0.0.0.0:8000`，有 GPU 时默认在 GPU 服务（否则 CPU），从 checkpoint 推断 dtype，并从 `max_position_embeddings` 设置 `max_length`；常见单 GPU 情况不要传 `--devices`。
26. 只为具体原因添加 flag；最常用三个：`--devices`（必须固定特定 GPU、跨 GPU 分片或强制 CPU 时；示例 `--devices gpu:0`、`--devices gpu:0,1,2,3`、`--devices gpu:all`、`--devices cpu`）。
27. `--quantization-encoding`：当 repo 有多个格式，或自动检测选错时添加；示例 `--quantization-encoding bfloat16`。
28. `--max-length`：当想要比模型最大上下文更短（节省 KV 内存）或需要限制以适配时添加；示例 `--max-length 4096`。
29. 其他 flag（device memory、batch size、task selection、sliding window、trust-remote-code、multi-GPU parallelism、speculative decoding）见 `references/flags.md`；在添加任何不确定的 flag 前阅读它，它解释每个 flag 做什么以及何时不要设置。
30. 决策顺序 1：默认优先；先试最小命令；对内置模型自动检测通常正确，GPU 已是默认设备。
31. 决策顺序 2：自定义架构要读包；`arch.py` 的 `default_encoding` 就是 `--quantization-encoding`；该编码约束设备：fp8、fp4、gptq 仅 GPU，而 GPU 已是默认，因此不要为它们添加 `--devices`（见 `references/custom-arch.md`）；`--max-length` 以 `config.json::max_position_embeddings` 为上限；若 checkpoint 带自定义建模文件则添加 `--trust-remote-code`，若包内含模板则添加 `--chat-template`；这些不是猜测，是从包和配置读出的。
32. 决策顺序 3：当选择有承载性时进一步检查；对不常见属性（sliding window、partial RoPE、MoE routing），检查 `config.json` 并用 `references/flags.md` 将发现映射到 flags。
33. 决策顺序 4：不确定时询问用户；如果决策依赖你看不到的信息（哪些 GPU 空闲、需要多少上下文、CPU 还是 GPU），问而不是猜；错误的 `--devices` 或 dtype 会缓慢且困惑地失败，快速提问更便宜。
34. 启动（后台运行并写日志）：`max serve --model <hf-repo-or-path> [flags] > /tmp/max-serve.log 2>&1 &`。
35. 如果在远程主机通过 SSH 启动，裸 `&` 会随 SSH 会话关闭而死亡，编译可能超过连接时间；要完全脱离：`setsid max serve --model <hf-repo-or-path> [flags] </dev/null > /tmp/max-serve.log 2>&1 &`。
36. 用一次调用等待就绪，监视日志心跳并在崩溃时快速失败，而不是阻塞完整超时：`timeout 600 bash -c 'until grep -qE "Server ready|Uvicorn running" /tmp/max-serve.log; do grep -qiE "Traceback|CRASHED|Error building|cannot be found|not found in registry" /tmp/max-serve.log && { echo SERVE_FAILED; tail -30 /tmp/max-serve.log; exit 1; }; sleep 3; done' && echo SERVE_READY`。
37. 就绪时服务器会打印：`Server ready on http://0.0.0.0:8000 (Press CTRL+C to quit)`。
38. 大模型首次启动会编译；安静间隔中出现 `Still compiling model (Ns elapsed)` 心跳是正常的，不是挂起；elapsed 计数是存活信号；等待它推进，只有计数冻结（或进程存活但日志 mtime 不动）才视为卡住。
39. 确认健康：`curl -s http://localhost:8000/v1/health`（就绪返回 200）；`curl -s http://localhost:8000/v1/models` 查看 served model name。
40. 发送真实请求：`curl -X POST http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"<hf-repo-or-path>","messages":[{"role":"user","content":"The capital of France is"}],"max_completion_tokens":32}'`。
41. 请求中的 `model` 字段必须匹配传给 `--model` 的值（如果你覆盖了，则匹配 `--served-model-name`）。
42. 读取响应：不要因为服务器绿灯就认为 bring-up 完成；检查文本是否真正连贯，不是重复或乱码；如果服务正常但输出错误，是 parity/正确性问题，不是 serving 问题。
43. 首次服务会下载权重并编译图，这是慢的部分；两者都会缓存，之后服务同一模型会快很多。
44. 权重通过 `huggingface_hub` 下载到共享 Hugging Face 缓存（默认 `~/.cache/huggingface`；设置 `HF_HOME` 可迁移）；重新服务同一 repo 会复用缓存权重，不再下载。
45. 编译也会缓存；若要在 demo 或部署前预热两个缓存，让首次 `max serve` 跳过下载和 `Still compiling` 等待，先运行 `max warm-cache --model <hf-repo-or-path> [--custom-architectures /abs/path/to/my_arch]`。
46. 编译产物（MEF）是平台特定的，所以要在相同硬件上预热缓存（或传 `--target`，例如 `cuda:sm_90`，从不同主机为部署目标编译）。
47. 故障排查：将症状与 `references/troubleshooting.md` 匹配；它覆盖看似神秘但有一行修复的启动失败（encoding mismatch、`architectures[0]` name mismatch、`trust_remote_code`、加载时 OOM、端口占用、设备路由错误）。先读 serve log；真正错误通常在最终 traceback 上方几行。

适用边界 · 注意事项

• 模型尚未在 MAX 中实现，且没有可工作的 `arch.py`、计算图和权重；这是 bring-up/移植任务，应使用 `import-model` 移植架构，若已能服务但输出错误则用 `debug-model`。
• 模型已经能服务但输出不正确/不一致；这是 parity/正确性问题，不是 serving 问题。