Skip to content

Commit 3320b4e

Browse files
bergwolfbergwolf
authored
Merge pull request #137 from sozercan/docs-getting-started
docs: update getting started docs
2 parents 6717b0e + 5e63e05 commit 3320b4e

File tree

3 files changed

+136
-46
lines changed

3 files changed

+136
-46
lines changed

‎docs/aikit.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Using AIKit with ModelPack
2+
3+
This guide shows you how to use AIKit to package AI models as OCI artifacts using the ModelPack specification.
4+
5+
## What is AIKit?
6+
7+
[AIKit](https://kaito-project.github.io/aikit/docs/) is a comprehensive platform to quickly get started to host, deploy, build and fine-tune large language models (LLMs). AIKit also provides packaging models as OCI artifacts for distribution through any OCI-compliant registry.
8+
9+
## Prerequisites
10+
11+
- Docker with [BuildKit](https://docs.docker.com/build/buildkit/) support
12+
- [ORAS](https://oras.land/docs/installation) or [Skopeo](https://github.com/containers/skopeo/blob/main/install.md) for pushing to registries
13+
14+
## Package a Model
15+
16+
AIKit uses Docker BuildKit to package models from various sources (local files, HTTP/HTTPS, or Hugging Face).
17+
18+
### Example: Package from Hugging Face
19+
20+
```bash
21+
export HF_MODEL="Qwen/Qwen3-0.6B"
22+
export MODEL_NAME="qwen3"
23+
export OUTPUT_DIR="qwen"
24+
25+
docker buildx build \
26+
--build-arg BUILDKIT_SYNTAX=ghcr.io/kaito-project/aikit/aikit:latest \
27+
--target packager/modelpack \
28+
--build-arg source=huggingface://$HF_MODEL \
29+
--build-arg name=$MODEL_NAME \
30+
--output=$OUTPUT_DIR - <<< ""
31+
```
32+
33+
For more packaging options including compression modes, layer categorization, and exclusions, see the [AIKit packaging documentation](https://kaito-project.github.io/aikit/docs/packaging).
34+
35+
## Push to a Registry
36+
37+
Use ORAS or Skopeo to push the OCI layout to a remote registry:
38+
39+
```bash
40+
export REGISTRY="myregistry.com/mymodel:v1.0"
41+
42+
# Using ORAS
43+
oras cp --from-oci-layout $OUTPUT_DIR/layout:$MODEL_NAME $REGISTRY
44+
45+
# Or using Skopeo
46+
skopeo copy oci:$OUTPUT_DIR/layout docker://$REGISTRY
47+
```
48+
49+
## Pull from a Registry
50+
51+
Pull models using ORAS or Skopeo:
52+
53+
```bash
54+
export REGISTRY="myregistry.com/mymodel:v1.0"
55+
56+
# Using ORAS (preserves file names automatically)
57+
oras pull $REGISTRY --output path/to/model/
58+
59+
# Or using Skopeo
60+
skopeo copy docker://$REGISTRY dir://path/to/model/
61+
# rename files based on annotations
62+
(
63+
cd path/to/model/
64+
for digest in $(jq -r '.layers[].digest' manifest.json); do
65+
name=$(jq -r --arg digest "$digest" '.layers[] | select(.digest==$digest) | .annotations["org.cncf.model.filepath"]' manifest.json)
66+
if [ "$name" != "null" ]; then mv "${digest#sha256:}" "$name"; fi
67+
done
68+
)
69+
```
70+
71+
## Next Steps
72+
73+
- **See the [AIKit packaging documentation](https://kaito-project.github.io/aikit/docs/packaging)** for more information on packaging options
74+
- **Learn about the [Model CSI Driver](https://github.com/modelpack/model-csi-driver)** for Kubernetes integration
75+
- **Read the [full ModelPack specification](./spec.md)** for technical implementation details

‎docs/getting-started.md‎

Lines changed: 9 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -58,56 +58,19 @@ This section lists the core infrastructure components that ModelPack is working
5858
- Basic understanding of containers and OCI concepts
5959
- Access to an OCI-compatible registry (Docker Hub, Harbor, etc.)
6060

61-
### Practical Steps
61+
### Choose Your Tool
6262

63-
#### 1. Install modctl
63+
The ModelPack specification can be used with different tools depending on your needs:
6464

65-
Follow the instructions in the [modctl GitHub repository](https://github.com/modelpack/modctl/blob/main/docs/getting-started.md#installation) to install the CLI tool.
65+
- **[modctl](./modctl.md)**: CLI tool for building, pushing, pulling, and managing OCI model artifacts. Great for command-line workflows and CI/CD pipelines.
66+
- **[AIKit](./aikit.md)**: Package AI models as OCI artifacts from local, HTTP, or Hugging Face sources with extensible formats.
67+
- **[KitOps](https://kitops.ml/)**: ModelKit packaging and deployment platform that supports the ModelPack specification.
6668

67-
#### 2. Install Model CSI Driver
69+
### Install Model CSI Driver
6870

6971
If you plan to use models in Kubernetes, install the Model CSI Driver by following the instructions in the [Model CSI Driver repository](https://github.com/modelpack/model-csi-driver/blob/main/docs/getting-started.md#helm-installation).
7072

71-
#### 3. Download A Model
72-
73-
To package a model, you need to download it to your local directory. The following example shows how to download a model from Huggingface.
74-
75-
```bash
76-
export HF_MODEL="Qwen/Qwen3-0.6B"
77-
export MODEL_PATH=my-model-directory
78-
79-
# Install the huggingface cli
80-
pip install 'huggingface_hub'
81-
82-
# Login the huggingface cli
83-
hf auth login --token <your-huggingface-token>
84-
85-
# Download a model
86-
hf download $HF_MODEL --local-dir $MODEL_PATH
87-
```
88-
89-
#### 4. Package Your First Model
90-
91-
The following script will walk through how to build a ModelPack format model artifact and push it to the model registry.
92-
93-
```bash
94-
# Please modify the MODEL_REGISTRY environment variable to point to your OCI model registry
95-
export MODEL_REGISTRY=myregistry.com
96-
97-
# If $MODEL_REGISTRY needs authentication, please login first
98-
modctl login -u <username> -p <password> $MODEL_REGISTRY
99-
100-
# Generate a sample Modelfile, and edit the fields as needed
101-
modctl modelfile generate $MODEL_PATH
102-
103-
# Build a model artifact from your model files
104-
modctl build -t $MODEL_REGISTRY/mymodel:v1.0 $MODEL_PATH
105-
106-
# Push to an OCI registry
107-
modctl push $MODEL_REGISTRY/mymodel:v1.0
108-
```
109-
110-
#### 5. Use Models in Kubernetes
73+
## Use Models in Kubernetes
11174

11275
Here's an example Kubernetes pod spec that mounts a model artifact using the model CSI driver. The model will be available under the `/model` directory inside the container.
11376

@@ -137,8 +100,8 @@ This example shows how to mount a model artifact directly into a Kubernetes pod
137100
138101
## Next Steps
139102
140-
1. **Explore the [full ModelPack specification](./spec.md)** for technical implementation details
141-
2. **Try more options with the [modctl tool](https://github.com/modelpack/modctl)** for additional hands-on experience
103+
1. **Get hands-on experience**: Follow the step-by-step guides for [modctl](./modctl.md) or [AIKit](./aikit.md)
104+
2. **Explore the [full ModelPack specification](./spec.md)** for technical implementation details
142105
3. **Join the community** on [CNCF Slack #modelpack](https://cloud-native.slack.com/archives/C07T0V480LF)
143106
4. **Contribute** to the ModelPack project - see our [contributing guidelines](../CONTRIBUTING.md)
144107

‎docs/modctl.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Using modctl with ModelPack
2+
3+
This guide shows you how to use `modctl` to package, distribute, and manage AI models using the ModelPack specification.
4+
5+
## Installation
6+
7+
Follow the instructions to install `modctl` from the [modctl GitHub repository](https://github.com/modelpack/modctl/blob/main/docs/getting-started.md#installation) to install the CLI tool.
8+
9+
## Download A Model
10+
11+
To package a model, you need to download it to your local directory. The following example shows how to download a model from Huggingface.
12+
13+
```bash
14+
export HF_MODEL="Qwen/Qwen3-0.6B"
15+
export MODEL_PATH=my-model-directory
16+
17+
# Install the huggingface cli
18+
pip install 'huggingface_hub'
19+
20+
# Login the huggingface cli
21+
hf auth login --token <your-huggingface-token>
22+
23+
# Download a model
24+
hf download $HF_MODEL --local-dir $MODEL_PATH
25+
```
26+
27+
## Package Your First Model
28+
29+
The following script will walk through how to build a ModelPack format model artifact and push it to the model registry.
30+
31+
```bash
32+
# Please modify the MODEL_REGISTRY environment variable to point to your OCI model registry
33+
export MODEL_REGISTRY=myregistry.com
34+
35+
# If $MODEL_REGISTRY needs authentication, please login first
36+
modctl login -u <username> -p <password> $MODEL_REGISTRY
37+
38+
# Generate a sample Modelfile, and edit the fields as needed
39+
modctl modelfile generate $MODEL_PATH
40+
41+
# Build a model artifact from your model files
42+
modctl build -t $MODEL_REGISTRY/mymodel:v1.0 $MODEL_PATH
43+
44+
# Push to an OCI registry
45+
modctl push $MODEL_REGISTRY/mymodel:v1.0
46+
```
47+
48+
## Next Steps
49+
50+
- **Explore more [modctl commands](https://github.com/modelpack/modctl)** for additional functionality
51+
- **Learn about the [Model CSI Driver](https://github.com/modelpack/model-csi-driver)** for Kubernetes integration
52+
- **Read the [full ModelPack specification](./spec.md)** for technical implementation details

0 commit comments

Comments
 (0)