KTransformers kt-kernel CLIkt设计与实战统一命令行驱动推理、量化与诊断【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers本文基于官方文档 kt-cli.md 与kt-kernel/python/cli/下的完整实现源码展开。读完本文你将掌握kt命令的双模设计交互式引导 / 直接传参自动化、首次运行初始化流程、run/chat/quant/model/config/bench/doctor/sft等全部子命令的参数细节与底层调用链并能结合配置项与诊断项把 CLI 真正用于 MoE 模型的 CPU/GPU 异构推理落地。官方文档注KT-CLI 仍处于活跃开发阶段under active development部分功能尚未完成例如本文后文将说明microbench与sft在当前源码中仍是“coming soon”占位。一、设计哲学双模运行降低文档阅读成本原文档对 KT-CLI 的设计哲学给出了三点核心主张交互式模式Interactive Mode不带参数直接运行命令CLI 会给出分步引导提示step-by-step guided prompts用户无需通读长篇文档即可完成任务直接模式Direct Mode直接传参用于自动化与脚本场景参数兼容性直接模式的参数与前文 SGLang KTransformers 的工作流完全兼容可以无缝迁移。这三点在源码中都有明确对应可以在 主入口文件 中找到交互式模式的总开关typer.Typer(..., no_args_is_helpFalse, ...)见 main.py#L48-L54。no_args_is_helpFalse让“不带参数运行kt”不再直接打印帮助而是进入人工处理分支若是首次运行则启动初始化向导否则才回退打印帮助见 main.py#L503-L524。SGLang 参数透传兼容性的实现核心kt run之所以能“无缝迁移”旧 SGLang 启动参数是因为main()中对run做了特殊短路处理——绕过 typer 的常规校验直接把kt run之后的所有参数交给底层 click 命令见 main.py#L535-L541而 run 命令 使用context_settings{ignore_unknown_options: True, allow_extra_args: True}声明见 run.py#L34-L37未识别的选项会被收集进ctx.args原样追加到最终 SGLang 启动命令中。命令帮助文本的国际化_get_help()维护了version/chat/quant/bench/microbench/doctor/model/config/sft等命令的英文与中文帮助文案见 main.py#L28-L44配合kt-kernel/python/cli/i18n.py的语言机制实现--help输出的双语化。1.1 命令入口与帮助输出按原文档说明通过kt --help查看用法kt [OPTIONS] COMMAND [ARGS]...输出为 “KTransformers CLI - A unified command-line interface for KTransformers.”。选项仅有--help。命令清单与 main.py 中的注册代码 对应命令说明源自 main.py 帮助文案version显示版本信息chat与运行中的模型进行交互式聊天quant量化模型权重bench运行完整基准测试microbench运行微基准测试doctor诊断环境问题model管理模型和存储路径config管理配置sft使用 LlamaFactory 进行微调从源码结构看文档命令表之外还有两个注册入口kt edit编辑模型信息main.py#L473以及kt run启动推理服务器未出现在--help表中因为它是被main()特殊接管调用的main.py#L534-L541。CLI 的版本号来自已安装的kt-kernel包元数据包缺失时回退读取仓库根目录 version.py见 cli/init.py#L12-L21。二、首次运行初始化向导语言、模型发现、存储路径原文档强调“直接运行命令CLI 会交互式引导你完成流程”。kt无参运行时的首次初始化正是这句话的落地其流程在 _show_first_run_setup 中实现包含三个阶段语言选择1 English / 2 中文结果写入配置项general.language并调用set_lang()即时生效模型权重发现提供三种方式1全局扫描调用discover_and_register_global(min_size_gb2.0, max_depth6, ...)自动扫描所有非系统路径main.py#L178-L1802手动指定路径循环调用discover_and_register_path(...)逐个目录扫描并去重3跳过稍后用kt model手动管理模型存储路径选择scan_storage_locations(min_size_gb50.0)扫描可用磁盘空间最小 50GB 的挂载点展示前 5 个选项并允许自定义路径默认回退~/.ktransformers/models选中路径若剩余空间不足 100GB 会给出黄色警告最终写入配置项paths.models并置general._initializedTrue。首次运行还会自动安装 Shell 补全脚本按$SHELL检测 bash/zsh/fish将 completions 目录下的kt-completion.bash/_kt/kt.fish复制到~/.local/share/bash-completion/completions/、~/.zfunc/、~/.config/fish/completions/等标准补全目录见 _install_shell_completion。这也是app typer.Typer(add_completionFalse)禁用 typer 动态补全、改用静态补全脚本的原因。三、配置文件体系~/.ktransformers/config.yaml所有命令共享同一套配置管理实现在 config/settings.py配置文件位于~/.ktransformers/config.yamlDEFAULT_CONFIG_FILEsettings.py#L13-L17加载时以DEFAULT_CONFIG为基底深合并用户配置解析失败时打警告并沿用默认值语言解析优先级为KT_LANG环境变量 配置文件general.language 系统 locale见 _apply_saved_language。DEFAULT_CONFIG 定义的默认键值如下可直接作为运维参考配置键默认值含义general.languageauto界面语言auto/en/zhpaths.models~/.ktransformers/models模型权重存储目录首次向导会改写paths.cache~/.ktransformers/cache缓存目录paths.weights空自定义量化后权重路径kt quant输出优先使用该目录server.host/server.port0.0.0.0/30000推理服务默认监听地址与端口inference.env.PYTORCH_ALLOC_CONFexpandable_segments:True启动推理时注入的环境变量inference.env.SGLANG_ENABLE_JIT_DEEPGEMM0启动推理时注入的环境变量download.resume/download.verifyTrue/True下载断点续传与校验开关advanced.sglang_args/advanced.llamafactory_args[]追加传给 SGLang / LlamaFactory 的额外参数dependencies.sglang.sourcegithubSGLang 安装来源pypi或github配合repo/branch指定 kvcache-ai 分支对应子命令见 commands/config.pykt config init # 重新运行首次设置向导调用 _show_first_run_setup kt config show # 以 YAML 高亮打印全部配置 kt config show server.port # 查看单个键 kt config set key value # 设置配置值自动解析为 bool/int/float/YAML 复合类型 kt config get key # 读取单个键 kt config reset -y # 重置为默认 kt config path # 打印配置文件路径值得注意的是model-path-list / model-path-add / model-path-remove三个旧命令已被标记为 deprecated 并隐藏会转调kt model path-*的新命令config.py#L110-L135说明存储路径管理已收敛到kt model子树下。四、核心命令逐个拆解4.1kt run启动 SGLang 异构推理服务run是整个 CLI 的中心命令以 “SGLang kt-kernel” 组合拉起模型推理服务。参数声明在 run.py#L38-L83常用选项包括选项说明--host/-H、--port/-p服务监听地址与端口缺省取配置server.host/server.port--gpu-experts每层放置到 GPU 的专家数量MoE 异构切分核心参数--cpu-threadsCPU 推理线程数--numa-nodesKT 线程池数量或为每个线程池显式指定 NUMA 节点 ID可多次指定如--numa-nodes 0 --numa-nodes 1--tensor-parallel-size/--tp张量并行规模--model-path、--weights-path自定义模型路径 / 自定义量化权重路径--kt-method、--kt-gpu-prefill-thresholdKT 量化方法、GPU prefill token 阈值--attention-backend、--max-total-tokens、--max-running-requests、--chunked-prefill-size、--mem-fraction-static、--watchdog-timeout、--served-model-name常规服务调优参数--enable-shared-experts-fusion/--disable-shared-experts-fusion共享专家融合开关--quantize/-q启动前执行量化--dry-run只打印将执行的命令而不实际启动--advanced展开高级选项run 命令的 docstring 明确给出了透传约定见 run.py#L111-L119Examples: kt run deepseek-v3 | kt run m2 --tensor-parallel-size 2 | kt run /path/to/model --gpu-experts 4 Custom Options: Pass any SGLang server option directly (e.g., kt run m2 --fp8-gemm-backend triton). Common: --fp8-gemm-backend, --tool-call-parser, --reasoning-parser, --dp-size, --enable-ma这正是原文档“参数与前 SGLang KTransformers 方案完全兼容”的实现机制未声明的选项经ignore_unknown_options收集后原样拼接进 SGLang 启动命令。4.2kt chatOpenAI 兼容的交互式聊天客户端实现见 commands/chat.py完整参数chat.py#L39-L90选项默认值说明--host/-H、--port/-p配置server.host/30000连接的服务地址--model/-m服务端第一个模型多模型服务下指定模型--temperature/-t0.7采样温度0.0–2.0--max-tokens2048最大生成 token 数--system/-s无系统提示词--save-history/--no-save-history开启保存会话历史默认存入~/.ktransformers/chat_history/chat_时间戳.json--history-file无指定历史文件路径--stream/--no-stream开启流式输出运行机理值得展开前置依赖是openaiSDK缺失时提示pip install openai客户端以base_urlhttp://host:port/v1、api_keyEMPTY连接 SGLang 的 OpenAI 兼容端点chat.py#L148-L152连接前会检测HTTP_PROXY/HTTPS_PROXY等代理环境变量若检测到则询问是否使用默认对本地连接临时禁用代理流式路径_stream_response会区分reasoning_content推理链dim 样式与正文输出并尝试用AutoTokenizer精确统计 token 数统计Total / TTFT / TPOT / In / Out四项指标chat.py#L281-L370会话内支持斜杠命令/quit /exit /q退出/help /h帮助/clear /c清空历史/history /hist查看历史/info /i查看当前参数/retry /r撤回上一条助手回复重新生成见 _handle_command。典型用法继承自命令 docstring 示例kt chat # 连接默认服务server.host:30000 kt chat --host 127.0.0.1 -p 8080 # 连接指定服务 kt chat -t 0.9 --max-tokens 4096 # 调整生成参数4.3kt quantAMX 格式量化交互式与直接模式双轨kt quant把 MoE 模型权重转换为 kt-kernel 使用的 AMX 量化 safetensors 格式实现见 commands/quant.py。交互式模式触发条件quant.py#L93-L99未提供model或缺少method/cpu_threads/numa_nodes中任一项且处于 TTY 终端时进入interactive_quant_config()分步引导否则走直接模式。直接模式参数quant.py#L37-L86参数说明model位置参数模型名或路径必填--method/-m量化方法int4直接模式默认或int8--input-type/-i输入权重类型fp8直接模式默认、fp16、bf16--output/-o输出目录缺省时按优先级paths.weights配置目录 首个paths.models目录 模型所在目录命名格式{模型名}-AMX{INT4/INT8}-NUMA{节点数}--cpu-threads量化用 CPU 线程数缺省自动取物理核心数--numa-nodesNUMA 节点数缺省自动检测--no-merge不合并 safetensor 分片--gpu使用 GPU 加速转换--yes/-y跳过所有确认提示执行流程中的关键校验均可在源码中逐条对应拒绝 AMX 格式的输入is_amx_weights()通过解析 safetensors 键中的.numa.N.模式判定见 model.py#L46-L82校验必须是 MoE 模型analyze_moe_model()提示 “AMX quantization is designed for MoE models (e.g., DeepSeek-V3)”磁盘空间分析按量化位宽/输入位宽如 4/16估算输出大小要求可用空间 ≥ 估算值 × 1.2不足则告警并需确认输出目录已存在时自动追加-2、-3后缀避免覆盖最终调用的是仓库内的转换脚本kt-kernel/scripts/convert_cpu_weights.pyCLI 仅做参数拼装与实时输出--input-path/--input-type/--output/--quant-method/--cpuinfer-threads/--threadpool-countquant.py#L313-L343成功后自动将量化产物注册进用户模型注册表UserModelRegistry写入amx_source_model、amx_quant_method、amx_numa_nodes等元数据并提示用kt model list查看、kt run 新模型名使用。4.4kt model模型下载、列表与路径管理model子树实现在 commands/model.py约 2800 行是管理面最大的命令组kt model无子命令回调函数直接调用list_models()展示模型列表含 SHA256 校验状态列not_checked/checking/passed/failed见 model.py#L27-L43kt model download支持交互式分步引导——Step 1 选择仓库源HuggingFace / ModelScope--repo-type/-tStep 2 输入仓库 ID如deepseek-ai/DeepSeek-V3选项有--local-dir/-d缺省按配置自动探测、--resume/--no-resume默认断点续传、--yes/-y跳过所有提示。针对 HuggingFace 不可达的场景下载前会执行 5 秒连通性检查check_huggingface_connectivity(timeout5)失败则自动切换 hf-mirror.com 镜像model.py#L172-L185kt model path-add / path-list / path-remove管理多模型存储路径替代已废弃的kt config model-path-*kt edit编辑模型注册信息由model.edit_model注册到顶层main.py#L473。4.5kt bench与kt microbench基准测试实现在 commands/bench.pykt bench --type moe --iterations 50 # 跑单个组件基准 kt bench --type all # 依次跑 moe/mla/linear/attention kt bench --type inference --model model # 端到端推理基准 kt microbench moe -b 1 -s 1 -n 100 -w 10 # 微基准参数已就绪--type/-t取值为枚举BenchType {inference, mla, moe, linear, attention, all}bench.py#L25-L34--iterations/-n默认 10--output/-o输出 JSON 结果组件基准的执行方式是定位kt-kernel安装路径后以子进程运行bench/目录下的现成脚本moe - bench_moe.py、mla - bench_mla.py、linear - bench_linear.py、attention - bench_attention.pybench.py#L252-L257这些脚本与 kt-kernel/bench/ 目录一一对应需要如实指出的现状--type inference目前仅打印 “Inference benchmarking not yet implemented”bench.py#L228-L241microbench虽然定义了component、--batch-size、--seq-len、--iterations默认 100、--warmup默认 10、--output参数并写好了脚本映射但函数体在执行前即打印 “coming soon” 并退出bench.py#L123-L128。这与原文档开头的“功能开发中”注记一致。4.6kt doctor环境诊断清单kt doctorcommands/doctor.py支持--verbose/-v以表格形式输出逐项状态ok/warning/error与修复提示。逐项检查内容与源码对应关系检查项判定逻辑源码依据Python 版本要求 3.10_check_python_versionCUDAdetect_cuda_version()缺失为 warningCUDA 可选但推荐GPUdetect_gpus()汇总名称与总显存CPU / 指令集展示核心/线程数ISA 判定四级有 AMX“AMX available - best performance for INT4/INT8” 有 AVX512 仅 AVX2warning 无 AVX2error“AVX2 required for kt-kernel”见 doctor.py#L163-L199NUMA 拓扑节点数与每节点线程数verbose 下展示每个节点的 CPU 区间kt-kernel 变体解析安装目录下_kt_kernel_ext_*.so文件名确定当前变体amx/avx512/avx2amx 为 okavx2 为 warning未安装则 error 并提示pip install kt-kerneldoctor.py#L223-L291内存总量 32GB 给 warning“32GB RAM recommended for large models”verbose 下展示频率与类型磁盘对每个已配置的模型路径检查剩余空间 100GB 给 warning依赖包kt-kernel0.4.0、sglang0.4.0、torch2.4.0、transformers4.45.0后两者为必装项doctor.py#L338-L343SGLang 来源区分 sglang-ktkvcache-ai fork/ 源码 editable / PyPI 版PyPI 原版给 warning并进一步校验 SGLang 是否支持 kt-kernel不支持时提示重装doctor.py#L366-L436冲突环境变量检测SGLANG_DSV4_2604_SUBMODE值为2604B时警告仅适用于 MXFP4 启动其他 kt-method 下会导致启动崩溃环境管理器检测 conda/docker 等建议用 conda 或 docker 安装诊断结论区会汇总发现问题时输出 “has issues” 警告全部通过输出 “all ok”并视情况追加 SGLang 安装指引或 kt-kernel 适配指引。对准备部署 DeepSeek-V3 一类 MoE 模型的机器kt doctor -v是最快的环境自检入口。4.7kt sft与kt versionkt sft对应原文档 “Fine-tuning with LlamaFactory”。当前 commands/sft.py 中train / chat / export三个子命令均打印 “coming soon” 占位无实际执行逻辑——即该命令族已预留接口但尚未落地使用 LlamaFactory 微调仍需参考项目其他文档的独立流程kt version展示 CLI 版本即kt-kernel包版本、Python 版本、平台、CUDA 版本以及kt-kernel与 SGLang 的安装版本和来源PyPI / 源码 / editable / git remote--verbose/-v追加ktransformers、llamafactory、typer、rich、torch、transformers的包版本表SGLang 未安装时打印安装指引version.py#L52-L102。五、典型工作流串联结合前述命令一条完整的 MoE 模型本地部署路径可以这样走各步骤均为查看/安装/运行/配置说明kt # 1. 首次运行语言选择 模型发现 存储路径设置 kt doctor -v # 2. 环境体检CPU 指令集 / 内存 / SGLang 来源 kt model download # 3. 交互式下载HF 不可达时自动切镜像 kt quant # 4. 交互式量化到 AMX INT4/INT8 kt run model --gpu-experts 4 --dry-run # 5. 先 dry-run 预览 SGLang 启动命令 kt run model --gpu-experts 4 # 6. 正式拉起推理服务 kt chat -t 0.7 # 7. 连接 30000 端口聊天自动记录 TTFT/TPOT 指标 kt config set server.port 30001 # 8. 需要时调整默认端口 kt bench --type moe # 9. 跑 MoE 算子基准六、源码导航小结关注点位置入口、命令注册、首次向导、补全安装kt-kernel/python/cli/main.py配置默认值与读写kt-kernel/python/cli/config/settings.py各子命令实现kt-kernel/python/cli/commands/run.py/chat.py/quant.py/model.py/config.py/bench.py/doctor.py/sft.py/version.py模型发现/注册/校验/下载工具kt-kernel/python/cli/utils/Shell 补全脚本kt-kernel/python/cli/completions/量化调用脚本kt-kernel/scripts/convert_cpu_weights.py组件基准脚本kt-kernel/bench/官方文档本文核心依据doc/en/kt-kernel/kt-cli.md总体来看KT-CLI 把 “SGLang KTransformers/kt-kernel” 异构推理工作流中最高频的六件事——环境体检、模型下载、AMX 量化、服务启动、交互验证、算子基准——收敛进一个kt入口交互模式降低了初次使用门槛直接模式加上对 SGLang 参数的透传保证了脚本化场景的平滑迁移。结合~/.ktransformers/config.yaml的默认值体系与doctor的分项诊断读者可以按本文第四节逐命令核对参数完成从部署到验证的完整闭环。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考