@lvxintao/mt-mlx-cli

v1.3.2

Published

a month ago

CLI tool for MLX model training platform

0High
0Medium
0Low

lvxintao

mt-mlx-cli

美团 Poker MLX 算法平台的命令行工具，覆盖从算法开发到模型上线的完整链路。

当前版本：v1.2.2

安装

npm install -g @lvxintao/mt-mlx-cli@latest --registry=http://r.npm.sankuai.com

资源文件

skills/mt-mlx-cli/SKILL.md — Claude Code 技能文件，提供交互式 AI 辅助
skills/mt-mlx-cli/examples/ — 完整 YAML 配置模板（训练/评估/预测），包含所有字段注释

认证

v1.2.2 起默认使用 MTSSO 无浏览器认证，无需打开浏览器；MTSSO 不可用时自动回退到浏览器 SSO 登录。

mt-mlx-cli login        # 认证（MTSSO 无浏览器）
mt-mlx-cli status       # 确认登录状态
mt-mlx-cli logout       # 清除凭据

命令总览

| 命令 | 用途 | |------|------| | login / logout / status | 认证管理 | | model | 算法管理（创建、Fork、更新、运行、发布、列表、查版本） | | train | 训练任务（提交、状态、指标、列表、配置导出、停止） | | eval | 评估任务（提交、状态、指标、列表、配置导出、停止） | | predict | 预测任务（提交、状态、列表、配置导出、停止） | | serving | 在线服务模型管理 | | config | CLI 配置管理 | | update | 检查并升级 CLI |

核心概念

| 概念 | 说明 | 获取方式 | |------|------|---------| | algo-id | 算法唯一标识（数字） | model list / model new / model fork 返回 | | taskId | 训练/评估/预测任务唯一标识 | 提交任务后返回 | | modelVersion | 某次训练产出的模型版本，可以是名称字符串（如 "20260723143304705537"）或数字 ID（如 1956369） | model latest-version <algo-id> 查最新已发布版本；train config <taskId> 看某次训练的具体版本 |

算法管理（model）

算法的生命周期：new → run → publish。已发布的算法不可变，如需修改请 Fork 或创建新算法。

model new — 创建算法

mt-mlx-cli model new --name "ctr_v2" --files model.py config.py --description "CTR预估V2"
# 返回 algo-id

| 参数 | 说明 | 默认值 | |------|------|--------| | --name <name> | 算法名称 | 必填 | | --files <files...> | 上传的源文件 | 必填 | | --description <desc> | 算法描述 | Created via CLI | | --verbose | 详细日志 | false |

model fork — Fork 算法

mt-mlx-cli model fork 40801 --name "ctr_v3_improved"
# 返回新的 algo-id

| 参数 | 说明 | 默认值 | |------|------|--------| | --name <name> | 新算法名称 | 必填 | | --verbose | 详细日志 | false |

model get — 下载算法代码

mt-mlx-cli model get 40801

| 参数 | 说明 | 默认值 | |------|------|--------| | --verbose | 详细日志 | false |

model update — 更新算法文件

仅限未发布算法。已发布算法不可修改。

mt-mlx-cli model update 40801 --files model.py custom_layer.py

| 参数 | 说明 | 默认值 | |------|------|--------| | --files <files...> | 要上传/更新的源文件 | 必填 | | --verbose | 详细日志 | false |

model run — 运行算法

触发平台编译检查，算法状态变为"运行成功"后方可发布。

mt-mlx-cli model run 41755                # 触发运行
mt-mlx-cli model run 41755 --status       # 查看最新运行状态和日志

| 参数 | 说明 | 默认值 | |------|------|--------| | --status | 查看最新运行状态和日志 | false | | --verbose | 详细日志 | false |

model publish — 发布算法

运行成功后发布。一旦发布，算法不可变。

mt-mlx-cli model publish 41757           # 发布到私有仓库
mt-mlx-cli model publish 41757 --public  # 发布到公共仓库

| 参数 | 说明 | 默认值 | |------|------|--------| | --public | 发布到公共仓库 | false（私有） | | --verbose | 详细日志 | false |

model list — 列出算法

mt-mlx-cli model list                     # 列出我的算法（最近 20 条）
mt-mlx-cli model list --search "ctr"      # 按名称搜索
mt-mlx-cli model list --all               # 列出所有算法
mt-mlx-cli model list --all --search "ctr" --limit 50

| 参数 | 说明 | 默认值 | |------|------|--------| | --all | 列出所有算法（非仅当前用户） | false | | --search <keyword> | 按名称搜索 | - | | --limit <n> | 最大返回条数 | 20 | | --verbose | 详细日志 | false |

