+
+###### CycloneDX for the Qwen/Qwen-7B assembly
+
+The simplified JSON below shows how to declare a few files from the model repository's complete file list as the `components` of the inventory whose `subject` is the model.
+
+> **Note**: In the JSON below, we use the Package URL (PURL) syntax to provide the additional path (with the model repository or "package") to each individual file by appending it using the `#` hash symbol as a separator. Also, notice that the commit hash (identifier) varies per file.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B"
+ // ...
+ },
+ "components": [
+ {
+ "type": "file",
+ "name": "config.json",
+ "description": "Model configuration file using the 'QWenLMHeadModel' model class in Hugging Face Transformers",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@e7a368b#config.json",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ {
+ "scheme": "purl",
+ "value": "pkg:huggingface/Qwen/Qwen-7B@e7a368b0774370edec29674e7c51f52fc7663f59#config.json"
+ }
+ ]
+ }
+ ]
+ // ...
+ },
+ {
+ "type": "file",
+ "name": "configuration_qwen.py",
+ "description": "Python 'QWenConfig' class implementation for the Qwen-7B model using Hugging Face Transformers",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@a6ca629#configuration_qwen.py",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ {
+ "scheme": "purl",
+ "value": "pkg:huggingface/Qwen/Qwen-7B@a6ca629d063f56f34d184852301e8852a7afbd58#configuration_qwen.py"
+ }
+ ]
+ }
+ ]
+ // ...
+ },
+ {
+ "type": "data",
+ "name": "model-00001-of-00008.safetensors",
+ "description": "Model tensor data (01 of 08)",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6#model-00001-of-00008.safetensors",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ {
+ "scheme": "purl",
+ "value": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6d8ec63ce606f816e2d08072da6309f965#model-00001-of-00008.safetensors"
+ }
+ ]
+ }
+ ],
+ "data": [
+ {
+ "type": "dataset",
+ "contents": {
+ "url": "https://huggingface.co/Qwen/Qwen-7B/blob/main/model-00001-of-00008.safetensors"
+ }
+ }
+ ]
+ // ...
+ },
+ {
+ "type": "data",
+ "name": "model-00002-of-00008.safetensors",
+ "description": "Model tensor data (02 of 08)",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6#model-00002-of-00008.safetensors",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ {
+ "scheme": "purl",
+ "value": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6d8ec63ce606f816e2d08072da6309f965#model-00002-of-00008.safetensors"
+ }
+ ]
+ }
+ ],
+ "data": [
+ {
+ "type": "dataset",
+ "contents": {
+ "url": "https://huggingface.co/Qwen/Qwen-7B/blob/main/model-00002-of-00008.safetensors"
+ }
+ }
+ ]
+ // ...
+ }
+ // ...
+ ]
+ }
+ ],
+ "definitions": {
+ "parties": [
+ {
+ "refId": "party-hugging-face",
+ "roles": [ { "role": "supplier" } ],
+ "organization": { "name": "Hugging Face" }
+ }
+ ]
+ }
+ // ...
+}
+```
+
+Then the completeness of the model component's composing files would be asserted as a composition as follows:
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "compositions": [
+ {
+ "kind": "components",
+ "aggregate": "complete",
+ "targets": [
+ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9"
+ ]
+ }
+ ]
+ // ...
+}
+```
+
+###### Discussion of composition fields
+
+- **kind** - The `components` kind asserts the completeness of the components included in each target (here, the inventory of the model component).
+- **aggregate** - Note the composition `aggregate` value is assigned to be "complete" since all constituent files are known and declared in the AI/ML-BOM as part of the model component's inventory.
+- **targets** - References the `refId` of the model component whose inventory is being asserted.
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 composition `assemblies` array is replaced by `targets` together with a required `kind`.
+
+### Declaring a model's pedigree
+
+ML models are often derived from existing, pre-trained models to optimize performance, reduce resource consumption, and adapt to specialized tasks without training from scratch. Some reasons for this include:
+
+* **Fine-Tuning**: Specialized adaptation where a general model (e.g., LLM) is retrained on a smaller, targeted dataset to improve performance for specific domains.
+* **Quantization**: Reduces model size and increases inference speed by mapping parameters to lower-precision tensor formats (e.g., from [`FP32`](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) to `int8` or `Q4_K_M` precision), which also lowers energy consumption for edge devices.
+* **Format Conversions**: Transforming models between frameworks (e.g., PyTorch to ONNX) ensures interoperability, allowing deployment on different frameworks and accelerators.
+* **Pruning**: Derives a smaller model by removing redundant or less important parameters (weights) that do not significantly contribute to output accuracy.
+* **Adapters**: Adding small, trainable layers (adapters) to a frozen base model to adapt it to new tasks without changing the original, large model weights, saving on storage for multi-task scenarios.
+
+It is important to capture any of these transformations in the model's lineage ("pedigree") or in an AI/ML-BOM. This should be accomplished via the CycloneDX `pedigree` object and describing a model's `ancestors` as a hierarchical graph.
+
+###### Example: Declaring the finetuning of llama3 model for a coding variant
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "name": "unsloth/Llama-3.2-3B-Instruct",
+ "refId": "pkg:huggingface/unsloth/Llama-3.2-3B-Instruct@1.0.0",
+ "description": "A pre-optimized, specialized versions of the meta-llama/Llama-3.2-3B-Instruct model designed to work seamlessly with Unsloth's training framework",
+ "parties": [
+ {
+ "refId": "party-unsloth",
+ "roles": [ { "role": "publisher" } ],
+ "organization": { "name": "Unsloth" }
+ }
+ ],
+ "identifiers": [
+ {
+ "party": "party-unsloth",
+ "identities": [
+ { "scheme": "purl", "value": "pkg:huggingface/unsloth/Llama-3.2-3B-Instruct@1.0.0" }
+ ]
+ }
+ ],
+ // ...,
+ "pedigree": {
+ "ancestors": [
+ {
+ "type": "machine-learning-model",
+ "name": "meta-llama/Llama-3.2-3B-Instruct",
+ "description": "The original base model from Meta Llama used for fine-tuning.",
+ "parties": [
+ {
+ "refId": "party-meta",
+ "roles": [ { "role": "publisher" } ],
+ "organization": { "name": "Meta" }
+ }
+ ],
+ "identifiers": [
+ {
+ "party": "party-meta",
+ "identities": [
+ { "scheme": "purl", "value": "pkg:huggingface/meta-llama/Llama-3.2-3B-Instruct" }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **ancestors** - `ancestors` entries are themselves CycloneDX `component` objects (or references to components declared elsewhere, such as in `definitions.components`). It should be noted that these models may have their own AI/ML-BOMs, which can be located via their identifiers (e.g., the `purl` identity) or via `externalReferences` for readers to follow.
+
+##### Declaring known descendants
+
+If, at the time an AI/ML-BOM is created for a model, its downstream model variants (e.g., finetunings, quantizations, etc., derived from the model) are known, these can also be recorded within the `pedigree` object as `descendants` in a similar manner.
+
+
diff --git a/ML-BOM/2.0/en/0x21-Design-Model-Card-Overview.md b/ML-BOM/2.0/en/0x21-Design-Model-Card-Overview.md
new file mode 100644
index 00000000..956ca335
--- /dev/null
+++ b/ML-BOM/2.0/en/0x21-Design-Model-Card-Overview.md
@@ -0,0 +1,116 @@
+# Model cards
+
+A model card describes the intended uses of a machine learning model and potential limitations, including biases and ethical considerations. Model cards typically include the training parameters, the datasets used to train the model, performance metrics, and other relevant data useful for ML transparency.
+
+Throughout the model card sections of this guide, we will show how to use the CycloneDX 2.0 schema to encode information from model cards in a more current and robust way.
+
+## Overview
+
+In CycloneDX 2.0, model card information is no longer held in a single, fixed `modelCard` object. Instead, it is provided as structured, machine-readable, and referenceable data across the AI/ML-BOM:
+
+| Model card information | CycloneDX 2.0 location |
+|---|---|
+| Model details, identity, and licensing | The model `component` (`name`, `version`, `description`, `identifiers`, `licenses`, `externalReferences`) |
+| Developers, suppliers, and intended users | The model component's `parties` (and shared `definitions.parties`) |
+| Learning types, tasks, architecture, parameters, inputs & outputs, training data, and limitations | The model component's `modelProperties` |
+| Quantitative analysis (performance metrics) and environmental impact (energy consumption) | The model component's `measurements` |
+| Intended use cases | `definitions.useCases`, asserted by the model component's `useCaseAssertions` |
+| Ethical considerations and fairness assessments | The BOM's top-level `risks` |
+| The "model card" view itself | A model card `perspective` (see [Model card perspectives](#model-card-perspectives)) |
+
+`modelProperties` *SHOULD* be specified for any component of type `machine-learning-model` and must not be specified for other component types.
+
+This section describes the design and best practices when providing this information for a model in an AI/ML-BOM as part of the model's CycloneDX `component` definition and its related objects.
+
+For convenience, here are links to the specific sections for each of those informational areas:
+
+* [Model properties](0x22-Design-Model-Card-Parameters.md#model-properties)
+ * [Model metadata](0x22-Design-Model-Card-Parameters.md#model-metadata)
+ * [Learning types](0x22-Design-Model-Card-Parameters.md#learning-types)
+ * [Tasks](0x22-Design-Model-Card-Parameters.md#tasks)
+ * [Architecture](0x22-Design-Model-Card-Parameters.md#architecture)
+ * [Parameter count & quantization](0x22-Design-Model-Card-Parameters.md#parameter-count--quantization)
+ * [Datasets](0x22-Design-Model-Card-Parameters.md#datasets)
+ * [Inputs & Outputs](0x22-Design-Model-Card-Parameters.md#inputs--outputs)
+ * [Declaring other properties](0x22-Design-Model-Card-Parameters.md#declaring-other-properties)
+ * [Configuration parameters & hyperparameters](0x22-Design-Model-Card-Parameters.md#configuration-parameters--hyperparameters)
+
+* [Quantitative analysis](0x23-Design-Model-Card-Quantitative-Analysis.md#model-quantitative-analysis)
+ * [Benchmarks](0x23-Design-Model-Card-Quantitative-Analysis.md#benchmarks)
+ * [Metrics](0x23-Design-Model-Card-Quantitative-Analysis.md#metrics)
+ * [Performance metrics](0x23-Design-Model-Card-Quantitative-Analysis.md#performance-metrics)
+ * [Graphics](0x23-Design-Model-Card-Quantitative-Analysis.md#graphics)
+
+* [Considerations](0x24-Design-Model-Card-Considerations.md#model-design-considerations)
+ * [Users & use cases](0x24-Design-Model-Card-Considerations.md#users--use-cases)
+ * [Technical limitations](0x24-Design-Model-Card-Considerations.md#technical-limitations)
+ * [Performance tradeoffs](0x24-Design-Model-Card-Considerations.md#performance-tradeoffs)
+ * [Ethical considerations](0x24-Design-Model-Card-Considerations.md#ethical-considerations)
+ * [Fairness assessments](0x24-Design-Model-Card-Considerations.md#fairness-assessments)
+ * [Environmental impact consideration](0x24-Design-Model-Card-Considerations.md#environmental-considerations)
+ * [Energy consumptions](0x24-Design-Model-Card-Considerations.md#energy-consumptions)
+
+* [Additional model-related information](0x40-Design-Additional-Model-Information.md#additional-model-related-information)
+ * [Using CycloneDX AI/ML properties](0x40-Design-Additional-Model-Information.md#using-cyclonedx-aiml-properties)
+ * [Tokenizers and prompt templates](0x40-Design-Additional-Model-Information.md#tokenizers-and-prompt-templates)
+ * [Including manufacturing information for the ML model](0x40-Design-Additional-Model-Information.md#including-manufacturing-information-for-the-ml-model)
+
+## Model card perspectives
+
+Because model card information is spread across the AI/ML-BOM, CycloneDX 2.0 introduces *perspectives*: a perspective is a "lens" that maps AI/ML-BOM data into the terms of a particular audience. A model card perspective maps each model card section (its `nativeName`, such as "Intended Use" or "Ethical Considerations") to the AI/ML-BOM data that supplies it using an [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) JSONPath `expression`, along with the section's `relevance` (`required`, `recommended`, or `optional`) and an optional `weight` that can drive completeness scoring.
+
+This means the same AI/ML-BOM can be presented as different model cards (e.g., a canonical model card informed by EU AI Act requirements, a model hub's model card, or a corporate model card) without duplicating data, and new model card formats can be supported without changing the schema.
+
+###### Example: A model card perspective (abridged)
+
+```json
+{
+ "perspectives": [
+ {
+ "refId": "perspective-model-card",
+ "name": "Model Card",
+ "domains": [ "machine-learning", "transparency" ],
+ "mappings": [
+ {
+ "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.tasks",
+ "nativeName": "Supported Tasks",
+ "relevance": "required",
+ "weight": 0.9
+ },
+ {
+ "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.limitations",
+ "nativeName": "Technical Limitations",
+ "relevance": "required",
+ "weight": 0.9
+ },
+ {
+ "expression": "$.risks.risks[?(@.domains[?(@.type=='ethical')])]",
+ "nativeName": "Ethical Considerations",
+ "relevance": "required",
+ "weight": 0.9
+ },
+ {
+ "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.measurements[?(@.activity)]",
+ "nativeName": "Environmental Impact",
+ "relevance": "recommended"
+ }
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+> **Note**: Perspectives are under active development in CycloneDX 2.0. A canonical model card perspective, informed by EU AI Act requirements, is planned for a future revision of this guide.
+
+
+
+### Design notes
+
+Please note that at the time of initial development (CycloneDX v1.5), the CycloneDX model card schema was heavily influenced by [Tensorflow ModelCard Toolkit](https://github.com/tensorflow/model-card-toolkit) and specifically its [ModelCard fields](https://www.tensorflow.org/responsible_ai/model_card_toolkit/api_docs/python/model_card_toolkit/ModelCard) since it was one of the few frameworks available for reference.
+
+Since that time, the AI/ML landscape has progressed rapidly, both in the design of model architectures and in the increased emphasis on providing model disclosure to comply with governmental regulations. In order to account for these changes, CycloneDX 2.0 replaces the 1.x `modelCard` object with the structured `modelProperties`, `measurements`, `parties`, use cases, risks, and perspectives described in this guide.
+
+
diff --git a/ML-BOM/2.0/en/0x22-Design-Model-Card-Parameters.md b/ML-BOM/2.0/en/0x22-Design-Model-Card-Parameters.md
new file mode 100644
index 00000000..c2a3939d
--- /dev/null
+++ b/ML-BOM/2.0/en/0x22-Design-Model-Card-Parameters.md
@@ -0,0 +1,555 @@
+# Model properties
+
+
+
+
+
+This section will feature guidance on filling out information in the CycloneDX model component's `modelProperties` object and its subcomponents, including:
+
+* [Model metadata](#model-metadata)
+ * [Learning types](#learning-types) - The learning paradigms used to train the model.
+ * [Tasks](#tasks) - The tasks the model is designed to perform, which directly influence the input and/or output. Examples include classification, regression, text generation, etc.
+ * [Architecture](#architecture) - The model's architecture, described by its family (e.g., Transformer, Convolutional Neural Network (CNN), Recurrent Neural Network (RNN)), its structural features, its runtime topology, and the name of its specific implementation (e.g., `LlamaForCausalLM`, ResNet-50, YOLOv3).
+ * [Parameter count & quantization](#parameter-count--quantization)
+ * [Providing links to papers & articles](#providing-links-to-papers--articles)
+* [Datasets](#datasets) - The datasets used to train and evaluate the model.
+ * [Declaring datasets](#declaring-datasets)
+* [Inputs & Outputs](#inputs--outputs) - Describes the input and output parameters of the model.
+* [Declaring other properties](#declaring-other-properties)
+ * [Configuration parameters & hyperparameters](#configuration-parameters--hyperparameters)
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 `modelCard.modelParameters` object is replaced by `modelProperties` on the model `component`. The 1.7 `approach.type`, `task`, `architectureFamily`, and `modelArchitecture` strings are replaced by the `learningTypes`, `tasks`, and `architecture` fields, which use controlled vocabularies that can be validated and compared across BOMs.
+
+## Model metadata
+
+The `modelProperties` fields, grouped in this section, are intended to describe some of the metadata used to classify the associated ML model.
+
+### Learning types
+
+Describes the learning paradigms used to train the model. Since modern models often combine several paradigms (e.g., self-supervised pre-training followed by supervised fine-tuning and reinforcement-learning-based alignment), `learningTypes` is an array which supports the following predefined values:
+
+| Type | Description |
+|---|---|
+| **supervised** | Supervised machine learning involves training an algorithm on labeled data to predict or classify new data based on the patterns learned from the labeled examples. |
+| **unsupervised** | Unsupervised machine learning involves training algorithms on unlabeled data to discover patterns, structures, or relationships without explicit guidance, allowing the model to identify inherent structures or clusters within the data. |
+| **reinforcement-learning** | Reinforcement learning is a type of machine learning where an agent learns to make decisions by interacting with an environment to maximize cumulative rewards, through trial and error. |
+| **semi-supervised** | Semi-supervised machine learning utilizes a combination of labeled and unlabeled data during training to improve model performance, leveraging the benefits of both supervised and unsupervised learning techniques. |
+| **self-supervised** | Self-supervised machine learning involves training models to predict parts of the input data from other parts of the same data, without requiring external labels, enabling learning from large amounts of unlabeled data. |
+
+A custom learning type may be provided as an object with a `name` and `description` when none of the predefined values apply.
+
+Please note that links to external documentation detailing the model training approach (and other information) can be provided using [external references](#providing-links-to-papers--articles), which are discussed later in this section. Detailed training workflows (e.g., sequenced pre-training, fine-tuning, and alignment phases) can be described using CycloneDX `formulation` and referenced from `modelProperties.training.formula` (see [Including manufacturing information for the ML model](0x40-Design-Additional-Model-Information.md#including-manufacturing-information-for-the-ml-model)).
+
+### Tasks
+
+Describes the tasks (or goals) the machine learning model is designed to perform. A model may support multiple tasks, so `tasks` is an array. CycloneDX 2.0 predefines a vocabulary of tasks aligned with common model hub categories, including:
+
+* **Text**: `text-generation`, `text-classification`, `token-classification`, `question-answering`, `summarization`, `translation`, `text-to-text`, `fill-mask`, `sentence-similarity`, `zero-shot-classification`, `few-shot-learning`
+* **Vision & multimodal**: `image-classification`, `image-segmentation`, `object-detection`, `image-to-image`, `image-to-text`, `text-to-image`, `text-to-video`, `depth-estimation`, `video-classification`
+* **Audio**: `audio-classification`, `automatic-speech-recognition`, `audio-to-audio`, `text-to-audio`, `text-to-speech`, `voice-activity-detection`
+* **Tabular, time-series & other**: `tabular-classification`, `tabular-regression`, `time-series-forecasting`, `reinforcement-learning`, `robotics`, `graph-ml`, `feature-extraction`, `embedding`
+
+Tasks not covered by the predefined values (for example, the more general categories below) may be declared as custom tasks using an object with a `name` and `description`:
+
+* **Anomaly Detection**: Identifying outliers or unusual patterns in data.
+* **Clustering**: Grouping unlabeled data based on similar characteristics (e.g., customer segmentation).
+* **Dimensionality Reduction**: Simplifying complex data by reducing the number of variables while preserving core information.
+* **Recommendation/Association**: Finding relationships between items (e.g., "users who bought this also bought...").
+
+### Architecture
+
+The `architecture` object describes what a model is built from, how it is built, and how it runs, using three tiers of controlled vocabulary, along with a `name` and `description` for the specific implementation:
+
+| Field | Question answered | Cardinality |
+|---|---|---|
+| `family` | What is the model fundamentally built from? | one value |
+| `features` | Which structural mechanisms does it use? | array |
+| `topology` | How are parameters activated at runtime? | one value |
+
+Each tier accepts a predefined value or a custom object with a `name` and `description`, so every tier remains extensible.
+
+#### Architecture family
+
+An architecture family defines the model's neural network's structural and data-processing methodology. It typically does not describe a single model but rather the general design of the neural network (NN), the mathematical approach, context, attention mechanisms, and the like. It should provide insight to those versed in the field on how the model is constructed.
+
+The predefined architecture family values are: `transformer`, `cnn`, `rnn`, `lstm`, `gru`, `gan`, `vae`, `mamba`, `ssm`, `gnn`, `mlp`, `rwkv`, `snn`, `kan`, `diffusion`, `flow-matching`, `rbm`, `capsnet`, `neuromorphic`, and `hybrid` (for models that combine families, such as hybrid Mamba/Transformer designs).
+
+Some examples of commonly referenced neural network (NN) architecture families include:
+
+* **Transformers** (`transformer`) - an architecture designed to process sequential data (like text, speech, or images) in parallel rather than in order.
+* **Convolutional Neural Network** (`cnn`) - an architecture designed to efficiently detect patterns (like edges, shapes, and textures) to typically classify or analyze visual (videos/image) or auditory data, but can be applied to text analysis, behavioral patterns and more.
+* **Recurrent Neural Network** (`rnn`) - an architecture designed for processing sequential data like text, speech, and time series, typically used for tasks where order matters, such as language translation, speech recognition and time-series forecasting.
+* **Long Short-Term Memory** (`lstm`) - a specialized variant of a Recurrent Neural Network (RNN) architecture designed specifically to overcome the limitations of traditional RNNs in learning long-term dependencies.
+* **Gated Recurrent Units** (`gru`) - a specialized variant of a Recurrent Neural Network (RNN) architecture designed to overcome challenges like the vanishing gradient problem and enhance the modeling of long-term dependencies in sequential datasets.
+* **Generative Adversarial Networks** (`gan`) - an architecture used to train two neural networks, a *Generator* and a *Discriminator*, to compete against each other to generate more authentic data from a starting training dataset. The Generator tries to fool the Discriminator by creating fake data, while the Discriminator tries to identify fakes, leading to continuous improvement in data quality.
+
+Again, the list above represents architecture families commonly referenced in research to establish an understanding of general model design; however, the architectural landscape continues to grow as researchers specialize and optimize for different use cases, goals, and datasets.
+
+#### Architecture features
+
+Architecture features identify the structural mechanisms present in a model, including macro-level layouts, attention variants, and parameter-efficient adaptation mechanisms. The predefined values are:
+
+* **Layout**: `decoder-only`, `encoder-only`, `encoder-decoder`, `dual-encoders`, `siamese-network`, `u-net`, `vae-bottleneck`, `hybrid-backbone`, `state-space-model`, `flow-matching`, `mixture-of-experts`
+* **Attention & positional encoding**: `cross-attention`, `cross-attention-gated`, `grouped-query-attention`, `sliding-window-attention`, `rotary-position-embedding`
+* **Layers & adaptation**: `residual-connections`, `gated-linear-units`, `adapter-layers`, `projector-layers`, `vision-encoder`, `multimodal-fusion`
+* **Inference & augmentation**: `speculative-decoding`, `retrieval-augmented`, `memory-augmented`, `reranker`
+
+#### Architecture topology
+
+The topology describes how the model's parameters are activated at runtime. The predefined values are: `dense`, `sparse` (e.g., Mixture-of-Experts routing), `dynamic`, `liquid`, `mixture-of-depths`, `early-exit`, and `recurrent-hybrid`.
+
+#### Architecture name
+
+The architecture `name` field is intended to include specific keywords to identify an implementation (class or library) or technical descriptors of the architectural "blueprint" needed to run a specific model.
+
+These are typically found in one of several locations relative to the model:
+
+* **Model Card**: the associated "model card" (e.g., `README.md` in Hugging Face) may contain mentions of specific class names like `LlamaForCausalLM`, `BertModel`, or `VisionTransformer`.
+* **Framework-Specific Implementation Keywords** or tags: Depending on your code environment (PyTorch, TensorFlow, llama.cpp, etc.) that identify specific model code within the platform or environment.
+* **Framework-Specific Configuration files** (e.g., Hugging Face transformer's `config.json` file): may contain the name of the class or function used to configure the framework for the specific implementation recommended for the associated model.
+* **Academic Research Papers** (e.g., arXiv): may include detailed descriptors of processing algorithms, supported training or inference engines or specific, named implementations
+
+### Parameter count & quantization
+
+* **parameterCount** - The total number of trainable parameters of the model, expressed as an integer (e.g., `7000000000` rather than `"7B"`).
+* **quantization** - Describes the quantization applied to the model's weights (if any), including the `method` (e.g., `k-quant`, `gptq`, `awq`), the number of `bits`, the `scheme` (`affine` or `symmetric`), the `granularity` (`per-tensor`, `per-channel`, or `per-group`), and for grouped or per-channel quantization, the `groupSize` and `axis`.
+
+###### Example: Model metadata for the Qwen-7B model
+
+This example demonstrates best practices for the Qwen-7B model using information published within and for the model's repository on Hugging Face.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "modelProperties": {
+ "learningTypes": [ "self-supervised", "supervised", "reinforcement-learning" ],
+ "tasks": [ "text-generation" ],
+ "architecture": {
+ "name": "QWenLMHeadModel",
+ "description": "Decoder-only Transformer using rotary position embeddings and SwiGLU activations.",
+ "family": "transformer",
+ "features": [
+ "decoder-only",
+ "rotary-position-embedding",
+ "gated-linear-units"
+ ],
+ "topology": "dense"
+ },
+ "parameterCount": 7000000000
+ // ...
+ }
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **learningTypes** - Qwen-7B was pre-trained using self-supervised (next-token prediction) learning on a large corpus; the supervised fine-tuning (SFT) and reinforcement learning from human feedback (RLHF) methods, also declared as [hyperparameter properties](#example-model-parameters--hyperparameters-for-the-qwen-7b-model) later in this section, are represented by `supervised` and `reinforcement-learning`.
+* **architecture.name** - the value `QWenLMHeadModel` was located in the model's `config.json` model configuration file.
+* **architecture.features** - Lists the structural mechanisms documented in the Qwen Technical Report.
+* **architecture.topology** - The value `dense` indicates that all of the model's parameters are active for each token (in contrast to a `sparse` Mixture-of-Experts model).
+* **parameterCount** - The nominal parameter count ("7B") as published by the model provider, expressed as an integer.
+
+#### Providing links to papers & articles
+
+Most models are fully described in terms of research papers, articles, and other reference documents. In those cases, they should be provided as `externalReferences` under the `component`. Links specific to the architecture may also be provided as `externalReferences` within the `architecture` object itself.
+
+###### Example: "Qwen Technical Report"
+
+This shows how the Qwen research team disclosed comprehensive details about the Qwen model's design, training, implementation, and evaluation as a formal research paper in Cornell University's arXiv scholarly article distribution service.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "externalReferences": [
+ {
+ "type": "documentation",
+ "url": "https://arxiv.org/abs/2309.16609",
+ "comment": "Qwen Technical Report"
+ }
+ ]
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+## Datasets
+
+Details the datasets used to train and evaluate the model.
+
+#### Declaring datasets
+
+In CycloneDX 2.0, each dataset used to train, fine-tune, test, or evaluate a machine learning model is described as a CycloneDX component of type `data` and referenced from the model:
+
+* **Training datasets** are referenced from `modelProperties.training.datasets`, using the `refId` of the data component (or a BOM-Link to a data component declared in another BOM).
+* **Evaluation datasets** are referenced from each performance metric's `evaluationDatasets` (see [Quantitative analysis](0x23-Design-Model-Card-Quantitative-Analysis.md#model-quantitative-analysis)).
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 `modelParameters.datasets` array allowed either in-line dataset objects or `ref` references to data components. In 2.0, `modelProperties.training.datasets` contains only references; information previously provided in-line is now provided on the referenced `data` component (e.g., within its `data` array).
+
+How much detail is provided for each data component depends on the context, as discussed in the next sections.
+
+##### Datasets with minimal information
+
+A data component may be kept minimal to simplify the association between training datasets and the model, specifically addressing scenarios where data is difficult to reference as an independent, fully described component.
+
+Key applications:
+
+* **Filtered Data**: Documenting specific slices or individual snippets of data used for fine-tuning or testing.
+* **Private Repositories**: Providing transparency via BOMs for non-public datasets in public model cards (e.g, private data used for models in the healthcare or financial services industries).
+* **Unstructured Sources**: Referencing data not housed in traditional databases or management tools (e.g., data within S3 buckets, event data within Security information and event management (SIEM) systems).
+
+
+
+###### Example: Custom health model with private dataset
+
+This example shows a model fine-tuned (by a fictional "ACME Health" company) from the public [m42-health/Llama3-Med42-8B](https://huggingface.co/m42-health/Llama3-Med42-8B) model using a private dataset.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ "specFormat": "CycloneDX",
+ "specVersion": "2.0",
+ "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
+ "version": 1,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/acme-health/custom-Llama3-Med42-8B@2ee9dc9",
+ "name": "acme-health/custom-Llama3-Med42-8B",
+ "description": "Customized Med42-v2 large language models (LLMs) which uses the Llama3 architecture and fine-tuned using private clinical dataset.",
+ // ...,
+ "modelProperties": {
+ // ...,
+ "training": {
+ "datasets": [
+ "dataset-ultrafeedback",
+ // ...,
+ "dataset-acme-midwest-health"
+ ]
+ }
+ // ...
+ }
+ },
+ "components": [
+ {
+ "type": "data",
+ "refId": "dataset-ultrafeedback",
+ "name": "UltraFeedback dataset",
+ "data": [
+ {
+ "type": "dataset",
+ "classification": "public",
+ "contents": {
+ "url": "https://huggingface.co/datasets/openbmb/UltraFeedback"
+ }
+ }
+ ]
+ },
+ // ...,
+ {
+ "type": "data",
+ "refId": "dataset-acme-midwest-health",
+ "name": "ACME Midwest health data",
+ "data": [
+ {
+ "type": "dataset",
+ "classification": "confidential",
+ "contents": {
+ "url": "https://acme.ai/adatasets/health/patient?region=midwest"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **classification** - The predefined data classifications are `public`, `internal`, `confidential`, `restricted`, and `classified` (custom classifications are also supported). The ACME private dataset is classified as `confidential`.
+* **url** - Please note that URLs may be to either public or private resources. For example, in the case of the ACME `confidential` dataset above, the URL is likely behind an Access Control Point (ACP) which regulates traffic to the private resource in accordance with the ACME company's governance policies.
+
+##### Datasets as fully described data components
+
+This method is preferable for most security and compliance contexts, as it allows for the full expression of provenance, pedigree, attestations, and other contextual information as a full CycloneDX component.
+
+###### Example: health model with public datasets
+
+This example shows the recommended best practice of declaring the datasets for the base model used in the previous example (i.e., [m42-health/Llama3-Med42-8B](https://huggingface.co/m42-health/Llama3-Med42-8B)) as their own, fully identified CycloneDX components.
+
+The public datasets, as documented in the model's research paper, include:
+
+* [openbmb/UltraFeedback](https://huggingface.co/datasets/openbmb/UltraFeedback)
+* [snorkelai/Snorkel-Mistral-PairRM-DPO](https://huggingface.co/snorkelai/Snorkel-Mistral-PairRM-DPO)
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ "specFormat": "CycloneDX",
+ "specVersion": "2.0",
+ "serialNumber": "urn:uuid:eb033070-85d1-45f4-9eb7-f50510f83853",
+ "version": 1,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/m42-health/Llama3-Med42-8B@ceab7e7",
+ "name": "m42-health/Llama3-Med42-8B",
+ "description": "an open, clinical large language models (LLM) instruct and preference-tuned by M42 to expand access to medical knowledge. Built off LLaMA-3 and designed to provide high-quality answers to medical questions.",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ { "scheme": "purl", "value": "pkg:huggingface/m42-health/Llama3-Med42-8B@ceab7e7ee4b9dbde7ba82867f34274db51487d83" }
+ ]
+ }
+ ],
+ // ...,
+ "modelProperties": {
+ // ...,
+ "training": {
+ "datasets": [
+ "pkg:huggingface/openbmb/UltraFeedback@40b4365",
+ "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a"
+ ]
+ }
+ }
+ },
+ "components": [
+ {
+ "name": "UltraFeedback dataset",
+ "type": "data",
+ "refId": "pkg:huggingface/openbmb/UltraFeedback@40b4365",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ { "scheme": "purl", "value": "pkg:huggingface/openbmb/UltraFeedback@40b436560ca83a8dba36114c22ab3c66e43f6d5e" }
+ ]
+ }
+ ]
+ // ...
+ },
+ {
+ "name": "Snorkel-Mistral-PairRM-DPO dataset",
+ "type": "data",
+ "refId": "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a",
+ "identifiers": [
+ {
+ "party": "party-hugging-face",
+ "identities": [
+ { "scheme": "purl", "value": "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a875b4c692dfaff6c675b10af07b45511" }
+ ]
+ }
+ ]
+ // ...
+ }
+ ]
+ }
+ ],
+ "definitions": {
+ "parties": [
+ {
+ "refId": "party-hugging-face",
+ "roles": [ { "role": "supplier" } ],
+ "organization": { "name": "Hugging Face" }
+ }
+ ]
+ }
+}
+```
+
+> **Tip**: Datasets may be further described using properties from the proposed `cdx:ai-ml:dataset` namespace of the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy) ([PR #175](https://github.com/CycloneDX/cyclonedx-property-taxonomy/pull/175)), such as the dataset's `stage`, `category`, and EU AI Act data `sources`.
+
+
+
+
+### Inputs & outputs
+
+Describes the input and output parameters of the model. Each entry in the `inputs` and `outputs` arrays describes one parameter, including its:
+
+* **name** and **description**
+* **modality** - `text`, `image`, `audio`, `video`, `multimodal`, `embedding`, or `logits`
+* **dataType** - The numeric or symbolic data type (e.g., `string`, `float32`, `bfloat16`, `int64`, `uint8`)
+* **mimeType** - The media type for encoded content (e.g., `image/png`)
+* **shape** - The dimensional shape (e.g., tensor dimensions), where dynamic dimensions are expressed as `null` or `-1`
+* **processingStage** - The stage of the parameter relative to tokenization or encoding: `pre-tokenizer`, `post-tokenizer`, `pre-encoder`, `post-encoder`, `pre-processing`, `post-processing`, or `raw`
+* **required**, **defaultValue**, and **constraints** (e.g., `minLength`, `maxLength`, `minValue`, `maxValue`, `allowedValues`, `pattern`)
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 `inputs`/`outputs` objects only supported a single `format` string.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "modelProperties": {
+ // ...,
+ "inputs": [
+ {
+ "name": "prompt",
+ "description": "The text prompt to be completed by the model.",
+ "modality": "text",
+ "dataType": "string",
+ "processingStage": "pre-tokenizer",
+ "required": true
+ }
+ ],
+ "outputs": [
+ {
+ "name": "completion",
+ "description": "The generated text completion.",
+ "modality": "text",
+ "dataType": "string",
+ "processingStage": "post-processing"
+ }
+ ]
+ }
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+In order to provide information on other model configuration parameters and hyperparameters, it is recommended to follow the best practice as shown in the next section "[Declaring other properties](#declaring-other-properties)" and its "[Example: Model parameters & hyperparameters for the Qwen-7B model](#example-model-parameters--hyperparameters-for-the-qwen-7b-model)".
+
+
+
+### Declaring other properties
+
+#### Configuration parameters & hyperparameters
+
+In general, model configuration parameters describe values used to configure model processing applications, frameworks, and implementations of model architectures. For example, most models on Hugging Face typically include configuration files for both the models and the tokenizers they are designed to work with, using the [Hugging Face Transformers](https://huggingface.co/docs/transformers/) library and its underlying PyTorch framework.
+
+> **Note**: Configuration parameters and hyperparameters that are not represented by native `modelProperties` fields are provided using CycloneDX `properties` and the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy) reserved namespaces `cdx:ai-ml:model:parameter` and `cdx:ai-ml:model:hyperparameter` as needed. Because the taxonomy can be extended at any time (independently of the schema's standardization cycle), it is the preferred mechanism for describing the rapidly evolving set of AI/ML configuration values.
+
+###### Example: Model parameters & hyperparameters for the Qwen-7B model
+
+As shown in the [Qwen/Qwen-7B model repository files](0x20-Design-Model-Component-Metadata.md#example-qwenqwen-7b-model-repository-files) example in the previous section, we see the model includes several configuration files, including:
+
+- [config.json](https://huggingface.co/Qwen/Qwen-7B/blob/main/config.json) - which contains configuration parameters (as key-value pairs) used for initializing the model's implementation.
+- [generation_config.json](https://huggingface.co/Qwen/Qwen-7B/blob/main/generation_config.json) - which contains model hyperparameters (as key-value pairs) and their suggested (default) values used for configuring the model for token generation (inference).
+
+The JSON below shows how a few of the [Qwen/Qwen-7B](https://huggingface.co/Qwen/Qwen-7B) model's parameters, as contained in the [config.json](https://huggingface.co/Qwen/Qwen-7B/blob/main/config.json) configuration file, would be declared within the CycloneDX `modelProperties` object's `properties` array using the CycloneDX reserved namespace for AI/ML.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "modelProperties": {
+ // ...,
+ "parameterCount": 7000000000,
+ "properties": [
+ {
+ "name": "cdx:ai-ml:model:parameter:tune_method",
+ "value": "sft"
+ },
+ {
+ "name": "cdx:ai-ml:model:parameter:tune_method",
+ "value": "rlhf"
+ },
+ {
+ "name": "cdx:ai-ml:model:hyperparameter:num_hidden_layers",
+ "value": "32"
+ },
+ {
+ "name": "cdx:ai-ml:model:hyperparameter:hidden_size",
+ "value": "4096"
+ },
+ {
+ "name": "cdx:ai-ml:model:hyperparameter:context_length",
+ "value": "8192"
+ },
+ {
+ "name": "cdx:ai-ml:model:hyperparameter:vocab_size",
+ "value": "151936"
+ },
+ {
+ "name": "cdx:ai-ml:model:hyperparameter:quantization",
+ "value": "BF16"
+ }
+ // ...
+ ]
+ }
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+Please note that the example above includes only a small set of parameters and hyperparameters that extend the `cdx:ai-ml:model:parameter` and `cdx:ai-ml:model:hyperparameter` paths. Actual models may have a more comprehensive set of properties declared.
+
+The example above contains the following native field and `cdx:ai-ml:model:parameter` and `cdx:ai-ml:model:hyperparameter` properties, which are explained below:
+
+- **parameterCount** - Total number of learned parameters in the model. In CycloneDX 2.0, this native integer field replaces the `cdx:ai-ml:model:parameter:count` property.
+- **properties**
+
+ * **context_length** - The maximum sequence length the model supports during training and inference.
+ * **num_hidden_layers** - The total number of intermediate (hidden) processing layers situated between the input layer and the output layer of the model.
+ * **hidden_size** - The dimension of the input and output representations (i.e., of the token embeddings) used by the internal (hidden) layers of a model's neural network.
+ * **tune_method** - Indicates the fine-tuning methods used to develop the model. In this case, `sft` (Supervised Fine-Tuning) and `rlhf` (Reinforcement Learning from Human Feedback).
+ * **quantization** - The numerical precision (number of bits) used to store the model's tensor weights, which affects model memory usage. Where a model's weights have been quantized (e.g., 4-bit GGUF `Q4_K_M`), the quantization method, bits, scheme, and granularity should also be described using the native `modelProperties.quantization` object.
+ * **vocab_size** - The size of the model's vocabulary.
+
+##### Tokenizer parameters and hyperparameters
+
+The same methodology used to provide model hyperparameter names and values for models can also be applied to model tokenizers by instead using the `cdx:ai-ml:tokenizer:hyperparameter` path and extending it with a path with a parameter name.
+
+
diff --git a/ML-BOM/2.0/en/0x23-Design-Model-Card-Quantitative-Analysis.md b/ML-BOM/2.0/en/0x23-Design-Model-Card-Quantitative-Analysis.md
new file mode 100644
index 00000000..43f291b3
--- /dev/null
+++ b/ML-BOM/2.0/en/0x23-Design-Model-Card-Quantitative-Analysis.md
@@ -0,0 +1,232 @@
+# Model quantitative analysis
+
+
+
+
+
+This section will feature guidance on providing quantitative analysis information using the CycloneDX model component's `measurements` array and its performance metric objects, including:
+
+* [Metrics](#metrics)
+ * [Performance metrics](#performance-metrics)
+* [Graphics](#graphics)
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 `modelCard.quantitativeAnalysis.performanceMetrics` array is replaced by performance metric entries in the component's `measurements` array. Each metric now has a separate `type` and `benchmark`, a typed `measure` with a numeric `value` and a `unit`, numeric `confidenceInterval` bounds, and references to the `evaluationDatasets` used. The 1.7 `quantitativeAnalysis.graphics` collection is replaced by per-metric `graphics`.
+
+## What is quantitative analysis
+
+Quantitative analysis is the process of using metrics on benchmarks to determine if a model is reliable, safe, or better than another. It involves comparing the metric results against the benchmark standard to assess performance, identify limitations, and track progress over time.
+
+
+
+### The value of quantitative analysis
+
+* **Numerical Metrics**: Provides measurable data (e.g., error rates, latency, performance scores) rather than subjective feedback.
+* **Objective Evaluation**: Provides reproducible, scalable results that can be compared across different models or versions.
+* **Pattern & Trend Detection**: Identifies numerical patterns, correlations, and trends within large or complex datasets that might be missed manually.
+* **Testing Hypotheses**: Enables the statistical testing of assumptions about model behavior allowing for comparisons against similar models for given tasks.
+
+## Benchmarks
+
+Benchmarks are standardized test datasets, scenarios, or tasks that define the "playing field". They provide a consistent environment for evaluating different models and enable the comparison of their metrics across similar models.
+
+### Types of machine learning benchmarks
+
+Benchmarks use standardized datasets to objectively compare model quality, efficiency, fairness, and speed, providing a shared baseline for identifying areas for improvement in various categories.
+
+* [Large Language Models (LLM)](0x90-Appendix-A_Glossary.md#large-language-model-llm) and [Natural Language Processing (NLP)](0x90-Appendix-A_Glossary.md#natural-language-processing-nlp) (e.g., speech recognition or text classification): These benchmarks evaluate reasoning, knowledge, and generation capabilities. A few examples of datasets used to benchmark these models against different tasks include:
+
+ * **General Tasks**
+ * [MMLU](https://huggingface.co/datasets/cais/mmlu), [MMLU-Pro](https://huggingface.co/datasets/TIGER-Lab/MMLU-Pro) (Massive Multitask Language Understanding): Tests knowledge across STEM, humanities, and social sciences.
+ * [HellaSwag](https://huggingface.co/datasets/Rowan/hellaswag) / [WinoGrande](https://huggingface.co/datasets/allenai/winogrande): Common sense reasoning and pronoun resolution tasks.
+ * [GLUE](https://gluebenchmark.com/): benchmarking resources for training, evaluating, and analyzing natural language understanding systems. GLUE's dataset is available in Hugging Face Hub ([nyu-mll/glue](https://huggingface.co/datasets/nyu-mll/glue)) and supports multiple tasks that can be evaluated independently, for example:
+ * *ax* - evaluates sentence understanding through Natural Language Inference (NLI) problems.
+ * *cola* - The Corpus of Linguistic Acceptability consists of English acceptability judgments drawn from books and journal articles on linguistic theory.
+ * *mnli* - The Multi-Genre Natural Language Inference Corpus consists of sentence pairs with textual entailment annotations. Given a premise sentence and a hypothesis sentence, the task is to predict whether the premise entails the hypothesis.
+ * **Math/STEM tasks**
+ * [GSM8K](https://huggingface.co/datasets/openai/gsm8k) (OpenAI, Grade School Math 8K): a dataset of 8.5K high quality linguistically diverse grade school math word problems.
+ * [MATH-500](https://huggingface.co/datasets/HuggingFaceH4/MATH-500) (Hugging Face): Benchmarks specifically designed to evaluate mathematical reasoning.
+ * **Coding Tasks**
+ * [HumanEval](https://huggingface.co/datasets/openai/openai_humaneval) (OpenAI): used to evaluate the functional correctness of code generated LLMs. It consists of hand-crafted programming problems designed to test reasoning and code synthesis abilities.
+ * [MBPP](https://huggingface.co/datasets/Muennighoff/mbpp) (Mostly Basic Python Problems ): Benchmarks for evaluating code generation and programming capabilities.
+ * [CodeXGLUE](https://github.com/microsoft/CodeXGLUE/tree/main/Code-Code/code-refinement) (MicroSoft, Code Refinement): Used to evaluate a model's ability to remove (i.e., "fix") bugs from Java code (i.e., refine the code) with accuracy being reported as [BLEU](https://learn.microsoft.com/en-us/azure/ai-services/translator/custom-translator/concepts/bleu-score) scores.
+ * **Other Tasks**
+ * [IMDB](https://www.kaggle.com/datasets/lakshmi25npathi/imdb-dataset-of-50k-movie-reviews): a large dataset of 50K, highly polarized, movie reviews for NLP sentiment analysis and classification.
+
+* [Computer Vision](0x90-Appendix-A_Glossary.md#computer-vision) (e.g., digital image or video recognition): These benchmarks measure the performance, accuracy, and efficiency of models in tasks like image classification, object detection, segmentation, and tracking. Some example "vision" datasets include:
+
+ * [ImageNet](https://image-net.org): large-scale dataset for computer vision, featuring over 14 million annotated, high-resolution images across thousands of object categories organized by the [WordNet](https://en.wikipedia.org/wiki/WordNet) hierarchy.
+ * [MathVista](https://huggingface.co/datasets/AI4Math/MathVista): Used to evaluating math reasoning in Visual Contexts. It consists of three datasets, *IQTest*, *FunctionQA*, and *PaperQA*, which are tailored to evaluate visual reasoning on puzzle test figures, algebraic reasoning over functional plots, and scientific reasoning with academic paper figures, respectively.
+ * [MNIST](https://www.tensorflow.org/datasets/catalog/mnist) (Modified National Institute of Standards and Technology database): a large database of handwritten digits (glyphs) that is commonly used for training various image processing systems.
+
+Again, the list above contains only a small number of benchmarking datasets that can be used to train and evaluate models.
+
+> **Tip**: Since a benchmark's dataset can be declared as a `data` component, each performance metric can reference the exact dataset (and version) it was computed against using `evaluationDatasets`.
+
+## Metrics
+
+AI benchmarking metrics are standardized, quantitative measures used to evaluate and compare the performance, accuracy, efficiency, and reliability of artificial intelligence models against established, uniform tasks and datasets. They serve as a gauge of progress in capabilities such as reasoning, coding, and language understanding, enabling simple comparisons with similar models.
+
+> **Note**: A component's `measurements` array can contain both *performance metrics* (described in this section) and *energy consumption* measurements (see [Environmental considerations](0x24-Design-Model-Card-Considerations.md#environmental-considerations)).
+
+#### Performance metrics
+
+Performance metrics are specific, quantitative measures used to evaluate a model's behavior, such as accuracy, precision, recall, perplexity, or inference speed. They provide the raw, numerical data for analysis.
+
+Each performance metric includes the following fields:
+
+* **type** (required) - The type of metric (e.g., `accuracy`, `f1`, `pass@1`, `perplexity`, `latency`, `throughput`).
+* **measure** (required) - The metric's numeric `value` and its `unit` (e.g., `%`, `1` for unitless ratios, `ms`, `tokens/s`).
+* **benchmark** - The benchmark (and its configuration, e.g., number of shots) used to compute the metric.
+* **slice** - The named subset of the evaluation data the metric was computed on.
+* **confidenceInterval** - The numeric `lowerBound` and/or `upperBound` of the metric.
+* **evaluationDatasets** - References to the `data` components the metric was computed against.
+* **graphics** - Graphics (or references to graphics) illustrating the metric.
+
+##### Common Performance Metrics
+
+* **Accuracy**: Overall correctness; typically represented as a percentage of correct responses to the full set of problems posed by a benchmark's dataset.
+* **Precision**: Of predicted positives, how many are correct.
+* **Recall** (Sensitivity): Of actual positives, how many are found.
+* **F1 Score**: Harmonic mean of *Precision* and *Recall*.
+* **Latency/Throughput**: Speed of prediction (inference), e.g., time-to-first-token (`ms`) or generation rate (`tokens/s`).
+
+
+
+###### Example: Declaring the MMLU accuracy score for Qwen-7B
+
+The Qwen accuracy scores for various benchmarks are published in the [QwenLM/Qwen](https://github.com/QwenLM/Qwen?tab=readme-ov-file#performance) GitHub repository's README.
+
+This appears as a table that includes all Qwen models, along with other similar models for comparison. Here is the table row for all Qwen-7B benchmarks:
+
+| Model | MMLU | C-Eval | GSM8K | MATH | HumanEval | MBPP | BBH | CMMLU |
+|:------------------|:--------:|:--------:|:--------:|:--------:|:---------:|:--------:|:--------:|:--------:|
+| **Qwen-7B** | 58.2 | 63.5 | 51.7 | 11.6 | 29.9 | 31.6 | 45.0 | 62.2 |
+
+The MMLU score from the table would be declared as a performance metric as follows:
+
+```json
+{
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "measurements": [
+ {
+ "type": "accuracy",
+ "benchmark": "MMLU (5-shot)",
+ "measure": {
+ "value": 58.2,
+ "unit": "%"
+ },
+ "confidenceInterval": {
+ "lowerBound": 57.48,
+ "upperBound": 58.92
+ },
+ "evaluationDatasets": [
+ "pkg:huggingface/cais/mmlu"
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **type** / **benchmark** - The metric type (`accuracy`) is separated from the benchmark and its configuration (`MMLU (5-shot)`), which allows the same metric type to be compared across benchmarks.
+* **measure** - The value is provided as a number with an explicit unit (`%`) rather than as a string.
+* **slice** - the `slice` property was omitted indicating the full dataset was used for performance benchmarking.
+* **confidenceInterval** - the values provided reflect the 95% Statistical Confidence Interval (±0.72) of the accuracy for the full MMLU test set (approx. 14,000 questions).
+* **evaluationDatasets** - References the `refId` of a `data` component (declared elsewhere in the BOM) describing the MMLU dataset.
+
+###### Example: Declaring a GLUE F1 Score
+
+This example shows how to provide an [F1 score](https://en.wikipedia.org/wiki/F-score) (i.e., the harmonic mean of precision and recall measurements) for a model's performance on classification tasks within the [GLUE benchmark](https://zilliz.com/glossary/glue-benchmark).
+
+```json
+{
+ "measurements": [
+ {
+ "type": "f1",
+ "benchmark": "GLUE",
+ "slice": "cola",
+ "measure": {
+ "value": 0.87,
+ "unit": "1"
+ }
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **slice** - the `slice` property references a named subset `cola` (Corpus of Linguistic Acceptability) which is a subset of the GLUE tests; "cola" consists of single-sentence task to determine if a sentence is grammatically correct or not.
+* **unit** - The unit `1` denotes a unitless (dimensionless) ratio between 0 and 1.
+
+## Graphics
+
+Model cards typically include graphs, charts, and other graphics that highlight the model's performance benchmarks, often relative to other models. This section exemplifies the use of the CycloneDX `graphics` object to include these graphics in the AI/ML-BOM as part of its quantitative analysis information.
+
+Graphics may be provided in-line on a performance metric, or declared once in the BOM's `definitions.graphics` and referenced (by `refId`) from each metric they illustrate.
+
+###### Example: Qwen model comparative benchmarks
+
+The [QwenLM/Qwen](https://github.com/QwenLM/Qwen) GitHub repository includes the following JPG format spider diagram showing benchmarking comparisons for their Qwen2 models, along with some peer models:
+
+
+
+This could be encoded in a CycloneDX AI/ML-BOM as follows:
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "name": "Qwen/Qwen2-72B",
+ // ...,
+ "measurements": [
+ {
+ "type": "accuracy",
+ "benchmark": "MMLU (5-shot)",
+ "measure": { "value": 84.2, "unit": "%" },
+ "graphics": [
+ { "ref": "graphic-qwen2-benchmarks" }
+ ]
+ }
+ // ...
+ ]
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ],
+ "definitions": {
+ "graphics": [
+ {
+ "refId": "graphic-qwen2-benchmarks",
+ "name": "Qwen2 Performance Benchmarks (spider diagram)",
+ "description": "benchmark_score",
+ "image": {
+ "mediaType": "image/jpeg",
+ "encoding": "base64",
+ "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA"
+ }
+ }
+ ]
+ }
+}
+```
+
+###### Field discussion
+
+* **definitions.graphics** - Declaring the graphic once allows every metric shown in the spider diagram to reference it.
+* **mediaType** - The media type of the image (in 1.7, this field was named `contentType`).
+* **encoding** - CycloneDX, currently, only supports a `base64` encoding type.
+
+
diff --git a/ML-BOM/2.0/en/0x24-Design-Model-Card-Considerations.md b/ML-BOM/2.0/en/0x24-Design-Model-Card-Considerations.md
new file mode 100644
index 00000000..ac0227db
--- /dev/null
+++ b/ML-BOM/2.0/en/0x24-Design-Model-Card-Considerations.md
@@ -0,0 +1,608 @@
+# Model Design Considerations
+
+
+
+
+
+This section will feature guidance on providing the design considerations for a model, including:
+
+* [Users & use cases](#users--use-cases) - Who are the intended users of the model, and what are the intended use cases for the model inclusive of the Operational Design Domains (ODD)?
+* [Technical limitations](#technical-limitations) - What are the known technical limitations of the model? For example, "What kind(s) of data should the model be expected not to perform well on?", "What are the factors that might degrade model performance?".
+* [Performance tradeoffs](#performance-tradeoffs) - What are the known tradeoffs in accuracy/performance of the model?
+* [Ethical considerations](#ethical-considerations) - How to disclose known ethical risks involved in the application of this model?
+* [Fairness assessments](#fairness-assessments) - How does the model affect groups at risk of being systematically disadvantaged? What are the harms and benefits to the various affected groups?
+* [Environmental considerations](#environmental-considerations) - What are the various environmental impacts the corresponding machine learning model has exhibited across its lifecycle?
+
+> **CycloneDX 1.7 → 2.0**: The 1.7 `modelCard.considerations` object is replaced by several, more structured and referenceable objects:
+>
+> | CycloneDX 1.7 `considerations` field | CycloneDX 2.0 |
+> |---|---|
+> | `users` | `parties` (e.g., personas) with the `end-user` role |
+> | `useCases` | `definitions.useCases`, whose `actors` reference parties, asserted by the model via `useCaseAssertions` |
+> | `technicalLimitations` | `modelProperties.limitations` |
+> | `performanceTradeoffs` | `modelProperties.limitations` (see [Performance tradeoffs](#performance-tradeoffs)) |
+> | `ethicalConsiderations` | `risks.risks` with an `ethical` (or other) domain, whose `affects` references the model, and `responses` for mitigations |
+> | `fairnessAssessments` | `risks.risks` with a `fairness` domain, whose `affects` references the model and the party (persona) at risk, with graded harm and benefit `impacts` |
+> | `environmentalConsiderations` | Energy consumption entries in the model component's `measurements` |
+
+## Users & use cases
+
+The intended users of the model are described as CycloneDX `parties`, and its envisioned use cases are described as CycloneDX use cases.
+
+* **Users** - Each kind of user is a party (typically a `persona`) with the `end-user` role. Unlike a simple list of labels, a party may also be an identifiable `organization`, `person`, or `system` (e.g., an AI agent), with legal names, jurisdictions, and identifiers, so that obligations (e.g., as a deployer under the EU AI Act) can be assigned.
+* **Use cases** - Each use case is declared in the BOM's `definitions.useCases`, naming its `actors` (references to parties) and optionally its pre- and post-conditions, main flow steps, alternative flows, exceptions, and success criteria.
+* **Use case assertions** - The model component declares its relationship to each use case using `useCaseAssertions` (e.g., `implements`, `supports`, `participates-in`, or `inhibits`).
+
+###### Example: Qwen/Qwen-7B
+
+This example shows what kind of user and use case information would be expected for a typical `7B` parameter size Large Language Model (LLM) that is multi-lingual and supports code/instruct capabilities.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "useCaseAssertions": [
+ {
+ "assertionType": "supports",
+ "useCaseRefs": [
+ "uc-code-assistant",
+ "uc-translation",
+ "uc-support-triage",
+ "uc-research-summarization",
+ "uc-edge-device",
+ "uc-security-log-analysis",
+ "uc-local-assistant"
+ ]
+ }
+ ]
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ],
+ "definitions": {
+ "parties": [
+ { "refId": "user-software-developer", "roles": [ { "role": "end-user" } ], "persona": { "label": "Software developer", "archetype": "developer" } },
+ { "refId": "user-content-creator", "roles": [ { "role": "end-user" } ], "persona": { "label": "Multilingual Content Creator" } },
+ { "refId": "user-support-architect", "roles": [ { "role": "end-user" } ], "persona": { "label": "Customer Support Systems Architect" } },
+ { "refId": "user-researcher", "roles": [ { "role": "end-user" } ], "persona": { "label": "Academic Researcher / Student", "archetype": "researcher" } },
+ { "refId": "user-edge-engineer", "roles": [ { "role": "end-user" } ], "persona": { "label": "Edge Device Engineer" } },
+ { "refId": "user-security-analyst", "roles": [ { "role": "end-user" } ], "persona": { "label": "Enterprise Security Analyst", "scope": "internal" } },
+ { "refId": "user-local-ai", "roles": [ { "role": "end-user" } ], "persona": { "label": "Local AI Enthusiast / Privacy-First User" } }
+ ],
+ "useCases": [
+ {
+ "refId": "uc-code-assistant",
+ "name": "IDE code assistant",
+ "description": "Utilizing the Qwen \"instruct\" variants within an IDE for real-time code completion, bug fixing, and unit test generation, benefiting from its \"Agentic\" capabilities for repository-scale understanding.",
+ "actors": [ "user-software-developer" ]
+ },
+ {
+ "refId": "uc-translation",
+ "name": "Content translation",
+ "description": "Translating business, education, or other content or informational materials to other languages and dialects while maintaining the original tone and cultural nuances.",
+ "actors": [ "user-content-creator" ]
+ },
+ {
+ "refId": "uc-support-triage",
+ "name": "Customer support triage",
+ "description": "Deploying low-latency chatbots for high-volume inquiries where the 7B model acts as a \"triage\" agent, answering common questions and only escalating complex logic to other support mechanisms.",
+ "actors": [ "user-support-architect" ]
+ },
+ {
+ "refId": "uc-research-summarization",
+ "name": "Research summarization and drafting",
+ "description": "Summarizing long-form research papers and generating initial drafts for school projects, utilizing the model's long context window to ingest entire documents at once.",
+ "actors": [ "user-researcher" ]
+ },
+ {
+ "refId": "uc-edge-device",
+ "name": "On-device natural language control",
+ "description": "Implementing the model on specialized hardware for real-time perception and reasoning to help an intelligent device navigate and interact with its environment based on natural language commands.",
+ "actors": [ "user-edge-engineer" ]
+ },
+ {
+ "refId": "uc-security-log-analysis",
+ "name": "Self-hosted security log analysis",
+ "description": "Running a self-hosted instance to analyze internal security logs for anomalies, ensuring that sensitive infrastructure data never leaves the organization's firewall.",
+ "actors": [ "user-security-analyst" ]
+ },
+ {
+ "refId": "uc-local-assistant",
+ "name": "Local personal assistant",
+ "description": "Running a personal assistant locally on a laptop to answer questions or process private information such as emails or calendars without sending data to an external server.",
+ "actors": [ "user-local-ai" ]
+ }
+ ]
+ }
+}
+```
+
+###### Field discussion
+
+* **parties** - Each user is a `persona` party with the `end-user` role. Where applicable, a predefined persona `archetype` (e.g., `developer`, `researcher`) may be used, and the persona's `scope` (`internal`, `external`, or `mixed`) may be provided.
+* **useCases.actors** - There is no expectation that there is a 1:1 correlation between users and use cases. However, every use case should name at least one actor that corresponds to a declared user (party).
+* **useCaseAssertions** - The model `supports` each of the use cases. A component that is the primary capability realizing a use case would instead assert `implements`.
+
+> **Tip**: For use cases that matter for regulatory or risk evaluation, the `mainFlow` steps (each naming its acting party), `exceptions`, and `successCriteria` should be provided so that evaluators can trace exactly who does what with the model.
+
+## Technical limitations
+
+Since ML models are fundamentally probabilistic and operate on pattern recognition from the data they are trained on, they are prone to various technical limitations.
+
+Some of these limitations include:
+
+* **Hallucination & Inaccuracy**: Due to their autoregressive nature, models prioritize generating plausible-sounding text over factual accuracy (a.k.a. "sycophancy").
+* **Context Window Constraints**: Limited memory prevents the model from processing or remembering long, complex interactions or large documents at once.
+* **Reasoning & Math Deficiencies**: They often struggle with complex, multi-step logic and mathematical reasoning.
+* **Knowledge Cutoff**: Models are generally frozen in time, meaning they cannot access real-time information without external retrieval systems.
+* **Opacity** (lack of traceable reasoning): models' complex architectures make it difficult to trace how a specific output was generated.
+* **Probabilistic Output Inconsistency**: The same prompt can yield different results (e.g., using different seeds or system context carryover), causing reliability issues.
+* **Bias Reinforcement**: Models often replicate or amplify biases present in their training data. This has become more problematic as reliance on synthetic training data has increased.
+
+Technical limitations are provided in the model's `modelProperties.limitations` array. Limitations that expose users or other parties to potential harm should *also* be documented as risks (see [Ethical considerations](#ethical-considerations)).
+
+###### Example: Sample technical limitations for Qwen-7B
+
+This example shows a list of technical limitations that might be associated with a typical multi-lingual, code-/instruction-capable Large Language Model (LLM) with a similar parameter size.
+
+```json
+{
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "modelProperties": {
+ // ...,
+ "limitations": [
+ "Greedy Decoding Degradation. The model is optimized for sampling-based generation. Using greedy decoding (temperature=0) can lead to performance degradation, repetitive loops, and \"stuck\" reasoning steps, particularly in the new Thinking Mode",
+ "Native Context Window Boundaries. While the model supports up to 131,072 tokens using YaRN scaling, its native pre-training context is limited to 32,768 tokens. Performance may degrade on very long sequences if proper scaling factors (like RoPE or YaRN) are not manually configured for local deployments.",
+ "Synthetic Data \"Sanding\" Effects. Research indicates that Qwen, like many models trained on massive synthetic datasets, can suffer from \"model collapse\" where rare edge cases or minority user behaviors are underrepresented, potentially leading to errors in complex, real-world production environments.",
+ "Thinking Mode History Overhead. In multi-turn conversations, including the model's internal \"thinking\" steps in the chat history can confuse the model and consume unnecessary tokens. Best practices require developers to filter out \"thinking\" content from the history to maintain coherence."
+ ]
+ }
+}
+```
+
+## Performance Tradeoffs
+
+When creating Machine Learning (ML) models, developers must navigate several core performance tradeoffs to align model capabilities with business needs and technical constraints.
+
+Some of these tradeoff considerations include:
+
+* **Accuracy vs. Interpretability**: Complex models often provide higher accuracy but are "black boxes," making them hard to interpret. Simpler models are easy to explain but may not capture complex patterns, sacrificing performance for transparency.
+* **Accuracy vs. Speed/Latency**: Highly accurate models often require significant computation, leading to slower inference times. In production, a slightly less accurate model that responds in milliseconds is frequently preferred over a highly accurate model that takes seconds.
+* **Bias vs. Variance** (Generalization): Highly flexible models (low bias) can overfit to training data, leading to high variance and poor performance on new data. Conversely, simpler models (high bias) may underfit, missing patterns altogether.
+* **Complexity vs. Resource Constraints** (Cost): Larger, more complex models require more data, training time, and computational power (GPUs/CPUs). Developers must balance the need for model performance against budget, infrastructure, and deployment constraints.
+* **Precision vs. Recall**: For models that perform classification, developers often must choose whether to minimize false positives (high precision) or false negatives (high recall).
+
+CycloneDX 2.0 does not define a dedicated field for performance tradeoffs. Since a tradeoff describes a constraint on accuracy, scalability, or appropriate use, tradeoffs should be included in the model's `modelProperties.limitations` array. A tradeoff whose consequence is significant enough to warrant assessment may instead (or additionally) be modeled as a risk with paired `harm` and `benefit` impacts (see [Fairness assessments](#fairness-assessments)).
+
+
+
+###### Example: Performance tradeoffs for Qwen-7B
+
+This example shows how to provide performance trade-offs for a few acknowledged parameters in the Qwen 7B parameter model.
+
+```json
+{
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B",
+ // ...,
+ "modelProperties": {
+ // ...,
+ "limitations": [
+ // ...,
+ "Performance tradeoff: Intelligence Plateau in Domain-Specific Tasks. Research indicates that for specialized fields like legal text analysis, performance often flattens beyond the 7B parameter mark. While efficient, the 7B model may not offer the incremental reasoning gains found in the 32B or 235B models for complex, high-stakes domain reasoning.",
+ "Performance tradeoff: Enhanced Quantization Sensitivity. The Qwen-7B employs advanced pre-training techniques that reduce parameter redundancy. A documented tradeoff of this efficiency is a higher sensitivity to low-bit quantization (3-bit and below), where it exhibits more pronounced performance degradation compared to previous 7B generations.",
+ "Performance tradeoff: Context Window Consistency. While the 7B model supports a native context window of 32,768 tokens, its performance degrades significantly more than the Qwen-8B (which uses YaRN scaling to reach 128K+) when handling massive document sets. Users must tradeoff deep long-document comprehension for the 7B's lower memory footprint.",
+ "Performance tradeoff: Conciseness vs. Contextual Nuance. Experiments show that the older 7B design prioritizes cleaner, easier-to-read, and more concise outputs. The tradeoff is a loss of the \"faithful and nuanced\" insights and richer context provided by the newer 8B and larger architectures.",
+ "Performance tradeoff: Agentic Capability Limitations. The 7B model shows a documented gap in its ability to follow complex multi-step instructions or navigate large software repositories, requiring tighter chunking and more finely tuned prompts to be effective",
+ "Performance tradeoff: Hardware Efficiency vs. Throughput. Running the 7B model on older hardware (e.g., 8GB VRAM cards) is possible but results in a tradeoff of throughput. Modern inference techniques like continuous batching and PagedAttention are less effective at this scale than on the larger, more parallelizable MoE models.",
+ "Performance tradeoff: Decoding Strategy Rigidity. The 7B model is highly sensitive to sampling parameters; specifically, using greedy decoding (temperature=0) can lead to severe repetition loops and \"endless repetitions\". To maintain performance, users must tradeoff predictability for more complex sampling-based generation."
+ ]
+ }
+}
+```
+
+###### Field discussion
+
+* **limitations** - Prefixing each entry with "Performance tradeoff:" allows tradeoffs to be distinguished from other technical limitations.
+
+## Ethical considerations
+
+In CycloneDX 2.0, known ethical considerations are declared as *risks* in the BOM's top-level `risks` object. This turns each design-time consideration into an acknowledged, referenceable risk attached to the model. Each risk includes:
+
+* **refId**, **name**, and **statement** (required) - A concise name, and a statement that reads as *source → event → impact*.
+* **domains** - The risk domains, such as `ethical`, `fairness`, `societal`, `privacy`, `security`, `safety`, `environmental`, `human-rights`, or `legal`.
+* **affects** - References to what the risk applies to: the model component's `refId` and, where relevant, parties (e.g., groups at risk).
+* **inherentRisk** - An optional rating including the `likelihood` and graded `impacts` (each a `harm` or `benefit`, with a `level` from `negligible` to `catastrophic` and impact `categories`).
+* **responses** - The mitigations, each with a `strategy` (e.g., `reduce`, `avoid`, `share`, `accept`, or `enhance` for benefits) and a `description`.
+* **status** - `identified`, `assessed`, `treated`, `monitored`, or `retired`.
+
+> **Note**: Separating the risk `name` from its `statement` removes the 1.7 practice of overloading the `name` field to describe the consideration.
+
+###### Example: Qwen-7B ethical considerations
+
+Based on technical reports and safety evaluations such as Qwen3Guard, the following ethical considerations and mitigations are documented and typical of a multi-lingual LLM of similar parameter size and with a dense architecture:
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9",
+ "name": "Qwen/Qwen-7B"
+ // ...
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ],
+ "risks": {
+ "risks": [
+ {
+ "refId": "risk-bias",
+ "name": "Algorithmic and Cultural Bias",
+ "statement": "Training on trillions of tokens across many languages → the model reflects societal biases and stereotypes present in its training data → representational harm to affected groups.",
+ "domains": [ { "type": "ethical" }, { "type": "fairness" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-bias-detection",
+ "strategy": "reduce",
+ "description": "Use the Qwen-Gender framework or Chain-of-Thought (CoT) prompting to detect and reduce implicit biases in generated text."
+ }
+ ]
+ },
+ {
+ "refId": "risk-jailbreak",
+ "name": "Vulnerability to Adversarial Attacks (Jailbreaking)",
+ "statement": "Despite safety tuning, users craft adversarial prompts (\"Prompt Hacking\" or \"Jailbreaking\") → safety constraints are bypassed → the model generates toxic or illegal content.",
+ "domains": [ { "type": "ethical" }, { "type": "security" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-guard-filter",
+ "strategy": "reduce",
+ "description": "Implement Qwen3Guard as an input/output filter to classify and block unsafe queries or responses in real-time."
+ }
+ ]
+ },
+ {
+ "refId": "risk-hallucination",
+ "name": "Misinformation or Hallucinations",
+ "statement": "Probabilistic generation without grounding → the model fabricates false or misleading information, especially regarding sensitive topics like government actions or historical events → users are misinformed.",
+ "domains": [ { "type": "ethical" }, { "type": "societal" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-rag-grounding",
+ "strategy": "reduce",
+ "description": "Explicitly instruct the model to \"Prioritize Safety\" in the prompt and use Retrieval-Augmented Generation (RAG) to ground responses in verified external documents."
+ }
+ ]
+ },
+ {
+ "refId": "risk-pii-leakage",
+ "name": "Privacy, Sensitive or Personally Identifiable Information (PII) Content Leakage",
+ "statement": "Sensitive or personally identifiable data present in the pre-training corpus → the model reproduces such data in its outputs → privacy violation.",
+ "domains": [ { "type": "ethical" }, { "type": "privacy" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-local-deploy-pii-scrub",
+ "strategy": "reduce",
+ "description": "Deploy the model locally using tools like Ollama to ensure sensitive data stays within a secure environment, and apply regex-based PII scrubbing to outputs."
+ }
+ ]
+ },
+ {
+ "refId": "risk-inference-energy",
+ "name": "Environmental Impact (Inference Energy)",
+ "statement": "Continuous large-scale deployment of even mid-sized models like the 7B → significant energy consumption → increased carbon footprint.",
+ "domains": [ { "type": "ethical" }, { "type": "environmental" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-quantize-efficient-inference",
+ "strategy": "reduce",
+ "description": "Utilize 4-bit quantization and low-latency inference engines to reduce the FLOPs required per token, minimizing the power draw per query."
+ }
+ ]
+ },
+ {
+ "refId": "risk-instruction-misalignment",
+ "name": "Instruction Misalignment",
+ "statement": "In-context learning → \"emergent misalignment\" where the model prioritizes following a user's conversational style → established safety boundaries are not respected.",
+ "domains": [ { "type": "ethical" }, { "type": "safety" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" ],
+ "status": "identified",
+ "responses": [
+ {
+ "refId": "resp-system-prompt-hard-switch",
+ "strategy": "reduce",
+ "description": "Standardize output formats using system prompts and utilize the \"hard switch\" to disable the model's internal thinking mode when maximum safety and predictability are required."
+ }
+ ]
+ }
+ // ...
+ ]
+ }
+}
+```
+
+###### Field discussion
+
+* **affects** - Each risk references the model component by its `refId`, so that tools can find all of the risks attributed to a given model.
+* **domains** - Every ethical consideration carries the `ethical` domain, with an additional domain (e.g., `privacy`, `security`, `environmental`) to further qualify it.
+* **status** - The value `identified` reflects that the risks are documented by the provider at design time, and that the responses are the provider's recommended mitigations. Deployers that implement and verify a mitigation may update a risk's status (e.g., to `treated`) and rate the remaining (`residualRisk`) for their system.
+* **inherentRisk** - Omitted in this example since the source documentation does not grade the risks. Where an assessment has been performed, providers should include a rating with graded `impacts` (see the next section).
+
+## Fairness assessments
+
+Fairness assessments convey information about the benefits and harms of the model to an identified at-risk group. They involve measuring how models treat different social groups to ensure they do not perpetuate or amplify harmful social biases.
+
+For Large Language Models (LLMs), like Qwen, Mistral, or GPT, etc., assessments typically evaluate the model focusing on its training data, internal probabilities (weights and biases), and final generated text using metrics that can be statistically analyzed.
+
+Assessments consider evaluations at all stages of the model development lifecycle, including:
+
+* **Data Bias Auditing** (Pre-processing): Analyzing training datasets for under-represented groups, improper labeling, or historical biases that could cause discriminatory outcomes.
+* **Disaggregated Performance Metrics** (Measurement): Evaluating model performance (e.g., accuracy, false positives/negatives) across different demographic groups (e.g., race, gender) to identify, for example, higher error rates for certain populations.
+* **Impact Assessments** (Contextual): Assessing how AI systems affect specific groups of people, identifying potential harms to rights, safety, or livelihoods, which is a key requirement for high-risk AI under the EU AI Act.
+* **Adversarial Testing** (Verification): Intentionally challenging the AI model with edge cases to uncover hidden biases or vulnerabilities.
+* **Algorithmic Fairness Interventions** (In-processing/Post-processing): Implementing technical solutions to correct identified disparities, such as modifying the model architecture during training or adjusting output thresholds to ensure fair decision-making.
+
+In CycloneDX 2.0, each fairness assessment is declared as a risk with the `fairness` domain, mapped from its 1.7 form as follows:
+
+| CycloneDX 1.7 `fairnessAssessments` field | CycloneDX 2.0 |
+|---|---|
+| `groupAtRisk` | A `persona` party (with a custom `affected-group` role) referenced from the risk's `affects` |
+| `harms` | An `inherentRisk.impacts` entry with `polarity` `harm`, a `level`, `categories`, and the 1.7 text as its `description` |
+| `benefits` | An `inherentRisk.impacts` entry with `polarity` `benefit`, a `level`, `categories`, and the 1.7 text as its `description` |
+| `mitigationStrategy` | `responses` entries (`reduce` for harms, `enhance` for benefits) |
+
+Disaggregated performance metrics that substantiate a fairness assessment can be provided as performance metrics (with a `slice` naming the group) in the model's `measurements` (see [Performance metrics](0x23-Design-Model-Card-Quantitative-Analysis.md#performance-metrics)).
+
+###### Example: LLM fairness assessment for Qwen-7B
+
+This example shows how fairness assessment information would be included in a CycloneDX AI/ML-BOM.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ // ...,
+ "definitions": {
+ "parties": [
+ {
+ "refId": "group-protected-characteristics",
+ "roles": [ { "name": "affected-group", "description": "A group of people at risk of being systematically disadvantaged by the model." } ],
+ "persona": {
+ "label": "People identified by protected characteristics",
+ "description": "People identified by characteristics such as race, gender, and disability status."
+ }
+ },
+ {
+ "refId": "group-other-language-speakers",
+ "roles": [ { "name": "affected-group" } ],
+ "persona": {
+ "label": "Non-English/Non-Chinese speakers",
+ "description": "Non-English/Non-Chinese speakers, speakers of regional dialects or specific geographic regions (e.g., Southeast Asia or the Middle East) on thinking or \"reasoning\" tasks."
+ }
+ }
+ ]
+ },
+ "risks": {
+ "risks": [
+ {
+ "refId": "risk-fairness-discriminatory-outcomes",
+ "name": "Discriminatory outcomes across protected characteristics",
+ "statement": "Biases in training data → the model produces discriminatory outcomes across protected characteristics in task assignment scenarios → individuals in the affected groups are unfairly labeled or treated.",
+ "domains": [ { "type": "fairness" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9", "group-protected-characteristics" ],
+ "status": "assessed",
+ "inherentRisk": {
+ "impacts": [
+ {
+ "polarity": "harm",
+ "level": "major",
+ "categories": [ "discrimination" ],
+ "description": "The model was found to produce discriminatory outcomes across protected characteristics, including race, gender, and disability status. For example, individuals categorized as \"gypsy\" or \"mute\" were incorrectly labeled as untrustworthy in task assignment scenarios."
+ }
+ ]
+ },
+ "responses": [
+ {
+ "refId": "resp-rlaif-alignment",
+ "strategy": "reduce",
+ "description": "Researchers recommend using Reinforcement Learning from Artificial Intelligence Feedback (RLAIF) and rule-based rewards to align the model with specific legal standards like the EU AI Act."
+ }
+ ]
+ },
+ {
+ "refId": "risk-fairness-quality-of-service",
+ "name": "Quality-of-service disparity across languages",
+ "statement": "Reasoning capabilities trained predominantly on English and Mandarin data → oversimplified, factually incorrect, or hallucinated responses in other supported languages → lower quality of service for speakers of those languages.",
+ "domains": [ { "type": "fairness" } ],
+ "affects": [ "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9", "group-other-language-speakers" ],
+ "status": "assessed",
+ "inherentRisk": {
+ "impacts": [
+ {
+ "polarity": "harm",
+ "level": "moderate",
+ "categories": [ "fairness" ],
+ "description": "Quality-of-Service Harm: The model may provide high-quality, nuanced reasoning in English or Mandarin but offer oversimplified, factually incorrect, or \"hallucinated\" information when queried in other supported languages."
+ }
+ ]
+ },
+ "responses": [
+ {
+ "refId": "resp-cross-lingual-sft",
+ "strategy": "reduce",
+ "description": "Cross-Lingual Alignment: Developers can use multilingual Supervised Fine-Tuning (SFT), training on additional high-quality, parallel corpora from other languages on \"reasoning capabilities\" (e.g., logic, math, coding)."
+ }
+ ]
+ }
+ // ...
+ ]
+ }
+}
+```
+
+###### Field discussion
+
+* **parties** - Each group at risk becomes a referenceable `persona` party, so the same group can be linked to multiple risks, use cases, and assessments. CycloneDX does not predefine an "affected group" role, so a custom role (with a `name` and `description`) is used.
+* **affects** - Lists both the model and the party at risk.
+* **impacts** - Each harm (or benefit) is graded with a `level` (`negligible`, `low`, `moderate`, `major`, or `catastrophic`) and one or more impact `categories` (e.g., `discrimination`, `fairness`, `human-rights`, `societal`, `psychological`). The levels shown in this example are illustrative; providers should assign levels based on their own assessments.
+* **benefits** - Where a model provides a benefit to the same group (e.g., faster, more accessible answers), it should be declared as an additional impact with `polarity` `benefit`, and any response that increases the benefit should use the `enhance` strategy.
+
+> **Tip**: Beyond design time, the `risks` object also supports `assessments` (e.g., a periodic AI impact assessment by a named assessor party), `riskAppetites`, and `residualRisk` and `targetRisk` ratings, allowing deployers to score these risks for their own systems and use cases.
+
+## Environmental considerations
+
+### Energy consumptions
+
+This section describes how model providers can publish the energy costs incurred at different stages of the model's lifecycle to address potential regulatory requirements. This information includes the energy sources (i.e., for the datacenters) as well as disclosure of CO2 emission cost equivalents and CO2 offsets (credits).
+
+The intent is for CycloneDX to be able to support the general requirements referenced by the [EU’s AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng), which refers to ‘environmental protection’ in its subject matter.
+
+Summary of EU AI Act Environmental Disclosure Rules for GPAI Models:
+
+* **Requirement**: Providers of General-Purpose AI (GPAI) models must disclose the known or estimated energy consumption used during their model's development.
+ * *This information is provided only upon request to the EU's AI Office and national competent authorities.*
+* **Reference**: These requirements are outlined in [Article 53](https://artificialintelligenceact.eu/article/53/) and [Annex XI](https://artificialintelligenceact.eu/annex/11/) of the [EU AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng).
+* **Exemption**: Models released under a free and open-source license are exempt from this disclosure obligation.
+
+> **Note**: Since most trained models are published under some form of open license, most providers do not currently disclose the costs of training their models.
+
+In CycloneDX 2.0, energy consumption is declared as an entry in the model component's `measurements` array (alongside its performance metrics). Each energy consumption entry consists of the following, which are explained in more detail below:
+
+* **Activity** (required): The type of activity that was part of the ML model development or operational lifecycle with an associated energy cost.
+
+ | Value | Description |
+ |---|---|
+ | **design** | A model design including problem framing, goal definition and algorithm selection.|
+ | **data-collection** |Model data acquisition including search, selection and transfer.|
+ | **data-preparation** | Model data preparation including data cleaning, labeling and conversion. |
+ | **training** | Model building, training and generalized tuning. |
+ | **fine-tuning** | Refining a trained model to produce desired outputs for a given problem space. |
+ | **validation** | Model validation including model output evaluation and testing. |
+ | **deployment** | Explicit model deployment to a target hosting infrastructure. |
+ | **operation** | Ongoing operation of a deployed model (e.g., hosting). |
+ | **inference** | Generating an output response from a hosted model from a set of inputs. |
+ | **end-of-life** | Decommissioning or retirement of the model. |
+
+ The values `manufacturing` and `transport` are also defined for physical components. An activity whose description does not match the predefined values can be provided as a custom activity object with a `name` and `description` (this replaces the 1.7 value `other`).
+
+* **Description**: An optional description of the activity's energy consumption.
+
+* **Formula**: An optional reference to the `formulation` formula describing the activity (e.g., the training workflow).
+
+* **Energy providers**: The provider(s) of the energy consumed by the associated model development lifecycle activity. Each entry includes the following fields:
+ * **description**: A description of the energy provider.
+ * **provider** (required): The party (e.g., `organization`) that provides the energy, which may include its name, addresses, URLs and identifiers. In 1.7, this was the `organization` field.
+ * **energySource** (required): A value that is one of `coal`, `oil`, `natural-gas`, `nuclear`, `wind`, `solar`, `geothermal`, `hydropower`, `biofuel`, `biomass`, `hydrogen`, `tidal`, `unknown`, or a custom energy source.
+ * **energyProvided** (required): The energy provided by the energy source for an associated activity using Kilowatt-hours (kWh).
+ * **externalReferences**: Optional references (links) to the energy provider.
+
+* **Activity energy cost** (required): The total energy cost associated with the model lifecycle activity using Kilowatt-hours (kWh).
+
+* **CO2 cost equivalent**: The CO2 cost (debit) equivalent to the total energy cost using tonnes of Carbon Dioxide (CO2) equivalent (tCO2eq).
+
+* **CO2 cost offset**: The CO2 offset (credit) for the CO2 equivalent cost using tonnes of Carbon Dioxide (CO2) equivalent (tCO2eq).
+
+###### Example: "Fake" llama3 environmental considerations
+
+This example is for a "fake" model based upon the llama3 architecture.
+
+```json
+{
+ "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json",
+ "specFormat": "CycloneDX",
+ "specVersion": "2.0",
+ "serialNumber": "urn:uuid:ed5c5ba0-2be6-4b58-ac29-01a7fd375123",
+ "version": 1,
+ "inventories": [
+ {
+ "subject": {
+ "type": "machine-learning-model",
+ "refId": "pkg:huggingface/FakeAI/Llama3@abcd123",
+ "name": "FakeAI/Llama3",
+ // ...,
+ "measurements": [
+ {
+ "activity": "training",
+ "energyProviders": [
+ {
+ "description": "Meta data-center, US-East",
+ "provider": {
+ "roles": [ { "role": "supplier" } ],
+ "organization": {
+ "name": "Fake.ai",
+ "addresses": [
+ {
+ "country": "United States",
+ "region": "New Jersey",
+ "locality": "Newark"
+ }
+ ]
+ }
+ },
+ "energySource": "natural-gas",
+ "energyProvided": {
+ "value": 0.4,
+ "unit": "kWh"
+ }
+ }
+ ],
+ "activityEnergyCost": {
+ "value": 0.4,
+ "unit": "kWh"
+ },
+ "co2CostEquivalent": {
+ "value": 31.22,
+ "unit": "tCO2eq"
+ },
+ "co2CostOffset": {
+ "value": 31.22,
+ "unit": "tCO2eq"
+ }
+ }
+ ]
+ },
+ "components": [
+ // ...
+ ]
+ }
+ ]
+}
+```
+
+###### Field discussion
+
+* **provider** - The energy provider is a CycloneDX party, which requires at least one role; the `supplier` role is used for the organization that supplies the energy.
+* **addresses** - A party organization may have multiple postal addresses (in 1.7, `address` was a single object).
+* **unit** - the unit `tCO2eq` is defined by the European Commission and stands for metric tonnes of carbon dioxide equivalent, a standardized unit used to measure the total greenhouse gas emissions (including methane and nitrous oxide) generated during the development, training, and operation of AI systems.
+
+
diff --git a/ML-BOM/2.0/en/0x40-Design-Additional-Model-Information.md b/ML-BOM/2.0/en/0x40-Design-Additional-Model-Information.md
new file mode 100644
index 00000000..6a22e971
--- /dev/null
+++ b/ML-BOM/2.0/en/0x40-Design-Additional-Model-Information.md
@@ -0,0 +1,460 @@
+# Additional model-related information
+
+This section describes the design and best practices when providing other model-related information for an ML model's component within a CycloneDX AI/ML-BOM.
+
+Currently, the v2.0 CycloneDX specification may not have specific objects or fields to document certain types of information directly. However, these sections will show how CycloneDX extension mechanisms, such as `properties`, `tags`, and `externalReferences`, can be used to provide and classify such additional ML-related information.
+
+For convenience, here are links to the specific sections for some of these acknowledged informational areas:
+
+* [Using CycloneDX AI/ML properties](#using-cyclonedx-aiml-properties)
+ * [Declaring a model's modalities](#declaring-a-models-modalities)
+ * [Annotating a model's supported languages](#annotating-a-models-supported-languages)
+ * [Providing free-form tags for search](#providing-free-form-tags-for-search)
+ * [Providing a model's usage policy](#providing-a-models-usage-policy)
+* [Tokenizers and prompt templates](#tokenizers-and-prompt-templates)
+* [Including manufacturing information for the ML model](#including-manufacturing-information-for-the-ml-model)
+ * [Declaring hardware and software training components](#declaring-hardware-and-software-training-components)
+ * [Providing training workflow details](#providing-training-workflow-details)
+ * [Declaring the runtime topology](#declaring-the-runtime-topology)
+
+## Using CycloneDX AI/ML properties
+
+This section includes discussion and examples of supported AI/ML-related metadata properties that can be used to classify models in their AI/ML-BOM. This method utilizes reserved [AI/ML property names](https://github.com/CycloneDX/cyclonedx-property-taxonomy/blob/main/cdx/ai-ml.md) registered under the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy).
+
+> **Note**: The CycloneDX schema is standardized through Ecma International (and ISO) and changes on its ratification cycle, whereas new names and values can be registered in the property taxonomy at any time. Properties therefore allow AI/ML-BOMs to keep pace with new AI/ML concepts without waiting for a schema revision. Names that are not (yet) registered may be declared using the `_undefined:CycloneDX enables various methods of conveying non-normative and legal information. Primarily, this is accomplished via `externalReferences`, component `properties`, as well as through explicit `licenses` objects and `copyright` fields. | +| 1.(d) | draw up and make publicly available a sufficiently detailed summary about the content used for training of the general-purpose AI model, according to a template provided by the AI Office. | The model component's `modelProperties` allows for a description of the model's training [Learning types](0x22-Design-Model-Card-Parameters.md#learning-types) and references to its training datasets (`training.datasets`).**Note**: CycloneDX, as a Bills-of-Materials standard, accounts for each dataset as its own, fully described, component. See [Declaring Datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets). | +| 2. | The obligations set out in paragraph 1, points (a) and (b), shall not apply to providers of AI models that are released under a free and open-source licence that allows for the access, usage, modification, and distribution of the model, and whose parameters, including the weights, the information on the model architecture, and the information on model usage, are made publicly available. This exception shall not apply to general-purpose AI models with systemic risks. | *N/A* | +| 3. | Providers of general-purpose AI models shall cooperate as necessary with the Commission and the national competent authorities in the exercise of their competences and powers pursuant to this Regulation. | *N/A* | +| 4. | Providers of general-purpose AI models may rely on codes of practice within the meaning of [Article 56](https://artificialintelligenceact.eu/article/56/) to demonstrate compliance with the obligations set out in paragraph 1 of this Article, until a harmonised standard is published. Compliance with European harmonised standards grants providers the presumption of conformity to the extent that those standards cover those obligations. Providers of general-purpose AI models who do not adhere to an approved code of practice or do not comply with a European harmonised standard shall demonstrate alternative adequate means of compliance for assessment by the Commission. | Article 56 references new "Codes of Practice" that provide:• a means to ensure that the information, referred to in Article 53, is kept up to date.• an adequate level of detail for the summary about the content used for training;• identification of the type and nature of the systemic risks at Union level, including their sources, where appropriate;• measures, procedures and modalities for the assessment and management of the systemic risks at Union level, including the documentation thereof, which shall be proportionate to the risks.
Future guide revisions will provide updates as these codes are developed to facilitate CycloneDX compliance. | +| 5. | For the purpose of facilitating compliance with [Annex XI](https://artificialintelligenceact.eu/annex/11/), in particular points 2 (d) and (e) thereof, the Commission is empowered to adopt delegated acts in accordance with [Article 97](https://artificialintelligenceact.eu/article/97/) to detail measurement and calculation methodologies with a view to allowing for comparable and verifiable documentation. | In short, Article 97 provides for *"The power to adopt delegated acts is conferred on the Commission subject to the conditions laid down in this Article.* which would *"enter into force upon only if no objection has been expressed by either the European Parliament or the Council within a period of three months of notification*.
As any additional "delegated acts" are developed, future revisions of this guide will provide updates to facilitate compliance using CycloneDX.| +| 6. | The Commission is empowered to adopt delegated acts in accordance with [Article 97](https://artificialintelligenceact.eu/article/97/)(2) to amend [Annexes XI](https://artificialintelligenceact.eu/annex/11) and [XII](https://artificialintelligenceact.eu/annex/12) in light of evolving technological developments. | *See commentary provided to paragraph 5.* | +| 7. | Any information or documentation obtained pursuant to this Article, including trade secrets, shall be treated in accordance with the confidentiality obligations set out in [Article 78](https://artificialintelligenceact.eu/article/78/). | In short, Article 78 provides assurances to providers that their *"the intellectual property rights and confidential business information or trade secrets of a natural or legal person, including source code"* will remain confidential and protected by law when handled by regulators and officials.
The CycloneDX Bills-of-Materials (BOMs) format can be used to convey any information a provider chooses to encode subject to their legal discretion. | + +--- + +### ANNEX XI: Technical Documentation Referred to in Article 53(1), Point (a) – Technical Documentation for Providers of General-Purpose AI Models + +This section contains mappings for [ANNEX XI: Technical Documentation Referred to in Article 53](https://artificialintelligenceact.eu/annex/11/). + +#### Annex XI mappings + +| Section | Section text | Guide references | Relevant schema (v2.0) | +| --- | --- | --- | --- | +| 1 | Information to be provided by all providers of general-purpose AI models The technical documentation referred to in [Article 53](https://artificialintelligenceact.eu/article/53) (1), point (a) shall contain at least the following information as appropriate to the size and risk profile of the model: | *See details in subsections below* | N/A | +| 1.1 | A general description of the general-purpose AI model including: | CycloneDX describes models as components:• [Declaring ML models](0x20-Design-Model-Component-Metadata.md#declaring-ml-models) | • `inventories[].subject`. ▪ `type`: `"machine-learning-model"` ▪ `name` ▪ `version` ▪ `description` ▪ `parties[]` with `roles` (e.g., `manufacturer`, `supplier`, `publisher`) | +| 1.1.(a) | the tasks that the model is intended to perform and the type and nature of AI systems in which it can be integrated; | Tasks:• [Tasks](0x22-Design-Model-Card-Parameters.md#tasks)Use cases and users:• [Considerations: Users & use cases](0x24-Design-Model-Card-Considerations.md#users--use-cases) | • `inventories[].subject.modelProperties.tasks[]`• `inventories[].subject.parties[]` (e.g., role `end-user`)• `definitions.useCases[]`. ▪ `actors[]` ▪ `mainFlow[]`• `inventories[].subject.useCaseAssertions[]` | +| 1.1.(b) | the acceptable use policies applicable; | Use policies:• [Providing a model's usage policy](0x40-Design-Additional-Model-Information.md#providing-a-models-usage-policy) _- See example for the Qwen model._ | Usage policies can be provided as a CycloneDX external reference.• `inventories[].subject.externalReferences[]`**Note**: multiple references to published usage policies can be provided. | +| 1.1.(c) | the date of release and methods of distribution; | Release information:• [Providing model release notes](0x20-Design-Model-Component-Metadata.md#providing-model-release-notes) | Release dates and methods are provided using the `releaseNotes` fields in the model's component:• `inventories[].subject.releaseNotes`. ▪ `type` ▪ `title` ▪ `description` ▪ `timestamp` ▪ `notes[]` ▪ etc.**Note:** *Release notes may also be declared once in `definitions.releaseNotes[]` and referenced.* | +| 1.1.(d) | the architecture and number of parameters; | Model architecture:• [Architecture](0x22-Design-Model-Card-Parameters.md#architecture)• [Parameter count & quantization](0x22-Design-Model-Card-Parameters.md#parameter-count--quantization) | • `inventories[].subject.modelProperties`. ▪ `architecture`. ▪ `name` ▪ `family` ▪ `features[]` ▪ `topology` ▪ `parameterCount` ▪ `quantization` | +| 1.1.(e) | the modality (e.g. text, image) and format of inputs and outputs; | Modality/modalities:• [Declaring a model's modalities](0x40-Design-Additional-Model-Information.md#declaring-a-models-modalities)Inputs & Outputs• [Inputs & Outputs](0x22-Design-Model-Card-Parameters.md#inputs--outputs) | Inputs & Outputs:• `inventories[].subject.modelProperties`. ▪ `inputs[]` (`modality`, `dataType`, `mimeType`, `shape`, etc.) ▪ `outputs[]`Modality/modalities:• `inventories[].subject.properties[]` (`cdx:ai-ml:model:modality`) | +| 1.1.(f) | the licence. | Component license:• [Describing models as components](0x20-Design-Model-Component-Metadata.md#describing-models-as-components) ▪ _See [Example: Declaring an ML model in an AI/ML-BOM](0x20-Design-Model-Component-Metadata.md#example-declaring-an-ml-model-in-an-aiml-bom) which uses the CycloneDX `license` object._ | CycloneDX provides multiple, robust options for recording license information:• `inventories[].subject.licenses[]` | +| 1.2 | A detailed description of the elements of the model referred to in point 1, and relevant information of the process for the development, including the following elements: | *See details in subsections below* | N/A | +| 1.2.(a) | the technical means (e.g. instructions of use, infrastructure, tools) required for the general-purpose AI model to be integrated in AI systems; | Detailing inference workflows, tasks, steps and resources to be used in testing and production:• [Including manufacturing information for the ML model](0x40-Design-Additional-Model-Information.md#including-manufacturing-information-for-the-ml-model)• [Declaring the runtime topology](0x40-Design-Additional-Model-Information.md#declaring-the-runtime-topology) | Detailed inference and testing workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`**Note**: The CycloneDX `formulation` object can be used to convey `workflows` for such things as `inference` in the context of various target frameworks or their runtime topologies. | +| 1.2.(b) | the design specifications of the model and training process, including training methodologies and techniques, the key design choices including the rationale and assumptions made; what the model is designed to optimise for and the relevance of the different parameters, as applicable; | Considerations when designing the model:• [Learning types](0x22-Design-Model-Card-Parameters.md#learning-types)• [Technical limitations](0x24-Design-Model-Card-Considerations.md#technical-limitations)• [Performance tradeoffs](0x24-Design-Model-Card-Considerations.md#performance-tradeoffs)• [Ethical considerations](0x24-Design-Model-Card-Considerations.md#ethical-considerations)Describing design, data preparation and training workflows along with detailed tasks, steps and resources:• [Including manufacturing information for the ML model](0x40-Design-Additional-Model-Information.md#including-manufacturing-information-for-the-ml-model)• [Declaring hardware and software training components](0x40-Design-Additional-Model-Information.md#declaring-hardware-and-software-training-components) ▪ [Providing training workflow details](0x40-Design-Additional-Model-Information.md#providing-training-workflow-details) ▪ [Declaring the runtime topology](0x40-Design-Additional-Model-Information.md#declaring-the-runtime-topology) | Considerations:• `inventories[].subject.modelProperties`. ▪ `learningTypes[]` ▪ `limitations[]` ▪ `training.formula`• `risks.risks[]` (affecting the model)Detailed workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`**Note**: CycloneDX 2.0 formulation `taskTypes` do not (yet) include AI/ML-specific values such as `training` or `fine-tuning`; the `build` task type is used for model training in this guide. | +| 1.2.(c) | information on the data used for training, testing and validation, where applicable, including the type and provenance of data and curation methodologies (e.g. cleaning, filtering, etc.), the number of data points, their scope and main characteristics; how the data was obtained and selected as well as all other measures to detect the unsuitability of data sources and methods to detect identifiable biases, where applicable; | Data or dataset declaration, provenance and pedigree:• [Datasets](0x22-Design-Model-Card-Parameters.md#datasets) ▪ [Declaring datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets) ▪ [Datasets with minimal information](0x22-Design-Model-Card-Parameters.md#datasets-with-minimal-information) ▪ [Datasets as fully described data components](0x22-Design-Model-Card-Parameters.md#datasets-as-fully-described-data-components) | Training dataset references:• `inventories[].subject.modelProperties.training.datasets[]`Dataset components:• `component` (in `inventories[].components[]` or `definitions.components[]`) ▪ `type`: `"data"` ▪ `name` ▪ `description` ▪ `identifiers[]` ▪ `data[]` (`type`: `"dataset"`, `contents`, `classification`, `governance`) ▪ `pedigree` ▪ `externalReferences[]` ▪ `properties[]` ▪ etc.Detailed data preparation workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]` | +| 1.2.(d) | the computational resources used to train the model (e.g. number of floating point operations), training time, and other relevant details related to the training; | Detailing training workflows, tasks, steps and resources:• [Including manufacturing information for the ML model](0x40-Design-Additional-Model-Information.md#including-manufacturing-information-for-the-ml-model) ▪ [Declaring hardware and software training components](0x40-Design-Additional-Model-Information.md#declaring-hardware-and-software-training-components) ▪ [Providing training workflow details](0x40-Design-Additional-Model-Information.md#providing-training-workflow-details) ▪ [Declaring the runtime topology](0x40-Design-Additional-Model-Information.md#declaring-the-runtime-topology) | Detailed training workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`• `inventories[].subject.modelProperties.training.formula` (reference to the training formula)**Note**: CycloneDX 2.0 formulation `taskTypes` do not (yet) include AI/ML-specific values such as `training` or `fine-tuning`; the `build` task type is used for model training in this guide. | +| 1.2.(e) | known or estimated energy consumption of the model. With regard to point (e), where the energy consumption of the model is unknown, the energy consumption may be based on information about computational resources used. | Per-activity energy consumptions, energy provider information, CO2 costs and CO2 cost offsets:• [Energy Consumptions](0x24-Design-Model-Card-Considerations.md#energy-consumptions) | • `inventories[].subject.measurements[]` (energy consumption entries) ▪ `activity` ▪ `energyProviders[]` ▪ `activityEnergyCost` ▪ `co2CostEquivalent` ▪ `co2CostOffset`**Note**: _Energy consumptions can be reported on a per-activity basis (e.g., `data-collection`, `training`, `fine-tuning`, etc.) and can reference the declared workflows via `formula`._ | +| 2 | Additional information to be provided by providers of general-purpose AI models with systemic risk | *See details in subsections below* | N/A | +| 2.1 | A detailed description of the evaluation strategies, including evaluation results, on the basis of available public evaluation protocols and tools or otherwise of other evaluation methodologies. Evaluation strategies shall include evaluation criteria, metrics and the methodology on the identification of limitations. | Describing and recording results for performance (evaluation) tests:• [Model quantitative analysis](0x23-Design-Model-Card-Quantitative-Analysis.md#model-quantitative-analysis) ▪ [Performance Metrics](0x23-Design-Model-Card-Quantitative-Analysis.md#performance-metrics) ▪ [Graphics](0x23-Design-Model-Card-Quantitative-Analysis.md#graphics) | • `inventories[].subject.measurements[]` (performance metric entries) ▪ `type` ▪ `benchmark` ▪ `measure` ▪ `slice` ▪ `confidenceInterval` ▪ `evaluationDatasets[]` ▪ `graphics[]`• `definitions.graphics[]`**Note:** Evaluation processes can be encoded as `formulation` `workflows`, and their compositional `tasks`, `steps`, `inputs`, `outputs` and more. | +| 2.2 | Where applicable, a detailed description of the measures put in place for the purpose of conducting internal and/or external adversarial testing (e.g. red teaming), model adaptations, including alignment and fine-tuning. | "Ethical considerations" and "Fairness assessments" can be documented as risks as shown in these sections:• [Ethical considerations](0x24-Design-Model-Card-Considerations.md#ethical-considerations)• [Fairness assessments](0x24-Design-Model-Card-Considerations.md#fairness-assessments)Model adaptations (e.g., fine-tuning) are described by the model's pedigree and training workflows:• [Declaring a model's pedigree](0x20-Design-Model-Component-Metadata.md#declaring-a-models-pedigree)• [Providing training workflow details](0x40-Design-Additional-Model-Information.md#providing-training-workflow-details) | • `risks`. ▪ `risks[]` (`domains`, `affects`, `inherentRisk`, `residualRisk`, `responses`) ▪ `assessments[]` (e.g., red teaming or AI impact assessments, with assessor parties)• `definitions.parties[]` (personas for groups at risk)• `inventories[].subject.pedigree` | +| 2.3 | Where applicable, a detailed description of the system architecture explaining how software components build or feed into each other and integrate into the overall processing. | The composition of model components, including data:• [Declaring ML Models](0x20-Design-Model-Component-Metadata.md#declaring-ml-models) ▪ [Describing models as components](0x20-Design-Model-Component-Metadata.md#describing-models-as-components) ▪ [Model repositories as components](0x20-Design-Model-Component-Metadata.md#model-repositories-as-components) ▪ [Describing a model repository as a CycloneDX assembly](0x20-Design-Model-Component-Metadata.md#describing-a-model-repository-as-a-cyclonedx-assembly) | Component and service relationships:• `compositions[]` (completeness of nested relationships) ▪ `kind`: `"components"` or `"dependencies"` ▪ `aggregate` ▪ `targets[]`Hierarchical (nested) relationships (for assemblies):• `inventories[].components[]`• `components[].components[]`Direct dependencies:• `dependencies[]` (`ref`, `dependsOn`, `provides`)Process and data flows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`**Note**: _When models are incorporated into hardware and software systems (including as components of type `service`), CycloneDX supports declaring full dependency relationships as well as detailing service and data processing workflows. CycloneDX 2.0 `blueprints` can further describe system architecture, data flows, and trust zones._ | + +--- + +### Annex: Template for the Public Summary of Training Content for General-Purpose AI models required by Article 53 + +This section provides mappings for the _"Explanatory Notice"_ and _"Template for the Public Summary of Training Content"_ which seek to address relevant legal text from [Article 53](https://artificialintelligenceact.eu/article/53/)(1)(d) of the AI Act: + +_Providers of general-purpose AI models shall […] draw up and make publicly available a sufficiently detailed summary about the content used for training of the general-purpose AI model, according to a template provided by the AI Office._ + +As well as [Recital 107](https://artificialintelligenceact.eu/recital/107/) of the AI Act: + +_In order to increase transparency on the data that is used in the pre-training and training of general-purpose AI models, including text and data protected by copyright law, it is adequate that providers of such models draw up and make publicly available a sufficiently detailed summary of the content used for training the general-purpose AI model._ + +#### Template mapping notes + +Subsections under Section 2, _"Lists of data sources"_, require similar information about data or datasets and their collection processes using different techniques and from different sources. Therefore, much of the _"Guide references"_ and _"CycloneDX Commentary"_ text will be similar across the following subsections: + +* 2.1 Publicly available datasets +* 2.2 Private non-publicly available datasets obtained from third parties +* 2.3 Data crawled and scraped from online sources +* 2.4 User data +* 2.5 Synthetic data +* 2.6 Other data sources + +#### Template mappings + +| Section | Text | Guide references | CycloneDX Commentary | +| --- | --- | --- | --- | +| 1. | General information | See [Annex XI mappings](#annex-xi-mappings), Section 1.1• [Declaring ML models](0x20-Design-Model-Component-Metadata.md#declaring-ml-models) | The majority of this information would be provided within the model's CycloneDX component, declared as the `inventories[].subject` of the AI/ML-BOM. | +| 1.1 | Provider identification | See [Annex XI mappings](#annex-xi-mappings), Section 1.1• [Declaring ML models](0x20-Design-Model-Component-Metadata.md#declaring-ml-models) | Manufacturer, supplier and publisher information is provided as parties of the model component, each with the corresponding role:• `inventories[].subject.parties[]` (or `definitions.parties[]`) ▪ `roles[]`: `manufacturer` - _The organization that built or created the model._ ▪ `roles[]`: `supplier` - _The organization that supplied the model for use_ ▪ `roles[]`: `publisher` - _The organization that published the model_ ▪ `roles[]`: `provider`, or a custom role (e.g., _"EU AI Act provider, Art. 3(3)"_) | +| 1.1.(i) | Provider name and contact details | See [template mappings](#template-mappings), Section 1.1 (above) | Each party's `organization` includes:• `name`, `legalName`, `jurisdiction`, `identifiers[]` (e.g., LEI, DUNS, VAT)• `addresses[]` and `url[]`Points-of-contact can be declared as `person` parties (with `email[]` and `phone[]`) having roles such as `legal-contact` or `support-contact`, related to the organization via `relations`. | +| 1.1.(ii) | Authorised representative name and contact details | See [template mappings](#template-mappings), Section 1.1.(i) (above) | An authorised representative can be declared as an additional party with a custom role (e.g., `{ "name": "authorised-representative", "description": "EU AI Act, Art. 54" }`).Each `person` party includes:• `name`, `email[]` and `phone[]` | +| 1.2 | Model identification | A discussion of model identifiers with examples:• [Model identifiers](0x20-Design-Model-Component-Metadata.md#model-identifiers) | The model component's identifiers are asserted by a party and include support for the [Package-URL (PURL) Specification](https://github.com/package-url/purl-spec) which provides syntax for identifying a model from various source repositories:• `inventories[].subject.identifiers[]`. ▪ `party` ▪ `identities[]` (`scheme`: `"purl"`, `value`)**Note**: _In addition, CycloneDX provides predefined (e.g., `model-number`) and custom identity schemes for identifiers from registered proprietary or other publication sources._ | +| 1.2.(i) | Versioned model name(s) | A model's name, identifiers and version are considered unique attributes of the model component. These are provided in the `inventories[].subject` as shown here:• [Describing models as components](0x20-Design-Model-Component-Metadata.md#describing-models-as-components)• [Model identifiers](0x20-Design-Model-Component-Metadata.md#model-identifiers)If a model is derived from another model, that relationship would be described by pedigree:• [Declaring a model's pedigree](0x20-Design-Model-Component-Metadata.md#declaring-a-models-pedigree) | Model name, version and identifiers:• `inventories[].subject`Model pedigree:• `inventories[].subject.pedigree`**Note**: _An AI/ML Bill-of-Materials is intended to represent a single identifiable model. Each separate version published or supplied from a different source, should be represented by its own unique AI/ML-BOM which can capture its pedigree, including any changes from the original model, by reference to its AI/ML-BOM via pedigree fields._ | +| 1.2.(ii) | Model dependencies | Dependencies of a model needs to consider both the datasets used for training and/or finetuning as well as listing dependencies on tokenizers, templates and any configurations. Accounting for these resources are shown in the following sections, respectively:• [Model repositories as components](0x20-Design-Model-Component-Metadata.md#model-repositories-as-components)• [Declaring datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets) ▪ [Datasets as fully described data components](0x22-Design-Model-Card-Parameters.md#datasets-as-fully-described-data-components) | Model component compositions (e.g., datasets, tensor data, tokenizers, configurations, etc.):• `compositions[]` (completeness of nested relationships) ▪ `kind`: `"components"` or `"dependencies"` ▪ `aggregate` ▪ `targets[]`Hierarchical (nested) relationships (for assemblies):• `inventories[].components[]`• `components[].components[]`Direct dependencies:• `dependencies[]` (`ref`, `dependsOn`, `provides`)Explicit declaration of model datasets used (using CycloneDX data component references):• `inventories[].subject.modelProperties.training.datasets[]`Process and data flows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]` | +| 1.2.(iii) | Date of placement of the model on the Union market: | This information would be provided in the model's release notes:• [Providing model release notes](0x20-Design-Model-Component-Metadata.md#providing-model-release-notes) | Release notes:• `inventories[].subject.releaseNotes` | +| 1.3. | Modalities, overall training data size and other characteristic *(general information about the overall training data after pre-processing and before the training of the model)* | *See details in subsections below* | N/A | +| 1.3.(i) | Modality *(e.g., text, image, audio, video, other)* | Model modalities:• [Declaring a model's modalities](0x40-Design-Additional-Model-Information.md#declaring-a-models-modalities)**Note**: *Multi-model models should include modality information for each sub-model.* | Modalities:• `inventories[].subject.properties[]` (`cdx:ai-ml:model:modality`)• `inventories[].subject.modelProperties.inputs[].modality`**Note**: _Utilizes property values defined in the [CycloneDX Property Taxonomy for AI/ML](https://github.com/CycloneDX/cyclonedx-property-taxonomy/blob/main/cdx/ai-ml.md)_ | +| 1.3.(ii) | Training data size | The CycloneDX component can be used to describe a training dataset with any level of detail required. In general, this section describes the general method on how to declare public and private datasets:• [Declaring datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets)Additionally, other types of information about each component dataset can be provided via various fields such as:• _pedigree_`• _external references_ to documentation• _properties_ for customized for tagging information to domain-specific requirements such as data sizes. | Dataset component(s):• `component` (in `inventories[].components[]` or `definitions.components[]`) ▪ `type`: `"data"` ▪ `name` ▪ `description` ▪ `identifiers[]` ▪ `data[]` (`type`: `"dataset"`, `contents`, `classification`, `governance`) ▪ `pedigree` ▪ `externalReferences[]` ▪ `properties[]` ▪ etc.**Note**: _The proposed `cdx:ai-ml:dataset:size` property ([taxonomy PR #175](https://github.com/CycloneDX/cyclonedx-property-taxonomy/pull/175)) can record dataset sizes. Ideally, each dataset would have its own independent Bill-of-Materials that fully described the details of its design, dependencies (i.e., data sources) and manufacturing which could be referenced by the AI/ML-BOM._ | +| 1.3.(iii) | Types of content | A discrete description of the types of content used to train a model would be provided as CycloneDX data components.• [Declaring datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets)Additional content information can be provided via external documentation and referenced in the model's component declaration.• [Providing links to papers & articles](0x22-Design-Model-Card-Parameters.md#providing-links-to-papers--articles) | Dataset components, their descriptions and external references to documentation:• `component` (in `inventories[].components[]` or `definitions.components[]`) ▪ `type`: `"data"` ▪ `name` ▪ `description` ▪ `data[]` (`type`: `"dataset"`, `contents`, `classification`, `governance`)Model component's external references:• `inventories[].subject.externalReferences[]` | +| 2 | List of data sources *(information about specific sources of data used to train the general-purpose AI model)* | *See details in subsections below* | N/A | +| 2.1 | Publicly available datasets | Each _public_ dataset used to train a model would be provided as a CycloneDX data component.• [Declaring datasets](0x22-Design-Model-Card-Parameters.md#declaring-datasets) ▪ [Datasets with minimal information](0x22-Design-Model-Card-Parameters.md#datasets-with-minimal-information) ▪ [Datasets as fully described data components](0x22-Design-Model-Card-Parameters.md#datasets-as-fully-described-data-components) | Dataset component(s):• `component` (in `inventories[].components[]` or `definitions.components[]`) ▪ `type`: `"data"` ▪ `name` ▪ `description` ▪ `identifiers[]` ▪ `data[]` (`type`: `"dataset"`, `contents`, `classification`, `governance`) ▪ `pedigree` ▪ `externalReferences[]` ▪ `properties[]` ▪ etc.**Note**: _The proposed `cdx:ai-ml:dataset:data:sources` property ([taxonomy PR #175](https://github.com/CycloneDX/cyclonedx-property-taxonomy/pull/175)) records the EU AI Act data source category (e.g., `publicly-available`, `third-party-private`, `web-crawl`, `user-data`, `synthetic`, `other`). Ideally, each public dataset would have its own independent Bill-of-Materials that fully described the details of its design, dependencies (i.e., data sources) and manufacturing which could be referenced by the AI/ML-BOM._ | +| 2.2 | Private non-publicly available datasets obtained from third parties | Private dataset information would be provided similarly to public datasets.See [template mappings](#template-mappings), Section 2.1 _"Publicly available data"_ (above) | _See referenced section._ | +| 2.2.1 | Datasets commercially licensed by rightsholders or their representatives | Commercial dataset information would be provided similarly to public datasets.See [template mappings](#template-mappings), Section 2.1 _"Publicly available data"_ (above) | _See referenced section._ | +| 2.2.1.(i) | concluded transactional commercial licensing agreement (modalities covered by license) | License information would be provided in the CycloneDX data component:• [Describing models as components](0x20-Design-Model-Component-Metadata.md#describing-models-as-components) ▪ _[Example: Declaring an ML model in an AI/ML-BOM](0x20-Design-Model-Component-Metadata.md#example-declaring-an-ml-model-in-an-aiml-bom)_ which uses the CycloneDX `license` object. | CycloneDX provides multiple, robust options for recording license information:• `component.licenses[]` (on the data component)**Note**: *modality-specific licensing may have considerations in future CycloneDX versions.* | +| 2.2.2 | Private datasets obtained from other third parties | Third-party, private dataset information would be provided similarly to public datasets.See [template mappings](#template-mappings), Section 2.1 _"Publicly available data"_ (above) | _See referenced section._ | +| 2.2.2.(i) | Specify the modality(ies) of the content covered by the datasets concerned. | Model data component modalities are declared in the same way as for the model component itself:• [Declaring a model's modalities](0x40-Design-Additional-Model-Information.md#declaring-a-models-modalities) | Data component modalities as properties:• `component.properties[]`**Note**: _Utilizes property values defined in the [CycloneDX Property Taxonomy for AI/ML](https://github.com/CycloneDX/cyclonedx-property-taxonomy/blob/main/cdx/ai-ml.md)_ | +| 2.2.2.(ii) | If publicly known, list private datasets obtained from other third parties | Publicly known, third-party, private dataset information would be provided similarly to public datasets.See [template mappings](#template-mappings), Section 2.1 _"Publicly available data"_ (above) | _See referenced section._ | +| 2.2.2.(iii) | General description of non-publicly known private datasets obtained from third parties | Non-publicly known, third-party, private dataset information would be provided similarly to public datasets.See [template mappings](#template-mappings), Section 2.1 _"Publicly available data"_ (above) | _See referenced section._ | +| 2.2.2.(iv) | Additional comments *(optional)* _e.g., the period of data collection, size of the datasets and further details_ | CycloneDX Bills-of-Materials (e.g., an AI/ML-BOM) supports `annotations` that allow for comments (made by people, organizations, or tools) about any object with a `refId` such as `components` or the BOM itself. | Comments using annotations:• `annotations[]` ▪ `subjects[]` - _list of references (e.g., components, etc.) the annotation applies to._ ▪ `annotator` - _The organization, individual, or component which created the textual content of the annotation._ ▪ `timestamp` ▪ `text` - _The textual content of the annotation._ ▪ `signatures` _(optional)_ - _digital signature(s) of the signer(s)._**Note**: _Each annotation can optionally have its own unique `refId` which allows reference from other annotations._ | +| 2.3 | Data crawled and scraped from online sources *(excluding publicly available datasets already compiled by third parties and made available on platforms such as common crawl that are covered under Section 2.1)* _The following subsections only apply if "crawlers were used for data collection"._ | *While this guide does not provide specific examples for data crawling, the training workflow example can serve as a template for extrapolating how to document the methods and data sources using CycloneDX workflows.*See [Annex XI mappings](#annex-xi-mappings), Section 1.2.(b) (above) | Any data collection processes would be described using CycloneDX workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`**Note**: _Best practices would have the data collection processes, for the resultant subject named dataset, captured in a Manufacturing Bill-of-Materials (or MBOM) which could be referenced by an AI/ML-BOM for a model that used that dataset for training or finetuning._ | +| 2.3.(i) | specify crawler name(s)/identifier(s) | The _data crawler_ would be declared as a CycloneDX component with its name and identifiers provided as described for a model component.See applicable references in the following [template mappings](#template-mappings) table sections (above):• Section 1.2, "Model identification"• Section 1.2.(i), "Versioned model name(s)" | _See referenced sections._ | +| 2.3.(ii) | Purposes of the crawler(s) | The crawler software would be declared as a CycloneDX `component` (or `service`) which can include its `description`, documentation via `externalReferences`, `properties` and `annotations`.See [template mappings](#template-mappings), Section 2.1, "Publicly available datasets" (above) for how to include component information and [template mappings](#template-mappings), Section 2.2.2.(iv), "Additional comments" for `annotations`. | _See referenced sections._| +| 2.3.(iii) | General description of crawler behaviour | See referenced methods for annotations in [template mappings](#template-mappings), Section 2.3.(i) (above) | _See referenced section._ | +| 2.3.(iv) | Period of data collection | See referenced methods in [template mappings](#template-mappings), Section 2.2.2.(iv) (above) | _See referenced section._ | +| 2.3.(v) | Comprehensive description of the type of content and online sources crawled | Each content source the crawler software targeted would be declared as a CycloneDX `component` with the ability to describe the content names, identifiers and location.See [template mappings](#template-mappings), Section 2.1, "Publicly available datasets" (above) for how to include component information. | _See referenced section._ | +| 2.3.(vi) | Type of modality covered | Each content source can include modality `properties` as referenced in [template mappings](#template-mappings), Section 2.2.2.(i) (above). | _See referenced section._ | +| 2.3.(vii) | Summary of the most relevant domain names crawled | The BOM for the software crawler should have a detailed listing of all crawled sources represented as CycloneDX components (or services). This comprehensive information could be provided using the crawler's BOM itself or the BOM used to produce a summary view. | N/A | +| 2.3.(viii) | Additional comments *(optional)*_e.g., domain names, URLs and the sources of individual works_ | See [template mappings](#template-mappings), Section 2.2.2.(iv) (above) | _See referenced section.__**Note**: Additionally, CycloneDX `workflows` that describe data collection processes can contain optional `timeStart` and `timeEnd` timestamps for the overall process and each of its composing `tasks`._ | +| 2.4 | User data*(information about user data collected by all services and products of the provider, including through mail services, social media platforms, content platforms)*_The following subsections only apply if user information sources were used._ | *While this guide does not provide specific examples for documenting user data collection, the training workflow example can serve as a template for extrapolating how to achieve this using CycloneDX.*See [Annex XI mappings](#annex-xi-mappings), Section 1.2.(b) (above) | Any data collection processes would be described using CycloneDX workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` ▪ `runtimeTopology[]`**Note**: _Best practices would have the data collection processes, for the resultant subject named dataset, captured in a Manufacturing Bill-of-Materials (or MBOM) which could be referenced by an AI/ML-BOM for a model that used that dataset for training or finetuning._ | +| 2.4.(i) | provide a general description of the provider’s services or products that were used to collect the user data | Data collection processes can be encoded using CycloneDX `formulation` `workflows` whose `tasks` reference, as resources, full descriptions of the provider's services or products (i.e., CycloneDX components, including components of type `service`) used. | Any services or software used in data collection processes would be declared as components and referenced from CycloneDX formulations:• `definitions.components[]`• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `resourceReferences[]` | +| 2.4.(ii) | Additional comments *(optional)* | See referenced methods for annotations in [template mappings](#template-mappings), Section 2.3.(i) (above) | _See referenced section._ | +| 2.5 | Synthetic data_The following subsections only apply if synthetic information sources were used._ | *While this guide does not provide specific examples for capturing synthetic data generation processes, the training workflow example can serve as a template for extrapolating how to document the methods and data sources using CycloneDX workflows.*See [Annex XI mappings](#annex-xi-mappings), Section 1.2.(b) (above) | _See referenced section._ | +| 2.5.(i) | modality of the synthetic data | See referenced methods for providing modalities in [template mappings](#template-mappings), Section 2.2.2.(i) (above) | _See referenced section._ | +| 2.5.(ii) | specify the general-purpose AI model(s) used to generate the synthetic data if available on the market | Any model used to generate synthetic data can be described using its own CycloneDX model `component` which could be listed as a resource within the `workflow` that describes the synthetic data generation process.See section [Annex XI mappings](#annex-xi-mappings), Section 1.1 (above) | _See referenced section._ | +| 2.5.(iii) | Information about other AI models, including provider’s own AI model(s) not available on the market, used to generate synthetic data to train the model | Any models used to generate _Synthetic data_ would themselves be declared as a CycloneDX components.See [Annex XI mappings](#annex-xi-mappings), Section 1.1 (above) | _See referenced section._ | +| 2.5.(iv) | Additional comments *(optional)* | See Section 2.2.2.(iv) (above) | _See referenced section._ | +| 2.6 | Other sources of data_The following subsections only apply if other information sources were used._ | *While this guide does not provide specific examples for capturing data from other sources, the training workflow example can serve as a template for extrapolating how to document the methods and data sources using CycloneDX workflows.*See "[Annex XI mappings](#annex-xi-mappings), Section 1.2.(b)" (above) | _See referenced section._ | +| 2.6.(i) | provide a narrative description of these data sources and the data | See referenced methods for annotations in Section 2.3.(i) (above) | _See referenced section._ | +| 2.6.(ii) | Additional comments *(optional)* | See referenced methods for annotations in Section 2.3.(i) (above) | _See referenced section._ | +| 3 | Data processing aspects The following subsections only apply if synthetic information sources were used. | *See details in subsections below* | N/A | +| 3.1 | Respect of reservation of rights from text and data mining exception or limitation*(measures implemented by the provider to identify and comply with the reservation of rights from the text and data mining (TDM) exception or limitation expressed pursuant to Article 4(3))* | *While this guide does not provide specific examples on providing measure implemented to comply with the reservation of rights from the text and data mining (TDM) exception and similar requirements, descriptive steps can be provided for each dataset's data acquisition process to show implementation of these measures.* | Detailed data acquisition steps with implementation descriptions:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]`Specifically, each `task` and `step` of a `workflow` has a `description` field as well as `properties` where domain-specific named properties and values can be recorded. Additionally, components used to acquire data can be annotated to include information about their configurations and policies with perhaps links to these as their own component artifacts. See [template mappings](#template-mappings), Section 2.2.2.(iv) (above) | +| 3.1.(i) | Additional comments *(optional)* | See [template mappings](#template-mappings), Section 2.2.2.(iv) (above) | _See referenced section._ | +| 3.2 | Removal of illegal content*measures taken to avoid or remove illegal content under Union law from the training data (such as blacklists, keywords, and model-based classifiers), without requiring disclosure of specific details about the provider’s internal business practices or trade secrets* | *While this guide does not provide specific examples for content removal or filtering, the training workflow example can serve as a template for extrapolating how to document the methods and data sources using CycloneDX workflows.* See references in table "[Annex XI mappings](#annex-xi-mappings), Section 1.2.(c)" (above) | Detailed data preparation workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]` | +| 3.3 | Other information *(optional)**Other relevant information about data processing* | CycloneDX allows organizations to document descriptive details for each dataset's processing and preparation workflow.See references in "[Annex XI mappings](#annex-xi-mappings), Section 1.2.(c)" (above) | Detailed data processing workflows:• `formulation[]`. ▪ `workflows[]` ▪ `tasks[]` ▪ `steps[]`Specifically, each `task` and `step` of a `workflow` has a `description` field as well as `properties` where domain-specific, named properties and values can be recorded. | + + \ No newline at end of file diff --git a/ML-BOM/2.0/en/0x93_Appendix-C_Complete_Example.md b/ML-BOM/2.0/en/0x93_Appendix-C_Complete_Example.md new file mode 100644 index 00000000..fa5abb20 --- /dev/null +++ b/ML-BOM/2.0/en/0x93_Appendix-C_Complete_Example.md @@ -0,0 +1,1159 @@ +# Appendix C: Complete Example + +This appendix includes a complete AI/ML-BOM example that combines most of the isolated examples for the Qwen model shown throughout this guide. + +#### Example: Qwen-7B AI/ML-BOM + +Unlike the abbreviated examples elsewhere in this guide, the AI/ML-BOM below contains no `// ...` placeholders and validates against the [CycloneDX 2.0 JSON schema](https://github.com/CycloneDX/specification/tree/2.0-dev/schema/2.0). + +> **Note**: For brevity, the `formulation` entry for the model's training only describes the top-level `workflow` topology (i.e., the run-time "stack"), but none of the `tasks` or `steps` that could be detailed. Similarly, only a few of the model repository's files are listed, so the composition's `aggregate` is `incomplete`. + +> **Note**: Some of the datasets, identifiers, and measurements combined into this example (e.g., the ACME datasets and identifier, the GLUE score, and the energy consumption) come from the illustrative examples in earlier sections and are not published information about Qwen-7B. + +The example is organized as follows: + +* **inventories** - The Qwen-7B model is the `subject` of the AI/ML-BOM's single inventory, whose `components` include files from the model repository (configuration, tokenizer, chat template, and tensor data) and the datasets used for training and evaluation. +* **compositions** - Asserts the completeness of the model's inventory. +* **formulation** - The model training workflow and its runtime topology. +* **risks** - The model's ethical considerations and fairness assessments. +* **definitions** - The components of the training "stack", the parties (suppliers, intended users, and groups at risk), the use cases, and graphics shared across the AI/ML-BOM. +* **perspectives** - An abridged "Model Card" perspective that maps the AI/ML-BOM data to familiar model card sections. + +```json +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:ec45525e-516c-4405-9de3-4fbdaef7f09a", + "version": 1, + "inventories": [ + { + "subject": { + "type": "machine-learning-model", + "refId": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9", + "group": "Qwen", + "name": "Qwen/Qwen-7B", + "version": "ef3c5c9c57b252f3149c1408daf4d649ec8b6c85", + "description": "Qwen-7B is a Transformer-based large language model, which is pretrained on a large volume of data, including web texts, books, codes, etc.", + "parties": [ + { + "refId": "party-alibaba-cloud", + "roles": [ + { + "role": "manufacturer" + } + ], + "organization": { + "name": "Alibaba Cloud", + "url": [ + { + "url": "https://www.alibabacloud.com" + } + ] + } + }, + { + "ref": "party-hugging-face" + } + ], + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9c57b252f3149c1408daf4d649ec8b6c85" + } + ] + }, + { + "party": "party-acme", + "identities": [ + { + "scheme": { + "name": "acme:research:model:llm:id", + "description": "ACME Research internal LLM registry identifier" + }, + "value": "MODEL-ID-12345-INTERNAL" + } + ] + } + ], + "licenses": [ + { + "license": { + "name": "Tongyi Qianwen LICENSE AGREEMENT", + "text": { + "content": "By clicking to agree or by using or distributing any portion or element of the Tongyi Qianwen Materials, ..." + } + } + } + ], + "releaseNotes": { + "type": "major", + "title": "Qwen 7B initial release", + "timestamp": "2023-08-03T15:30:00Z", + "notes": [ + { + "locale": "en-US", + "text": { + "content": "United States (US), English release date." + } + } + ] + }, + "externalReferences": [ + { + "type": "vcs", + "url": "https://huggingface.co/Qwen/Qwen-7B" + }, + { + "type": "model-card", + "url": "https://huggingface.co/Qwen/Qwen-7B" + }, + { + "type": "documentation", + "url": "https://arxiv.org/abs/2309.16609", + "comment": "Qwen Technical Report" + }, + { + "type": "documentation", + "url": "https://qwen.ai/usagepolicy", + "comment": "Usage policy" + } + ], + "tags": [ + "pytorch", + "transformers", + "text-generation" + ], + "pedigree": { + "descendants": [ + { + "type": "machine-learning-model", + "name": "Qwen/Qwen-7B-Chat", + "description": "The chat (instruction-following) variant of Qwen-7B, aligned using supervised fine-tuning (SFT) and reinforcement learning from human feedback (RLHF).", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B-Chat" + } + ] + } + ] + } + ] + }, + "useCaseAssertions": [ + { + "assertionType": "supports", + "useCaseRefs": [ + "uc-code-assistant", + "uc-translation", + "uc-support-triage", + "uc-research-summarization", + "uc-edge-device", + "uc-security-log-analysis", + "uc-local-assistant" + ] + } + ], + "modelProperties": { + "learningTypes": [ + "self-supervised", + "supervised", + "reinforcement-learning" + ], + "tasks": [ + "text-generation" + ], + "architecture": { + "name": "QWenLMHeadModel", + "description": "Decoder-only Transformer using rotary position embeddings and SwiGLU activations.", + "family": "transformer", + "features": [ + "decoder-only", + "rotary-position-embedding", + "gated-linear-units" + ], + "topology": "dense" + }, + "parameterCount": 7000000000, + "inputs": [ + { + "name": "prompt", + "description": "The text prompt to be completed by the model.", + "modality": "text", + "dataType": "string", + "processingStage": "pre-tokenizer", + "required": true + } + ], + "outputs": [ + { + "name": "completion", + "description": "The generated text completion.", + "modality": "text", + "dataType": "string", + "processingStage": "post-processing" + } + ], + "training": { + "formula": "formula-model-training", + "datasets": [ + "pkg:huggingface/openbmb/UltraFeedback@40b4365", + "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a", + "dataset-acme-midwest-health" + ] + }, + "limitations": [ + "Greedy Decoding Degradation. The model is optimized for sampling-based generation. Using greedy decoding (temperature=0) can lead to performance degradation, repetitive loops, and \"stuck\" reasoning steps, particularly in the new Thinking Mode", + "Native Context Window Boundaries. While the model supports up to 131,072 tokens using YaRN scaling, its native pre-training context is limited to 32,768 tokens. Performance may degrade on very long sequences if proper scaling factors (like RoPE or YaRN) are not manually configured for local deployments.", + "Synthetic Data \"Sanding\" Effects. Research indicates that Qwen, like many models trained on massive synthetic datasets, can suffer from \"model collapse\" where rare edge cases or minority user behaviors are underrepresented, potentially leading to errors in complex, real-world production environments.", + "Thinking Mode History Overhead. In multi-turn conversations, including the model's internal \"thinking\" steps in the chat history can confuse the model and consume unnecessary tokens. Best practices require developers to filter out \"thinking\" content from the history to maintain coherence.", + "Performance tradeoff: Intelligence Plateau in Domain-Specific Tasks. Research indicates that for specialized fields like legal text analysis, performance often flattens beyond the 7B parameter mark. While efficient, the 7B model may not offer the incremental reasoning gains found in the 32B or 235B models for complex, high-stakes domain reasoning.", + "Performance tradeoff: Enhanced Quantization Sensitivity. The Qwen-7B employs advanced pre-training techniques that reduce parameter redundancy. A documented tradeoff of this efficiency is a higher sensitivity to low-bit quantization (3-bit and below), where it exhibits more pronounced performance degradation compared to previous 7B generations.", + "Performance tradeoff: Context Window Consistency. While the 7B model supports a native context window of 32,768 tokens, its performance degrades significantly more than the Qwen-8B (which uses YaRN scaling to reach 128K+) when handling massive document sets. Users must tradeoff deep long-document comprehension for the 7B's lower memory footprint.", + "Performance tradeoff: Conciseness vs. Contextual Nuance. Experiments show that the older 7B design prioritizes cleaner, easier-to-read, and more concise outputs. The tradeoff is a loss of the \"faithful and nuanced\" insights and richer context provided by the newer 8B and larger architectures.", + "Performance tradeoff: Agentic Capability Limitations. The 7B model shows a documented gap in its ability to follow complex multi-step instructions or navigate large software repositories, requiring tighter chunking and more finely tuned prompts to be effective", + "Performance tradeoff: Hardware Efficiency vs. Throughput. Running the 7B model on older hardware (e.g., 8GB VRAM cards) is possible but results in a tradeoff of throughput. Modern inference techniques like continuous batching and PagedAttention are less effective at this scale than on the larger, more parallelizable MoE models.", + "Performance tradeoff: Decoding Strategy Rigidity. The 7B model is highly sensitive to sampling parameters; specifically, using greedy decoding (temperature=0) can lead to severe repetition loops and \"endless repetitions\". To maintain performance, users must tradeoff predictability for more complex sampling-based generation." + ], + "properties": [ + { + "name": "cdx:ai-ml:model:parameter:tune_method", + "value": "sft" + }, + { + "name": "cdx:ai-ml:model:parameter:tune_method", + "value": "rlhf" + }, + { + "name": "cdx:ai-ml:model:hyperparameter:num_hidden_layers", + "value": "32" + }, + { + "name": "cdx:ai-ml:model:hyperparameter:hidden_size", + "value": "4096" + }, + { + "name": "cdx:ai-ml:model:hyperparameter:context_length", + "value": "8192" + }, + { + "name": "cdx:ai-ml:model:hyperparameter:vocab_size", + "value": "151936" + }, + { + "name": "cdx:ai-ml:model:hyperparameter:quantization", + "value": "BF16" + } + ] + }, + "measurements": [ + { + "type": "accuracy", + "benchmark": "MMLU (5-shot)", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": 57.48, + "upperBound": 58.92 + }, + "evaluationDatasets": [ + "pkg:huggingface/cais/mmlu" + ], + "graphics": [ + { + "ref": "graphic-qwen-benchmarks" + } + ] + }, + { + "type": "f1", + "benchmark": "GLUE", + "slice": "cola", + "measure": { + "value": 0.87, + "unit": "1" + } + }, + { + "activity": "training", + "energyProviders": [ + { + "description": "Meta data-center, US-East", + "provider": { + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Fake.ai", + "addresses": [ + { + "country": "United States", + "region": "New Jersey", + "locality": "Newark" + } + ] + } + }, + "energySource": "natural-gas", + "energyProvided": { + "value": 0.4, + "unit": "kWh" + } + } + ], + "activityEnergyCost": { + "value": 0.4, + "unit": "kWh" + }, + "co2CostEquivalent": { + "value": 31.22, + "unit": "tCO2eq" + }, + "co2CostOffset": { + "value": 31.22, + "unit": "tCO2eq" + }, + "formula": "formula-model-training" + } + ], + "properties": [ + { + "name": "cdx:ai-ml:model:modality", + "value": "text" + }, + { + "name": "cdx:ai-ml:model:modality", + "value": "code" + }, + { + "name": "cdx:ai-ml:model:language", + "value": "en,fr,de,it,ja,zh" + } + ] + }, + "components": [ + { + "type": "file", + "name": "config.json", + "description": "Model configuration file using the 'QWenLMHeadModel' model class in Hugging Face Transformers", + "refId": "pkg:huggingface/Qwen/Qwen-7B@e7a368b#config.json", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@e7a368b0774370edec29674e7c51f52fc7663f59#config.json" + } + ] + } + ] + }, + { + "type": "file", + "name": "configuration_qwen.py", + "description": "Python 'QWenConfig' class implementation for the Qwen-7B model using Hugging Face Transformers", + "refId": "pkg:huggingface/Qwen/Qwen-7B@a6ca629#configuration_qwen.py", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@a6ca629d063f56f34d184852301e8852a7afbd58#configuration_qwen.py" + } + ] + } + ] + }, + { + "type": "library", + "name": "tokenization_qwen.py", + "description": "Python tokenization classes for QWen (QWenTokenizer)", + "refId": "pkg:huggingface/Qwen/Qwen-7B@e7a368b#tokenization_qwen.py", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@e7a368b0774370edec29674e7c51f52fc7663f59#tokenization_qwen.py" + } + ] + } + ], + "properties": [ + { + "name": "cdx:ai-ml:model:tokenizer", + "value": "true" + }, + { + "name": "cdx:ai-ml:tokenizer:hyperparameter:tokenizer_class", + "value": "QWenTokenizer" + } + ] + }, + { + "type": "file", + "refId": "qwen-7b-chat-template", + "name": "ChatML", + "description": "The ChatML chat template used to format conversational input for the model.", + "externalReferences": [ + { + "type": "documentation", + "url": "https://huggingface.co/learn/llm-course/en/chapter11/2#common-template-formats" + } + ], + "properties": [ + { + "name": "cdx:ai-ml:model:template:chat", + "value": "true" + } + ] + }, + { + "type": "data", + "name": "model-00001-of-00008.safetensors", + "description": "Model tensor data (01 of 08)", + "refId": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6#model-00001-of-00008.safetensors", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6d8ec63ce606f816e2d08072da6309f965#model-00001-of-00008.safetensors" + } + ] + } + ], + "data": [ + { + "type": "dataset", + "contents": { + "url": "https://huggingface.co/Qwen/Qwen-7B/blob/main/model-00001-of-00008.safetensors" + } + } + ] + }, + { + "type": "data", + "name": "model-00002-of-00008.safetensors", + "description": "Model tensor data (02 of 08)", + "refId": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6#model-00002-of-00008.safetensors", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/Qwen/Qwen-7B@abcb6d6d8ec63ce606f816e2d08072da6309f965#model-00002-of-00008.safetensors" + } + ] + } + ], + "data": [ + { + "type": "dataset", + "contents": { + "url": "https://huggingface.co/Qwen/Qwen-7B/blob/main/model-00002-of-00008.safetensors" + } + } + ] + }, + { + "type": "data", + "name": "UltraFeedback dataset", + "refId": "pkg:huggingface/openbmb/UltraFeedback@40b4365", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/openbmb/UltraFeedback@40b436560ca83a8dba36114c22ab3c66e43f6d5e" + } + ] + } + ], + "data": [ + { + "type": "dataset", + "classification": "public", + "contents": { + "url": "https://huggingface.co/datasets/openbmb/UltraFeedback" + } + } + ] + }, + { + "type": "data", + "name": "Snorkel-Mistral-PairRM-DPO dataset", + "refId": "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/snorkelai/Snorkel-Mistral-PairRM-DPO@07af5d0a875b4c692dfaff6c675b10af07b45511" + } + ] + } + ] + }, + { + "type": "data", + "name": "ACME Midwest health data", + "refId": "dataset-acme-midwest-health", + "data": [ + { + "type": "dataset", + "classification": "confidential", + "contents": { + "url": "https://acme.ai/adatasets/health/patient?region=midwest" + } + } + ] + }, + { + "type": "data", + "name": "MMLU", + "refId": "pkg:huggingface/cais/mmlu", + "description": "Massive Multitask Language Understanding evaluation dataset.", + "identifiers": [ + { + "party": "party-hugging-face", + "identities": [ + { + "scheme": "purl", + "value": "pkg:huggingface/cais/mmlu" + } + ] + } + ] + } + ] + } + ], + "compositions": [ + { + "kind": "components", + "aggregate": "incomplete", + "targets": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ] + } + ], + "formulation": [ + { + "refId": "formula-model-training", + "workflows": [ + { + "refId": "workflow-model-training", + "uid": "a3f9e2b1-7d8c-4a5f-9e6b-3c2d1a0b8f7e", + "name": "Model training workflow", + "description": "Describes the tasks used for training the model described by the AI/ML-BOM.", + "taskTypes": [ + "build" + ], + "resourceReferences": [ + { + "ref": "pkg:oci/nvidia-pytorch@sha256:f398a0" + }, + { + "ref": "nvidia-h100-pcie-gpu-1" + } + ], + "runtimeTopology": [ + { + "ref": "pkg:oci/nvidia-pytorch@sha256:f398a0", + "dependsOn": [ + "nvidia-h100-pcie-gpu-1" + ], + "provides": [ + "pkg:pypi/cuda-toolkit@13.1.1", + "pkg:generic/nvidia-cuda-runtime@12.2.0", + "pkg:pypi/pytorch@2.10.0", + "pkg:generic/nccl@2.29.2" + ] + } + ] + } + ] + } + ], + "risks": { + "risks": [ + { + "refId": "risk-bias", + "name": "Algorithmic and Cultural Bias", + "statement": "Training on trillions of tokens across many languages → the model reflects societal biases and stereotypes present in its training data → representational harm to affected groups.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "fairness" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-bias-detection", + "strategy": "reduce", + "description": "Use the Qwen-Gender framework or Chain-of-Thought (CoT) prompting to detect and reduce implicit biases in generated text." + } + ] + }, + { + "refId": "risk-jailbreak", + "name": "Vulnerability to Adversarial Attacks (Jailbreaking)", + "statement": "Despite safety tuning, users craft adversarial prompts (\"Prompt Hacking\" or \"Jailbreaking\") → safety constraints are bypassed → the model generates toxic or illegal content.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "security" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-guard-filter", + "strategy": "reduce", + "description": "Implement Qwen3Guard as an input/output filter to classify and block unsafe queries or responses in real-time." + } + ] + }, + { + "refId": "risk-hallucination", + "name": "Misinformation or Hallucinations", + "statement": "Probabilistic generation without grounding → the model fabricates false or misleading information, especially regarding sensitive topics like government actions or historical events → users are misinformed.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "societal" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-rag-grounding", + "strategy": "reduce", + "description": "Explicitly instruct the model to \"Prioritize Safety\" in the prompt and use Retrieval-Augmented Generation (RAG) to ground responses in verified external documents." + } + ] + }, + { + "refId": "risk-pii-leakage", + "name": "Privacy, Sensitive or Personally Identifiable Information (PII) Content Leakage", + "statement": "Sensitive or personally identifiable data present in the pre-training corpus → the model reproduces such data in its outputs → privacy violation.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "privacy" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-local-deploy-pii-scrub", + "strategy": "reduce", + "description": "Deploy the model locally using tools like Ollama to ensure sensitive data stays within a secure environment, and apply regex-based PII scrubbing to outputs." + } + ] + }, + { + "refId": "risk-inference-energy", + "name": "Environmental Impact (Inference Energy)", + "statement": "Continuous large-scale deployment of even mid-sized models like the 7B → significant energy consumption → increased carbon footprint.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "environmental" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-quantize-efficient-inference", + "strategy": "reduce", + "description": "Utilize 4-bit quantization and low-latency inference engines to reduce the FLOPs required per token, minimizing the power draw per query." + } + ] + }, + { + "refId": "risk-instruction-misalignment", + "name": "Instruction Misalignment", + "statement": "In-context learning → \"emergent misalignment\" where the model prioritizes following a user's conversational style → established safety boundaries are not respected.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "safety" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9" + ], + "status": "identified", + "responses": [ + { + "refId": "resp-system-prompt-hard-switch", + "strategy": "reduce", + "description": "Standardize output formats using system prompts and utilize the \"hard switch\" to disable the model's internal thinking mode when maximum safety and predictability are required." + } + ] + }, + { + "refId": "risk-fairness-discriminatory-outcomes", + "name": "Discriminatory outcomes across protected characteristics", + "statement": "Biases in training data → the model produces discriminatory outcomes across protected characteristics in task assignment scenarios → individuals in the affected groups are unfairly labeled or treated.", + "domains": [ + { + "type": "fairness" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9", + "group-protected-characteristics" + ], + "status": "assessed", + "inherentRisk": { + "impacts": [ + { + "polarity": "harm", + "level": "major", + "categories": [ + "discrimination" + ], + "description": "The model was found to produce discriminatory outcomes across protected characteristics, including race, gender, and disability status. For example, individuals categorized as \"gypsy\" or \"mute\" were incorrectly labeled as untrustworthy in task assignment scenarios." + } + ] + }, + "responses": [ + { + "refId": "resp-rlaif-alignment", + "strategy": "reduce", + "description": "Researchers recommend using Reinforcement Learning from Artificial Intelligence Feedback (RLAIF) and rule-based rewards to align the model with specific legal standards like the EU AI Act." + } + ] + }, + { + "refId": "risk-fairness-quality-of-service", + "name": "Quality-of-service disparity across languages", + "statement": "Reasoning capabilities trained predominantly on English and Mandarin data → oversimplified, factually incorrect, or hallucinated responses in other supported languages → lower quality of service for speakers of those languages.", + "domains": [ + { + "type": "fairness" + } + ], + "affects": [ + "pkg:huggingface/Qwen/Qwen-7B@ef3c5c9", + "group-other-language-speakers" + ], + "status": "assessed", + "inherentRisk": { + "impacts": [ + { + "polarity": "harm", + "level": "moderate", + "categories": [ + "fairness" + ], + "description": "Quality-of-Service Harm: The model may provide high-quality, nuanced reasoning in English or Mandarin but offer oversimplified, factually incorrect, or \"hallucinated\" information when queried in other supported languages." + } + ] + }, + "responses": [ + { + "refId": "resp-cross-lingual-sft", + "strategy": "reduce", + "description": "Cross-Lingual Alignment: Developers can use multilingual Supervised Fine-Tuning (SFT), training on additional high-quality, parallel corpora from other languages on \"reasoning capabilities\" (e.g., logic, math, coding)." + } + ] + } + ] + }, + "definitions": { + "components": [ + { + "type": "container", + "name": "h100-training-image", + "version": "25.03-py3-igpu", + "refId": "pkg:oci/nvidia-pytorch@sha256:f398a0", + "identifiers": [ + { + "party": "party-nvidia", + "identities": [ + { + "scheme": "purl", + "value": "pkg:oci/nvidia-pytorch@sha256:f398a0955ec5fcf9e3bbf77610225ff4e953e137423ab248e2bf32cd4971a1dc?repository_url=nvcr.io/nvidia/pytorch&tag=25.03-py3-igpu" + } + ] + } + ] + }, + { + "type": "library", + "name": "nvidia-cuda-runtime", + "version": "12.2.0", + "refId": "pkg:generic/nvidia-cuda-runtime@12.2.0" + }, + { + "type": "library", + "name": "pytorch", + "version": "2.10.0", + "refId": "pkg:pypi/pytorch@2.10.0" + }, + { + "type": "library", + "name": "cuda-toolkit", + "version": "13.1.1", + "refId": "pkg:pypi/cuda-toolkit@13.1.1" + }, + { + "type": "library", + "name": "nccl", + "version": "2.29.2", + "refId": "pkg:generic/nccl@2.29.2" + }, + { + "type": "device", + "name": "NVIDIA H100 Tensor Core GPU", + "description": "NVIDIA H100 Tensor Core GPU PCIe Device", + "refId": "nvidia-h100-pcie-gpu-1" + } + ], + "parties": [ + { + "refId": "party-hugging-face", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Hugging Face", + "url": [ + { + "url": "https://huggingface.co" + } + ] + } + }, + { + "refId": "party-acme", + "roles": [ + { + "role": "asserter" + } + ], + "organization": { + "name": "ACME" + } + }, + { + "refId": "party-nvidia", + "roles": [ + { + "role": "publisher" + } + ], + "organization": { + "name": "NVIDIA" + } + }, + { + "refId": "user-software-developer", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Software developer", + "archetype": "developer" + } + }, + { + "refId": "user-content-creator", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Multilingual Content Creator" + } + }, + { + "refId": "user-support-architect", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Customer Support Systems Architect" + } + }, + { + "refId": "user-researcher", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Academic Researcher / Student", + "archetype": "researcher" + } + }, + { + "refId": "user-edge-engineer", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Edge Device Engineer" + } + }, + { + "refId": "user-security-analyst", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Enterprise Security Analyst" + } + }, + { + "refId": "user-local-ai", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "label": "Local AI Enthusiast / Privacy-First User" + } + }, + { + "refId": "group-protected-characteristics", + "roles": [ + { + "name": "affected-group", + "description": "A group of people at risk of being systematically disadvantaged by the model." + } + ], + "persona": { + "label": "People identified by protected characteristics", + "description": "People identified by characteristics such as race, gender, and disability status." + } + }, + { + "refId": "group-other-language-speakers", + "roles": [ + { + "name": "affected-group" + } + ], + "persona": { + "label": "Non-English/Non-Chinese speakers", + "description": "Non-English/Non-Chinese speakers, speakers of regional dialects or specific geographic regions (e.g., Southeast Asia or the Middle East) on thinking or \"reasoning\" tasks." + } + } + ], + "useCases": [ + { + "refId": "uc-code-assistant", + "name": "IDE code assistant", + "description": "Utilizing the Qwen \"instruct\" variants within an IDE for real-time code completion, bug fixing, and unit test generation, benefiting from its \"Agentic\" capabilities for repository-scale understanding.", + "actors": [ + "user-software-developer" + ] + }, + { + "refId": "uc-translation", + "name": "Content translation", + "description": "Translating business, education, or other content or informational materials to other languages and dialects while maintaining the original tone and cultural nuances.", + "actors": [ + "user-content-creator" + ] + }, + { + "refId": "uc-support-triage", + "name": "Customer support triage", + "description": "Deploying low-latency chatbots for high-volume inquiries where the 7B model acts as a \"triage\" agent, answering common questions and only escalating complex logic to other support mechanisms.", + "actors": [ + "user-support-architect" + ] + }, + { + "refId": "uc-research-summarization", + "name": "Research summarization and drafting", + "description": "Summarizing long-form research papers and generating initial drafts for school projects, utilizing the model's long context window to ingest entire documents at once.", + "actors": [ + "user-researcher" + ] + }, + { + "refId": "uc-edge-device", + "name": "On-device natural language control", + "description": "Implementing the model on specialized hardware for real-time perception and reasoning to help an intelligent device navigate and interact with its environment based on natural language commands.", + "actors": [ + "user-edge-engineer" + ] + }, + { + "refId": "uc-security-log-analysis", + "name": "Self-hosted security log analysis", + "description": "Running a self-hosted instance to analyze internal security logs for anomalies, ensuring that sensitive infrastructure data never leaves the organization's firewall.", + "actors": [ + "user-security-analyst" + ] + }, + { + "refId": "uc-local-assistant", + "name": "Local personal assistant", + "description": "Running a personal assistant locally on a laptop to answer questions or process private information such as emails or calendars without sending data to an external server.", + "actors": [ + "user-local-ai" + ] + } + ], + "graphics": [ + { + "refId": "graphic-qwen-benchmarks", + "name": "Qwen Performance Benchmarks (spider diagram)", + "description": "benchmark_score", + "image": { + "mediaType": "image/jpeg", + "encoding": "base64", + "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA" + } + } + ] + }, + "perspectives": [ + { + "refId": "perspective-model-card", + "name": "Model Card", + "description": "An abridged model card view of this AI/ML-BOM.", + "domains": [ + "machine-learning", + "transparency" + ], + "mappings": [ + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject['name','version','description']", + "nativeName": "Model Details", + "relevance": "required", + "weight": 1.0 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.licenses", + "nativeName": "License", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.tasks", + "nativeName": "Supported Tasks", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.architecture", + "nativeName": "Architecture", + "relevance": "recommended" + }, + { + "expression": "$.definitions.useCases[*]", + "nativeName": "Intended Use", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.training", + "nativeName": "Training Data", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.measurements[?(@.type)]", + "nativeName": "Evaluation Results", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.modelProperties.limitations", + "nativeName": "Technical Limitations", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.risks.risks[?(@.domains[?(@.type=='ethical')])]", + "nativeName": "Ethical Considerations", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.risks.risks[?(@.domains[?(@.type=='fairness')])]", + "nativeName": "Fairness Assessments", + "relevance": "recommended" + }, + { + "expression": "$.inventories[?(@.subject.type=='machine-learning-model')].subject.measurements[?(@.activity)]", + "nativeName": "Environmental Impact", + "relevance": "recommended" + } + ] + } + ] +} +``` + + diff --git a/ML-BOM/2.0/en/images/QwenLM-radar_72b.jpg b/ML-BOM/2.0/en/images/QwenLM-radar_72b.jpg new file mode 100644 index 00000000..743e68fa Binary files /dev/null and b/ML-BOM/2.0/en/images/QwenLM-radar_72b.jpg differ diff --git a/ML-BOM/2.0/en/images/anatomy.svg b/ML-BOM/2.0/en/images/anatomy.svg new file mode 100644 index 00000000..287bf81f --- /dev/null +++ b/ML-BOM/2.0/en/images/anatomy.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ML-BOM/2.0/en/images/cover.jpg b/ML-BOM/2.0/en/images/cover.jpg new file mode 100644 index 00000000..2e18de49 Binary files /dev/null and b/ML-BOM/2.0/en/images/cover.jpg differ diff --git a/ML-BOM/2.0/en/images/cover.pdf b/ML-BOM/2.0/en/images/cover.pdf new file mode 100644 index 00000000..5362b586 Binary files /dev/null and b/ML-BOM/2.0/en/images/cover.pdf differ diff --git a/ML-BOM/2.0/en/images/hf-model-repo-Qwen-7B-file-list.png b/ML-BOM/2.0/en/images/hf-model-repo-Qwen-7B-file-list.png new file mode 100644 index 00000000..d55ffa54 Binary files /dev/null and b/ML-BOM/2.0/en/images/hf-model-repo-Qwen-7B-file-list.png differ diff --git a/ML-BOM/2.0/en/images/ml-anatomy-model-card-considerations.svg b/ML-BOM/2.0/en/images/ml-anatomy-model-card-considerations.svg new file mode 100644 index 00000000..2989d0e3 --- /dev/null +++ b/ML-BOM/2.0/en/images/ml-anatomy-model-card-considerations.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ML-BOM/2.0/en/images/ml-anatomy-model-card-parameters.svg b/ML-BOM/2.0/en/images/ml-anatomy-model-card-parameters.svg new file mode 100644 index 00000000..9f1cd1ad --- /dev/null +++ b/ML-BOM/2.0/en/images/ml-anatomy-model-card-parameters.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ML-BOM/2.0/en/images/ml-anatomy-model-card-quant-analysis.svg b/ML-BOM/2.0/en/images/ml-anatomy-model-card-quant-analysis.svg new file mode 100644 index 00000000..9bb0a4a1 --- /dev/null +++ b/ML-BOM/2.0/en/images/ml-anatomy-model-card-quant-analysis.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ML-BOM/2.0/en/images/ml-bom-metadata-component.svg b/ML-BOM/2.0/en/images/ml-bom-metadata-component.svg new file mode 100644 index 00000000..1c1debea --- /dev/null +++ b/ML-BOM/2.0/en/images/ml-bom-metadata-component.svg @@ -0,0 +1,651 @@ + +