Skip to content

Commit f64bbf0

Browse files
ilopezlunaericcurtin
ilopezluna
and
ericcurtin
authored
feat: add CNCF ModelPack type definitions (#859)
* feat: add CNCF ModelPack type definitions, conversion utilities, and manifest ArtifactType support - Add CNCF ModelPack media type constants and Model type (modelpack/types.go) - Add DockerConfigToModelPack conversion utility (modelpack/convert.go) - Add CNCFModel partial type for CNCF format support (partial/cncf_model.go) - Add ArtifactType field to OCI Manifest struct (oci/manifest.go) - Update partial/mutate layers for format-aware manifest options - Replace deprecated WithConfigMediaType with WithManifestOptions - Add model-spec v0.0.7 dependency * feat: add --format flag to package command and CNCF build support in builder - Add BuildFormat type and WithFormat option to builder for Docker/CNCF selection - Implement CNCF artifact creation with media type remapping and config conversion - Add --format CLI flag to 'docker model package' command with validation - Improve context size error handling (return error for invalid values) - Add comprehensive builder tests for CNCF format (artifact validation, media types) - Add integration tests for CNCF format packaging - Update CLI reference documentation * feat: add CNCF model unpacking, detection, and mmproj file handling - Add DiffID extraction support for CNCF remote layers (oci/remote) - Add CNCF layer handling in bundle unpack with media type classification - Detect mmproj files by filepath annotation in CNCF generic weight layers - Add findModelFileExcluding helper for mmproj-aware model file discovery - Add comprehensive tests for DiffID extraction, CNCF layer unpacking, mmproj detection, and parse with CNCF mmproj GGUF files * fix: harden remappedLayer descriptor and add format auto-detection Address review feedback from PR #860: 1. remappedLayer.GetDescriptor: pre-compute digest and size at construction time via newRemappedLayer(), surfacing errors eagerly instead of silently producing invalid OCI descriptors. 2. FromModel format inheritance: when --format is not explicitly set, auto- detect the source model's format (Docker vs CNCF) from its config. This prevents producing inconsistent artifacts when repackaging a CNCF model without an explicit --format flag. 3. CLI conditional --format: only pass WithFormat to the builder when the user explicitly sets --format, allowing the builder's auto-detection to work for the repackaging case. * fix: preserve determinism in DockerConfigToModelPack and fix normalizeParamSize comment - Remove time.Now() fallback in DockerConfigToModelPack: propagate desc.Created directly (nil when unset) so callers control timestamps and converted configs remain deterministic across runs. - Fix normalizeParamSize comment to accurately describe its behavior (lowercases, does not truncate decimal precision). * refactor: remove normalizeParamSize, pass Parameters as-is to CNCF config The function only lowercased the string, which is unnecessary — the CNCF model-spec does not mandate lowercase paramSize values. Pass cfg.Parameters directly to keep the same value as the Docker format. * fix: use newRemappedLayer in FromDirectory for consistent digest/size caching The CNCF path in FromDirectory was constructing remappedLayer directly, bypassing the digest/size pre-computation added in newRemappedLayer. This left cachedDigest/cachedSize zero-valued for layers that aren't descriptor providers, producing invalid OCI descriptors. --------- Co-authored-by: Eric Curtin <eric.curtin@docker.com>
1 parent 3e93eff commit f64bbf0

24 files changed

Lines changed: 1856 additions & 242 deletions

‎cmd/cli/commands/integration_test.go‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,8 @@ func createAndPushTestModel(t *testing.T, registryURL, modelRef string, contextS
269269

270270
// Set context size if specified
271271
if contextSize != nil {
272-
pkg = pkg.WithContextSize(*contextSize)
272+
pkg, err = pkg.WithContextSize(*contextSize)
273+
require.NoError(t, err)
273274
}
274275

275276
// Construct the full reference with the local registry host for pushing from test host
@@ -1053,6 +1054,7 @@ func TestIntegration_PackageModel(t *testing.T) {
10531054
opts := packageOptions{
10541055
ggufPath: absPath,
10551056
tag: targetTag,
1057+
format: "docker",
10561058
}
10571059

10581060
// Execute the package command using the helper function with test client
@@ -1088,6 +1090,7 @@ func TestIntegration_PackageModel(t *testing.T) {
10881090
ggufPath: absPath,
10891091
tag: targetTag,
10901092
contextSize: 4096,
1093+
format: "docker",
10911094
}
10921095

10931096
// Create a command for context
@@ -1120,6 +1123,7 @@ func TestIntegration_PackageModel(t *testing.T) {
11201123
opts := packageOptions{
11211124
ggufPath: absPath,
11221125
tag: targetTag,
1126+
format: "docker",
11231127
}
11241128

11251129
// Create a command for context
@@ -1142,6 +1146,34 @@ func TestIntegration_PackageModel(t *testing.T) {
11421146
require.NoError(t, err, "Failed to remove model")
11431147
})
11441148

1149+
// Test case 4: Package with CNCF format
1150+
t.Run("package GGUF with CNCF format", func(t *testing.T) {
1151+
targetTag := "ai/packaged-cncf:latest"
1152+
1153+
// Create package options with CNCF format
1154+
opts := packageOptions{
1155+
ggufPath: absPath,
1156+
tag: targetTag,
1157+
format: "cncf",
1158+
}
1159+
1160+
// Execute the package command using the helper function with test client
1161+
t.Logf("Packaging GGUF file as CNCF format %s", targetTag)
1162+
err := packageModel(env.ctx, newPackagedCmd(), env.client, opts)
1163+
require.NoError(t, err, "Failed to package GGUF model with CNCF format")
1164+
1165+
// Verify the model was loaded and tagged
1166+
model, err := env.client.Inspect(targetTag, false)
1167+
require.NoError(t, err, "Failed to inspect CNCF packaged model")
1168+
require.Contains(t, model.Tags, normalizeRef(t, targetTag), "Model should have the expected tag")
1169+
1170+
t.Logf("✓ Successfully packaged model with CNCF format: %s (ID: %s)", targetTag, model.ID[7:19])
1171+
1172+
// Cleanup
1173+
err = removeModel(env.client, model.ID, true)
1174+
require.NoError(t, err, "Failed to remove model")
1175+
})
1176+
11451177
// Verify all models are cleaned up
11461178
models, err = listModels(false, env.client, true, false, "")
11471179
require.NoError(t, err)

‎cmd/cli/commands/package.go‎

Lines changed: 52 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,8 @@ Packaging behavior:
208208
c.Flags().StringVar(&opts.mmprojPath, "mmproj", "", "absolute path to multimodal projector file")
209209
c.Flags().BoolVar(&opts.push, "push", false, "push to registry (if not set, the model is loaded into the Model Runner content store)")
210210
c.Flags().Uint64Var(&opts.contextSize, "context-size", 0, "context size in tokens")
211+
c.Flags().StringVar(&opts.format, "format", "docker",
212+
"output artifact format: \"docker\" (default) or \"cncf\" (CNCF ModelPack spec)")
211213
return c
212214
}
213215

@@ -222,21 +224,36 @@ type packageOptions struct {
222224
mmprojPath string
223225
push bool
224226
tag string
227+
format string // "docker" (default) or "cncf"
225228
}
226229

227-
// builderInitResult contains the result of initializing a builder from various sources
230+
// builderInitResult contains the result of initializing a builder from
231+
// various sources.
228232
type builderInitResult struct {
229233
builder *builder.Builder
230-
distClient *distribution.Client // Only set when building from existing model
231-
cleanupFunc func() // Optional cleanup function for temporary files
234+
distClient *distribution.Client // Only set when building from existing model.
235+
cleanupFunc func() // Optional cleanup function for temporary files.
232236
}
233237

234-
// initializeBuilder creates a package builder from GGUF, Safetensors, DDUF, or existing model
238+
// initializeBuilder creates a package builder from GGUF, Safetensors, DDUF,
239+
// or existing model.
235240
func initializeBuilder(ctx context.Context, cmd *cobra.Command, client *desktop.Client, opts packageOptions) (*builderInitResult, error) {
236241
result := &builderInitResult{}
237242

243+
// Only pass format option to the builder if the --format flag was
244+
// explicitly set by the user. When omitted, the builder inherits
245+
// the source model's format automatically (see builder.FromModel).
246+
var buildOpts []builder.BuildOption
247+
if cmd.Flags().Changed("format") {
248+
buildFmt := builder.BuildFormatDocker
249+
if opts.format == "cncf" {
250+
buildFmt = builder.BuildFormatCNCF
251+
}
252+
buildOpts = append(buildOpts, builder.WithFormat(buildFmt))
253+
}
254+
238255
if opts.fromModel != "" {
239-
// Get the model store path
256+
// Get the model store path.
240257
userHomeDir, err := os.UserHomeDir()
241258
if err != nil {
242259
return nil, fmt.Errorf("get user home directory: %w", err)
@@ -246,14 +263,14 @@ func initializeBuilder(ctx context.Context, cmd *cobra.Command, client *desktop.
246263
modelStorePath = envPath
247264
}
248265

249-
// Create a distribution client to access the model store
266+
// Create a distribution client to access the model store.
250267
distClient, err := distribution.NewClient(distribution.WithStoreRootPath(modelStorePath))
251268
if err != nil {
252269
return nil, fmt.Errorf("create distribution client: %w", err)
253270
}
254271
result.distClient = distClient
255272

256-
// Package from existing model
273+
// Package from existing model.
257274
cmd.PrintErrf("Reading model from store: %q\n", opts.fromModel)
258275

259276
mdl, err := distClient.GetModel(opts.fromModel)
@@ -266,35 +283,44 @@ func initializeBuilder(ctx context.Context, cmd *cobra.Command, client *desktop.
266283
}
267284
}
268285

269-
// Type assert to ModelArtifact - the Model from store implements both interfaces
286+
// Type assert to ModelArtifact.
270287
modelArtifact, ok := mdl.(types.ModelArtifact)
271288
if !ok {
272289
return nil, fmt.Errorf("model does not implement ModelArtifact interface")
273290
}
274291

275292
cmd.PrintErrf("Creating builder from existing model\n")
276-
result.builder, err = builder.FromModel(modelArtifact)
293+
result.builder, err = builder.FromModel(modelArtifact, buildOpts...)
277294
if err != nil {
278295
return nil, fmt.Errorf("create builder from model: %w", err)
279296
}
280297
} else if opts.ggufPath != "" {
281298
cmd.PrintErrf("Adding GGUF file from %q\n", opts.ggufPath)
282-
pkg, err := builder.FromPath(opts.ggufPath)
299+
pkg, err := builder.FromPath(opts.ggufPath, buildOpts...)
283300
if err != nil {
284301
return nil, fmt.Errorf("add gguf file: %w", err)
285302
}
286303
result.builder = pkg
287304
} else if opts.ddufPath != "" {
288305
cmd.PrintErrf("Adding DDUF file from %q\n", opts.ddufPath)
289-
pkg, err := builder.FromPath(opts.ddufPath)
306+
pkg, err := builder.FromPath(opts.ddufPath, buildOpts...)
290307
if err != nil {
291308
return nil, fmt.Errorf("add dduf file: %w", err)
292309
}
293310
result.builder = pkg
294311
} else if opts.safetensorsDir != "" {
295-
// Safetensors model from directory — uses V0.2 layer-per-file packaging
312+
// Safetensors model from directory — uses V0.2 layer-per-file packaging.
296313
cmd.PrintErrf("Scanning directory %q for safetensors model...\n", opts.safetensorsDir)
297-
pkg, err := builder.FromDirectory(opts.safetensorsDir)
314+
var dirOpts []builder.DirectoryOption
315+
if cmd.Flags().Changed("format") {
316+
dirFmt := builder.BuildFormatDocker
317+
if opts.format == "cncf" {
318+
dirFmt = builder.BuildFormatCNCF
319+
}
320+
dirOpts = append(dirOpts, builder.WithOutputFormat(dirFmt))
321+
}
322+
pkg, err := builder.FromDirectory(opts.safetensorsDir,
323+
dirOpts...)
298324
if err != nil {
299325
return nil, fmt.Errorf("create safetensors model from directory: %w", err)
300326
}
@@ -344,9 +370,17 @@ func fetchModelFromDaemon(ctx context.Context, cmd *cobra.Command, client *deskt
344370
}
345371

346372
func packageModel(ctx context.Context, cmd *cobra.Command, client *desktop.Client, opts packageOptions) error {
347-
// Use daemon-side repackaging for simple config-only changes (no new layers)
373+
// Validate format flag.
374+
if opts.format != "docker" && opts.format != "cncf" {
375+
return fmt.Errorf("invalid --format value %q: must be \"docker\" or \"cncf\"", opts.format)
376+
}
377+
378+
// Use daemon-side repackaging for simple config-only changes (no new
379+
// layers). Disabled for CNCF format because the daemon produces
380+
// Docker-format artifacts.
348381
canUseDaemonRepackage := opts.fromModel != "" &&
349382
!opts.push &&
383+
opts.format != "cncf" &&
350384
len(opts.licensePaths) == 0 &&
351385
opts.chatTemplatePath == "" &&
352386
opts.mmprojPath == "" &&
@@ -408,7 +442,10 @@ func packageModel(ctx context.Context, cmd *cobra.Command, client *desktop.Clien
408442
// Set context size
409443
if cmd.Flags().Changed("context-size") {
410444
cmd.PrintErrf("Setting context size %d\n", opts.contextSize)
411-
pkg = pkg.WithContextSize(int32(opts.contextSize))
445+
pkg, err = pkg.WithContextSize(int32(opts.contextSize))
446+
if err != nil {
447+
return err
448+
}
412449
}
413450

414451
// Add license files

‎cmd/cli/docs/reference/docker_model_package.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,17 @@ options:
7171
experimentalcli: false
7272
kubernetes: false
7373
swarm: false
74+
- option: format
75+
value_type: string
76+
default_value: docker
77+
description: |
78+
output artifact format: "docker" (default) or "cncf" (CNCF ModelPack spec)
79+
deprecated: false
80+
hidden: false
81+
experimental: false
82+
experimentalcli: false
83+
kubernetes: false
84+
swarm: false
7485
- option: from
7586
value_type: string
7687
description: reference to an existing model to repackage

‎cmd/cli/docs/reference/model_package.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,18 @@ Packaging behavior:
4242

4343
### Options
4444

45-
| Name | Type | Default | Description |
46-
|:--------------------|:--------------|:--------|:---------------------------------------------------------------------------------------|
47-
| `--chat-template` | `string` | | absolute path to chat template file (must be Jinja format) |
48-
| `--context-size` | `uint64` | `0` | context size in tokens |
49-
| `--dduf` | `string` | | absolute path to DDUF archive file (Diffusers Unified Format) |
50-
| `--from` | `string` | | reference to an existing model to repackage |
51-
| `--gguf` | `string` | | absolute path to gguf file |
52-
| `-l`, `--license` | `stringArray` | | absolute path to a license file |
53-
| `--mmproj` | `string` | | absolute path to multimodal projector file |
54-
| `--push` | `bool` | | push to registry (if not set, the model is loaded into the Model Runner content store) |
55-
| `--safetensors-dir` | `string` | | absolute path to directory containing safetensors files and config |
45+
| Name | Type | Default | Description |
46+
|:--------------------|:--------------|:---------|:---------------------------------------------------------------------------------------|
47+
| `--chat-template` | `string` | | absolute path to chat template file (must be Jinja format) |
48+
| `--context-size` | `uint64` | `0` | context size in tokens |
49+
| `--dduf` | `string` | | absolute path to DDUF archive file (Diffusers Unified Format) |
50+
| `--format` | `string` | `docker` | output artifact format: "docker" (default) or "cncf" (CNCF ModelPack spec) |
51+
| `--from` | `string` | | reference to an existing model to repackage |
52+
| `--gguf` | `string` | | absolute path to gguf file |
53+
| `-l`, `--license` | `stringArray` | | absolute path to a license file |
54+
| `--mmproj` | `string` | | absolute path to multimodal projector file |
55+
| `--push` | `bool` | | push to registry (if not set, the model is loaded into the Model Runner content store) |
56+
| `--safetensors-dir` | `string` | | absolute path to directory containing safetensors files and config |
5657

5758

5859
<!---MARKER_GEN_END-->

‎go.mod‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ require (
2222
github.com/moby/moby/api v1.54.1
2323
github.com/moby/moby/client v0.4.0
2424
github.com/moby/term v0.5.2
25+
github.com/modelpack/model-spec v0.0.7
2526
github.com/muesli/termenv v0.16.0
2627
github.com/nxadm/tail v1.4.11
2728
github.com/olekukonko/tablewriter v1.1.4
@@ -128,8 +129,8 @@ require (
128129
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.35.0 // indirect
129130
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.35.0 // indirect
130131
go.opentelemetry.io/otel/metric v1.43.0 // indirect
131-
go.opentelemetry.io/otel/sdk v1.43.0 // indirect
132-
go.opentelemetry.io/otel/sdk/metric v1.43.0 // indirect
132+
go.opentelemetry.io/otel/sdk v1.41.0 // indirect
133+
go.opentelemetry.io/otel/sdk/metric v1.41.0 // indirect
133134
go.opentelemetry.io/otel/trace v1.43.0 // indirect
134135
go.opentelemetry.io/proto/otlp v1.9.0 // indirect
135136
go.yaml.in/yaml/v2 v2.4.3 // indirect

‎go.sum‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,8 @@ github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g
199199
github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
200200
github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
201201
github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
202+
github.com/modelpack/model-spec v0.0.7 h1:3fAxau4xUqF0Pf1zzFC5lItF0gEaiXLxaCcPAH8PW8I=
203+
github.com/modelpack/model-spec v0.0.7/go.mod h1:5Go37og1RmvcTdVI5Remd+PpQRNLlKSNwSNbXmEqu50=
202204
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
203205
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
204206
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -300,10 +302,10 @@ go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.35.0 h1:m639+
300302
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.35.0/go.mod h1:LjReUci/F4BUyv+y4dwnq3h/26iNOeC3wAIqgvTIZVo=
301303
go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
302304
go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
303-
go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
304-
go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
305-
go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
306-
go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
305+
go.opentelemetry.io/otel/sdk v1.41.0 h1:YPIEXKmiAwkGl3Gu1huk1aYWwtpRLeskpV+wPisxBp8=
306+
go.opentelemetry.io/otel/sdk v1.41.0/go.mod h1:ahFdU0G5y8IxglBf0QBJXgSe7agzjE4GiTJ6HT9ud90=
307+
go.opentelemetry.io/otel/sdk/metric v1.41.0 h1:siZQIYBAUd1rlIWQT2uCxWJxcCO7q3TriaMlf08rXw8=
308+
go.opentelemetry.io/otel/sdk/metric v1.41.0/go.mod h1:HNBuSvT7ROaGtGI50ArdRLUnvRTRGniSUZbxiWxSO8Y=
307309
go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
308310
go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
309311
go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=

0 commit comments

Comments
 (0)