mirror of
https://github.com/kvcache-ai/ktransformers.git
synced 2026-11-05 01:07:28 +00:00
[GH-ISSUE #1608] 🚨FAQs | 常见问题🚨 #1048
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
kvcache-ai/ktransformers#1048
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @KMSorSMS on GitHub (Nov 13, 2025).
Original GitHub issue: https://github.com/kvcache-ai/ktransformers/issues/1608
Most of problems / 大多数问题
How to install kt-kernel/ 怎么安装 kt-kernel
Please update repository and install again following the link below:
请参考文档进行安装,以及常见问题指导:
https://github.com/kvcache-ai/ktransformers/blob/main/kt-kernel/README.md
Inference with kt-kernel+Sglang/ 在 kt-kernel + Sglang 上推理
1. Install SGLang
2. Prepare Weights
You need both GPU weights and CPU weights for heterogeneous inference:
GPU Weights: Use the original / quantized model weights.
CPU Weights: Quantize to AMX-optimized format using the conversion script:
Supported input formats: FP8, FP16, BF16 → INT4/INT8.
For more details, see:
Note: LLAMAFILE backend supports GGUF format directly, but this feature is still in preview.
3. Launch SGLang Server
Start the SGLang server with your normal SGLang parameters, and add the following KT-Kernel specific parameters to enable CPU-GPU heterogeneous inference:
KT-Kernel Parameters to Add:
--kt-method: Backend method (AMXINT4, AMXINT8, or LLAMAFILE)--kt-weight-path: Path to the converted CPU weights--kt-cpuinfer: Number of CPU inference threads (set to physical cores)--kt-threadpool-count: Number of thread pools (set to NUMA node count)--kt-num-gpu-experts: Number of experts to keep on GPU--kt-max-deferred-experts-per-token: Deferred experts for pipelined executionExample:
Support models/ 支持的模型列表
Known Issues & Tips / 已知问题与提示
"KT fallback" log messages are normal / "KT fallback" 日志是正常的
If you see logs like
KT fallback: layer X prepare weight = XXms, compute = XXms, this is expected behavior indicating that Layer-wise Prefill is working correctly. The "fallback" naming is misleading and will be updated in a future release.如果看到类似
KT fallback: layer X prepare weight = XXms的日志,这是预期行为,说明 Layer-wise Prefill 已正常启动。"fallback" 这个名称有误导性,后续版本会优化。Low GPU utilization during prefill / Prefill 阶段 GPU 利用率低
If your GPU utilization is low during prefill, enable Layer-wise Prefill by adding:
This allows the GPU to participate in prefill computation, significantly improving prefill throughput.
如果 prefill 阶段 GPU 利用率很低,请添加
--kt-gpu-prefill-token-threshold 2048参数开启 Layer-wise Prefill。GPTQ_INT4 + tensor-parallel-size > 1 / GPTQ_INT4 与多卡 TP 不兼容
GPTQ-Int4 quantized MoE models may fail with
IndexError: start out of rangewhen usingtensor-parallel-size > 1with GPU experts. This is an SGLang-side weight loader issue. Workarounds:--tensor-parallel-size 1GPTQ-Int4 量化的 MoE 模型在
tensor-parallel-size > 1且使用 GPU experts 时可能报错。这是 SGLang 侧的问题。建议降低 TP 或使用 FP8 权重。@james0zan commented on GitHub (Nov 13, 2025):
We need a tracking matrix of model support.
For example, the currenct staus of GLM series model, what kind of weight are supported, what are not.
@KMSorSMS commented on GitHub (Nov 13, 2025):
You are welcome to report new models that are supported in the kt_kernel with your snapshot to prove
@kiankyars commented on GitHub (Dec 22, 2025):
I'm not too sure what the issue is here. Is this just an FAQ because I'm looking for a good first issue to contribute? I
@KMSorSMS commented on GitHub (Dec 22, 2025):
@kiankyars Yes, this is just an FAQ. This FAQ contains answers to common questions that may help you. If you can’t find what you’re looking for here, please feel free to open a new issue.
@wqshmzh commented on GitHub (Apr 12, 2026):
One has to prepare CPU+GPU models, which means he or she is supposed to download the model twice, right ? So that one model occupies the disk for two times. It is very space consuming. Previous versions of ktransformers do not require doing so. Why things changed after updates ?
@KMSorSMS commented on GitHub (Apr 12, 2026):
I think this is no longer necessary if you use the original-precision mode. Previously, two sets of weights were needed because the INT4/INT8 weights are not the same as the original weights. In low-precision mode, we use INT4/INT8 weights for the MoE experts, while the rest of the model stays unchanged, so both versions had to be kept. If you run in original-precision mode, such as rawint4, then this is no longer needed.
@wqshmzh commented on GitHub (Apr 21, 2026):
@KMSorSMS I dont have enough resources to run full-precision models. I always use unsloth's UD models, the precisions of moe and other parts are different in UD models. So do I need to download the original full precision model and unsloth's model twice now?
@KMSorSMS commented on GitHub (Apr 21, 2026):
@wqshmzh I see — yes, in your case you'll need both. The original full-precision model is required (only its non-MoE parts are actually used, but there's no way to download just those, so the full model has to be pulled down), and Unsloth's UD model is needed for the MoE parts. So both downloads are necessary.
@mytbk commented on GitHub (May 28, 2026):
好像没什么关于现在的 SGLang+kt-kernel 架构的文档。我不清楚 kt-kernel 是专用于 CPU 还是也支持 GPU 的,我看 kt-kernel 的 setup.py 和 CMakeLists.txt 里面还提到了 CUDA/MUSA/ROCM,而且在 CUDA 环境的确会调用 nvcc. 另外 llama.cpp 的集成也看得不是很懂,是用来支持 GGUF 相关量化的吗?
我现在的主要部署方式是在自己的机器上先配好 venv 安装,再把 venv 挪到生产环境,所以想知道要构建 kt 有哪些是必须要构建的。
@KMSorSMS commented on GitHub (May 29, 2026):
@mytbk https://ktransformers.net/zh/docs
@cxj01 commented on GitHub (Aug 10, 2026):
@KMSorSMS SFT时要求cpu要支持amx指令集?只支持avx指令集的cpu训练不了?
@KMSorSMS commented on GitHub (Aug 10, 2026):
应该不是的,目前能支持 avx 了。 @JimmyPeilinLi
@cxj01 commented on GitHub (Aug 10, 2026):
@KMSorSMS @JimmyPeilinLi 目前哪个版本之后开始支持,我安装了ktransformers==0.6.4 还不支持。
@cxj01 commented on GitHub (Aug 10, 2026):
@KMSorSMS @JimmyPeilinLi
[rank0]: File "/aiproject/name/lixiufeng/miniconda3/envs/kt-sft/lib/python3.11/site-packages/kt_kernel/sft/amx.py", line 90, in init
[rank0]: raise RuntimeError(
[rank0]: RuntimeError: AMX SFT backend not available. kt_kernel_ext was not compiled with AMX SFT support.
[rank0]: Please recompile with AMX SFT enabled.
@JimmyPeilinLi commented on GitHub (Aug 10, 2026):
@cxj01 我认为可能是需要更新 llamafactory 的代码。https://github.com/hiyouga/LlamaFactory/pull/10738 是我们目前在 llamafactory 提交 AVX 的支持 PR,我们双方正在联合 review。后续合入会更新一版 cookbook,并发布新的 kt 的 pypi 包以确保支持
@JimmyPeilinLi commented on GitHub (Aug 10, 2026):
@cxj01 补充一下,avx的原精度微调应该是在v0.7 之后才支持的功能,v0.6.4 的 kt 应该不支持,可能需要源码编译一下目前。
@cxj01 commented on GitHub (Aug 10, 2026):
@JimmyPeilinLi 直接拉最新的master(kt)代码,编译安装即可吧?不用切到特定的提交上吧?
@yyj6666667 commented on GitHub (Aug 10, 2026):
对,后面直接拉取编译就行, 现在还需要等LlamaFactory 合入, 我们也在做相关的清理
@CodeIntegrity commented on GitHub (Aug 27, 2026):
docker镜像很久没更新了,看工作流好像是报错,是否能更新一下
@yyj6666667 commented on GitHub (Aug 27, 2026):
docker后面我们重新配置CI, 目前请先用pip install