├── .github └── workflows │ └── lint.yml ├── .gitignore ├── .golangci.yml ├── .markdownlint.yml ├── .typos.toml ├── CONTRIBUTING.md ├── LICENSE ├── MAINTAINERS.md ├── README.md ├── ROADMAP.md ├── code-of-conduct.md ├── docs ├── annotations.md ├── config.md ├── img │ ├── build-and-push.png │ ├── infra-trends.png │ ├── manifest.svg │ └── pull-and-serve.png └── spec.md ├── go.mod ├── go.sum └── specs-go └── v1 ├── annotations.go ├── config.go └── mediatype.go /.github/workflows/lint.yml: -------------------------------------------------------------------------------- 1 | name: Lint 2 | 3 | on: 4 | push: 5 | branches: [main, release-*] 6 | pull_request: 7 | branches: [main, release-*] 8 | 9 | permissions: 10 | contents: read 11 | 12 | jobs: 13 | lint: 14 | name: Lint 15 | runs-on: ubuntu-latest 16 | timeout-minutes: 30 17 | steps: 18 | - name: Checkout code 19 | uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 20 | 21 | - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 22 | with: 23 | go-version-file: go.mod 24 | cache: false 25 | 26 | - name: Golangci lint 27 | uses: golangci/golangci-lint-action@v6 28 | with: 29 | version: v1.61 30 | args: --verbose 31 | 32 | - name: Markdown lint 33 | uses: docker://avtodev/markdown-lint:v1@sha256:6aeedc2f49138ce7a1cd0adffc1b1c0321b841dc2102408967d9301c031949ee 34 | with: 35 | config: '.markdownlint.yml' 36 | args: '**/*.md' 37 | 38 | - uses: crate-ci/typos@b74202f74b4346efdbce7801d187ec57b266bac8 # v1.27.3 39 | with: 40 | config: .typos.toml 41 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Binaries for programs and plugins 2 | *.exe 3 | *.exe~ 4 | 5 | # Test binary, built with `go test -c` 6 | *.test 7 | 8 | # Output of the go coverage tool, specifically when used with LiteIDE 9 | *.out 10 | 11 | # Dependency directories (remove the comment below to include it) 12 | vendor/ 13 | .idea 14 | .vscode 15 | .cache 16 | *.DS_Store 17 | target/ 18 | scheduler/test/misc 19 | manager/dist/* 20 | !manager/dist/.gitkeep 21 | .chglog 22 | 23 | # vscode 24 | .vscode/* 25 | !.vscode/settings.json 26 | !.vscode/tasks.json 27 | !.vscode/launch.json 28 | !.vscode/extensions.json 29 | *.code-workspace 30 | 31 | # General 32 | .DS_Store 33 | .AppleDouble 34 | .LSOverride 35 | 36 | # Icon must end with two \r 37 | Icon 38 | 39 | # Thumbnails 40 | ._* 41 | 42 | # Files that might appear in the root of a volume 43 | .DocumentRevisions-V100 44 | .fseventsd 45 | .Spotlight-V100 46 | .TemporaryItems 47 | .Trashes 48 | .VolumeIcon.icns 49 | .com.apple.timemachine.donotpresent 50 | 51 | # Directories potentially created on remote AFP share 52 | .AppleDB 53 | .AppleDesktop 54 | Network Trash Folder 55 | Temporary Items 56 | .apdisk 57 | -------------------------------------------------------------------------------- /.golangci.yml: -------------------------------------------------------------------------------- 1 | run: 2 | timeout: 3m 3 | modules-download-mode: readonly 4 | 5 | linters-settings: 6 | gocyclo: 7 | min-complexity: 100 8 | gci: 9 | sections: 10 | - standard 11 | - default 12 | 13 | issues: 14 | new: true 15 | exclude-rules: 16 | - linters: 17 | - staticcheck 18 | text: "SA1019:" 19 | 20 | linters: 21 | disable-all: true 22 | enable: 23 | - gci 24 | - gofmt 25 | - misspell 26 | - govet 27 | - goconst 28 | - gocyclo 29 | - staticcheck 30 | - errcheck 31 | 32 | output: 33 | formats: 34 | - format: colored-line-number 35 | path: stdout 36 | print-issued-lines: true 37 | print-linter-name: true 38 | -------------------------------------------------------------------------------- /.markdownlint.yml: -------------------------------------------------------------------------------- 1 | MD010: false 2 | 3 | MD013: false 4 | 5 | MD046: 6 | style: "fenced" 7 | -------------------------------------------------------------------------------- /.typos.toml: -------------------------------------------------------------------------------- 1 | [files] 2 | extend-exclude = [ 3 | "go.mod", 4 | "*.svg" 5 | ] 6 | ignore-hidden = true 7 | ignore-files = true 8 | ignore-dot = true 9 | ignore-vcs = true 10 | ignore-global = true 11 | ignore-parent = true 12 | 13 | [default] 14 | binary = false 15 | check-filename = true 16 | check-file = true 17 | unicode = true 18 | ignore-hex = true 19 | identifier-leading-digits = false 20 | locale = "en" 21 | extend-ignore-identifiers-re = [] 22 | extend-ignore-re = [] 23 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributors' Guide 2 | 3 | ## Getting started 4 | 5 | Welcome to the Cloud Native AI Model Format Specification project! We are excited to have you contribute. Here are some steps to help you get started. 6 | 7 | ## Setting up your local environment 8 | 9 | * **Clone the repository**: 10 | 11 | ```sh 12 | git clone https://github.com/CloudNativeAI/model-spec.git 13 | cd model-spec 14 | ``` 15 | 16 | * **Install dependencies**: Ensure you have [Go](https://go.dev/) installed, as the current spec implementation is written in Go. Follow the [official instructions to install Go](https://go.dev/doc/install). 17 | 18 | ## Where to put changes 19 | 20 | Right now, we have a simple directory structure: 21 | 22 | * `docs`: All detailed documents about the model spec. 23 | * `docs/img`: Any referenced images in the documents should be put here. 24 | * `specs-go`: A Go implementation of the model specification. 25 | 26 | ## Raise a pull request 27 | 28 | * **Create a new branch**: 29 | 30 | ```sh 31 | git checkout -b your-branch-name 32 | ``` 33 | 34 | * **Make your changes and commit them**: 35 | 36 | ```sh 37 | git add . 38 | git commit -s -m "Your descriptive commit message" 39 | ``` 40 | 41 | * **Push your changes to your fork**: 42 | 43 | ```sh 44 | git push your-fork-repo your-branch-name 45 | ``` 46 | 47 | * **Open a pull request**: Go to the GitHub repository, compare your branch, and submit a pull request with a detailed description of your changes. 48 | 49 | ## Make sure pull request CI passes 50 | 51 | Please check the CI status in your pull request and fix anything that fails. Here are some simple instructions to validate CI locally. 52 | 53 | * **Install golangci-lint**: follow the [official installation guide](https://golangci-lint.run/welcome/install/#local-installation) to install golangci-lint. 54 | 55 | * **Check for linting issues**: 56 | 57 | ```sh 58 | golangci-lint run --verbose 59 | ``` 60 | 61 | We appreciate your contributions and look forward to working with you! 62 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | The current Maintainers for the project are 4 | 5 | - chlins 6 | - gaius-qi 7 | - bergwolf 8 | - sabre1041 9 | - tarilabs 10 | - wy65701436 11 | - bmicklea 12 | - raravena80 13 | - aftersnow 14 | - gorkem 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # CNAI Model Format Specification 2 | 3 | [![GoDoc](https://godoc.org/github.com/CloudNativeAI/model-spec?status.svg)](https://godoc.org/github.com/CloudNativeAI/model-spec) 4 | [![Discussions](https://img.shields.io/badge/discussions-on%20github-blue?style=flat-square)](https://github.com/CloudNativeAI/model-spec/discussions) 5 | 6 | The Cloud Native Artifacial Intelligence (CNAI) Model Specification aims to provide a standard way to package, distribute and run AI models in a cloud native environment. 7 | 8 | ## Rationale 9 | 10 | Looking back in history, there are clear trends in the evolution of infrastructure. At first, there is the machine centric infrastructure age. GNU/Linux was born there and we saw a boom of Linux distributions then. Then comes the Virtual Machine centric infrastructure age, where we saw the rise of cloud computing and the development of virtualization technologies. The third age is the container centric infrastructure, and we saw the rise of container technologies like Docker and Kubernetes. The fourth age, which has just begun, is the AI model centric infrastructure age, where we will see a burst of technologies and projects around AI model development and deployment. 11 | 12 | ![img](docs/img/infra-trends.png) 13 | 14 | Each of the new ages has brought new technologies and new ways of thinking. The container centric infrastructure has brought us the OCI image specification, which has become the standard for packaging and distributing software. The AI model centric infrastructure will bring us new ways of packaging and distributing AI models. The model specification is an attempt to define a standard to help package, distribute and run AI models in a cloud native environment. 15 | 16 | ## Current Work 17 | 18 | The specification, provides a compatible way to package and distribute models based on the current [OCI image specification](https://github.com/opencontainers/image-spec/) and [the artifacts guidelines](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage). For compatibility reasons, it only contains part of the model metadata, and handles model artifacts as opaque binaries. However, it provides a convenient way to package AI models in the container image format and can be used as [OCI volume sources](https://github.com/kubernetes/enhancements/issues/4639) in Kubernetes environments. 19 | 20 | For details, please see [the specification](docs/spec.md). 21 | 22 | ## LICENSE 23 | 24 | Apache 2.0 License. Please see [LICENSE](LICENSE) for more information. 25 | 26 | ## Community, Support, Discussion 27 | 28 | You can engage with this project by joining the discussion on our Slack channel: [#model-spec-discussion](https://cloud-native.slack.com/archives/C07T0V480LF) in the [CNCF Slack workspace](https://slack.cncf.io/). 29 | 30 | ## Contributing 31 | 32 | Any feedback, suggestions, and contributions are welcome. Please feel free to open an issue or pull request. 33 | 34 | Especially, we look forward to integrating the model specification with different model registry implementations (like [Harbor](https://goharbor.io/) and [Kubeflow model registry](https://www.kubeflow.org/docs/components/model-registry/overview/)), as well as existing model centric infrastructure projects like [Huggingface](https://huggingface.co/), [KitOps](https://kitops.ml/), [Kubeflow](https://www.kubeflow.org/), [Lepton](https://www.lepton.ai/), [Ollama](https://github.com/ollama/ollama), [ORAS](https://oras.land/), and others. 35 | 36 | Enjoy! 37 | -------------------------------------------------------------------------------- /ROADMAP.md: -------------------------------------------------------------------------------- 1 | # Roadmap 2 | 3 | ## Overview 4 | 5 | This document outlines the future directions and plans for the Cloud Native AI Model Format Specification project. Our goal is to develop a comprehensive specification that facilitates seamless integration of AI models with the cloud-native ecosystem. 6 | 7 | ## Phases 8 | 9 | ### Phase 1: Model Image Packaging and Distribution 10 | 11 | - **Goal**: Define a standardized approach for packaging and distributing AI model images. 12 | - **Tasks**: 13 | - Develop a model image format specification. 14 | - Create tools and libraries to support the packaging process. 15 | - Collaborate with the broader CNCF community to gather feedback and ensure alignment with other cloud-native projects. 16 | - Promote the adoption of the specification through community engagement, presentations, and workshops. 17 | 18 | ### Phase 2: Community Engagement and Adoption 19 | 20 | - **Goal**: Gain attention and support from the broader CNCF community and other relevant projects. 21 | - **Tasks**: 22 | - Identify key stakeholders and projects within the CNCF community. 23 | - Establish communication channels and partnerships with these stakeholders. 24 | - Organize community events, discussion panels, and presentations to showcase the benefits of our specification. 25 | - Collect feedback and iterate on the specification based on community input. 26 | 27 | ### Phase 3: Define Runtime Specification 28 | 29 | - **Goal**: Create a runtime specification that supports the integration of various inference engines with the cloud-native ecosystem. 30 | - **Tasks**: 31 | - Research and analyze popular inference engines and their applicability to AI model deployment. 32 | - Define a set of requirements and features for the runtime specification. 33 | - Develop a draft runtime specification and share it with the community for feedback. 34 | - Implement reference implementations and tools to facilitate the adoption of the runtime specification. 35 | 36 | ### Phase 4: Integration and Testing 37 | 38 | - **Goal**: Ensure that the model packaging, distribution, and runtime specifications work seamlessly together. 39 | - **Tasks**: 40 | - Conduct thorough testing of the model packaging and runtime specifications. 41 | - Integrate the specifications with popular inference engines and cloud-native platforms. 42 | - Address any issues or gaps identified during the testing phase. 43 | - Release stable versions of the specifications and supporting tools. 44 | 45 | ## Future Directions 46 | 47 | - Explore additional features and enhancements based on community feedback and technological advancements. 48 | - Continue to engage with the CNCF community and other relevant projects to promote the adoption and evolution of the specifications. 49 | - Maintain and improve the tools and libraries supporting the specifications. 50 | 51 | ## Conclusion 52 | 53 | We are excited about the future of the Cloud Native AI Model Format Specification project and look forward to collaborating with the community to build a robust and widely adopted standard for AI model deployment in the cloud-native ecosystem. 54 | -------------------------------------------------------------------------------- /code-of-conduct.md: -------------------------------------------------------------------------------- 1 | # CNAI Model Spec Community Code of Conduct 2 | 3 | The Cloud Native AI Model Specification project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). 4 | -------------------------------------------------------------------------------- /docs/annotations.md: -------------------------------------------------------------------------------- 1 | # Annotations 2 | 3 | This property contains arbitrary metadata, and SHOULD follow the rules of [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md). 4 | 5 | ## Pre-defined Annotation Keys 6 | 7 | ### Layer Annotation Keys 8 | 9 | - **`org.cnai.model.filepath`**: Specifies the file path of the layer (string). 10 | 11 | - **`org.cnai.model.file.metadata+json`**: Specifies the metadata of the file (string), value is the JSON string of [File Metadata Annotation Value](#File-Metadata-Annotation-Value). 12 | 13 | ### Layer Annotation Values 14 | 15 | #### File Metadata Annotation Value 16 | 17 | ```go 18 | // FileMetadata represents the metadata of file, which is the value definition of AnnotationFileMetadata. 19 | type FileMetadata struct { 20 | // File name 21 | Name string `json:"name"` 22 | 23 | // File permission mode (e.g., Unix permission bits) 24 | Mode uint32 `json:"mode"` 25 | 26 | // User ID (identifier of the file owner) 27 | Uid uint32 `json:"uid"` 28 | 29 | // Group ID (identifier of the file's group) 30 | Gid uint32 `json:"gid"` 31 | 32 | // File size (in bytes) 33 | Size int64 `json:"size"` 34 | 35 | // File last modification time 36 | ModTime time.Time `json:"mtime"` 37 | 38 | // File type flag (e.g., regular file, directory, etc.) 39 | Typeflag byte `json:"typeflag"` 40 | } 41 | ``` 42 | -------------------------------------------------------------------------------- /docs/config.md: -------------------------------------------------------------------------------- 1 | # Model Artifact Configuration 2 | 3 | Each model artifact has an associated JSON structure which describes some basic information about the model such as name and version, as well as technical metadata such as format, precision and quantization. This content is referred to as _Model Artifact Configuration_ and is identified by the [media type][oci-media-type] `application/vnd.cnai.model.config.v1+json`. 4 | 5 | This section defines `application/vnd.cnai.model.config.v1+json` media type. 6 | 7 | ## Terminology 8 | 9 | The following terms are used in this section: 10 | 11 | - [Layer](./spec.md#guidance-on-layers) 12 | - Layer DiffID 13 | 14 | A layer DiffID is the hash of the layer's uncompressed tar archive. 15 | 16 | ## Properties 17 | 18 | - **descriptor** _object_, REQUIRED 19 | 20 | Contains the general information about the model. 21 | 22 | - **createdAt** _string_, OPTIONAL 23 | 24 | The date and time at which the model was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6]. 25 | 26 | - **authors** _array of strings_, OPTIONAL 27 | 28 | A list of contact details for the individuals or organizations responsible for the model (freeform string). 29 | 30 | - **vendor** _string_, OPTIONAL 31 | 32 | The name of the organization or company distributing the model. 33 | 34 | - **family** _string_, OPTIONAL 35 | 36 | The model family or lineage, such as "llama3", "gpt2", or "qwen2". 37 | 38 | - **name** _string_, OPTIONAL 39 | 40 | The name of the model. 41 | 42 | - **version** _string_, OPTIONAL 43 | 44 | The version of the model. 45 | 46 | - **title** _string_, OPTIONAL 47 | 48 | A human-readable title for the model. 49 | 50 | - **description** _string_, OPTIONAL 51 | 52 | A human-readable description of the model. 53 | 54 | - **docURL** _string_, OPTIONAL 55 | 56 | A URL to get more information or details about the model. 57 | 58 | - **sourceURL** _string_, OPTIONAL 59 | 60 | A URL to get the source code or resources needed to build or understand the model's implementation. 61 | 62 | - **revision** _string_, OPTIONAL 63 | 64 | The source control revision identifier for the model. 65 | 66 | - **licenses** _array of string_, OPTIONAL 67 | 68 | A list of licenses under which the model is distributed, represented as [SPDX License Expressions][spdx-license-expression]. 69 | 70 | - **config** _object_, REQUIRED 71 | 72 | Contains the technical metadata for the model. 73 | 74 | - **architecture** _string_, OPTIONAL 75 | 76 | The architecture of the model, such as "transformer", "cnn", or "rnn". 77 | 78 | - **format** _string_, OPTIONAL 79 | 80 | The format for the model, such as "onnx", "tensorflow", or "pytorch". 81 | 82 | - **paramSize** _string_, OPTIONAL 83 | 84 | The total number of parameters of the model parameters, such as "8b", "16b", "32b", etc. 85 | 86 | - **precision** _string_, OPTIONAL 87 | 88 | The computational precision of the model, e.g., "bf16", "fp16", "int8", or "mixed". 89 | 90 | - **quantization** _string_, OPTIONAL 91 | 92 | Quantization technique applied to the model, such as "awq", or "gptq". 93 | 94 | - **modelfs** _object_, REQUIRED 95 | 96 | Contains hashes of each uncompressed layer's content. 97 | 98 | - **type** _string_, REQUIRED 99 | 100 | Must be set to "layers". 101 | 102 | - **diff_ids** _array of strings_, REQUIRED 103 | 104 | An array of layer content hashes (`DiffIDs`), in order from first to last. 105 | 106 | ## Example 107 | 108 | Here is an example model artifact configuration JSON document: 109 | 110 | ```json 111 | { 112 | "descriptor": { 113 | "createdAt": "2025-01-01T00:00:00Z", 114 | "authors": ["xyz@xyz.com"], 115 | "vendor": "XYZ Corp.", 116 | "family": "xyz3", 117 | "name": "xyz-3-8B-Instruct", 118 | "version": "3.1", 119 | "title": "XYZ 3 8B Instruct", 120 | "description": "xyz is a large language model.", 121 | "docURL": "https://www.xyz.com/get-started/", 122 | "sourceURL": "https://github.com/xyz/xyz3", 123 | "revision": "1234567890", 124 | "licenses": ["Apache-2.0"] 125 | }, 126 | "config": { 127 | "architecture": "transformer", 128 | "format": "pytorch", 129 | "paramSize": "8b", 130 | "precision": "fp16", 131 | "quantization": "gptq" 132 | }, 133 | "modelfs": { 134 | "type": "layers", 135 | "diff_ids": [ 136 | "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", 137 | "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" 138 | ] 139 | } 140 | } 141 | ``` 142 | 143 | [oci-media-type]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#properties 144 | [rfc3339-s5.6]: https://tools.ietf.org/html/rfc3339#section-5.6 145 | [spdx-license-expression]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/ 146 | -------------------------------------------------------------------------------- /docs/img/build-and-push.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CloudNativeAI/model-spec/b1d3255096f6f5fb6ddff31fa40e28c5d8f3a8b5/docs/img/build-and-push.png -------------------------------------------------------------------------------- /docs/img/infra-trends.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CloudNativeAI/model-spec/b1d3255096f6f5fb6ddff31fa40e28c5d8f3a8b5/docs/img/infra-trends.png -------------------------------------------------------------------------------- /docs/img/manifest.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.cncf.cnai.model.manifest.v1+json",
  "annotations": {
    "org.cnai.model.foramt.name": "safetensors",
    "org.cnai.model.format.version": "0.4.5",
    ...
  }
  "config": {
      "mediaType": "application/vnd.oci.image.config.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad...",
      "size": 2
  }
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "artifactType": "application/vnd.cncf.cnai.model.layer.v1.tar",
      "digest": "sha256:3f4d90098f5b5a6f6a76e9d...",
      "size": 2219949
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "artifactType": "application/vnd.cncf.cnai.model.layer.v1.tar",
      "digest": "sha256:760cd441450d65fb33710ad...",
      "size": 10865
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "artifactType": "application/vnd.cncf.cnai.model.layer.v1.tar",
      "digest": "sha256:10ff7ae0a5c3a62cb7a36f6...",
      "size": 165
    },
    ...
  ]
}
{...
/model-001-of-002.safetensors
/model-002-of-002.safetensors
/model.safetensors.index.json
/tokenizer_config.json
/...
/model-001-of-002.safetensors...
Read Only Volumes based on OCI Artifacts
Read Only Volumes based on OCI Artifacts -------------------------------------------------------------------------------- /docs/img/pull-and-serve.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CloudNativeAI/model-spec/b1d3255096f6f5fb6ddff31fa40e28c5d8f3a8b5/docs/img/pull-and-serve.png -------------------------------------------------------------------------------- /docs/spec.md: -------------------------------------------------------------------------------- 1 | # Model Format Specification 2 | 3 | The specification defines an open standard for packaging and distribution of Artificial Intelligence models as OCI artifacts, adhering to [the OCI image specification][image-spec]. 4 | 5 | The goal of this specification is to outline a blueprint and enable the creation of interoperable solutions for packaging and retrieving AI/ML models by leveraging the existing OCI ecosystem, thereby facilitating efficient model management, deployment and serving in cloud-native environments. 6 | 7 | ## Use Cases 8 | 9 | - An OCI Registry can store and manage AI/ML model artifacts, making model versions, metadata, and parameters both retrievable and easily displayed. 10 | - A Data Scientist can package models together with their metadata (e.g., format, precision) and upload them to a registry, facilitating collaboration with MLOps Engineers while streamlining the deployment process to efficiently deliver models into production. 11 | - A model serving/deployment platform can read model metadata (e.g., format, precision) from a registry to understand the AI/ML model details, identify the required server runtime 12 | (as well as startup parameters, necessary resources, etc.), and serve the model in Kubernetes by [mounting it directly as a volume source](https://kubernetes.io/blog/2024/08/16/kubernetes-1-31-image-volume-source/) 13 | without needing to pre-download it in an init-container or bundle it within the server runtime container. 14 | 15 | ## Overview 16 | 17 | At a high level, the Model Format Specification is based on the [OCI Image Format Specification][image-spec] and incorporates [all its components](https://github.com/opencontainers/image-spec/blob/main/spec.md#understanding-the-specification). 18 | 19 | ### OCI Image Manifest Specification For Model Artifacts 20 | 21 | The image manifest of model artifacts follows the [OCI Image Manifest Specification][image-manifest] and adheres to the [artifacts guidance](https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md). 22 | 23 | - **`mediaType`** _string_ 24 | 25 | This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`, refer to the [Guidelines for Artifact Usage](https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md). 26 | 27 | - **`artifactType`** _string_ 28 | 29 | This REQUIRED property MUST be `application/vnd.cnai.model.manifest.v1+json`. 30 | 31 | - **`config`** _[descriptor](config.md)_ 32 | 33 | This REQUIRED property references a configuration object for a AI/ML model, by digest. 34 | 35 | - **`mediaType`** _string_ 36 | 37 | This REQUIRED property MUST be `application/vnd.cnai.model.config.v1+json`. 38 | 39 | - **`layers`** _array of objects_ 40 | 41 | - **`mediaType`** _string_ 42 | 43 | Implementations SHOULD support the following media types: 44 | 45 | - `application/vnd.cnai.model.weight.v1.raw`: The layer is an unarchived, uncompressed model weights file. If the model weight files are large, implementations are RECOMMENDED to use this media type. 46 | 47 | - `application/vnd.cnai.model.weight.v1.tar`: The layer is a [tar archive][tar-archive] that contains the model weight file. If the model has multiple weight files, they SHOULD be packaged into separate layers. 48 | 49 | - `application/vnd.cnai.model.weight.v1.tar+gzip`: The layer is a [tar archive][tar-archive] that includes the configuration file for the model weights. The archive is compressed with [gzip][rfc1952_2]. 50 | 51 | - `application/vnd.cnai.model.weight.v1.tar+zstd`: The layer is a [tar archive][tar-archive] that includes the configuration file for the model weights. The archive is compressed with [zstd][rfc8478]. 52 | 53 | - `application/vnd.cnai.model.weight.config.v1.raw`: The layer is a [tar archive][tar-archive] that includes config of the model weights like tokenizer.json, config.json, etc. If the model weight config files are large, implementations are RECOMMENDED to use this media type. 54 | 55 | - `application/vnd.cnai.model.weight.config.v1.tar`: The layer is a [tar archive][tar-archive] that includes config of the model weights like tokenizer.json, config.json, etc. 56 | 57 | - `application/vnd.cnai.model.weight.config.v1.tar+gzip`: The layer is a [tar archive][tar-archive] that includes config of the model weights like tokenizer.json, config.json, etc. The archive is compressed with [gzip][rfc1952_2]. 58 | 59 | - `application/vnd.cnai.model.weight.config.v1.tar+zstd`: The layer is a [tar archive][tar-archive] that includes config of the model weights like tokenizer.json, config.json, etc. The archive is compressed with [zstd][rfc8478]. 60 | 61 | - `application/vnd.cnai.model.doc.v1.raw`: The layer is an unarchived, uncompressed documentation file. If the documentation files are large, implementations are RECOMMENDED to use this media type. 62 | 63 | - `application/vnd.cnai.model.doc.v1.tar`: The layer is a [tar archive][tar-archive] that includes documentation files like `README.md`, `LICENSE`, etc. 64 | 65 | - `application/vnd.cnai.model.doc.v1.tar+gzip`: The layer is a [tar archive][tar-archive] that includes documentation files like `README.md`, `LICENSE`, etc. The archive is compressed with [gzip][rfc1952_2]. 66 | 67 | - `application/vnd.cnai.model.doc.v1.tar+zstd`: The layer is a [tar archive][tar-archive] that includes documentation files like `README.md`, `LICENSE`, etc. The archive is compressed with [zstd][rfc8478]. 68 | 69 | - `application/vnd.cnai.model.code.v1.raw`: The layer is an unarchived, uncompressed code artifact. If the code files are large, implementations are RECOMMENDED to use this media type. 70 | 71 | - `application/vnd.cnai.model.code.v1.tar`: The layer is a [tar archive][tar-archive] that includes code artifacts like scripts, code files etc. 72 | 73 | - `application/vnd.cnai.model.code.v1.tar+gzip`: The layer is a [tar archive][tar-archive] that includes code artifacts like scripts, code files etc. The archive is compressed with [gzip][rfc1952_2]. 74 | 75 | - `application/vnd.cnai.model.code.v1.tar+zstd`: The layer is a [tar archive][tar-archive] that includes code artifacts like scripts, code files etc. The archive is compressed with [zstd][rfc8478]. 76 | 77 | - `application/vnd.cnai.model.dataset.v1.raw`: The layer is an unarchived, uncompressed dataset. If the dataset files are large, implementations are RECOMMENDED to use this media type. 78 | 79 | - `application/vnd.cnai.model.dataset.v1.tar`: The layer is a [tar archive][tar-archive] that includes datasets that may be needed for the lifecycle of AI/ML models. 80 | 81 | - `application/vnd.cnai.model.dataset.v1.tar+gzip`: The layer is a [tar archive][tar-archive] that includes datasets that may be needed for the lifecycle of AI/ML models. The archive is compressed with [gzip][rfc1952_2]. 82 | 83 | - `application/vnd.cnai.model.dataset.v1.tar+zstd`: The layer is a [tar archive][tar-archive] that includes datasets that may be needed for the lifecycle of AI/ML models. The archive is compressed with [zstd][rfc8478]. 84 | 85 | - **`annotations`** _string-string map_ 86 | 87 | This OPTIONAL property contains arbitrary attributes for the layer. For metadata specific to models, implementations SHOULD use the predefined annotation keys as outlined in the [Layer Annotation Keys](./annotations.md#layer-annotation-keys). 88 | 89 | ### Example Image Manifest For Model Artifacts 90 | 91 | ```JSON 92 | { 93 | "schemaVersion": 2, 94 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 95 | "artifactType": "application/vnd.cnai.model.manifest.v1+json", 96 | "config": { 97 | "mediaType": "application/vnd.cnai.model.config.v1+json", 98 | "digest": "sha256:d5815835051dd97d800a03f641ed8162877920e734d3d705b698912602b8c763", 99 | "size": 301 100 | }, 101 | "layers": [ 102 | { 103 | "mediaType": "application/vnd.cnai.model.weight.v1.tar", 104 | "digest": "sha256:3f907c1a03bf20f20355fe449e18ff3f9de2e49570ffb536f1a32f20c7179808", 105 | "size": 30327160 106 | }, 107 | { 108 | "mediaType": "application/vnd.cnai.model.weight.v1.tar", 109 | "digest": "sha256:6d923539c5c208de77146335584252c0b1b81e35c122dd696fe6e04ed03d7411", 110 | "size": 5018536960 111 | }, 112 | { 113 | "mediaType": "application/vnd.cnai.model.weight.config.v1.tar", 114 | "digest": "sha256:a5378e569c625f7643952fcab30c74f2a84ece52335c292e630f740ac4694146", 115 | "size": 106 116 | }, 117 | { 118 | "mediaType": "application/vnd.cnai.model.doc.v1.tar", 119 | "digest": "sha256:5e236ec37438b02c01c83d134203a646cb354766ac294e533a308dd8caa3a11e", 120 | "size": 23040 121 | } 122 | ] 123 | } 124 | ``` 125 | 126 | ## Guidance on Layers 127 | 128 | This section describes how to serialize AI/ML artifacts into a blob called a layer. 129 | 130 | **Implementers' note**: It is recommended to package weight files without compression to avoid unnecessary overhead of decompression by the container runtime as model weight files are typically incompressible. 131 | 132 | ### `+gzip` Media Types 133 | 134 | The `application/vnd.cnai.model.weight.v1.tar+gzip` represents an `application/vnd.cnai.model.weight.v1.tar` payload which has been compressed with [gzip][rfc1952_2]. The mediaTypes `application/vnd.cnai.model.weight.config.v1.tar+gzip`, `application/vnd.cnai.model.doc.v1.tar+gzip`, `application/vnd.cnai.model.code.v1.tar+gzip`, `application/vnd.cnai.model.dataset.v1.tar+gzip` refer to the gzip compressed payloads of their corresponding type. 135 | 136 | ### `+zstd` Media Types 137 | 138 | The `application/vnd.cnai.model.weight.v1.tar+zstd` represents an `application/vnd.cnai.model.weight.v1.tar` payload which has been compressed with the [zstd][rfc8478] algorithm. The mediaTypes `application/vnd.cnai.model.weight.config.v1.tar+zstd`, `application/vnd.cnai.model.doc.v1.tar+zstd`, `application/vnd.cnai.model.code.v1.tar+zstd`, `application/vnd.cnai.model.dataset.v1.tar+zstd` refer to the zstd compressed payloads of their corresponding type. 139 | 140 | ### File Attributes 141 | 142 | Where supported, MUST include file attributes 143 | 144 | - Modification Time (`mtime`) 145 | - User ID (`uid`) 146 | - User Name (`uname`) should be ignored on platforms that support User ID (`uid`) 147 | - Group ID (`gid`) 148 | - Group Name (`gname`) should be ignored on platforms that support Group ID (`gid`) 149 | - Mode (`mode`) 150 | 151 | ### Reproducibility 152 | 153 | To ensure tar layers are packaged in a reproducible way, implementation SHOULD adhere to the following guidance: 154 | 155 | - If the archive includes multiple files, files should be added to the archive in lexicographical order. 156 | - File metadata (such as modification time, owner/group id) should be set to known, constant values rather than the current values on disk. 157 | - Platform/implementation specific metadata should be omitted from the archive. 158 | 159 | ## Workflow 160 | 161 | The model format specification naturally aligns with the standard [OCI distribution specification][distribution-spec]. 162 | 163 | This section outlines the typical workflow for a model OCI artifact, which consists of two main stages: `BUILD & PUSH` and `PULL & SERVE`. 164 | 165 | ### BUILD & PUSH 166 | 167 | Build tools can package required resources into an OCI artifact following the model format specification. 168 | 169 | The generated artifact can then be pushed to OCI registries (e.g., Harbor, DockerHub) for storage and management. 170 | 171 | ![build-push](./img/build-and-push.png) 172 | 173 | ### PULL & SERVE 174 | 175 | Once the model artifact is stored in an OCI registry, the container runtime (e.g., containerd, CRI-O) can pull it from the OCI registry and mount it as a read-only volume during the model serving process, if required. 176 | 177 | ![pull-serve](./img/pull-and-serve.png) 178 | 179 | [image-spec]: https://github.com/opencontainers/image-spec/blob/main/spec.md#image-format-specification 180 | [rfc1952_2]: https://tools.ietf.org/html/rfc1952 181 | [tar-archive]: https://en.wikipedia.org/wiki/Tar_(computing) 182 | [image-manifest]: https://github.com/opencontainers/image-spec/blob/main/manifest.md 183 | [rfc8478]: https://tools.ietf.org/html/rfc8478 184 | [distribution-spec]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md 185 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/CloudNativeAI/model-spec 2 | 3 | go 1.23.1 4 | 5 | require github.com/opencontainers/go-digest v1.0.0 6 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= 2 | github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM= 3 | -------------------------------------------------------------------------------- /specs-go/v1/annotations.go: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2024 The CNAI Authors 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package v1 18 | 19 | import "time" 20 | 21 | const ( 22 | // AnnotationFilepath is the annotation key for the file path of the layer. 23 | AnnotationFilepath = "org.cnai.model.filepath" 24 | 25 | // AnnotationFileMetadata is the annotation key for the file metadata of the layer. 26 | AnnotationFileMetadata = "org.cnai.model.file.metadata+json" 27 | ) 28 | 29 | // FileMetadata represents the metadata of file, which is the value definition of AnnotationFileMetadata. 30 | type FileMetadata struct { 31 | // File name 32 | Name string `json:"name"` 33 | 34 | // File permission mode (e.g., Unix permission bits) 35 | Mode uint32 `json:"mode"` 36 | 37 | // User ID (identifier of the file owner) 38 | Uid uint32 `json:"uid"` 39 | 40 | // Group ID (identifier of the file's group) 41 | Gid uint32 `json:"gid"` 42 | 43 | // File size (in bytes) 44 | Size int64 `json:"size"` 45 | 46 | // File last modification time 47 | ModTime time.Time `json:"mtime"` 48 | 49 | // File type flag (e.g., regular file, directory, etc.) 50 | Typeflag byte `json:"typeflag"` 51 | } 52 | -------------------------------------------------------------------------------- /specs-go/v1/config.go: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2025 The CNAI Authors 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package v1 18 | 19 | import ( 20 | "time" 21 | 22 | digest "github.com/opencontainers/go-digest" 23 | ) 24 | 25 | // ModelConfig defines the execution parameters 26 | // which should be used as a base when running a model using an inference engine. 27 | type ModelConfig struct { 28 | // The model architecture, such as transformer, cnn, rnn, etc. 29 | Architecture string `json:"architecture,omitempty"` 30 | 31 | // The model format, such as onnx, tensorflow, pytorch, etc. 32 | Format string `json:"format,omitempty"` 33 | 34 | // The size of the model parameters, such as "8b", "16b", "32b", etc. 35 | ParamSize string `json:"paramSize,omitempty"` 36 | 37 | // The model precision, such as bf16, fp16, int8, mixed etc. 38 | Precision string `json:"precision,omitempty"` 39 | 40 | // The model quantization, such as awq, gptq, etc 41 | Quantization string `json:"quantization,omitempty"` 42 | } 43 | 44 | // ModelFS describes a layer content addresses 45 | type ModelFS struct { 46 | // Type is the type of the rootfs. MUST be set to "layers". 47 | Type string `json:"type"` 48 | 49 | // DiffIDs is an array of layer content hashes (DiffIDs), in order from bottom-most to top-most. 50 | DiffIDs []digest.Digest `json:"diff_ids"` 51 | } 52 | 53 | // ModelDescriptor defines the general information of a model 54 | type ModelDescriptor struct { 55 | // Date and time on which the model was built 56 | CreatedAt *time.Time `json:"createdAt,omitempty"` 57 | 58 | // The contact details of the people or organization responsible for the model 59 | Authors []string `json:"authors,omitempty"` 60 | 61 | // The model family, such as llama3, gpt2, qwen2, etc. 62 | Family string `json:"family,omitempty"` 63 | 64 | // The model name, such as llama3-8b-instruct, gpt2-xl, qwen2-vl-72b-instruct, etc. 65 | Name string `json:"name,omitempty"` 66 | 67 | // The URL to get documentation on the model 68 | DocURL string `json:"docURL,omitempty"` 69 | 70 | // The URL to get source code for building the model 71 | SourceURL string `json:"sourceURL,omitempty"` 72 | 73 | // The version of the packaged software 74 | Version string `json:"version,omitempty"` 75 | 76 | // The source control revision identifier for the packaged software 77 | Revision string `json:"revision,omitempty"` 78 | 79 | // The name of the distributing entity, organization or individual 80 | Vendor string `json:"vendor,omitempty"` 81 | 82 | // The license(s) under which contained software is distributed as an SPDX License Expression 83 | Licenses []string `json:"licenses,omitempty"` 84 | 85 | // The human-readable title of the model 86 | Title string `json:"title,omitempty"` 87 | 88 | // The human-readable description of the software packaged in the model 89 | Description string `json:"description,omitempty"` 90 | } 91 | 92 | // Model defines the basic information of a model. 93 | // It provides the `application/vnd.cnai.model.config.v1+json` mediatype when marshalled to JSON. 94 | type Model struct { 95 | // The model descriptor 96 | Descriptor ModelDescriptor `json:"descriptor"` 97 | 98 | // The model describes a layer content addresses 99 | ModelFS ModelFS `json:"modelfs"` 100 | 101 | // Config defines the execution parameters which should be used as a base when running a model using an inference engine. 102 | Config ModelConfig `json:"config,omitempty"` 103 | } 104 | -------------------------------------------------------------------------------- /specs-go/v1/mediatype.go: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2024 The CNAI Authors 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package v1 18 | 19 | const ( 20 | // ArtifactTypeModelManifest specifies the artifact type for a model manifest. 21 | ArtifactTypeModelManifest = "application/vnd.cnai.model.manifest.v1+json" 22 | ) 23 | 24 | const ( 25 | // MediaTypeModelConfig specifies the media type for a model configuration. 26 | MediaTypeModelConfig = "application/vnd.cnai.model.config.v1+json" 27 | 28 | // MediaTypeModelWeightRaw is the media type used for an unarchived, uncompressed model weights. 29 | MediaTypeModelWeightRaw = "application/vnd.cnai.model.weight.v1.raw" 30 | 31 | // MediaTypeModelWeight is the media type used for model weights. 32 | MediaTypeModelWeight = "application/vnd.cnai.model.weight.v1.tar" 33 | 34 | // MediaTypeModelWeightGzip is the media type used for gzipped model weights. 35 | MediaTypeModelWeightGzip = "application/vnd.cnai.model.weight.v1.tar+gzip" 36 | 37 | // MediaTypeModelWeightZstd is the media type used for zstd compressed model weights. 38 | MediaTypeModelWeightZstd = "application/vnd.cnai.model.weight.v1.tar+zstd" 39 | 40 | // MediaTypeModelWeightConfigRaw is the media type used for an unarchived, uncompressed model weights, including files like `tokenizer.json`, `config.json`, etc. 41 | MediaTypeModelWeightConfigRaw = "application/vnd.cnai.model.weight.config.v1.raw" 42 | 43 | // MediaTypeModelConfig specifies the media type for configuration of the model weights, including files like `tokenizer.json`, `config.json`, etc. 44 | MediaTypeModelWeightConfig = "application/vnd.cnai.model.weight.config.v1.tar" 45 | 46 | // MediaTypeModelConfigGzip specifies the media type for gzipped configuration of the model weights, including files like `tokenizer.json`, `config.json`, etc. 47 | MediaTypeModelWeightConfigGzip = "application/vnd.cnai.model.weight.config.v1.tar+gzip" 48 | 49 | // MediaTypeModelConfigZstd specifies the media type for zstd compressed configuration of the model weights, including files like `tokenizer.json`, `config.json`, etc. 50 | MediaTypeModelWeightConfigZstd = "application/vnd.cnai.model.weight.config.v1.tar+zstd" 51 | 52 | // MediaTypeModelDocRaw is the media type used for an unarchived, uncompressed model documentation, including documentation files like `README.md`, `LICENSE`, etc. 53 | MediaTypeModelDocRaw = "application/vnd.cnai.model.doc.v1.raw" 54 | 55 | // MediaTypeModelDoc specifies the media type for model documentation, including documentation files like `README.md`, `LICENSE`, etc. 56 | MediaTypeModelDoc = "application/vnd.cnai.model.doc.v1.tar" 57 | 58 | // MediaTypeModelDocGzip specifies the media type for gzipped model documentation, including documentation files like `README.md`, `LICENSE`, etc. 59 | MediaTypeModelDocGzip = "application/vnd.cnai.model.doc.v1.tar+gzip" 60 | 61 | // MediaTypeModelDocZstd specifies the media type for zstd compressed model documentation, including documentation files like `README.md`, `LICENSE`, etc. 62 | MediaTypeModelDocZstd = "application/vnd.cnai.model.doc.v1.tar+zstd" 63 | 64 | // MediaTypeModelCodeRaw is the media type used for an unarchived, uncompressed model code, including code artifacts like scripts, code files etc. 65 | MediaTypeModelCodeRaw = "application/vnd.cnai.model.code.v1.raw" 66 | 67 | // MediaTypeModelCode specifies the media type for model code, including code artifacts like scripts, code files etc. 68 | MediaTypeModelCode = "application/vnd.cnai.model.code.v1.tar" 69 | 70 | // MediaTypeModelCodeGzip specifies the media type for gzipped model code, including code artifacts like scripts, code files etc. 71 | MediaTypeModelCodeGzip = "application/vnd.cnai.model.code.v1.tar+gzip" 72 | 73 | // MediaTypeModelCodeZstd specifies the media type for zstd compressed model code, including code artifacts like scripts, code files etc. 74 | MediaTypeModelCodeZstd = "application/vnd.cnai.model.code.v1.tar+zstd" 75 | 76 | // MediaTypeModelDatasetRaw is the media type used for an unarchived, uncompressed model datasets, including datasets that may be needed throughout the lifecycle of AI/ML models. 77 | MediaTypeModelDatasetRaw = "application/vnd.cnai.model.dataset.v1.raw" 78 | 79 | // MediaTypeModelDataset specifies the media type for model datasets, including datasets that may be needed throughout the lifecycle of AI/ML models. 80 | MediaTypeModelDataset = "application/vnd.cnai.model.dataset.v1.tar" 81 | 82 | // MediaTypeModelDatasetGzip specifies the media type for gzipped model datasets, including datasets that may be needed throughout the lifecycle of AI/ML models. 83 | MediaTypeModelDatasetGzip = "application/vnd.cnai.model.dataset.v1.tar+gzip" 84 | 85 | // MediaTypeModelDatasetZstd specifies the media type for zstd compressed model datasets, including datasets that may be needed throughout the lifecycle of AI/ML models. 86 | MediaTypeModelDatasetZstd = "application/vnd.cnai.model.dataset.v1.tar+zstd" 87 | ) 88 | --------------------------------------------------------------------------------