kaito-project/aikit · 上手攻略

  • 仓库：kaito-project/aikit
  • 链接：https://github.com/kaito-project/aikit
  • 分类：LLMOps / 模型分发 + 推理 + 微调（容器化）
  • 作者：spark
  • 更新：2026-09-08

1. 是什么

AIKit 是 KAITO 项目（Kubernetes AI Toolchain Operator）下的子项目，定位 「把开源 LLM 用一条 docker run / 一个 YAML 跑起来」：把模型推理、LoRA 微调、模型打包成 OCI artifact 三件事打包成一个工具链，底层推理引擎用 LocalAI + llama.cpp / llama-ggml，微调用 Unsloth。

一句话：「Ollama 的容器化 + Unsloth 的微调 + CNCF ModelPack 的 OCI 分发」三合一，目标用户是想在本地、K8s 或 air-gapped 环境里把开源 LLM「当 Docker 镜像」分发与运行的工程团队。

2. 解决什么问题

  • 「模型散落一地」：HuggingFace 上一份权重，本地一份 GGUF，K8s 一份镜像，互相不通；AIKit 把「权重 → 镜像」做成可重复构建（chiseled Ubuntu 镜像 + uv 锁依赖 + SBOM + provenance attestation）。
  • 「微调环境难复现」：直接装 Unsloth 经常被 CUDA / Triton / PyTorch 版本折腾；AIKit 把 SFT / DPO 流程写进 BuildKit，支持声明式 YAML。
  • 「OpenAI API 兼容但只想跑开源」：LocalAI 提供 /v1/chat/completions 兼容端点，AIKit 直接内置，所以现成的 OpenAI client（Kubectl AI、Chatbot-UI、LangChain 等）零改造接入。
  • 「air-gapped / 内网分发」：模型可作为 OCI artifact 推到 Harbor / 内网 registry，air-gapped 环境从私有 registry 拉镜像即可。⚠️ 注意：runner images that download models at startup are not air-gapped by default——必须 baked-in / mirror 才行。

3. 快速安装

环境前置：

# 1) Docker ≥ 27 + Buildx ≥ 0.22 + BuildKit ≥ 0.20
docker --version          # Docker Engine 27+
docker buildx version     # Buildx 0.22+

# 2) NVIDIA 用户额外准备 CDI
nvidia-smi
nvidia-ctk cdi list

一行命令起 Llama 3.1 8B（CPU 也能跑）：

docker run -d --rm -p 8080:8080 ghcr.io/kaito-project/aikit/llama3.1:8b
# 打开 http://localhost:8080/chat 看 WebUI

OpenAI 兼容调用：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [{"role":"user","content":"explain kubernetes in a sentence"}]
  }'

GPU 版只需多一个 --gpus all：

docker run -d --rm --gpus all -p 8080:8080 \
  ghcr.io/kaito-project/aikit/llama3.1:8b

Apple Silicon（实验性）走 Podman：

podman run -d --rm --device /dev/dri -p 8080:8080 \
  ghcr.io/kaito-project/aikit/applesilicon/llama3.1:8b

⚠️ 只支持 gguf 模型；Apple Silicon runtime 不保证稳定，未来可能改 API。

4. 核心用法

4.1 开箱即用的预制镜像（CPU + GPU 都列）

模型 参数量 镜像
Llama 3.2 Instruct 1B / 3B …/aikit/llama3.2:1b / :3b
Llama 3.1 Instruct 8B …/aikit/llama3.1:8b
Llama 3.3 Instruct 70B …/aikit/llama3.3:70b
Mixtral Instruct 8×7B …/aikit/mixtral:8x7b
Phi-4 Instruct 14B …/aikit/phi4:14b
Gemma 2 Instruct 2B …/aikit/gemma2:2b
QwQ 32B …/aikit/qwq:32b
Codestral 0.1 22B …/aikit/codestral:22b
GPT-OSS 20B / 120B …/aikit/gpt-oss:20b / :120b
Flux.1 Dev（图） 12B …/aikit/flux1:dev（GPU only）

授权：Llama 系走 Meta Llama License；Mixtral / QwQ / GPT-OSS 是 Apache 2.0；Phi-4 是 MIT；Codestral 是 MNPL。⚠️ 商用前自核许可证。

4.2 自建镜像（标准流程）

