故障排查
先运行：
kt version
kt doctor
安装问题
| 现象 | 检查项 |
|---|---|
找不到 kt 命令 | 确认已激活安装 kt-kernel 的环境。 |
| import 或 wheel 错误 | 确认 Python 版本和 Linux x86-64 环境。 |
| CUDA 相关失败 | 确认驱动、PyTorch CUDA 变体和 GPU 架构。 |
| 未选择 AMX kernel | 检查 lscpu flags 以及 BIOS/kernel AMX 支持。 |
Serving 问题
| 现象 | 检查项 |
|---|---|
| 服务启动但模型加载失败 | 确认 --model-path、--kt-weight-path、--kt-method 匹配。 |
| 输出格式异常 | 检查 chat template、parser options 和 served model name。 |
| 启动 OOM | 降低 GPU expert 数或 token limits；确认模型特定内存假设。 |
| prefill 慢 | 检查 method、CPU backend、NUMA 设置和 layerwise prefill threshold。 |
微调问题
| 现象 | 检查项 |
|---|---|
| KT backend 未启用 | 确认 training YAML 中有 use_kt: true，Accelerate config 中有 kt_config.enabled: true。 |
| Backend mismatch | kt_backend 必须匹配 BF16 或已转换 INT8/INT4 expert 权重。 |
| LLaMA-Factory 无法 import KT 包 | 确认在 LLaMA-Factory 环境执行了 pip install -r requirements/ktransformers.txt。 |
上报问题需要的信息
提交 issue 时带上 runtime tuple、完整启动命令、包版本、硬件摘要和最早的 blocking log。