model latest-version — 获取最新发布版本

mt-mlx-cli model latest-version 41767
mt-mlx-cli model latest-version 41767 --json   # JSON 格式输出

| 参数 | 说明 | 默认值 | |------|------|--------| | --json | 以 JSON 格式输出 | false | | --verbose | 详细日志 | false |

训练任务（train）

训练任务统一通过 YAML 配置文件提交。命令行不再提供 --sample-from、--algo-id 等旧版 CLI 参数。

train — 提交训练

# 从 YAML 文件提交
mt-mlx-cli train --yaml train-config.yaml

# 以已有任务为模板（保留原配置，YAML 只写要覆盖的字段）
mt-mlx-cli train --template 660152 --yaml override.yaml

| 参数 | 说明 | 默认值 | |------|------|--------| | --yaml <path> | YAML 配置文件路径 | - | | --template <taskId> | 以已有训练任务配置为模板 | - | | --verbose | 详细日志 | false |

train config — 导出配置

mt-mlx-cli train config 660152                   # 查看配置
mt-mlx-cli train config 660152 --out config.yaml # 导出到文件

train status — 查看状态

mt-mlx-cli train status 660152
mt-mlx-cli train status 660152 --log             # 含日志

| 参数 | 说明 | 默认值 | |------|------|--------| | --log | 显示最新一次尝试的日志 | false | | --verbose | 详细日志 | false |

train metrics — 查看指标

按 session 展示训练指标（AUC、Loss 等），跨 worker 加权平均。

mt-mlx-cli train metrics 660463

train list — 列出任务

mt-mlx-cli train list
mt-mlx-cli train list --filter-algo-id 41767 --limit 20
mt-mlx-cli train list --filter-status "运行中"

| 参数 | 说明 | 默认值 | |------|------|--------| | --filter-status <status> | 按状态筛选 | - | | --filter-name <keyword> | 按任务名称模糊匹配 | - | | --filter-algo-id <id> | 按算法 ID 筛选 | - | | --limit <n> | 最大返回条数 | 20 | | --verbose | 详细日志 | false |

train stop — 停止任务

mt-mlx-cli train stop 660164

训练 YAML 最小配置

name: "ctr_v2_train"

train_config:
  algorithm_id: 41767
  epoch: 2
  base_dir: "viewfs://hadoop-meituan/user/hadoop-traffic/your_path/train_data"
  start_time: [2026, 7, 1]       # [年, 月, 日]
  end_time: [2026, 7, 20]

worker_config:
  batch_size: 384
  label_parse: "0:-1:1;1:0:1"
  shuffle_size: 10000
  eval_batch_size: 500000

psConfig:
  workerNum: 29
  workerCpu: 2
  workerMem: 4096

model_config:
  hparams:
    - graph_alpha: 0.00005
      embed_alpha: 0.0004

run_config:
  mode: "cpu"
  worker_num: 160
  worker_memory: "2048m"
  worker_vcore: 96
  executor_memory: "4096m"
  executor_vcore: 2
  data_reader_threads: 80
  data_parser_threads: 15
  run_class: "TrainModel"
  params:
    run_mode: "train"

hadoop_config:
  group_id: 5
  queue: "root.zw01.hadoop-traffic.dsp"

增量训练

在 train_config 中加入增量训练字段：

train_config:
  # ... 其他字段 ...
  incrementTrain: true
  epoch_offset: 0
  input_model_path: "viewfs://hadoop-meituan/.../model_workspace/lvxintao/model/xxx/20260723143304705537"
  input_model_version_id: 1956369

评估任务（eval）

与训练任务接口一致，通过 YAML 配置提交。

eval — 提交评估

mt-mlx-cli eval --yaml eval-config.yaml
mt-mlx-cli eval --template 662109 --yaml override.yaml

eval config / status / metrics / list / stop

与 train 对应子命令用法完全相同。

mt-mlx-cli eval config 662109 --out eval-config.yaml
mt-mlx-cli eval status 662109 --log
mt-mlx-cli eval metrics 662109
mt-mlx-cli eval list --filter-algo-id 41767
mt-mlx-cli eval stop 662109

评估 YAML 最小配置

name: "ctr_v2_eval"
modelVersion: "20260723143304705537"    # 不填则用最新发布版本

train_config:
  algorithm_id: 41767
  epoch: 1
  base_dir: "viewfs://hadoop-meituan/user/hadoop-traffic/your_path/eval_data"
  start_time: [2026, 7, 21]
  end_time: [2026, 7, 22]
  run_gauc: true
  run_pfi: false

