From b0e54caf0ded78f702d3d5684669701c45e85e41 Mon Sep 17 00:00:00 2001 From: Andreas Fehlner Date: Sun, 8 Nov 2026 08:46:27 +0100 Subject: [PATCH] fix(ML-BOM): normalize terminology (ML-BOM, CycloneDX, Hugging Face) - 'MLBOM' -> 'ML-BOM', matching usage throughout the guide. - 'the Cyclone model card' -> 'the CycloneDX model card' in three chapter intros. - 'Huggingface' -> 'Hugging Face' (official styling, used in the majority of the guide). purl values (pkg:huggingface/...) and URLs are intentionally unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Andreas Fehlner --- ML-BOM/en/0x15-Core-Concepts.md | 4 ++-- ML-BOM/en/0x20-Design-Model-Component-Metadata.md | 14 +++++++------- ML-BOM/en/0x22-Design-Model-Card-Parameters.md | 2 +- ...0x23-Design-Model-Card-Quantitative-Analysis.md | 2 +- ML-BOM/en/0x24-Design-Model-Card-Considerations.md | 2 +- ML-BOM/en/0x90-Appendix-A_Glossary.md | 2 +- ML-BOM/en/0x91-Appendix-B_References.md | 4 ++-- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/ML-BOM/en/0x15-Core-Concepts.md b/ML-BOM/en/0x15-Core-Concepts.md index 9a46b79d..756967f2 100644 --- a/ML-BOM/en/0x15-Core-Concepts.md +++ b/ML-BOM/en/0x15-Core-Concepts.md @@ -4,7 +4,7 @@ An ML-BOM typically documents the identifying elements, architecture, components, and its supply chain along with any configurations and developmental or executional considerations, inclusive of the following areas: -- **Model identifiers**: Identifying information such as the model's [Package URL (PURL)](https://tc54.org/purl/) (e.g., from Huggingface `pkg:huggingface/distilbert-base-uncased@043235d6088ecd3dd5fb5ca3592b6913fd51602`) or other domain-specific identifiers within other registries. +- **Model identifiers**: Identifying information such as the model's [Package URL (PURL)](https://tc54.org/purl/) (e.g., from Hugging Face `pkg:huggingface/distilbert-base-uncased@043235d6088ecd3dd5fb5ca3592b6913fd51602`) or other domain-specific identifiers within other registries. - **Model metadata**: Descriptive details such as the model's name, version, license, developer, purpose, use cases, architecture, (hyper)parameters and any additional identifying elements. @@ -14,7 +14,7 @@ An ML-BOM typically documents the identifying elements, architecture, components - **Tokenizers and prompt templates**: Descriptive details of specific tokenizers (e.g., libraries, files, configurations) and prompt templates used to train and/or interact with the model during runtime. -- **Hardware, software & frameworks**: A list of all hardware and software components including libraries, packages, frameworks (e.g., TensorFlow, PyTorch, Huggingface), along with specific versions and associated licenses used in aspects of the model's lifecycle. This informational category may also include operational and application aspects of models (perhaps as agents) used within compositional frameworks and workflows, along with the protocols used for communication. +- **Hardware, software & frameworks**: A list of all hardware and software components including libraries, packages, frameworks (e.g., TensorFlow, PyTorch, Hugging Face), along with specific versions and associated licenses used in aspects of the model's lifecycle. This informational category may also include operational and application aspects of models (perhaps as agents) used within compositional frameworks and workflows, along with the protocols used for communication. - **Training & testing details**: Information about the computational environment and systems (software, hardware, operating system, and GPUs) used for training or evaluation along with necessary configurations, hyperparameters, and evaluation metrics. diff --git a/ML-BOM/en/0x20-Design-Model-Component-Metadata.md b/ML-BOM/en/0x20-Design-Model-Component-Metadata.md index 597cc3ad..b51f1df3 100644 --- a/ML-BOM/en/0x20-Design-Model-Component-Metadata.md +++ b/ML-BOM/en/0x20-Design-Model-Component-Metadata.md @@ -2,9 +2,9 @@ ## Overview -A Machine Learning Bill-of-Materials (MLBOM or ML-BOM) is an object model to describe a machine learning model, its compositional assets, and other descriptive information often used to assess risk and compliance. Support for MLBOM is included in CycloneDX v1.5 and higher. +A Machine Learning Bill-of-Materials (ML-BOM) is an object model to describe a machine learning model, its compositional assets, and other descriptive information often used to assess risk and compliance. Support for ML-BOM is included in CycloneDX v1.5 and higher. -An MLBOM relies on many of the common, core elements of the CycloneDX schema, as well as unique aspects specific to ML components, their architectures, metadata, training, and other information used to gauge regulatory compliance. +An ML-BOM relies on many of the common, core elements of the CycloneDX schema, as well as unique aspects specific to ML components, their architectures, metadata, training, and other information used to gauge regulatory compliance. This guide will provide specifics and best practices for conveying ML-related information using the CycloneDX schema. @@ -94,7 +94,7 @@ If possible, these model repositories should be treated as a software "package" The following example shows how the Hugging Face [Qwen/Qwen-7B](https://huggingface.co/Qwen/Qwen-7B) model repository would be declared as a CycloneDX `component` of type `machine-learning-model` in a CycloneDX ML-BOM as its subject component. -Since the model repository is hosted on Hugging Face, the [Huggingface package type](https://github.com/package-url/purl-spec/blob/main/types/huggingface-definition.json) may be used [Package URL specification](https://github.com/package-url/purl-spec) to identify the model. +Since the model repository is hosted on Hugging Face, the [Hugging Face package type](https://github.com/package-url/purl-spec/blob/main/types/huggingface-definition.json) may be used [Package URL specification](https://github.com/package-url/purl-spec) to identify the model. ```json { @@ -143,18 +143,18 @@ Since the model repository is hosted on Hugging Face, the [Huggingface package t This section provides best practice guidance on how the component fields were filled out for this example. - **bom-ref** - Since a PURL is available, it can also be used as the `bom-ref`. -- **purl** - The Package URL (PURL) follows the [Huggingface package type](https://github.com/package-url/purl-spec/blob/main/types/huggingface-definition.json) using a commit hash. +- **purl** - The Package URL (PURL) follows the [Hugging Face package type](https://github.com/package-url/purl-spec/blob/main/types/huggingface-definition.json) using a commit hash. - **manufacturer** - The name of the company which built the Qwen model. - **group** - In this example, we chose to include the optional group field to acknowledge the specific model repository is part of the Qwen family of models. - **name** - The model name reflects how the model is identified under Hugging Face using the `/` format. -- **version** - Models are not always versioned in the way software packages are (e.g., using `semver` format); however, within repositories such as Huggingface, the version is determined by its version control system's *commit hash*, *tag*, or *branch*. In the above example, the model's commit hash matches the `purl` value. +- **version** - Models are not always versioned in the way software packages are (e.g., using `semver` format); however, within repositories such as Hugging Face, the version is determined by its version control system's *commit hash*, *tag*, or *branch*. In the above example, the model's commit hash matches the `purl` value. - **externalReferences** - Used to provide unambiguous links to component's model repository and originating model card. - **vcs** - Provides a link to the version control system (i.e., the model provider aka. `supplier`). In this example, Hugging Face is used to affirm the associated PURL identifier. - **model-card** - Provides a link to the model's Hugging Face model card which is comprised of mostly unstructured information in the form of a markdown file (i.e., README.md).
*The CycloneDX representation of model card information will be detailed in a subsequent section. #### Model identifier(s) -As you can see in the above example, the `component` has a `bom-ref` that is also a valid [Package URL (PURL)](https://github.com/package-url/purl-spec) for a ["Qwen-7B" model hosted in a Huggingface model repository](https://huggingface.co/Qwen/Qwen-7B) using the [Hugging Face PURL type](https://github.com/package-url/purl-spec/blob/main/types-doc/huggingface-definition.md). When a valid `purl` value is available for a model, it is recommended that it also be used as its component's `bom-ref`. +As you can see in the above example, the `component` has a `bom-ref` that is also a valid [Package URL (PURL)](https://github.com/package-url/purl-spec) for a ["Qwen-7B" model hosted in a Hugging Face model repository](https://huggingface.co/Qwen/Qwen-7B) using the [Hugging Face PURL type](https://github.com/package-url/purl-spec/blob/main/types-doc/huggingface-definition.md). When a valid `purl` value is available for a model, it is recommended that it also be used as its component's `bom-ref`. If the model being described by an ML-BOM is instead hosted in a GitHub repository, it can also be referenced using a [GitHub Package URL](https://github.com/package-url/purl-spec/blob/main/types-doc/github-definition.md). For example, the ONNX vision model: [tiny-yolov2](https://github.com/onnx/models/tree/main/validated/vision/object_detection_segmentation/tiny-yolov2/model) would have a `github` PURL type. @@ -289,7 +289,7 @@ Specifically, a `component` entry would be created for each file and declared in ###### Example: Qwen/Qwen-7B model repository files -If we look inside the repository for the [Qwen/Qwen-7B model in Huggingface](https://huggingface.co/Qwen/Qwen-7B), we see the complete list of files that make up the "model" in its repository: +If we look inside the repository for the [Qwen/Qwen-7B model in Hugging Face](https://huggingface.co/Qwen/Qwen-7B), we see the complete list of files that make up the "model" in its repository: diff --git a/ML-BOM/en/0x22-Design-Model-Card-Parameters.md b/ML-BOM/en/0x22-Design-Model-Card-Parameters.md index e38c8ba5..2ee60721 100644 --- a/ML-BOM/en/0x22-Design-Model-Card-Parameters.md +++ b/ML-BOM/en/0x22-Design-Model-Card-Parameters.md @@ -2,7 +2,7 @@ ![](images/ml-anatomy-model-card-parameters.svg) -This section will feature guidance on filling out information in the Cyclone model card's `modelParameters` object and its subcomponents, including: +This section will feature guidance on filling out information in the CycloneDX model card's `modelParameters` object and its subcomponents, including: * [Model metadata](#model-metadata) * [Approach](#approach) - The overall approach to learning used by the model for problem solving. diff --git a/ML-BOM/en/0x23-Design-Model-Card-Quantitative-Analysis.md b/ML-BOM/en/0x23-Design-Model-Card-Quantitative-Analysis.md index cc357bb6..3dbd8dea 100644 --- a/ML-BOM/en/0x23-Design-Model-Card-Quantitative-Analysis.md +++ b/ML-BOM/en/0x23-Design-Model-Card-Quantitative-Analysis.md @@ -2,7 +2,7 @@ ![](images/ml-anatomy-model-card-quant-analysis.svg) -This section will feature guidance on filling out information in the Cyclone model card's `quantitativeAnalysis` object and its subcomponents, including: +This section will feature guidance on filling out information in the CycloneDX model card's `quantitativeAnalysis` object and its subcomponents, including: * [Metrics](#metrics) * [Performance metrics](#performance-metrics) diff --git a/ML-BOM/en/0x24-Design-Model-Card-Considerations.md b/ML-BOM/en/0x24-Design-Model-Card-Considerations.md index cb127f0a..c84c223a 100644 --- a/ML-BOM/en/0x24-Design-Model-Card-Considerations.md +++ b/ML-BOM/en/0x24-Design-Model-Card-Considerations.md @@ -2,7 +2,7 @@ ![](images/ml-anatomy-model-card-considerations.svg) -This section will feature guidance on filling out information in the Cyclone model card's design `considerations` object and its subcomponents, including: +This section will feature guidance on filling out information in the CycloneDX model card's design `considerations` object and its subcomponents, including: * [Users](#users) - Who are the intended users of the model? * [Use cases](#use-cases)- What are the intended use cases for the model inclusive of the Operational Design Domains (ODD)? diff --git a/ML-BOM/en/0x90-Appendix-A_Glossary.md b/ML-BOM/en/0x90-Appendix-A_Glossary.md index 7e1df566..0016a586 100644 --- a/ML-BOM/en/0x90-Appendix-A_Glossary.md +++ b/ML-BOM/en/0x90-Appendix-A_Glossary.md @@ -72,7 +72,7 @@ Major processing tasks in an NLP system include: speech recognition, text classi ### Model format terms -#### Huggingface Safetensors +#### Hugging Face Safetensors Safetensors addresses security and efficiency limitations present in traditional Python serialization approaches like pickle, used by PyTorch. The format uses a restricted deserialization process to prevent code execution vulnerabilities. diff --git a/ML-BOM/en/0x91-Appendix-B_References.md b/ML-BOM/en/0x91-Appendix-B_References.md index ece5b2d6..607f0c5f 100644 --- a/ML-BOM/en/0x91-Appendix-B_References.md +++ b/ML-BOM/en/0x91-Appendix-B_References.md @@ -63,7 +63,7 @@ The following AI or ML technologies were referenced in discussion and/or example The following ML models were referenced in discussion and/or examples in this guide: -##### Huggingface +##### Hugging Face Hugging Face model (repositories) typically support the `.safetensors` Hugging Face format; however, within the same repository, alternative formats are often found, such as PyTorch (`.bin`, `.pt`), GGUF (`.gguf`) @@ -81,7 +81,7 @@ Hugging Face model (repositories) typically support the `.safetensors` Hugging F ONNX models are typically single file format ending with the `.onnx` extension. -> **Note**: Most ONNX models have transitioned to and are now registered in Huggingface, but are downloaded from linked GitHub repository files not within the HF repo. itself. +> **Note**: Most ONNX models have transitioned to and are now registered in Hugging Face, but are downloaded from linked GitHub repository files not within the HF repo. itself. * Hugging Face * [onnx/DenseNet-121-9](https://huggingface.co/onnx/DenseNet-121-9/tree/main) - `densenet-9.onnx`