构建与分发 KTransformers Docker 镜像标准化命名、双 conda 环境与多 CPU 变体自动检测【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformersKTransformers 仓库的docker/目录提供了一套完整的 Docker 镜像打包与分发体系从 sglang、ktransformers、LLaMA-Factory 自动提取版本信息按统一命名规范生成镜像名支持 AMX/AVX512/AVX2 多 CPU 指令集变体的运行时自动检测并提供本地 tar 离线导出与 DockerHub 在线发布两条分发路径。读完本文你可以独立完成 KTransformers 镜像的构建、命名、导出、推送与加载运行并理解镜像内部双 conda 环境serve / fine-tune的组织方式与版本提取机制。一、打包体系概述打包系统源码位于 docker/ 目录提供四项核心能力自动化版本探测构建完成后自动从 sglang、ktransformers 和 LLaMA-Factory 中提取各自版本号用于生成标准化的镜像名/标签多 CPU 变体支持单个镜像同时包含 AMX、AVX512、AVX2 三种 CPU 内核变体容器运行时根据宿主 CPU 自动加载最优变体标准化命名规范镜像名/标签/tar 文件名遵循统一的模式便于识别与管理两种分发方式本地 tar 文件导出用于离线分发推送 DockerHub用于在线分发。二、标准化命名规范Docker 镜像遵循如下命名模式sglang-v{sglang版本}_ktransformers-v{ktransformers版本}_{cpu信息}_{gpu信息}_{功能模式}_{时间戳}命名示例tar 文件名sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022.tarDockerHub 标签完整标签 kvcache/ktransformers:sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022 简化标签 kvcache/ktransformers:v0.5.3-cu128说明以上版本号仅为文档示例值。实际构建时镜像中的真实版本例如当前仓库 version.py 中定义的0.7.0.post1会在构建末尾自动提取并填入标签无需手工指定。名称组成部分组成部分含义示例sglang 版本SGLang 包版本v0.5.6ktransformers 版本KTransformers 版本v0.5.3cpu 信息CPU 指令集支持x86-intel-multi含 AMX/AVX512/AVX2gpu 信息CUDA 版本cu128CUDA 12.8功能模式功能模式sft_llamafactory-v0.9.3或infer时间戳构建时间北京/UTC820241212143022从源码结构看这套命名规范由共享脚本 docker/docker-utils.sh 统一实现两个打包脚本tar 导出与 DockerHub 推送都source该文件复用同一套函数保证命名一致性get_beijing_timestamp以TZAsia/Shanghai生成YYYYMMDDHHMMSS格式时间戳对应命名中的“北京/UTC8”约定parse_cuda_short_version把12.8.1这类完整版本号压缩为cu128并通过正则校验X.Y/X.Y.Z格式generate_image_name按sglang-v{ver}_ktransformers-v{ver}_{cpu}_{gpu}_{func}_{timestamp}拼装完整名称当功能模式为sft时func段会自动拼接 LLaMA-Factory 版本形如sft_llamafactory-v{llama_ver}否则为infergenerate_simplified_tag生成v{ktransformers版本}-{cu 短版本}形式的简化标签如v0.5.3-cu128。三、打包脚本文件结构文件作用docker/Dockerfile主 Dockerfile负责多 CPU 变体构建与版本信息提取docker/docker-utils.sh两个脚本共享的工具函数时间戳、版本提取、命名、日志、校验docker/build-docker-tar.sh构建镜像并导出为 tar 文件docker/push-to-dockerhub.sh构建镜像并推送到 DockerHubdocker-utils.sh除命名函数外还提供extract_versions_from_image通过docker run --rm image cat /workspace/versions.env从镜像内读取版本文件见 docker/docker-utils.sh#L101-L130、validate_versions校验三个版本键是否存在unknown值只告警不失败、check_docker_running/check_disk_space/check_writable等前置校验。四、前置条件已安装并正在运行的 Docker若推送到 DockerHub需要 Docker Hub 账号并先执行docker login足够的磁盘空间建议至少 20GB——tar 脚本在 docker/build-docker-tar.sh#L234 中会以 20GB 为阈值检查输出目录剩余空间空间不足仅告警、不强制中断互联网访问或已配置本地镜像源。构建本身涉及从 GitHub 克隆 ktransformers 仓库及其子模块sglang、下载 ktransformers 与 flash_attn 预编译 wheel、编译 DeepEP 与 kt-kernel 等步骤脚本对构建时长的提示是30–60 分钟见 docker/build-docker-tar.sh#L303 的日志输出。五、快速开始5.1 构建本地 tar 文件cd docker # 基础构建默认 CUDA 12.8.1、sft 模式 ./build-docker-tar.sh # 指定 CUDA 版本并使用清华镜像源 ./build-docker-tar.sh \ --cuda-version 12.8.1 \ --ubuntu-mirror 1 # 带代理并自定义输出目录 ./build-docker-tar.sh \ --cuda-version 12.8.1 \ --ubuntu-mirror 1 \ --http-proxy http://127.0.0.1:16981 \ --https-proxy http://127.0.0.1:16981 \ --output-dir /path/to/output5.2 推送到 DockerHubcd docker # 基础推送必须提供 --repository ./push-to-dockerhub.sh \ --repository kvcache/ktransformers # 同时推送简化标签 ./push-to-dockerhub.sh \ --cuda-version 12.8.1 \ --repository kvcache/ktransformers \ --also-push-simplified # 若本地已存在镜像则跳过构建 ./push-to-dockerhub.sh \ --repository kvcache/ktransformers \ --skip-build六、脚本完整参数说明6.1 build-docker-tar.shBuild Configuration: --cuda-version VERSION CUDA 版本 (默认: 12.8.1)如 12.8.1 / 12.6.1 / 13.0.1 --ubuntu-mirror 0|1 是否使用清华 Ubuntu 源 (默认: 0) --http-proxy URL HTTP 代理地址 --https-proxy URL HTTPS 代理地址 --cpu-variant VARIANT CPU 变体标识 (默认: x86-intel-multi) --functionality TYPE 功能模式: sft 或 infer (默认: sft) Paths: --dockerfile PATH Dockerfile 路径 (默认: ./Dockerfile) --context-dir PATH 构建上下文目录 (默认: .) --output-dir PATH tar 输出目录 (默认: 当前目录) Options: --dry-run 只预览命令不实际构建 --keep-image 导出 tar 后保留本地 Docker 镜像 --build-arg KEYVALUE 附加构建参数可重复传入 -h, --help 显示帮助信息6.2 push-to-dockerhub.sh在build-docker-tar.sh全部参数基础上额外提供Registry Settings: --registry REGISTRY Docker 仓库服务 (默认: docker.io) --repository REPO 仓库名必填如 kvcache/ktransformers Options: --skip-build 若本地已存在镜像则跳过构建 --also-push-simplified 同时推送简化标签 (v{ver}-{cuda}) --max-retries N 推送最大重试次数 (默认: 3) --retry-delay SECONDS 重试间隔秒数 (默认: 5)从 docker/build-docker-tar.sh 的 build_image 函数 可以看到两个脚本最终都会组装同一条docker build命令把脚本参数转成 build-arg 传入 DockerfileCUDA_VERSION、UBUNTU_MIRROR、CPU_VARIANT、BUILD_ALL_CPU_VARIANTS1强制构建全部 CPU 变体、FUNCTIONALITY以及可选的HTTP_PROXY/HTTPS_PROXY并追加--network host以放开构建期网络。push-to-dockerhub.sh的推送环节还内置了重试逻辑push_image_with_retry 会按--max-retries/--retry-delay参数循环执行docker tagdocker push完整标签推送失败会终止流程简化标签推送失败则仅告警继续。6.3 各参数的实际影响--cuda-version决定基础镜像nvidia/cuda:${CUDA_VERSION}-cudnn-devel-ubuntu24.04及 sgl-kernel、torch、NCCL、DeepEP 的架构选择见 docker/Dockerfile#L576-L605 中按12.6.1 / 12.8.1 / 12.9.1 / 13.0.1分支选择 wheel 索引与TORCH_CUDA_ARCH_LIST--ubuntu-mirror 1在基础镜像层把 apt 源替换为清华镜像docker/Dockerfile#L50-L56conda 与 pip 则默认已配置清华源--functionality只接受sft或infer脚本会显式校验见 docker/build-docker-tar.sh#L239-L243。sft模式会额外创建fine-tuneconda 环境并安装 LLaMA-Factory 与 ktransformers wheelinfer模式只构建serve环境--build-arg可覆盖 Dockerfile 中任意 ARG例如SGL_VERSION、FLASHINFER_VERSION、KTRANSFORMERS_VERSION等Dockerfile 顶部定义了这些可覆盖的 ARG见 docker/Dockerfile#L1-L38。七、实战示例示例 1本地开发构建./build-docker-tar.sh \ --cuda-version 12.8.1 \ --output-dir ./builds \ --keep-image流程构建镜像 → 导出 tar 到./builds/→ 保留镜像供本地测试--keep-image控制否则脚本会通过cleanup_temp_images删除临时镜像。示例 2生产环境分发构建./build-docker-tar.sh \ --cuda-version 12.8.1 \ --ubuntu-mirror 1 \ --http-proxy http://127.0.0.1:16981 \ --https-proxy http://127.0.0.1:16981 \ --output-dir /mnt/data/releases示例 3发布到 DockerHub# 先登录 Docker Hub docker login # 再推送 ./push-to-dockerhub.sh \ --cuda-version 12.8.1 \ --repository kvcache/ktransformers \ --also-push-simplified成功后会生成两个标签完整标签kvcache/ktransformers:sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022简化标签kvcache/ktransformers:v0.5.3-cu128示例 4Dry Run 预演./build-docker-tar.sh --cuda-version 12.8.1 --dry-runDry run 模式下不会真正构建而是用占位版本号预览将要执行的构建命令、临时镜像标签与 tar 文件名。示例 5自定义构建参数./build-docker-tar.sh \ --cuda-version 12.8.1 \ --build-arg SGL_VERSION0.5.7 \ --build-arg FLASHINFER_VERSION0.5.4八、使用构建好的镜像8.1 从 tar 文件加载# 加载镜像 docker load -i sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022.tar # 运行容器 docker run -it --rm \ --gpus all \ sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022 \ /bin/bashtar 导出在 docker/build-docker-tar.sh#L385-L404 中实现先把临时镜像docker tag为标准化名称再docker save -o output_dir/名称.tar导出并打印 tar 文件体积。8.2 从 DockerHub 拉取# 使用完整标签 docker pull kvcache/ktransformers:sglang-v0.5.6_ktransformers-v0.5.3_x86-intel-multi_cu128_sft_llamafactory-v0.9.3_20241212143022 # 或使用简化标签 docker pull kvcache/ktransformers:v0.5.3-cu128 # 运行容器 docker run -it --rm \ --gpus all \ kvcache/ktransformers:v0.5.3-cu128 \ /bin/bash8.3 容器内部双 conda 环境sft模式下构建的镜像包含两个 conda 环境docker/Dockerfile#L541-L542 中创建# 激活推理环境基于 sglang 提供服务 conda activate serve # 或使用 Dockerfile 在 /root/.bashrc 中注入的别名 serve # 激活微调环境基于 LLaMA-Factory 训练仅 sft 模式存在 conda activate fine-tune # 或使用别名 finetune从 docker/Dockerfile 的构建流程看两个环境的分工是serve 环境Python 3.12安装 sgl-kernel、以可编辑模式安装 sglangktransformers 仓库的third_party/sglang子模块安装时注入与 ktransformers 对齐的SGLANG_KT_VERSION、下载 FlashInfer cubin、按 CUDA 版本编译 DeepEP、安装 NCCL并在末尾以CPUINFER_BUILD_ALL_VARIANTS1 ./install.sh build构建 kt-kerneldocker/Dockerfile#L654-L656从而让单镜像覆盖全部 CPU 变体fine-tune 环境Python 3.12仅sft模式安装 CUDA 11.8 运行时、PyTorch 2.8、以pip install -e .[torch,metrics]安装 LLaMA-Factory再安装 ktransformers 预编译 wheel 与 flash_attn wheel供 LLaMA-Factory 加速微调使用。九、多 CPU 变体与运行时自动检测镜像同时内置三种 CPU 变体AMX面向 Intel Sapphire Rapids 及更新平台第四代 Xeon 及以后AVX512面向 Intel Skylake-X、Ice Lake、Cascade Lake 等AVX2面向更老 CPU 的兼容兜底。容器运行时会自动探测宿主 CPU 并加载匹配变体需要强制指定或调试时可使用环境变量# 强制使用 AVX2 变体 export KT_KERNEL_CPU_VARIANTavx2 python your_script.py # 打开调试输出查看加载了哪个变体 export KT_KERNEL_DEBUG1 python your_script.py这两个环境变量的实现位于 kt-kernel 的 CPU 探测模块 kt-kernel/python/_cpu_detect.pyKT_KERNEL_CPU_VARIANT取值为amx/avx512/avx2其说明同样记录在 kt-kernel/README.md。镜像之所以能在一张盘上覆盖三代指令集是因为构建阶段固定传入了BUILD_ALL_CPU_VARIANTS1对应安装脚本的CPUINFER_BUILD_ALL_VARIANTS1与kt-kernel从源码构建时的“只针对当前 CPU 优化”形成对比——后者可参考 kt-kernel/README.md 的源构建章节。十、版本提取机制构建过程中版本是自动提取的来源为SGLangserve 环境中的 sglang 包版本KTransformersktransformers 仓库根目录的 version.py__version__当前为0.7.0.post1LLaMA-Factoryfine-tune 环境中的llamafactory.__version__仅sft模式infer模式下写为LLAMAFACTORY_VERSIONnone。Dockerfile 末尾的 “Extract version information for image naming” 阶段会把结果写入镜像内的/workspace/versions.envdocker/Dockerfile#L736-L762打包脚本再从中读取拼装命名。在运行中的容器里可直接查看cat /workspace/versions.env # 输出示例 # SGLANG_VERSION0.5.6 # KTRANSFORMERS_VERSION0.5.3 # LLAMAFACTORY_VERSION0.9.3一个值得留意的实现细节从源码结构看Dockerfile 当前写入的键是KTRANSFORMERS_VERSION、SGLANG_KT_VERSION与 ktransformers 版本对齐、LLAMAFACTORY_VERSION而命名函数 generate_image_name 解析时查找SGLANG_VERSION前缀的键。若实际构建中版本校验报 “unknown” 或命名解析失败可先docker run --rm image cat /workspace/versions.env检查实际键名确认与 docker/docker-utils.sh 中的 grep 模式一致。十一、故障排查11.1 磁盘空间不足导致构建失败df -h构建约需 15–20GB 空间可清理 Dockerdocker system prune -a11.2 版本提取失败显示 unknown依次检查克隆的仓库是否处于正确分支conda 环境中的 Python 包是否安装成功版本文件是否存在于预期位置。可手动验证 serve 环境docker run --rm image /bin/bash -c source /opt/miniconda3/etc/profile.d/conda.sh conda activate serve python -c import sglang; print(sglang.__version__) 11.3 推送 DockerHub 失败检查登录docker login检查仓库名必须包含命名空间如kvcache/ktransformers不能只写ktransformers脚本也会在此处直接报错见 docker/push-to-dockerhub.sh#L252-L256网络问题使用--max-retries与--retry-delay调整重试策略限流DockerHub 对免费账号存在拉取/推送速率限制。十二、进阶主题12.1 自定义 Dockerfile 位置./build-docker-tar.sh \ --dockerfile /path/to/custom/Dockerfile \ --context-dir /path/to/build/context脚本在 validate_config 中会分别校验 Dockerfile 文件存在与上下文目录存在再进入构建流程。12.2 只构建推理镜像当前镜像默认同时包含 serve 与 fine-tune 两个环境若只需要推理镜像可在 Dockerfile 中跳过 fine-tune 环境相关步骤Dockerfile 中这些步骤均以if [ $FUNCTIONALITY sft ]为条件见 docker/Dockerfile#L554-L564即通过--functionality infer传入的FUNCTIONALITY构建参数实现。12.3 定制 CPU 变体若只想构建特定 CPU 变体减小镜像体积可修改kt-kernel/install.sh的构建变量或在 Dockerfile 中调整传给安装脚本的环境变量例如去掉CPUINFER_BUILD_ALL_VARIANTS1见 kt-kernel/install.sh。12.4 CI/CD 集成两个脚本面向手动执行设计但同样可以嵌入 CI/CD 流水线例如# GitHub Actions 工作流示例 - name: Build and push Docker image run: | cd docker ./push-to-dockerhub.sh \ --cuda-version ${{ matrix.cuda_version }} \ --repository ${{ secrets.DOCKER_REPOSITORY }} \ --also-push-simplified小结docker/目录下的打包体系把“构建一次、多处分发”的关键环节都自动化了版本从镜像内versions.env自动提取、命名由 docker/docker-utils.sh 统一生成、CPU 多变体在构建期全量编译并在运行期自动选择、tar 与 DockerHub 两条分发通道共用同一套构建参数。维护镜像版本时建议优先通过--build-arg覆盖 docker/Dockerfile 顶部的 ARG如SGL_VERSION、KTRANSFORMERS_VERSION而不是修改脚本默认值遇到问题时/workspace/versions.env、KT_KERNEL_DEBUG1的探测日志和--dry-run预演是三个最常用的诊断入口。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考