worker_config:
  batch_size: 384
  label_parse: "0:-1:1;1:0:1"
  shuffle_size: 10000
  eval_batch_size: 500000

psConfig:
  workerNum: 29
  workerCpu: 2
  workerMem: 4096

model_config:
  hparams: []
  graph_state:
    phase: "EVALUATE"
    stage: ["predict_offline"]

run_config:
  mode: "cpu"
  worker_num: 160
  worker_memory: "2048m"
  worker_vcore: 96
  executor_memory: "1024m"
  executor_vcore: 2
  data_reader_threads: 80
  data_parser_threads: 15
  run_class: "AllDaysUnion"
  params:
    run_mode: "eval"
    separate_result_by_date: true

hadoop_config:
  group_id: 5
  queue: "root.zw01.hadoop-traffic.query"

预测任务（predict）

与 train/eval 一致的 YAML 驱动接口。

predict — 提交预测

mt-mlx-cli predict --yaml predict-config.yaml
mt-mlx-cli predict --template 660200 --yaml override.yaml

predict config / status / list / stop

mt-mlx-cli predict config 660200 --out predict-config.yaml
mt-mlx-cli predict status 660200
mt-mlx-cli predict list --filter-algo-id 41767
mt-mlx-cli predict stop 660200

预测 YAML 最小配置

name: "ctr_v2_predict"
modelVersion: "20260723143304705537"
stage: "item_on_predict"
savePath: "viewfs://hadoop-meituan/user/hadoop-traffic/your_path/predict_results"

train_config:
  algorithm_id: 41767
  epoch: 1
  base_dir: "viewfs://hadoop-meituan/user/hadoop-traffic/your_path/predict_data"
  start_time: [2026, 7, 23]
  end_time: [2026, 7, 23]

worker_config:
  batch_size: 384
  label_parse: "0:-1:1;1:0:1"

psConfig:
  workerNum: 29
  workerCpu: 1
  workerMem: 1552

model_config:
  hparams: []
  graph_state:
    phase: "PREDICT"
    stage: ["item_on_predict"]

run_config:
  mode: "cpu"
  worker_num: 160
  worker_memory: "2048m"
  worker_vcore: 96
  executor_memory: "1024m"
  executor_vcore: 2
  data_reader_threads: 80
  data_parser_threads: 15
  run_class: "AllDaysUnion"
  params:
    run_mode: "pred"
    save_path: "viewfs://hadoop-meituan/user/hadoop-traffic/your_path/predict_results"

hadoop_config:
  group_id: 5
  queue: "root.zw01.hadoop-traffic.mining"

YAML 配置说明

所有任务（train/eval/predict）均通过 YAML 文件配置，支持以下 6 个顶层配置块：

| 配置块 | 说明 | |--------|------| | train_config | 训练/数据相关配置（algorithm_id、epoch、base_dir、日期、增量训练等） | | worker_config | Worker 参数（batch_size、label_parse、shuffle_size 等） | | psConfig | 参数服务器配置（workerNum、workerCpu、workerMem） | | model_config | 模型配置（hparams、graph_state 等） | | run_config | 运行环境配置（mode、worker 资源、线程数、runClass 等） | | hadoop_config | Hadoop 配置（group_id、queue 等） |

配置复用技巧

导出已有配置再修改（推荐）：

mt-mlx-cli train config <历史taskId> --out config.yaml
# 编辑 config.yaml 调整参数
mt-mlx-cli train --yaml config.yaml

模板 + 覆盖（更轻量）：

mt-mlx-cli train --template <历史taskId> --yaml override.yaml

override.yaml 只写需要覆盖的字段，其余沿用模板原有值。

⚠️ 日期格式：使用数组 [年, 月, 日]，如 [2026, 7, 22]，不要用字符串。

在线服务（serving）

serving new — 提交上线

mt-mlx-cli serving new \
  --model-name "ctr_v2" \
  --model-path "viewfs://hadoop-meituan/.../model_workspace/lvxintao/model/ctr_v2/20260723143304705537" \
  --ps-appkey "com.sankuai.mtscene.lp.mlxps" \
  --predictor-appkey "com.sankuai.dsp.mlx.predictor" \
  --yarn-queue "root.zw01.hadoop-traffic.dsp"

| 参数 | 说明 | 默认值 | |------|------|--------| | --model-name <name> | 服务模型名称 | 必填 | | --model-path <path> | 模型 HDFS 路径 | 必填 | | --ps-appkey <appkey> | PS 集群 appkey | 必填 | | --predictor-appkey <appkey> | Predictor 集群 appkey | 必填 | | --yarn-queue <queue> | YARN 队列 | 必填 | | --verbose | 详细日志 | false |

