Skip to content

Commit f41784c

Browse files
docs: add versioned documentation for v0.7.x (#1521)
This PR adds versioned documentation for release v0.7.x. ## Changes - ✅ Created \`versioned_docs/version-v0.7.x/\` directory with current docs content - ✅ Created \`versioned_sidebars/version-v0.7.x-sidebars.json\` with current sidebar configuration - ✅ Updated \`versions.json\` to include the version - ✅ Fixed relative links in markdown files to account for versioned docs directory structure ## Release Type 🆕 **Minor Release**: This creates new versioned documentation for a new minor version. ## Triggered by Release tag: \`v0.7.0\` ## What's next? After merging this PR, the documentation for version v0.7.x will be available at: - Latest: \`/docs/\` (if this is the latest version) - Versioned: \`/docs/v0.7.x/\` The version will also appear in the documentation version dropdown." \ --head "$BRANCH_NAME" \ --base main Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: chewong <10557231+chewong@users.noreply.github.com>
1 parent cbc20c1 commit f41784c

41 files changed

Lines changed: 4250 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# AIKit Integration with KAITO
2+
3+
[AIKit](https://github.com/kaito-project/aikit/) provides a streamlined way to package and deploy large language models (LLMs) as container images.
4+
5+
This document demonstrates how to integrate AIKit-built models with KAITO workspaces for efficient AI model deployment on Kubernetes, including CPU-based inference and custom model creation with a variety of supported formats, such as GGUF, GPTQ, EXL2, and more.
6+
7+
For more detailed information about AIKit, please refer to the [AIKit documentation](https://kaito-project.github.io/aikit/docs/). For any AIKit-related issues, please open an issue in the [AIKit repository](https://github.com/kaito-project/aikit/issues).
8+
9+
## Overview
10+
11+
AIKit enables you to:
12+
13+
- 📦 [Package AI models](https://kaito-project.github.io/aikit/docs/create-images) as OCI container images with minimal configuration
14+
- 🤏 Minimal image size, resulting in less vulnerabilities and smaller attack surface with a custom distroless-based image
15+
- 🏃 Run models with a variety of inference backends, such as text or image generation
16+
- 🖥️ Supports [AMD64 and ARM64 CPUs](https://kaito-project.github.io/aikit/docs/create-images#multi-platform-support) and [GPU-accelerated inferencing with NVIDIA GPUs](https://kaito-project.github.io/aikit/docs/gpu)
17+
- 🪄 Integrate seamlessly with KAITO's infrastructure management and deployment workflows
18+
19+
:::note
20+
21+
While AIKit and KAITO integrate well, they are separate projects. AIKit focuses on model packaging and deployment, while KAITO provides infrastructure management and Kubernetes deployment workflows via controllers. There may be differences in what model formats are supported by each project.
22+
23+
:::
24+
25+
## Deploying AIKit Models to KAITO
26+
27+
### Cluster Setup
28+
29+
This guide will provide instructions using a [kind](https://kind.sigs.k8s.io/) cluster for local development and testing so it's easy to get started.
30+
31+
Please note that if you already have a Kubernetes cluster set up, you can skip the cluster setup section.
32+
33+
- Download and install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/)
34+
35+
- Create a kind cluster:
36+
37+
```bash
38+
kind create cluster --name kaito
39+
```
40+
41+
- Install [KAITO workspace controller](installation.md#install-kaito-workspace-controller) on your cluster
42+
43+
### KAITO Workspace Configuration
44+
45+
Create a KAITO workspace configuration file to deploy your model. Here's a complete example:
46+
47+
```yaml title="aikit-workspace.yaml"
48+
apiVersion: kaito.sh/v1beta1
49+
kind: Workspace
50+
metadata:
51+
name: workspace-llama-3point2-3b
52+
resource:
53+
labelSelector:
54+
matchLabels:
55+
apps: llama-3point2-3b
56+
preferredNodes:
57+
- kaito-control-plane
58+
inference:
59+
template:
60+
spec:
61+
containers:
62+
- name: llama-3point2-3b
63+
image: ghcr.io/kaito-project/aikit/llama3.2:3b
64+
args:
65+
- "run"
66+
- "--address=:5000"
67+
```
68+
69+
:::info Memory Requirements
70+
Before deploying models, check the model's memory requirements to avoid Out of Memory (OOM) errors. Add appropriate `resources.requests.memory` and `resources.limits.memory` to your container spec based on the model requirements.
71+
72+
For GGUF models:
73+
74+
- 7B models generally require at least 8GB of RAM
75+
- 13B models generally require at least 16GB of RAM
76+
- 70B models generally require at least 64GB of RAM
77+
78+
You can use [gguf-parser-go](https://github.com/gpustack/gguf-parser-go) to get a better estimate for the memory requirements for a given GGUF model, and quantization.
79+
:::
80+
81+
Label the nodes with the applicable label to ensure the workspace can schedule pods on them.
82+
83+
```bash
84+
kubectl label nodes kaito-control-plane apps=llama-3point2-3b
85+
```
86+
87+
Deploy the workspace using:
88+
89+
```bash
90+
kubectl apply -f aikit-workspace.yaml
91+
```
92+
93+
AIKit provides a number of pre-built and curated models that can be used directly. Please refer to [Pre-made Models](https://kaito-project.github.io/aikit/docs/premade-models) for available options.
94+
95+
:::tip
96+
97+
Alternatively, if you are on a supported cloud provider and want the cloud provider to auto-provision the nodes for you, you can define an `instanceType` for KAITO to autoprovision nodes, including CPU and GPU nodes.
98+
99+
You can specify the instance type based on your cloud provider's offerings. For example, for Azure, you can specify a `Standard_D2ads_v5`, which is a CPU SKU like this:
100+
101+
```yaml
102+
resource:
103+
instanceType: "Standard_D2ads_v5"
104+
labelSelector:
105+
matchLabels:
106+
apps: llama-3point2-3b
107+
```
108+
109+
:::
110+
111+
After workspace deployment succeeds, please refer to [Quick Start](quick-start#monitor-deployment) for monitoring the workspace and testing model inference.
112+
113+
#### Custom Model Creation and Integration
114+
115+
AIKit provides a simple way to create custom models without additional tools except for [Docker](https://docs.docker.com/desktop/install/linux-install/)!
116+
117+
Here's an example on how to create a custom model and integrate it with KAITO:
118+
119+
```bash
120+
export IMAGE_NAME="your-registry/your-model:latest"
121+
122+
docker buildx build -t $IMAGE_NAME --push \
123+
--build-arg="model=huggingface://TheBloke/Llama-2-7B-Chat-GGUF/llama-2-7b-chat.Q4_K_M.gguf" \
124+
"https://raw.githubusercontent.com/kaito-project/aikit/main/models/aikitfile.yaml"
125+
```
126+
127+
After building the image, you can use it in your KAITO workspace configuration by updating the `image` field.
128+
129+
For more information on creating custom models, refer to the [AIKit documentation](https://kaito-project.github.io/aikit/docs/create-images).
130+
131+
:::info
132+
AIKit supports a subset of backends, (such as [`llama.cpp`](https://kaito-project.github.io/aikit/docs/llama-cpp), [`diffusers`](https://kaito-project.github.io/aikit/docs/diffusion), [`exllamav2`](https://kaito-project.github.io/aikit/docs/exllama2), and others) from [LocalAI](https://localai.io/) at this time. Please see [Inference Supported Backends](https://kaito-project.github.io/aikit/docs/) section for more details, and updates.
133+
:::
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: AWS Setup
3+
---
4+
5+
This guide covers setting up auto-provisioning capabilities for KAITO on Amazon Elastic Kubernetes Service (EKS). Auto-provisioning allows KAITO to automatically create GPU nodes when needed for your AI workloads.
6+
7+
## Prerequisites
8+
9+
- An EKS cluster with KAITO workspace controller installed (see [Installation](installation))
10+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) for managing AWS resources
11+
- [eksctl](https://eksctl.io/installation/) for EKS cluster management
12+
- [kubectl](https://kubernetes.io/docs/tasks/tools/) configured to access your EKS cluster
13+
14+
## Understanding Auto-Provisioning on AWS
15+
16+
KAITO can use [Karpenter](https://karpenter.sh/) to automatically provision GPU nodes. This controller:
17+
18+
- Creates new GPU nodes when workspaces require specific instance types
19+
- Supports various AWS GPU instances (g4, g5, p3, p4 series, etc.)
20+
- Manages node lifecycle based on workload demands
21+
- Integrates with AWS IAM for secure access
22+
23+
:::note
24+
Alternative: If you already have GPU nodes or manage them separately, use the preferred nodes approach in the [Quick Start](quick-start) instead.
25+
:::
26+
27+
## Set Up Auto-Provisioning
28+
29+
### Create EKS Cluster and install Karpenter
30+
31+
Follow the instructions [here](https://karpenter.sh/docs/getting-started/getting-started-with-karpenter/) to create an EKS cluster and install Karpenter.
32+
33+
Then update the KAITO workspace controller Helm chart values for AWS:
34+
35+
```bash
36+
helm update kaito-workspace --namespace kaito-workspace --set cloudProviderName=aws
37+
```
38+
39+
### Using Auto-Provisioning
40+
41+
Once Karpenter is set up, you can create workspaces that automatically provision GPU nodes:
42+
43+
```yaml title="phi-4-workspace.yaml"
44+
apiVersion: kaito.sh/v1beta1
45+
kind: Workspace
46+
metadata:
47+
name: workspace-phi-4-mini
48+
resource:
49+
instanceType: "g5.4xlarge" # Will trigger node creation
50+
labelSelector:
51+
matchLabels:
52+
apps: phi-4-mini
53+
inference:
54+
preset:
55+
name: phi-4-mini-instruct
56+
```
57+
58+
Apply the workspace:
59+
60+
```bash
61+
kubectl apply -f phi-4-workspace.yaml
62+
```
63+
64+
## Supported AWS GPU Instance Types
65+
66+
The GPU provisioner supports various AWS GPU SKUs, see [supported options here](https://github.com/kaito-project/kaito/blob/main/pkg/sku/aws_sku_handler.go).
67+
68+
For the complete list and specifications, see the [AWS GPU instance documentation](https://docs.aws.amazon.com/dlami/latest/devguide/gpu.html).
69+
70+
## Clean Up
71+
72+
See the Karpenter documentation for instructions on how to clean up your EKS cluster and remove Karpenter [here](https://karpenter.sh/docs/getting-started/getting-started-with-karpenter/#9-delete-the-cluster).
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Azure Setup
3+
---
4+
5+
This guide covers setting up auto-provisioning capabilities for KAITO on Azure Kubernetes Service (AKS). Auto-provisioning allows KAITO to automatically create GPU nodes when needed for your AI workloads.
6+
7+
## Prerequisites
8+
9+
- An AKS cluster with KAITO workspace controller installed
10+
- See [Step 1](#step-1-create-and-configure-an-aks-cluster) to create an AKS cluster
11+
- See [Installation](installation) to install the KAITO workspace controller
12+
- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) for managing Azure resources
13+
- [kubectl](https://kubernetes.io/docs/tasks/tools/) configured to access your AKS cluster
14+
15+
## Understanding Auto-Provisioning on Azure
16+
17+
KAITO can use the [Azure GPU Provisioner](https://github.com/Azure/gpu-provisioner) to automatically provision GPU nodes. This controller:
18+
19+
- Creates new GPU nodes when workspaces require specific instance types
20+
- Supports various Azure GPU SKUs (Standard_NC series, etc.)
21+
- Manages node lifecycle based on workload demands
22+
- Integrates with Azure's managed identity system for secure access
23+
24+
### When to Use Auto-Provisioning
25+
26+
Choose auto-provisioning when:
27+
- You want KAITO to manage GPU node creation automatically
28+
- Your workloads have varying GPU requirements
29+
- You prefer to specify exact Azure instance types in your workspaces
30+
31+
:::note
32+
Alternative: If you already have GPU nodes or manage them separately, use the [preferred nodes approach](quick-start#option-1-using-preferred-nodes-existing-gpu-nodes) instead.
33+
:::
34+
35+
## Set Up Auto-Provisioning
36+
37+
### Step 1: Create and configure an AKS Cluster
38+
39+
If you don't have an AKS cluster yet, you can create one using the Azure CLI:
40+
41+
```bash
42+
export RESOURCE_GROUP="kaito-rg"
43+
export CLUSTER_NAME="kaito-cluster"
44+
export LOCATION="eastus"
45+
az group create --name $RESOURCE_GROUP --location $LOCATION
46+
az aks create --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --enable-oidc-issuer --enable-workload-identity --enable-managed-identity --generate-ssh-keys
47+
```
48+
49+
Connect to the cluster:
50+
```bash
51+
az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
52+
```
53+
54+
### Step 2: Create Managed Identity
55+
56+
Create a managed identity for the GPU provisioner with the necessary permissions:
57+
58+
```bash
59+
export SUBSCRIPTION=$(az account show --query id -o tsv)
60+
export IDENTITY_NAME="kaitoprovisioner"
61+
62+
# Create the managed identity
63+
az identity create --name $IDENTITY_NAME -g $RESOURCE_GROUP
64+
65+
# Get the principal ID for role assignment
66+
export IDENTITY_PRINCIPAL_ID=$(az identity show --name $IDENTITY_NAME -g $RESOURCE_GROUP --subscription $SUBSCRIPTION --query 'principalId' -o tsv)
67+
68+
# Assign Contributor role to the cluster
69+
az role assignment create \
70+
--assignee $IDENTITY_PRINCIPAL_ID \
71+
--scope /subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ContainerService/managedClusters/$CLUSTER_NAME \
72+
--role "Contributor"
73+
```
74+
75+
### Step 3: Install GPU Provisioner
76+
77+
Install the Azure GPU Provisioner using Helm:
78+
79+
```bash
80+
export GPU_PROVISIONER_VERSION=0.3.6
81+
82+
# Download and configure Helm values
83+
curl -sO https://raw.githubusercontent.com/Azure/gpu-provisioner/main/hack/deploy/configure-helm-values.sh
84+
chmod +x ./configure-helm-values.sh && ./configure-helm-values.sh $CLUSTER_NAME $RESOURCE_GROUP $IDENTITY_NAME
85+
86+
# Install GPU provisioner
87+
helm install gpu-provisioner \
88+
--values gpu-provisioner-values.yaml \
89+
--set settings.azure.clusterName=$CLUSTER_NAME \
90+
--wait \
91+
https://github.com/Azure/gpu-provisioner/raw/gh-pages/charts/gpu-provisioner-$GPU_PROVISIONER_VERSION.tgz \
92+
--namespace gpu-provisioner \
93+
--create-namespace
94+
```
95+
96+
### Step 4: Create Federated Credential
97+
98+
Create the federated identity credential to allow the GPU provisioner to access Azure resources:
99+
100+
```bash
101+
export AKS_OIDC_ISSUER=$(az aks show -n $CLUSTER_NAME -g $RESOURCE_GROUP --subscription $SUBSCRIPTION --query "oidcIssuerProfile.issuerUrl" -o tsv)
102+
103+
az identity federated-credential create \
104+
--name kaito-federatedcredential \
105+
--identity-name $IDENTITY_NAME \
106+
-g $RESOURCE_GROUP \
107+
--issuer $AKS_OIDC_ISSUER \
108+
--subject system:serviceaccount:"gpu-provisioner:gpu-provisioner" \
109+
--audience api://AzureADTokenExchange \
110+
--subscription $SUBSCRIPTION
111+
```
112+
113+
## Verify Setup
114+
115+
Check that the GPU provisioner is running correctly:
116+
117+
```bash
118+
# Check Helm installations
119+
helm list -n gpu-provisioner
120+
helm list -n kaito-workspace
121+
122+
# Check GPU provisioner status
123+
kubectl describe deploy gpu-provisioner -n gpu-provisioner
124+
kubectl get pods -n gpu-provisioner
125+
```
126+
127+
The GPU provisioner pod should be in a `Running` state. If it's failing, check the logs:
128+
129+
```bash
130+
kubectl logs --selector=app.kubernetes.io/name=gpu-provisioner -n gpu-provisioner
131+
```
132+
133+
## Using Auto-Provisioning
134+
135+
Once set up, you can create workspaces that automatically provision GPU nodes:
136+
137+
```yaml title="phi-4-workspace.yaml"
138+
apiVersion: kaito.sh/v1beta1
139+
kind: Workspace
140+
metadata:
141+
name: workspace-phi-4-mini
142+
resource:
143+
instanceType: "Standard_NC6s_v3" # Will trigger node creation
144+
labelSelector:
145+
matchLabels:
146+
apps: phi-4-mini
147+
inference:
148+
preset:
149+
name: phi-4-mini-instruct
150+
```
151+
152+
Then apply the workspace:
153+
154+
```bash
155+
kubectl apply -f phi-4-workspace.yaml
156+
```
157+
158+
## Supported Azure GPU Instance Types
159+
160+
The GPU provisioner supports various Azure GPU SKUs, see [supported options here](https://github.com/kaito-project/kaito/blob/main/pkg/sku/azure_sku_handler.go).
161+
162+
For the complete list and specifications, see the [Azure GPU-optimized VM sizes documentation](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes-gpu).
163+
164+
## Clean Up
165+
166+
To remove the auto-provisioning setup:
167+
168+
```bash
169+
# Uninstall GPU provisioner
170+
helm uninstall gpu-provisioner -n gpu-provisioner
171+
172+
# Delete the managed identity (optional)
173+
az identity delete --name $IDENTITY_NAME -g $RESOURCE_GROUP
174+
```

0 commit comments

Comments
 (0)