如果预制没你的模型，按官方文档「Create Your Own Image」：

# 1) 起 GPU builder
docker buildx create --name aikit-builder --use \
  --driver docker-container \
  --driver-opt image=moby/buildkit:buildx-stable-1-gpu \
  --buildkitd-flags '--allow-insecure-entitlement device'
docker buildx inspect aikit-builder --bootstrap

# 2) 拷一份配置
aikit init my-custom-llm
# 编辑 aikit.yaml：填 baseModel、backend（llama-cpp / llama-ggml）、runtime

# 3) build + push
aikit build ./aikit.yaml --tag ghcr.io/<org>/aikit-my-llm:8b --push

构建期会去拉 HuggingFace 权重 → 量化 → 打成 chiseled Ubuntu 镜像。

4.3 微调（SFT / DPO，目前只走 Unsloth）

新建 fine-tune YAML：

#syntax=ghcr.io/kaito-project/aikit/aikit:latest
apiVersion: v1alpha1
baseModel: "unsloth/llama-2-7b-bnb-4bit"
datasets:
  - source: "yahma/alpaca-cleaned"
    type: "alpaca"
    loader:
      type: huggingface
      split: train
      revision: 0123456789abcdef0123456789abcdef01234567   # 必须 40 位 commit hash
config:
  unsloth:
    packing: false
    maxSeqLength: 2048

跑：

aikit fine-tune ./aikit-finetune.yaml --tag ghcr.io/<org>/aikit-finetuned:7b --push

DPO 示例（必须正好 1 个 preference 数据集）：

objective:
  type: dpo
  beta: 0.1
  lossType: sigmoid
  maxPromptLength: 512
datasets:
  - source: organization/preferences
    type: preference
    loader:
      type: huggingface
      split: train
      revision: 0123456789abcdef0123456789abcdef01234567

4.4 模型作为 OCI artifact 分发

按 CNCF ModelPack 规范：

aikit package ./aikit.yaml --tag ghcr.io/<org>/aikit-modelpack:7b --push

内网 Harbor / GitLab Container Registry / AWS ECR 都吃 OCI artifact，可作为「模型制品」在 K8s 里以 imagePullPolicy 形式分发。⚠️ 注意凭证：URL 内嵌的 query / credential 不会被记到日志里，但URL 本身仍是构建定义的一部分，不要当 secret 用。

4.5 Kubernetes 部署

kubectl apply -f https://raw.githubusercontent.com/kaito-project/aikit/main/examples/k8s/llama3.1-8b.yaml

具体 YAML 模板在 examples/k8s/。如果你的集群装的是 KAITO operator，它会自动把 aikit 镜像调度到带 GPU 的节点。

5. 典型适用场景

  • air-gapped 内网交付模型：银行 / 政府 / 制造客户常要求「模型不能联网」，AIKit 把权重烘进 OCI 镜像正好对应。
  • K8s 上的 LLM 推理 / 微调流水线：KAITO operator 负责节点选择 + GPU 调度，AIKit 负责容器化，链路非常顺。
  • OpenAI 兼容网关：自托管替代 OpenAI API，对接现有 LangChain / LlamaIndex 应用无需改代码。
  • MLOps 教学 / PoC：一行命令拉起 Phi-4 / GPT-OSS 20B，WebUI 直观，零依赖。
  • 私有模型仓库：把微调后的 LoRA adapter 重新打成镜像版本化，复用 SBOM + provenance。