serving list / get — 查看

mt-mlx-cli serving list
mt-mlx-cli serving get <id>

CLI 配置管理（config）

配置存储在 ~/.mt-cli/config.json，作为持久化默认值。

mt-mlx-cli config list                    # 列出所有配置
mt-mlx-cli config get <key>               # 获取指定配置
mt-mlx-cli config set <key> <value>       # 设置配置

升级（update）

mt-mlx-cli update              # 检查并提示升级
mt-mlx-cli update --check      # 仅检查，不升级
mt-mlx-cli update --yes        # 自动升级，无需确认

典型工作流

从零开发并训练模型

# 1. 创建算法
mt-mlx-cli model new --name "my_model" --files model.py config.py --description "我的模型"
# → algo-id: 41767

# 2. 运行并发布
mt-mlx-cli model run 41767
mt-mlx-cli model run 41767 --status        # 等待运行成功
mt-mlx-cli model publish 41767

# 3. 准备训练配置并提交
mt-mlx-cli train --yaml train-config.yaml
# → taskId: 660152

# 4. 监控训练
mt-mlx-cli train status 660152
mt-mlx-cli train metrics 660152

迭代已发布算法

# 1. Fork 创建副本
mt-mlx-cli model fork 41767 --name "my_model_v2"

# 2. 拉取代码、本地修改、上传
mt-mlx-cli model get <新algo-id>
# 编辑代码...
mt-mlx-cli model update <新algo-id> --files model.py

# 3. 运行、发布、训练
mt-mlx-cli model run <新algo-id>
mt-mlx-cli model publish <新algo-id>
mt-mlx-cli train --yaml train-config.yaml

基于历史训练快速调整

# 导出历史任务配置
mt-mlx-cli train config 660152 --out config.yaml

# 编辑 config.yaml（比如只改日期和 batch_size）
# 然后提交
mt-mlx-cli train --yaml config.yaml

训练 → 评估 → 预测 → 上线

# 1. 训练完成后，导出配置获取 modelVersion
mt-mlx-cli train config 660152

# 2. 按需评估
mt-mlx-cli eval --yaml eval-config.yaml

# 3. 批量预测
mt-mlx-cli predict --yaml predict-config.yaml

# 4. 模型上线
mt-mlx-cli serving new \
  --model-name "my_model" \
  --model-path "viewfs://hadoop-meituan/.../model_workspace/lvxintao/model/my_model/20260723143304705537" \
  --ps-appkey "com.sankuai.mtscene.lp.mlxps" \
  --predictor-appkey "com.sankuai.dsp.mlx.predictor" \
  --yarn-queue "root.zw01.hadoop-traffic.dsp"

问题排查

# 1. 认证过期
mt-mlx-cli logout && mt-mlx-cli login

# 2. 任务失败 —— 看状态和日志
mt-mlx-cli train status <taskId> --log

# 3. 检查配置
mt-mlx-cli train config <taskId> --out debug.yaml

# 4. 查看指标
mt-mlx-cli train metrics <taskId>

# 5. 停止跑飞的任务
mt-mlx-cli train stop <taskId>
mt-mlx-cli eval stop <taskId>
mt-mlx-cli predict stop <taskId>

常见问题：

Loss 不下降 / AUC 异常 → 检查样本数据、label_parse 是否写反、模型代码是否有 bug
任务挂掉 → 看日志找 OOM 或数据读取错误
401 / 403 → 认证票据过期，重新 login

重要约束

已发布算法不可变：model publish 后只能 model fork 或 model new，不能 model update
先运行再发布：model new/update → model run（等成功）→ model publish
YAML 日期用数组格式：start_time: [2026, 7, 22]，不是字符串
modelVersion 默认行为：eval/predict 不填时自动使用算法最新发布版本

开发

# 安装依赖
npm install

# 构建
npm run build

# 开发模式运行
npm run dev -- train --help

# 运行测试
npm test
npm run test:watch

目录结构

mt-mlx-cli/
├── src/
│   ├── api/              # HTTP 客户端及 API 方法
│   ├── auth/             # MTSSO / SSO 认证
│   ├── cli/              # CLI 入口及命令实现
│   ├── config/           # 默认值与参数解析
│   ├── utils/            # 工具函数（配置存储、格式化、YAML 解析等）
│   └── types.ts          # 共享类型定义
├── tests/
│   └── unit/             # 单元测试
└── package.json

License

MIT