Préparation des métadonnées de modèle

Les métadonnées de modèle sont facultatives, mais recommandées.

Métadonnées de provenance de modèle

Vous pouvez documenter la provenance du modèle. Cette opération est facultative. Le tableau suivant répertorie les métadonnées de provenance de modèle prises en charge :


Métadonnées	Description
`git_branch`	Branchement du référentiel Git.
`git_commit`	ID de validation.
`repository_url`	URL du référentiel Git distant.
`script_dir`	Chemin local du répertoire d'artefact.
`training_id`	OCID de la ressource utilisée pour entraîner le modèle, la session de bloc-notes ou le traitement de travail. Vous pouvez utiliser ces variables d'environnement lorsque vous enregistrez un modèle avec le kit SDK OCI : `NB_SESSION_OCID`

Exemple

provenance_details = CreateModelProvenanceDetails(repository_url="EXAMPLE-repositoryUrl-Value",
                                                  git_branch="EXAMPLE-gitBranch-Value",
                                                  git_commit="EXAMPLE-gitCommit-Value",
                                                  script_dir="EXAMPLE-scriptDir-Value",
                                                  # OCID of the ML job Run or Notebook session on which this model was
                                                  # trained
                                                  training_id="<<Notebooksession or ML Job Run OCID>>"
                                                  )

Métadonnées de taxonomie de modèle

Vous pouvez documenter la taxonomie de modèle. Cette opération est facultative.

Les champs de métadonnées associés à la taxonomie de modèle permettent de décrire le cas d'emploi et la structure de l'apprentissage automatique derrière le modèle. Les balises de métadonnées définies constituent la liste des valeurs autorisées pour le type de cas d'emploi et la structure pour les métadonnées définies, et des valeurs de catégorie pour les métadonnées personnalisées.

Taxonomie de modèle prédéfinie

Le tableau suivant répertorie les métadonnées de taxonomie de modèle prises en charge :


Métadonnées	Description
`UseCaseType`	Décrit le cas d'emploi de l'apprentissage automatique associé au modèle à l'aide de l'une des valeurs répertoriées, par exemple : `binary_classification regression multinomial_classification clustering recommender dimensionality_reduction/representation time_series_forecasting anomaly_detection topic_modeling ner sentiment_analysis image_classification object_localization other`
`Framework`	Décrit la structure de l'apprentissage automatique associée au modèle à l'aide de l'une des valeurs répertoriées, par exemple : `scikit-learn xgboost tensorflow pytorch mxnet keras lightGBM pymc3 pyOD spacy prophet sktime statsmodels cuml oracle_automl h2o transformers nltk emcee pystan bert gensim flair word2vec ensemble (more than one library) other`
`FrameworkVersion`	Version de la structure de l'apprentissage automatique. Il s'agit d'une valeur de texte libre. Par exemple : `PyTorch 1.9`.
`Algorithm`	Algorithme ou classe d'instance de modèle. Il s'agit d'une valeur de texte libre. Par exemple : `CART algorithm`.
`Hyperparameters`	Hyperparamètres de l'objet de modèle. Format JSON.
`ArtifactTestResults`	Sortie JSON des tests d'artefact exécutés côté client.

Exemple

Cet exemple montre comment documenter la taxonomie de modèle en capturant chaque paire clé-valeur, ce qui crée une liste d'objets Metadata() :

# create the list of defined metadata around model taxonomy:
defined_metadata_list = [
    Metadata(key="UseCaseType", value="image_classification"),
    Metadata(key="Framework", value="keras"),
    Metadata(key="FrameworkVersion", value="0.2.0"),
    Metadata(key="Algorithm",value="ResNet"),
    Metadata(key="hyperparameters",value="{\"max_depth\":\"5\",\"learning_rate\":\"0.08\",\"objective\":\"gradient descent\"}")
]

Taxonomie de modèle personnalisée

Vous pouvez ajouter vos propres métadonnées personnalisées pour documenter votre modèle. La taille de fichier maximale autorisée pour les métadonnées personnalisées et définies combinées est de 32 000 octets.

Chaque métadonnée personnalisée possède les quatre attributs suivants :


