mxdeploy
国产 GPU（MetaX 曦云 C500 / MXMACA 生态）一键部署 + 评测 + AI 排障 CLI。 一条命令把模型跑起来，出 benchmark 报告，报错自动诊断。
📖 新手教程：docs/TUTORIAL.md — 从安装到实战，10 分钟上手。
Features
- 一键部署：精度检查 → vLLM 配置生成 → 服务拉起 → 健康检查，全程自动化，FP8 等不支持的模型自动拦截
- 环境体检：自动检测 mx-smi / torch(+metax) / vLLM(+maca) 适配状态，部署前先排雷
- 性能评测：流式压测吞吐 / 首token延迟 / P95 / TPOT / 显存，输出 table / JSON / Markdown 报告
- AI 排障：内置真实踩坑知识库（8+ 条规则），喂日志即出根因和修复方案，critical 级别自动失败退出
安装
pip install mxdeploy
要求 Python 3.10+，目标平台为 Linux（模力方舟曦云 C500 实测环境）。
快速开始
# 1. 环境体检 —— 检测 mx-smi / torch(+metax) / vLLM(+maca)
mxdeploy init
# 2. 一键部署模型
mxdeploy deploy Qwen/Qwen2.5-3B-Instruct
# 3. 性能测试，出报告
mxdeploy bench Qwen/Qwen2.5-3B-Instruct
# 4. AI 排障 —— 把报错日志喂给它
mxdeploy doctor deploy.log
命令一览
| 命令 | 功能 |
|---|---|
mxdeploy init |
环境体检：mx-smi / torch / vLLM / 系统信息 |
mxdeploy deploy <model> |
一键部署：精度检查、配置生成、服务拉起、健康检查 |
mxdeploy bench <model> |
性能测试：吞吐 / TTFT / P95 / TPOT / 显存 |
mxdeploy doctor <log> |
AI 排障：规则引擎 + LLM 分析 |
mxdeploy version |
版本信息 |
实测数据（模力方舟曦云 C500 16G vGPU，统一：并发8/请求50/max_tokens 256/util 0.8）
| 模型 | 精度 | 模式 | 吞吐 (t/s) | TTFT (ms) | TPOT (ms) | 成功率 |
|---|---|---|---|---|---|---|
| Qwen2.5-1.5B | FP16 | compile | 204.75 | 38.15 | 4.77 | 100% |
| DeepSeek-R1-Distill-1.5B | FP16 | compile | 200.55 | 34.54 | 4.93 | 100% |
| Qwen2.5-3B | FP16 | compile | 153.65 | 48.21 | 6.40 | 100% |
| Qwen2.5-7B-GPTQ-Int8 | INT8 | compile | 159.21 | 41.67 | 6.15 | 100% |
| GLM-4-9B-GPTQ-Int4 | INT4 | eager | 90.51 | 45.97 | 10.79 | 100% |
| Qwen2.5-14B-GPTQ-Int4 | INT4 | eager | 46.58 | 1398.79 | 14.05 | 100% |
完整矩阵报告见 docs/BENCHMARK_MATRIX_C500_16G.md。
排障知识库
全部规则来自真实部署实测，命中即给出修复方案：
| 规则 | 场景 |
|---|---|
| NET-001 | huggingface.co 超时 → 自动提示 HF_ENDPOINT 镜像 |
| ENV-001 | 非交互 SSH 缺 MACA_PATH → vLLM import 崩溃 |
| PIP-001 | pip 覆盖官方 torch(+metax) 适配版 |
| FP8-001 | 曦云 C500 不支持 FP8 → 提示换 FP16/INT8 |
| OOM-001 | 显存不足 → 给出量化/换卡建议 |
| MEM-002 | util 0.9 + torch.compile autotune OOM → 降 0.8 |
| MISC-003 | 模型需 trust-remote-code → 加 --trust-remote-code |
| MISC-004 | 量化版缺 chat_template → 从官方仓库补齐 tokenizer |
| ... | 更多规则见 mxdeploy doctor --list |
兼容性
- 平台：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 # 40 tests
License
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
mxdeploy-0.2.0.tar.gz
(32.6 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
mxdeploy-0.2.0-py3-none-any.whl
(31.6 kB
view details)
File details
Details for the file mxdeploy-0.2.0.tar.gz.
File metadata
- Download URL: mxdeploy-0.2.0.tar.gz
- Upload date:
- Size: 32.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1cee903dd446442c1610788e646683471307da04e3f3541b8b089cb950ebad24
|
|
| MD5 |
4a9ef488aa39f4cf75a9ff1789482f47
|
|
| BLAKE2b-256 |
ac9f87319cf208961c53a35704d7d85dfcd173d6b324838bc97107a2e6378cfa
|
File details
Details for the file mxdeploy-0.2.0-py3-none-any.whl.
File metadata
- Download URL: mxdeploy-0.2.0-py3-none-any.whl
- Upload date:
- Size: 31.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c5863300d9605c5dfb996e263de6e3980c6bbe555dfad63232c95108560fd3f0
|
|
| MD5 |
51bdaa8edd8f77710aec4425f01d6966
|
|
| BLAKE2b-256 |
59dadd5d782581e82d428e95495fed631dcfbbb4eae8af84f21d887ffdebfd64
|
