企业官网建设流程全解析

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

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

导读

max是 Modular Platform（MAX & 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,sagemaker：

• openai：/v1/completions、/v1/chat/completions、/v1/embeddings、/v1/models、/v1/health
• sagemaker：SageMaker 兼容的推理端点
• kserve：KServe 兼容的推理端点
• responses：/v1/responses（pixel_generation任务必需）

注意：OpenAI 路由在启用openai类型时总是被注册，但每个路由只有在模型以兼容的--task值提供服务时才真正生效——例如/v1/embeddings需要embeddings_generation任务。各端点 API 的详细说明见仓库文档 docs/max/rest-api/。

如果不需要 HTTP 服务、只想直接跑推理，可以改用max generate（文本补全）或max encode（embedding）。

多 GPU 与设备选择

向--devices传入逗号分隔的 GPU ID 列表即可使用多卡：

max serve \ --model google/gemma-3-12b-it \ --devices=gpu:0,1,2,3 \ --max-batch-size 16

• 用--devices=gpu:all可选中所有可见 GPU；
• 省略--devices时使用模型或配置的默认设备。

--devices是max serve的一等设备选择器，建议不要与 shell 层的CUDA_VISIBLE_DEVICES混用——两者是独立翻译的，叠加使用在多进程工作区中可能产生错误的设备路由。

加载自定义模型架构

可以通过--custom-architectures把自定义模型实现挂到 MAX 上，每个值的形式为path/to/module:module_name：

max 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：文本转 embedding

max 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.json

max 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。
• --model：Hugging Face 模型 ID 或本地路径。
• --endpoint：具体 API 端点，如/v1/completions或/v1/chat/completions。默认/v1/chat/completions。
• --base-url：API 服务的基础 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、seed），CLI 参数优先于文件值。

数据集选择

• --dataset-name：压测所用的数据集，决定数据集类与处理逻辑，默认sharegpt。
• --dataset-path：本地数据集文件路径，仅对支持本地覆盖的数据集有效。

输出控制

• --max-output-len：每个请求的最大输出长度（token 数）。
• --temperature、--top-p、--top-k：转发给服务器的采样参数。

LoRA 流量

• --lora：随每个请求发送的可选 LoRA 名称。
• --lora-paths：现有 LoRA adapter 路径，每项为path或name=path。
• --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 version=0.3.3 tp=1。
• --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。
• axolotl：Axolotl 格式的人/助对话数据集，使用打包的默认文件，可用--dataset-path覆盖。
• chat-judge：LLM-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-job：OpenAI Batch API 格式的批量图像负载，需--dataset-path（tar 归档或含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 数。
• TTFT（time to first token）：从请求开始到生成第一个 token 的时间。
• TPOT（time per output token）：生成每个输出 token 的平均耗时。
• ITL（inter-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 Format（MEF）本身是平台无关的，但编译过程中产出的序列化缓存（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_COMPILE=0（真实预热时）或MAX_EAGER_OP_PRECOMPILE=1（任一模式）；--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

脚本或其他工具需要机器可读输出时，加--json：

max list --json

JSON 输出的结构为{"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_COMPILE=0/MAX_EAGER_OP_PRECOMPILE=1与预热的冲突关系。
• 设备选择纪律：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