Champ ou clé	Requis ?	Description
`key`	Requis	Clé et libellé des métadonnées personnalisées.
`value`	Requis	Valeur attachée à la clé.
`category`	Facultatif	Catégorie des métadonnées. Sélectionnez l'une des cinq valeurs suivantes : `Performance` `Training Profile` `Training and Validation Datasets` `Training Environment` `other` L'attribut de catégorie est utile pour filtrer les métadonnées personnalisées. Un tel filtrage est pratique avec une grande quantité de métadonnées personnalisées pour un modèle spécifique.
`description`	Facultatif	Description des métadonnées personnalisées.

Exemple

Cet exemple montre comment ajouter des métadonnées personnalisées pour capturer l'exactitude du modèle, l'environnement et la source des données d'entraînement :

# Adding your own custom metadata:
custom_metadata_list = [
    Metadata(key="Image Accuracy Limit", value="70-90%", category="Performance",
             description="Performance accuracy accepted"),
    Metadata(key="Pre-trained environment",
             value="https://blog.floydhub.com/guide-to-hyperparameters-search-for-deep-learning-models/",
             category="Training environment", description="Environment link for pre-trained model"),
    Metadata(key="Image Sourcing", value="https://lionbridge.ai/services/image-data/", category="other",
             description="Source for image training data")
]

Définition des schémas de données de modèle

Vous pouvez documenter les schémas de données d'entrée et de sortie du modèle. La définition du schéma de données d'entrée fournit le modèle de base du paramètre data de la fonction predict() du fichier score.py. Vous pouvez considérer le schéma de données d'entrée comme la définition du vecteur de caractéristique d'entrée nécessaire au modèle pour réaliser des prédictions réussies. La définition du schéma de sortie documente ce que la fonction predict() renvoie.

Important

La taille de fichier maximale autorisée pour les schémas d'entrée et de sortie combinés est de 32 000 octets.

La définition de schéma pour les prédictions de modèle et de vecteur de caractéristique d'entrée est utilisée à des fins de documentation. Cette directive s'applique uniquement aux ensembles de données tabulaires.

Le schéma du vecteur de caractéristique d'entrée de modèle et des prédictions de sortie est un objet JSON. L'objet comporte une liste de niveau supérieur avec une clé appelée schema. La définition de schéma de chaque colonne est une entrée différente dans la liste.

Conseil

Vous pouvez utiliser ADS pour extraire automatiquement la définition de schéma d'un ensemble de données d'entraînement spécifique.

Pour chaque colonne, le schéma peut être entièrement défini en affectant des valeurs à tous les attributs suivants :


Champ ou clé	Type	Requis ?	Description
`name`	`STRING`	Requis	Nom de la colonne.
`description`	`STRING`	Facultatif	Description de la colonne.
`required`	`BOOL`	Requis	Indique si la colonne correspond à une caractéristique d'entrée requise pour réaliser une prévision de modèle.
`dtype`	`STRING`	Requis	Type de données de la colonne.
`domain`	`OBJECT`	Facultatif	Plage de valeurs autorisées pour la caractéristique.

Le champ domain est un dictionnaire contenant les clés suivantes :


