From 5714784a05f68d3c47c3e35b7440c5d24ba27b2c Mon Sep 17 00:00:00 2001 From: Peng Tao Date: Thu, 23 Jan 2025 03:49:44 +0000 Subject: [PATCH] spec: add initial model config definition Right now we define a lot of model general information as annotations. They should be defined as a field of model config. We use the guidelines below to decide if a model artifact description should be an annotation or in a structured config file: * If a description belongs to a specific layer, it SHOULD be an annotation * If a description describes a general property of the model, it SHOULD be in a config Also a `ModelFS` structure is introduced to describe the ordering of multiple layers. Fixes: #19 Fixes: #22 Signed-off-by: Peng Tao --- go.mod | 2 + go.sum | 2 + specs-go/v1/annotations.go | 70 ------------------------ specs-go/v1/config.go | 106 +++++++++++++++++++++++++++++++++++++ specs-go/v1/mediatype.go | 5 +- 5 files changed, 113 insertions(+), 72 deletions(-) create mode 100644 go.sum create mode 100644 specs-go/v1/config.go diff --git a/go.mod b/go.mod index c832c1b..cb0257b 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,5 @@ module github.com/CloudNativeAI/model-spec go 1.23.1 + +require github.com/opencontainers/go-digest v1.0.0 diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..30f45e9 --- /dev/null +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= +github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM= diff --git a/specs-go/v1/annotations.go b/specs-go/v1/annotations.go index f6eb237..f0da999 100644 --- a/specs-go/v1/annotations.go +++ b/specs-go/v1/annotations.go @@ -17,76 +17,6 @@ package v1 const ( - // AnnotationCreated is the annotation key for the date and time on which the model was built (date-time string as defined by RFC 3339). - AnnotationCreated = "org.cnai.model.created" - - // AnnotationAuthors is the annotation key for the contact details of the people or organization responsible for the model (freeform string). - AnnotationAuthors = "org.cnai.model.authors" - - // AnnotationURL is the annotation key for the URL to find more information on the model. - AnnotationURL = "org.cnai.model.url" - - // AnnotationDocumentation is the annotation key for the URL to get documentation on the model. - AnnotationDocumentation = "org.cnai.model.documentation" - - // AnnotationSource is the annotation key for the URL to get source code for building the model. - AnnotationSource = "org.cnai.model.source" - - // AnnotationVersion is the annotation key for the version of the packaged software. - // The version MAY match a label or tag in the source code repository. - // The version MAY be Semantic versioning-compatible. - AnnotationVersion = "org.cnai.model.version" - - // AnnotationRevision is the annotation key for the source control revision identifier for the packaged software. - AnnotationRevision = "org.cnai.model.revision" - - // AnnotationVendor is the annotation key for the name of the distributing entity, organization or individual. - AnnotationVendor = "org.cnai.model.vendor" - - // AnnotationLicenses is the annotation key for the license(s) under which contained software is distributed as an SPDX License Expression. - AnnotationLicenses = "org.cnai.model.licenses" - - // AnnotationRefName is the annotation key for the name of the reference for a target. - // SHOULD only be considered valid when on descriptors on `index.json` within model layout. - AnnotationRefName = "org.cnai.model.ref.name" - - // AnnotationTitle is the annotation key for the human-readable title of the model. - AnnotationTitle = "org.cnai.model.title" - - // AnnotationDescription is the annotation key for the human-readable description of the software packaged in the model. - AnnotationDescription = "org.cnai.model.description" -) - -const ( - // AnnotationArchitecture is the annotation key for the model architecture, such as `transformer`, `cnn`, `rnn`, etc. - AnnotationArchitecture = "org.cnai.model.architecture" - - // AnnotationFamily is the annotation key for the model family, such as `llama3`, `gpt2`, `qwen2`, etc. - AnnotationFamily = "org.cnai.model.family" - - // AnnotationName is the annotation key for the model name, such as `llama3-8b-instruct`, `gpt2-xl`, `qwen2-vl-72b-instruct`, etc. - AnnotationName = "org.cnai.model.name" - - // AnnotationFormat is the annotation key for the model format, such as `onnx`, `tensorflow`, `pytorch`, etc. - AnnotationFormat = "org.cnai.model.format" - - // AnnotationParamSize is the annotation key for the size of the model parameters. - AnnotationParamSize = "org.cnai.model.param.size" - - // AnnotationPrecision is the annotation key for the model precision, such as `bf16`, `fp16`, `int8`, etc. - AnnotationPrecision = "org.cnai.model.precision" - - // AnnotationQuantization is the annotation key for the model quantization, such as `awq`, `gptq`, etc. - AnnotationQuantization = "org.cnai.model.quantization" -) - -const ( - // AnnotationReadme is the annotation key for the layer is a README.md file (boolean), such as `true` or `false`. - AnnotationReadme = "org.cnai.model.readme" - - // AnnotationLicense is the annotation key for the layer is a license file (boolean), such as `true` or `false`. - AnnotationLicense = "org.cnai.model.license" - // AnnotationConfig is the annotation key for the layer is a configuration file (boolean), such as `true` or `false`. AnnotationConfig = "org.cnai.model.config" diff --git a/specs-go/v1/config.go b/specs-go/v1/config.go new file mode 100644 index 0000000..e3cd0d9 --- /dev/null +++ b/specs-go/v1/config.go @@ -0,0 +1,106 @@ +/* + * Copyright 2025 The CNAI Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package v1 + +import ( + "time" + + digest "github.com/opencontainers/go-digest" +) + +// ModelConfig defines the execution parameters +// which should be used as a base when running a model using an inference engine. +type ModelConfig struct { + // The model architecture, such as transformer, cnn, rnn, etc. + Architecture string `json:"architecture,omitempty"` + + // The model format, such as onnx, tensorflow, pytorch, etc. + Format string `json:"format,omitempty"` + + // The size of the model parameters + ParameterSize uint64 `json:"parameterSize,omitempty"` + + // The model precision, such as bf16, fp16, int8, mixed etc. + Precision string `json:"precision,omitempty"` + + // The model quantization, such as awq, gptq, etc + Quantization string `json:"puantization,omitempty"` +} + +// ModelFS describes a layer content addresses +type ModelFS struct { + // Type is the type of the rootfs. MUST be set to "layers". + Type string `json:"type"` + + // DiffIDs is an array of layer content hashes (DiffIDs), in order from bottom-most to top-most. + DiffIDs []digest.Digest `json:"diff_ids"` +} + +// ModelDescriptor defines the general information of a model +type ModelDescriptor struct { + // Date and time on which the model was built + CreateTime *time.Time `json:"createTime,omitempty"` + + // The contact details of the people or organization responsible for the model + Authors []string `json:"authors,omitempty"` + + // The model family, such as llama3, gpt2, qwen2, etc. + Family string `json:"family,omitempty"` + + // The model name, such as llama3-8b-instruct, gpt2-xl, qwen2-vl-72b-instruct, etc. + Name string `json:"name,omitempty"` + + // The URL to find more information on the model + InfoURL string `json:"infoURL,omitempty"` + + // The URL to get documentation on the model + DocURL string `json:"docURL,omitempty"` + + // The URL to get source code for building the model + SourceURL string `json:"sourceURL,omitempty"` + + // The version of the packaged software + Version string `json:"version,omitempty"` + + // The source control revision identifier for the packaged software + Revision string `json:"revision,omitempty"` + + // The name of the distributing entity, organization or individual + Vendor string `json:"vendor,omitempty"` + + // The license(s) under which contained software is distributed as an SPDX License Expression + Licenses []string `json:"licenses,omitempty"` + + // The human-readable title of the model + Title string `json:"title,omitempty"` + + // The human-readable description of the software packaged in the model + Description string `json:"description,omitempty"` +} + +// Model defines the basic information of a model. +// It provides the `application/vnd.cnai.model.config.v1+json` mediatype when marshalled to JSON. +type Model struct { + // The model descriptor + Descriptor ModelDescriptor `json:"descriptor"` + + // The model describes a layer content addresses + ModelFS ModelFS `json:"modelfs"` + + // Config defines the execution parameters which should be used as a base when running a model using an inference engine. + Config ModelConfig `json:"config,omitempty"` +} diff --git a/specs-go/v1/mediatype.go b/specs-go/v1/mediatype.go index 2114eff..90c169e 100644 --- a/specs-go/v1/mediatype.go +++ b/specs-go/v1/mediatype.go @@ -19,9 +19,10 @@ package v1 const ( // ArtifactTypeModelManifest specifies the media type for a model manifest. ArtifactTypeModelManifest = "application/vnd.cnai.model.manifest.v1+json" -) -const ( + // ArtifactTypeModelConfig specifies the media type for a model configuration. + ArtifactTypeModelConfig = "application/vnd.cnai.model.config.v1+json" + // ArtifactTypeModelLayer is the media type used for layers referenced by the manifest. ArtifactTypeModelLayer = "application/vnd.cnai.model.layer.v1.tar"