6. 坑与注意

  1. 微调只支持 NVIDIA GPU：AMD ROCm 还没支持；Apple Silicon 微调目前不支持。⚠️ 文档明确写「At this time, AIKit fine tuning process is only supported with NVIDIA GPUs」。
  2. Unsloth 是当前唯一微调 target：At this time, Unsloth is the only supported target, but can be extended for other fine tuning implementations in the future，需要 axolotl / llama-factory / swift 的团队需要等扩展。
  3. BuildKit 必须 ≥ 0.20 + Docker ≥ 27：旧版 Docker Desktop 会因为 BuildKit 太老直接报错；Windows WSL2 用户需要 Buildx 0.27+ 才能透传 GPU。
  4. CDI 配置是硬前置：NVIDIA Container Toolkit 配 CDI 不只是「可选」，GPU 构建完全依赖 nvidia.com/gpu=0 这种 selector，没配 CDI 就直接 build 失败。验证命令：nvidia-ctk cdi list 必出 nvidia.com/gpu=0。
  5. DPO 数据集必须正好 1 个：写多了会拒；并且 chosen / rejected 在 truncation 后必须仍然 token-distinct，否则 AIKit 会主动拒绝这条 pair（因为无 preference signal）。
  6. packing: false 是 response-only loss 的硬约束：loss: response 模式下 packing 必须关掉，否则 mask 跨会话边界。
  7. GPT-OSS 120B 内存账要算清：120B 即使是 GPTQ/GGUF 量化也要 ≥80 GB 显存，单卡 H100 / H200 准备；CPU 模式几乎不可用。⚠️
  8. Apple Silicon runtime 是 experimental：文档明示「may change in the future」，生产路径不要押宝。
  9. HuggingFace revision 必须是 40 位 commit hash：分支 / tag / 短 hash 都会被拒，目的是 reproducibility；少这个字段会发出 warning，但有它 build cache 才是 immutable。
  10. OCI 分发 ≠ air-gapped by default：「downloads models at startup」的 runner 镜像联网拉权重；只有 baked-in 或镜像 mirror 才算 air-gapped。
  11. 凭证不能放 URL 里：AIKit 会主动剥掉 query / fragment 中的 credential 来防泄漏，但 URL 仍作为构建配置的一部分，真要凭证请走 secret mount。
  12. 模型许可证混在一起：README 表里 Llama License / Apache 2.0 / MIT / MNPL / Gemma Terms / FLUX.1 Non-Commercial 都出现过，商用前逐个核；尤其 FLUX.1 Dev 是 Non-Commercial License，混着发 GPL 兼容策略容易踩雷。

7. 与同类对比

项目 核心思路 与 AIKit 的差异
Ollama 单机 LLM 运行，modelfile 描述 上手更简单，但缺少企业级微调、OCI artifact、air-gapped 镜像、SBOM / provenance
LocalAI（AIKit 底层依赖） OpenAI 兼容多模态推理 本地 CPU/GPU 推理无微调；AIKit 在它之上补微调 + OCI 打包 + K8s 集成
LM Studio 桌面 GUI 推理 桌面端，无 K8s / 微调 / OCI；面向个人 / 小团队
vLLM / SGLang / TensorRT-LLM 高吞吐推理服务器 性能更极限，但需要自行管镜像 / 模型分发；AIKit 走 chiseled 小镜像 + Unsloth 微调，吞吐量非首要目标
Unsloth 原始项目 单 GPU 笔记本微调 没有镜像化、没有 OCI 分发、没有 K8s 集成；AIKit 把 Unsloth 嵌进 BuildKit
Seldon / BentoML 模型 serving + 版本化 更偏 Python 服务框架；AIKit 偏「模型本身作为可分发的 OCI artifact」
KubeRay / Kserve K8s 上的推理 serving 调度 / 路由强项，模型打包弱；和 AIKit 形成「运行时 vs 制品」互补

如果你的场景是「让模型像 Docker 镜像一样被版本化、可审计、可在 air-gapped 环境分发」，AIKit 是当前少有的把 OCI artifact、Unsloth、KAITO 三件事串起来的工具链。

8. 一句话推荐结论

「把开源 LLM 当 Docker 镜像发」——AIKit 是把 OCI 分发、OpenAI 兼容推理、Unsloth 微调三件套缝起来的 K8s 原生工具链；想做 air-gapped 或私有模型仓库的团队优先评估。

⚠️ 待核验事项： - 「Apple Silicon runtime 实验性」标注源自 README Section "Apple Silicon is an experimental runtime"，未实测 M-series Max / Ultra 上的稳定性。 - GPT-OSS 120B 的量化等级 / 显存门槛未在 README 中给出精确数字；建议实际跑前先翻 HuggingFace model card。 - 「Apache 2.0」一栏多处复用为 GPT-OSS 20B / 120B / QwQ 32B 的 license 表述，但 GPT-OSS 的官方许可证在 OpenAI 仓库里另有定义，商用前以 OpenAI 官方页为准。

字数：约 2,500 CJK · 私域污染 SUM=0 · 边界：仅写 guides/kaito-project-aikit.md