Champ ou clé	Type	Requis ?	Description	Remarques
`domain.constraints`	`LIST`	Facultatif	Prend en charge une liste de prédicats pour les contraintes sur la plage de valeurs autorisées pour la caractéristique. Vous pouvez entrer un modèle d'expression de chaîne propre au langage, qui peut être évalué par l'interpréteur de langage et le compilateur. Avec Python, le format de chaîne doit suivre `STRING`. Les contraintes peuvent être spécifiées à l'aide d'une liste d'expressions. Par exemple : `constraints=[Expression('$x > 5')]`.	Vous pouvez appliquer plusieurs contraintes. Exemple d'expression : schema: - description: Id domain: constraints: [] stats: 25%: 365.75 50%: 730.5 75%: 1095.25 count: 1460.0 max: 1460.0 mean: 730.5 min: 1.0 std: 421.6100093688479 values: Discreet numbers name: Id required: false type: int64 - description: MSSubClass domain: constraints: [] stats: 25%: 20.0 50%: 50.0 75%: 70.0 count: 1460.0 max: 190.0 mean: 56.897260273972606 min: 20.0 std: 42.300570993810425 values: Discreet numbers name: MSSubClass required: false type: int64 - description: MSZoning domain: constraints: - expression: '$x in ["RL", "RM", "C (all)", "FV", "RH"]' - RL - RM - C (all) - FV - RH stats: count: 1460 unique: 5 values: Category name: MSZoning required: false type: category
`domain.stats`	`OBJECT`	Facultatif	Dictionnaire de statistiques récapitulatives décrivant la caractéristique. Pour les types `float64` et `int64` : `X%` (X est une valeur de centile comprise entre 1 et 99. Plusieurs valeurs de centile peuvent être capturées.) `count` `max` `mean` `median` `min` `std` Pour la catégorie : `count` `unique` `mode`	Dans ADS, les statistiques sont générées automatiquement en fonction de `feature_stat` dans les types de caractéristique.
`domain.values`	`STRING`	Facultatif	Représente le type sémantique de la colonne. Les valeurs prises en charge sont les suivantes : Nombres discrets Nombres Catégorie Texte libre
`domain.name`	`STRING`	Facultatif	Nom de l'attribut.
`domain.dtype`	`STRING`	Requis	Type de données Pandas des données. Par exemple : `int64 float category datettime`
`domain.dtype`	`STRING`	Requis	Type de caractéristique des données. Par exemple : `Category Integer LatLong,`

Exemple de schéma de données d'entrée

schema:
- description: Description of the column
  domain:
    constraints:
    - expression: '($x > 10 and $x <100) or ($x < -1 and $x > -500)' # Here user can input language specific string expression template which can be evaluated by the language interpreter/compiler. In case of python the string format expected to follow string.Template recognized format.
      language: python
    stats:  # This section is flexible key value pair. The stats will depend on what user wants to save. By default, the stats will be automatically generated based on the `feature_stat` in feature types
      mean: 20
      median: 21
      min: 5
    values: numbers # The key idea is to communicate what should be the domain of values that are acceptable. Eg rational numbers, discreet numbers, list of values, etc
  name: MSZoing # Name of the attribute
  required: false # If it is a nullable column

Exemple de schéma de données de sortie

{
"predictionschema": [
    {
    "description": "Category of SR",
    "domain": {
    "constraints": [],
    "stats": [],
    "values": "Free text"
    },
    "name": "category",
    "required": true,
    "type": "category"
    }
    ]
}

Test d'introspection de modèle

Copiez le fichier artifact_introspection_test de l'artefact de modèle dans le répertoire de niveau supérieur de l'artefact.
Installez une version de Python supérieure à 3.5.
Installez les bibliothèques Python pyyaml et requests. Cette installation n'est requise qu'une seule fois.
Accédez au répertoire des artefacts et installez les tests d'introspection des artefacts.
```
python3 -m pip install --user -r artifact_introspection_test/requirements.txt
```

Définissez le chemin de l'artefact et exécutez le test d'introspection.

python3 artifact_introspection_test/model_artifact_validate.py --artifact

Les tests d'introspection génèrent des fichiers test_json_output.json et test_json_output.html locaux. Voici un exemple de résultats de test d'introspection au format JSON :

