MAX CLI 命令速查：用 `max` 一个二进制完成模型服务、生成、编码与基准测试

MAX CLI 命令速查用max一个二进制完成模型服务、生成、编码与基准测试【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读max是 Modular PlatformMAX Mojo提供的统一命令行工具把模型推理的常见操作收敛到一个二进制中从启动 OpenAI 兼容的服务端max serve、直接跑文本生成max generate与文本编码max encode到对运行中的服务做负载压测max benchmark、部署前预编译与预热模型缓存max warm-cache/max warm-interpreter-cache以及列出 MAX 支持的全部模型架构max list。本文以 max/python/docs/cli/index.rst 为骨架逐条展开每个子命令的用法、参数与背后的实现入口并结合仓库源码说明其调用关系与适用前提帮助你快速上手并理解每条命令的底层行为。安装与总览maxCLI 随modular包一起安装。安装modular包后即可在终端直接使用max命令安装指引见仓库文档 docs/_includes/install-modular.mdx。从源码角度看max命令的入口定义在 max/python/max/_entrypoints/pipelines.py文件中的main函数是一个 click 命令组通过main.command(...)注册了serve、generate、encode、warm-cache、warm-interpreter-cache、list、benchmark等子命令。也就是说所有子命令共享同一个 CLI 基础设施日志配置、遥测开关、参数解析这也解释了为什么各子命令的参数风格高度一致例如--model统一接受 Hugging Face 模型 ID 或本地路径。max serve # 启动 OpenAI 兼容的服务端 max generate # 不用端点直接跑文本补全调试/测试用 max encode # 把文本转成 embedding 向量 max benchmark # 对运行中的服务做负载压测 max warm-cache # 部署前预编译并缓存模型 max warm-interpreter-cache # 预编译 eager interpreter 的算子缓存 max list # 列出 MAX 支持的模型架构max serve启动 OpenAI 兼容推理服务max serve启动一个带 OpenAI 兼容端点的模型服务模型通过 Hugging Face 模型 ID 或本地路径指定。以下示例在一张 GPU 上启动 Gemma 3 12B 服务并配置批大小与显存占用max serve \ --model google/gemma-3-12b-it \ --devices gpu:0 \ --max-batch-size 8 \ --device-memory-utilization 0.9端点的启用规则服务暴露哪些端点由环境变量MAX_SERVE_API_TYPES控制默认值为openai,sagemakeropenai/v1/completions、/v1/chat/completions、/v1/embeddings、/v1/models、/v1/healthsagemakerSageMaker 兼容的推理端点kserveKServe 兼容的推理端点responses/v1/responsespixel_generation任务必需注意OpenAI 路由在启用openai类型时总是被注册但每个路由只有在模型以兼容的--task值提供服务时才真正生效——例如/v1/embeddings需要embeddings_generation任务。各端点 API 的详细说明见仓库文档 docs/max/rest-api/。如果不需要 HTTP 服务、只想直接跑推理可以改用max generate文本补全或max encodeembedding。多 GPU 与设备选择向--devices传入逗号分隔的 GPU ID 列表即可使用多卡max serve \ --model google/gemma-3-12b-it \ --devicesgpu:0,1,2,3 \ --max-batch-size 16用--devicesgpu:all可选中所有可见 GPU省略--devices时使用模型或配置的默认设备。--devices是max serve的一等设备选择器建议不要与 shell 层的CUDA_VISIBLE_DEVICES混用——两者是独立翻译的叠加使用在多进程工作区中可能产生错误的设备路由。加载自定义模型架构可以通过--custom-architectures把自定义模型实现挂到 MAX 上每个值的形式为path/to/module:module_namemax serve \ --model google/gemma-3-12b-it \ --custom-architectures path/to/module1:module1 \ --custom-architectures path/to/module2:module2--custom-architectures的完整使用示例可参考仓库中的自定义模型架构文档max serve源码入口为 max/python/max/_entrypoints/pipelines.py 中的cli_serve支持--headless、--log-prefix、--max-queue-size、--max-pending-requests、--pretty-print-config等更多服务端选项。max generate无端点直接生成max generate直接从给定模型和提示词生成输出不走 HTTP 端点主要用于调试和测试。示例max generate \ --model google/gemma-3-12b-it \ --max-length 1024 \ --max-new-tokens 500 \ --top-k 40 \ --temperature 0.7 \ --seed 42 \ --prompt Explain quantum computing--max-batch-size、--max-length等参数可以按机器的实际资源例如 GPU 显存调整。视觉模型的图文生成用法见仓库文档 docs/max/serve/ 中的 Image to text 章节。源码层面generate子命令对应 max/python/max/_entrypoints/pipelines.py 中的cli_pipeline注册于第 415 行它使用WithLazySamplingAndPipelineOptions解析采样参数top_k、top_p、temperature、seed等与管线参数。max encode文本转 embeddingmax encode把输入文本转换为向量用于语义搜索、文本相似度与 NLP 下游任务。示例使用 Sentence-Transformers 模型max encode \ --model sentence-transformers/all-MiniLM-L6-v2 \ --prompt Convert this text into embeddings命令会打印 embedding 向量与本次运行的耗时。可以配合max list查看 MAX 支持哪些编码器架构。该子命令的源码入口是 max/python/max/_entrypoints/pipelines.py 中的encode内部调用max._entrypoints.cli.encode.pipeline_encode完成实际编码流程。max benchmark对运行中的服务做负载压测max benchmark对一个正在运行的模型服务执行全面的基准测试测量吞吐、延迟与资源利用率等指标。执行前请先通过max serve启动服务。快速上手示例对本地localhost上运行的google/gemma-3-27b-it服务做压测max benchmark \ --model google/gemma-3-27b-it \ --backend modular \ --endpoint /v1/chat/completions \ --num-prompts 50 \ --dataset-name arxiv-summarization \ --arxiv-summarization-input-len 12000 \ --max-output-len 1200默认情况下请求发往localhost:8000可通过--host与--port修改也可以直接用--base-url覆盖两者。把结果保存为 JSON 文件时用--result-filename指定路径路径可包含目录目录不存在会自动创建max benchmark ... --result-filename results/gemma-run.jsonmax benchmark是开源benchmark_serving.py脚本的便捷封装接受该脚本的全部选项。完整的参数列表运行max benchmark --help查看源码可参考 max/python/max/benchmark/若存在。命令注册点在 max/python/max/_entrypoints/pipelines.py 第 813 行最终调用sweep_main执行。核心选项分组后端配置--backend被压测的服务器类型。可选modular、modular-chat、vllm、vllm-chat、sglang、sglang-chat、trtllm、trtllm-chat。默认modular。--modelHugging Face 模型 ID 或本地路径。--endpoint具体 API 端点如/v1/completions或/v1/chat/completions。默认/v1/chat/completions。--base-urlAPI 服务的基础 URL设置后覆盖--host与--port。--host服务器主机默认localhost。--port服务器端口默认8000。--tokenizer使用的 Hugging Face tokenizer默认取模型的 tokenizer。负载生成--num-prompts要处理的单轮 prompt 数量默认不设置与--num-chat-sessions至少指定其一。--num-chat-sessions驱动的多轮对话会话数chat-judge数据集必填需配合支持多轮的数据集使用。--request-rate每秒请求数可传单个值或逗号分隔的扫描序列如1,2,4,8默认inf不限速。--max-concurrency最大并发请求数可传单个整数或逗号分隔序列。--seed负载生成器输入/输出长度、会话结构与内容的随机种子默认24301固定以保证可复现传--seed none或在 workload YAML 中写seed: null则每次取新随机种子取值会记入结果日志。--kv-block-size每轮缓存保留指标使用的 KV 缓存块大小token 数默认128。建议与服务器的--kv-cache-page-size一致否则保留率指标会不准确不影响压测本身。--fit-distributions用random_*系列参数与--delay-between-chat-turns重塑多轮负载需要--num-chat-sessions配合instruct-coder、agentic-code或nemotron-opencode数据集。--agentic-tool-profiles在每个人类轮之后追加 agent 循环工具调用负载按每个工具的长度分布合成而不是回放。参数形式为 YAML 文件路径或内联 YAML/JSON 映射。每个工具可配置weight相对权重默认 1、input-len工具返回结果的长度即Uj*、output-len发起调用的 assistant 消息Aj*的长度通常较小、delay耗时。仅支持instruct-coder、agentic-code、nemotron-opencode配合--fit-distributions使用。--agentic-rounds-per-turn每个人类轮后跟几个 agent 循环轮次每轮采样一次接受常量或分布字符串需配合--agentic-tool-profiles。--delay-between-chat-turns轮间延迟毫秒接受常量或分布字符串格式同--random-input-len。--workload-config指定 workload 选项的 YAML 文件键名使用连字符风格如num-prompts、seedCLI 参数优先于文件值。数据集选择--dataset-name压测所用的数据集决定数据集类与处理逻辑默认sharegpt。--dataset-path本地数据集文件路径仅对支持本地覆盖的数据集有效。输出控制--max-output-len每个请求的最大输出长度token 数。--temperature、--top-p、--top-k转发给服务器的采样参数。LoRA 流量--lora随每个请求发送的可选 LoRA 名称。--lora-paths现有 LoRA adapter 路径每项为path或namepath。--lora-uniform-traffic-ratio任一请求打到随机 LoRA而非基座模型的概率取值0.0–1.0默认0.0。--per-lora-traffic-ratio按--lora-paths顺序给出的各 adapter 流量占比总和不能超过1.0剩余部分给基座模型设置后覆盖--lora-uniform-traffic-ratio。--max-concurrent-lora-ops最大并发 LoRA 加载/卸载操作数默认1。结果保存--result-filename结果 JSON 文件路径不设置则不写文件路径可包含会自动创建的目录。--metadata随运行记录进结果 JSON 的键值对如--metadata version0.3.3 tp1。--log-dir日志输出目录默认backend-latency-Y.m.d-H.M.S。统计采集--collect-gpu-stats/--no-collect-gpu-stats上报 GPU 利用率与显存占用仅 NVIDIA默认开启只在max benchmark与服务器同机运行时有效。--collect-cpu-stats/--no-collect-cpu-stats上报 CPU 统计默认开启。--collect-server-stats/--no-collect-server-stats上报服务器统计默认开启。Profiling--profile采集 Nsight Systems GPU 轨迹并在运行结束后打印 top-N kernel 汇总内部转为--trace。服务器需预先在nsys launch下运行与max generate --profile不同后者是把客户端在nsys profile下重新执行。--profile-output--profile时的.nsys-rep文件路径默认$BUILD_WORKSPACE_DIRECTORY/max-profile.nsys-rep或当前目录下的max-profile.nsys-rep。--profile-top-n汇总表中展示的 kernel 数量默认15。--trace启用 nsys 追踪--profile的低层替代不带运行后的 kernel 汇总要求服务器在nsys launch下运行仅 NVIDIA GPU。--trace-file直接使用--trace时保存 nsys 轨迹的路径默认$BUILD_WORKSPACE_DIRECTORY/profile.nsys-rep或./profile.nsys-rep。--trace-session可选的 nsys 会话名。配置文件--config-file包含 benchmark 选项的 YAML 文件路径。数据集一览--dataset-name支持的数据集如下会自动从 Hugging Face Hub / Datasets 下载的会注明标有需本地文件的必须提供--dataset-path文本类sharegpt默认人机对话数据集来自 Hugging Face Hub 的anon8231489123/ShareGPT_Vicuna_unfiltered。axolotlAxolotl 格式的人/助对话数据集使用打包的默认文件可用--dataset-path覆盖。chat-judgeLLM-as-judge 多轮流负载由本地 JSONL 会话文件支撑每轮把上文内联进用户消息驱动方按轮发送[system?, user]。必须提供--dataset-path与--num-chat-sessions不支持单轮模式。示例 JSONL每行一个会话{ session_id: s1, turns: [ {text: You are a safety judge., role: system}, {text: Rate this content: ...} ] }obfuscated-conversations本地混淆对话数据集需--dataset-path指向本地 JSONL。可配--obfuscated-conversations-average-output-len默认175、--obfuscated-conversations-coefficient-of-variation默认0.1、--obfuscated-conversations-shuffle默认关闭。arxiv-summarization论文摘要数据集来自 Hugging Face Datasets--arxiv-summarization-input-len默认15000。sonnet诗歌数据集使用打包的文本文件可用--dataset-path覆盖--sonnet-input-len默认550--sonnet-prefix-len默认200。random可配置 token 分布的合成数据集。--random-input-len默认1024、--random-output-len默认128、--random-num-turns默认1均接受常量或分布字符串N(mean,std)、U(lower,upper)、DU(lower,upper)、NB(n,p)、G(shape,scale)、LN(mean,std)用;分别为首轮与后续轮设置分布如N(2048,200);N(512,50)。另有--random-sys-prompt-ratio默认0.0、--random-max-num-unique-sys-prompt默认1、--warm-shared-prefix需--random-sys-prompt-ratio 0默认关闭、--random-image-count默认0开启视觉模式、--random-image-size如512x512。synthetic与random使用相同分布参数的合成 token 负载但生成合成 token ID 而非词表文本支持通过--num-chat-sessions与random_*参数走多轮也支持--warm-shared-prefix。代码类instruct-coder指令跟随编码数据集Hugging Face Hublikaixin/InstructCoder支持单轮--num-prompts与多轮--num-chat-sessions模式多轮默认按自然 token 长度分组编辑任务每会话最多 5 轮配--fit-distributions时轮数改由--random-num-turns决定。agentic-code带工具调用轮次的多轮 agentic 编码负载Hugging Face Hubnovita/agentic_code_dataset_22默认逐会话回放完整录制对话--tool-calls/--no-tool-calls控制是否包含工具调用轮并转发工具定义默认开启。nemotron-opencode大规模 agentic 编码轨迹Hugging Facenvidia/Nemotron-SFT-OpenCode-v1按需流式加载工具 schema 转为 OpenAI function-tool 格式不支持--dataset-path。--tool-calls/--no-tool-calls默认开启。code_debug长上下文代码调试数据集Hugging Face Hubxinrongzhang2022/InfiniteBench单轮用--num-prompts也可通过--num-chat-sessions走固定两轮长上下文模板。视觉类batch-jobOpenAI Batch API 格式的批量图像负载需--dataset-pathtar 归档或含jobs.jsonl的解包目录--batch-job-image-dir指定服务器可访问的图像目录文件引用模式不设置时图像以 base64 内嵌。local-image本地图像视觉压测需--dataset-path每行含prompt与image_path的 JSONL。vision-arena带图像与问题的视觉-语言多模态评估数据集来自 Hugging Face Datasets。synthetic-pixel面向图像输出后端的合成像素生成负载。配置文件YAML与其在命令行写满参数可以用--config-file从 YAML 加载设置。选项定义在顶层benchmark_config键下同时提供时 CLI 参数优先于文件值。注意YAML 文件中的属性名必须使用snake_case下划线风格而不是命令行的连字符风格。例如--num-prompts要写成num_prompts。例如与其在命令行写max benchmark \ --model google/gemma-3-27b-it \ --backend modular \ --endpoint /v1/chat/completions \ --host localhost \ --port 8000 \ --num-prompts 50 \ --dataset-name arxiv-summarization \ --arxiv-summarization-input-len 12000 \ --max-output-len 1200可以创建这样的配置文件benchmark_config: model: google/gemma-3-27b-it backend: modular endpoint: /v1/chat/completions host: localhost port: 8000 num_prompts: 50 dataset_name: arxiv-summarization arxiv_summarization_input_len: 12000 max_output_len: 1200然后运行max benchmark --config-file gemma-benchmark.yaml更多配置示例可查看仓库中的 benchmark 配置目录 max/python/max/benchmark/configs/若存在。输出指标每次运行完成后打印以下指标请求吞吐每秒处理的完整请求数。输入 token 吞吐每秒处理的输入 token 数。输出 token 吞吐每秒生成的 token 数。TTFTtime to first token从请求开始到生成第一个 token 的时间。TPOTtime per output token生成每个输出 token 的平均耗时。ITLinter-token latency连续 token或 token 块生成之间的平均间隔。多轮负载还会额外报告每轮缓存 token 率每轮 prompt token 中由前缀缓存命中的百分比服务器上报 token 统计时可用。每轮 KV 缓存保留率对首轮之后的每一轮上一轮按块对齐的前缀仍留在缓存中的百分比当服务器在轮间丢弃缓存 token 时会显现出来。块对齐用--kv-block-size配置。开启--collect-gpu-stats时还会报告GPU 利用率至少一个 GPU kernel 正在执行的时间占比。峰值 GPU 显存压测期间的显存峰值。max warm-cache部署前预编译与预热模型缓存max warm-cache通过以下方式优化模型初始化时间部署前预编译模型预热 Hugging Face 缓存。在正式服务模型前运行它很有用。示例max warm-cache \ --model google/gemma-3-12b-it如果要在没有对应物理硬件的机器上为目标 API 与架构编译可传--target如cuda、cuda:sm_90、hip:gfx942。MAX 会使用虚拟设备完成编译适合在没有部署硬件的 CI 主机上构建 MEF 缓存max warm-cache \ --model google/gemma-3-12b-it \ --target cuda:sm_90平台相关性的重要说明Modular Executable FormatMEF本身是平台无关的但编译过程中产出的序列化缓存MEF 文件是平台相关的原因有二编译期间会发生平台相关的优化fallback 操作假定特定的运行时环境。此外MEF 缓存期间的权重变换与哈希可能影响性能。虽然项目正在通过权重外部化weight externalization改进这一点但当前编译出的 MEF 文件仍与平台绑定不能通用移植。源码实现上warm-cache子命令对应 max/python/max/_entrypoints/pipelines.py 中的cli_warm_cache它会从max.pipelines加载PIPELINE_REGISTRY与PipelineConfig当传入--target时调用max.serve.config.parse_api_and_target_arch解析目标 API 与目标架构随后加载并编译模型以准备缓存。max warm-interpreter-cache预编译 eager 解释器缓存MAX 内置一个解释器图调用到算子时逐个执行。对于矩阵乘法、逐元素数学等部分算子解释器首次运行时会构建一个优化过的编译版本保存到磁盘缓存并在后续运行中复用。每个算子 × 设备 × 数据类型组合对应一个编译版本首次全部编译可能要花几分钟。max warm-interpreter-cache会在当前硬件上一次性编译所有组合max warm-interpreter-cache要点由于编译结果依赖硬件请在计划运行的同型号机器上执行本命令。常见场景是系统初始化阶段例如 Dockerfile 中安装 MAX 后的一个步骤。MAX 会把缓存存放在引擎自身模型缓存的旁边并记录机器硬件信息因此同一台机器上的其他 MAX 进程无需额外配置即可复用。当某个环境变量与预热冲突时命令会拒绝执行MAX_EAGER_ALLOW_LAZY_COMPILE0真实预热时或MAX_EAGER_OP_PRECOMPILE1任一模式--check模式可容忍前者因为它不编译任何东西。可用env -u MAX_EAGER_ALLOW_LAZY_COMPILE max warm-interpreter-cache取消该变量。只检查不编译用--check报告本机是否已经预热$ max warm-interpreter-cache --check机器已预热时退出码为0否则为1因此可以在初始化脚本或健康检查中直接分支判断。强制重编译在已预热的机器上再次运行不会做任何事工具链变化后可用--force强制重编译$ max warm-interpreter-cache --force控制并行度编译在 worker 进程中并发进行默认每个算子族一个 worker上限为 CPU 数。用--jobs限制 worker 数或--jobs 1在进程内串行编译。该子命令的源码入口是 max/python/max/_entrypoints/pipelines.py 中的cli_warm_interpreter_cache注册于第 659 行它会批量编译所有已注册的算子族并把本机标记为已初始化provisioned后续 eager 进程以一次批量加载的方式采纳这份预热缓存而不是逐个目标现场编译。max list发现 MAX 支持的架构max list列出注册到 MAX 的全部管线架构以及每个架构的示例 Hugging Face 仓库 ID 和支持的数据类型编码用来确定max serve、max generate、max encode可以传什么模型max list输出按架构分组每个条目下列出示例仓库与支持编码Architecture: Llama3 Example Huggingface Repo Ids: modularai/Llama-3.1-8B-Instruct-GGUF Encoding Supported: float32 Encoding Supported: bfloat16脚本或其他工具需要机器可读输出时加--jsonmax list --jsonJSON 输出的结构为{architectures: {name: {example_repo_ids: [...], supported_encodings: [...]}}}。源码层面list子命令对应 max/python/max/_entrypoints/pipelines.py 中的cli_list注册于第 780 行其核心逻辑在max._entrypoints.cli.list模块的list_pipelines_to_console中实现支持文本与 JSON 两种输出格式。实战建议与适用前提先max list再选模型不确定某个模型/架构能否运行先跑max list对照示例仓库 ID 与支持的数据类型float32 / bfloat16 等避免在serve/generate/encode阶段才发现不兼容。服务端压测顺序max serve启动服务 →max benchmark压测max benchmark的默认目标是localhost:8000的modular后端测试其他后端vllm、sglang、trtllm等时显式指定--backend与--base-url。多轮与缓存指标需要评估前缀缓存/多轮对话场景时使用--num-chat-sessions与适合的数据集如chat-judge、agentic-code并保持--kv-block-size与服务端--kv-cache-page-size一致以获得准确的缓存保留率。可复现压测--seed默认固定为24301需要随机负载时显式传--seed none取值会记录在结果中。CI 构建 MEF 缓存在没有部署硬件的构建机上用max warm-cache --target cuda:sm_90或其他目标借助虚拟设备编译注意编译产物与平台绑定需在目标平台同类机器上使用。容器初始化预热把max warm-interpreter-cache放进 Dockerfile 的安装步骤之后可在首次真实推理时省去几分钟的逐组合编译注意MAX_EAGER_ALLOW_LAZY_COMPILE0/MAX_EAGER_OP_PRECOMPILE1与预热的冲突关系。设备选择纪律max serve用--devices如gpu:0,1或gpu:all选择设备避免与CUDA_VISIBLE_DEVICES叠加使用造成多进程设备路由错误。以上命令均来自max这一单一入口max/python/max/_entrypoints/pipelines.py参数解析由 click 框架统一完成因此子命令间的--model、--task、采样与批次参数风格一致从服务、压测到缓存预热可以形成一条完整的部署流水线。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考