mxdeploy

国产 GPU（MetaX 曦云 C500 / MXMACA 生态）一键部署 + 评测 + AI 排障 CLI。 一条命令把模型跑起来，出 benchmark 报告，报错自动诊断。

📖 新手教程：docs/TUTORIAL.md — 从安装到实战，10 分钟上手。

Features

• 一键部署：精度检查 → vLLM 配置生成 → 服务拉起 → 健康检查，全程自动化，FP8 等不支持的模型自动拦截；HF 模型自动下载（带实时进度条）
• 环境体检：自动检测 mx-smi / torch(+metax) / vLLM(+maca) 适配状态，秒级出报告（读包元数据，不加载 torch）
• 性能评测：流式压测吞吐 / 首token延迟 / P95 / TPOT / 显存，输出 table / JSON / Markdown 报告
• AI 排障：内置真实踩坑知识库（12 条规则），喂日志即出根因和修复方案，critical 级别自动失败退出
• 趣味进度反馈：init / deploy / bench / doctor 全部带进度条 + 各命令专属颜文字话术轮换（等待不再干等）

安装

pip install mxdeploy

要求 Python 3.10+，目标平台为 Linux（模力方舟曦云 C500 实测环境）。

快速开始

# 1. 环境体检 —— 检测 mx-smi / torch(+metax) / vLLM(+maca)
mxdeploy init

# 2. 一键部署模型（HF 模型自动下载 + 进度条）
mxdeploy deploy Qwen/Qwen2.5-3B-Instruct

# 3. 性能测试，出报告（自动探测已部署模型）
mxdeploy bench

# 4. AI 排障 —— 把报错日志喂给它
mxdeploy doctor deploy.log

命令一览

实测数据（模力方舟曦云 C500 16G vGPU，统一：并发8/请求50/max_tokens 256/util 0.8）

完整矩阵报告见 docs/BENCHMARK_MATRIX_C500_16G.md。

64G 整卡（模力方舟曦云 C500 64G，PyTorch 可见 63.59 GiB，同参数）

关键洞察：14B-INT4 eager 在 64G 整卡 46.57 t/s ≈ 16G vGPU 的 46.58 t/s——同一物理卡计算力，vGPU 分片不影响 eager 吞吐；64G 的优势是能跑 compile 模式和更大模型。 完整报告见 docs/BENCHMARK_64G_C500.md。

排障知识库

全部规则来自真实部署实测，命中即给出修复方案：

兼容性

• 平台：Linux（模力方舟曦云 C500 实例实测）
• Python：3.10+
• 依赖：沐曦适配版 torch（+metax）、vllm（+maca）——切勿用 pip 覆盖官方适配版
• 注意：非交互 SSH 环境需显式 export MACA_PATH=/opt/maca

开发

git clone https://github.com/leo1852098393-blip/mxdeploy
cd mxdeploy
pip install -e ".[dev]"
pytest        # 53 tests

License

Apache-2.0