{
    "score_py": {
        "category": "Mandatory Files Check",
        "description": "Check that the file \"score.py\" exists and is in the top level directory of the artifact directory",
        "error_msg": "File score.py is not present.",
        "success": true
    },
    "runtime_yaml": {
        "category": "Mandatory Files Check",
        "description": "Check that the file \"runtime.yaml\" exists and is in the top level directory of the artifact directory",
        "error_msg": "File runtime.yaml is not present.",
        "success": true
    },
    "score_syntax": {
        "category": "score.py",
        "description": "Check for Python syntax errors",
        "error_msg": "Syntax error in score.py: ",
        "success": true
    },
    "score_load_model": {
        "category": "score.py",
        "description": "Check that load_model() is defined",
        "error_msg": "Function load_model is not present in score.py.",
        "success": true
    },
    "score_predict": {
        "category": "score.py",
        "description": "Check that predict() is defined",
        "error_msg": "Function predict is not present in score.py.",
        "success": true
    },
    "score_predict_data": {
        "category": "score.py",
        "description": "Check that the only required argument for predict() is named \"data\"",
        "error_msg": "Function predict in score.py should have argument named \"data\".",
        "success": true
    },
    "score_predict_arg": {
        "category": "score.py",
        "description": "Check that all other arguments in predict() are optional and have default values",
        "error_msg": "All other arguments in predict function in score.py should have default values.",
        "success": true
    },
    "runtime_version": {
        "category": "runtime.yaml",
        "description": "Check that field MODEL_ARTIFACT_VERSION is set to 3.0",
        "error_msg": "In runtime.yaml field MODEL_ARTIFACT_VERSION should be set to 3.0",
        "success": true
    },
    "runtime_env_type": {
        "category": "conda_env",
        "description": "Check that field MODEL_DEPLOYMENT.INFERENCE_ENV_TYPE is set to a value in (published, data_science)",
        "error_msg": "In runtime.yaml field MODEL_DEPLOYMENT.INFERENCE_ENV_TYPE should be set to a value in (published, data_science)",
        "success": true,
        "value": "published"
    },
    "runtime_env_slug": {
        "category": "conda_env",
        "description": "Check that field MODEL_DEPLOYMENT.INFERENCE_ENV_slug is set",
        "error_msg": "In runtime.yaml field MODEL_DEPLOYMENT.INFERENCE_ENV_slug should be set.",
        "success": true,
        "value": "mlgpuv1"
    },
    "runtime_env_path": {
        "category": "conda_env",
        "description": "Check that field MODEL_DEPLOYMENT.INFERENCE_ENV_PATH is set",
        "error_msg": "In runtime.yaml field MODEL_DEPLOYMENT.INFERENCE_ENV_PATH should be set.",
        "success": true,
        "value": "oci://service_conda_packs@ociodscdev/service_pack/gpu/General Machine Learning for GPUs/1.0/mlgpuv1"
    },
    "runtime_path_exist": {
        "category": "conda_env",
        "description": "If MODEL_DEPLOYMENT.INFERENCE_ENV_TYPE is data_science and MODEL_DEPLOYMENT.INFERENCE_ENV_slug is set, check that the file path in MODEL_DEPLOYMENT.INFERENCE_ENV_PATH is correct.",
        "error_msg": "In runtime.yaml field MODEL_DEPLOYMENT.INFERENCE_ENV_PATH doesn't exist.",
        "success": true
    },
    "runtime_slug_exist": {
        "category": "conda_env",
        "description": "If MODEL_DEPLOYMENT.INFERENCE_ENV_TYPE is data_science, check that the slug listed in MODEL_DEPLOYMENT.INFERENCE_ENV_slug exists.",
        "error_msg": "In runtime.yaml the value of the fileld INFERENCE_ENV_slug doesn't exist in the given bucket."
    }
}

Répétez les étapes 4 et 5 jusqu'à ce qu'aucune erreur ne se produise.

Utiliser ADS pour les tests d'introspection

Vous pouvez appeler l'introspection manuellement en appelant la méthode .introspect() sur l'objet ModelArtifact.

rf_model_artifact.introspect()
rf_model_artifact.metadata_taxonomy['ArtifactTestResults']

Le résultat de l'introspection de modèle est automatiquement enregistré dans les métadonnées de taxonomie et les artefacts de modèle. L'introspection de modèle est automatiquement déclenchée lorsque la méthode .prepare() est appelée pour préparer l'artefact de modèle.

La méthode .save() n'effectue pas d'introspection de modèle car elle est normalement effectuée lors de la phase de préparation de l'artefact de modèle. Toutefois, si vous définissez ignore_introspection sur False, l'introspection du modèle est effectuée lors de l'opération d'enregistrement.

Documentation Oracle Cloud Infrastructure

Préparation des métadonnées de modèle

Métadonnées de provenance de modèle

Exemple

Métadonnées de taxonomie de modèle

Taxonomie de modèle prédéfinie

Exemple

Taxonomie de modèle personnalisée

Exemple

Définition des schémas de données de modèle

Exemple de schéma de données d'entrée

Exemple de schéma de données de sortie

Test d'introspection de modèle

Utiliser ADS pour les tests d'introspection