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 du 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 du modèle prises en charge :


Métadonnées	Description
`git_branch`	Branche du référentiel Git.
`git_commit`	ID validation.
`repository_url`	Adresse URL du référentiel Git distant.
`script_dir`	Chemin d'accès local au répertoire dl'artefacts
`training_id`	OCID de la ressource utilisée pour entraîner le modèle, la session de carnet ou l'exécution de travail. Vous pouvez utiliser ces variables d'environnement lorsque vous enregistrez un modèle avec la trousse SDK pour 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'utilisation et le cadre de l'apprentissage automatique derrière le modèle. Les marqueurs de métadonnées définis sont la liste des valeurs autorisées pour le type de cas d'utilisation, le cadre pour les métadonnées définies et les 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 du modèle prises en charge :


Métadonnées	Description
`UseCaseType`	Décrit le cas d'utilisation de l'apprentissage automatique associé au modèle à l'aide d'une des valeurs listé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`	Cadre d'apprentissage automatique associé au modèle à l'aide d'une des valeurs listé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 du cadre d'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. Il s'agit d'un format JSON.
`ArtifactTestResults`	La sortie JSON des tests d'artefact s'exécute côté client.

Exemple

Cet exemple montre comment documenter la taxonomie du modèle en saisissant chaque paire clé-valeur 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 définies et personnalisées combinées est de 32000 octets.

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


Champ ou clé	Obligatoire?	Description
`key`	Obligatoire	Clé et étiquette de vos métadonnées personnalisées.
`value`	Obligatoire	Valeur associé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. Ceci est pratique lorsqu'un modèle donnée comprend un grand nombre de métadonnées personnalisées.
`description`	Facultatif	Description des métadonnées personnalisées.

Exemple

Cet exemple montre comment ajouter des métadonnées personnalisées pour saisir 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 de 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 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 fonction d'entrée dont votre modèle a besoin pour réussir des prédictions. La définition de schéma de sortie documente ce que la fonction predict() retourne.

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 le vecteur de fonction d'entrée et les prédictions de modèle sont utilisées à des fins de documentation. Cette directive s'applique uniquement aux jeux de données tabulaires.

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

Conseil

Vous pouvez utiliser ADS pour extraire automatiquement la définition de schéma d'un jeu 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	Obligatoire?	Description
`name`	`STRING`	Obligatoire	Nom de la colonne.
`description`	`STRING`	Facultatif	Description de la colonne.
`required`	`BOOL`	Obligatoire	Indique si la colonne est une fonction d'entrée requise pour effectuer une prédiction de modèle.
`dtype`	`STRING`	Obligatoire	Type de données de la colonne de valeur.
`domain`	`OBJECT`	Facultatif	Intervalle de valeurs autorisées pour la fonction.

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


Champ ou clé	Type	Obligatoire?	Description	Notes
`domain.constraints`	`LIST`	Facultatif	Prend en charge une liste de prédicats pour restreindre l'intervalle de valeurs autorisées pour la fonction. Vous pouvez entrer un modèle d'expression de chaîne propre à un langage, qui peut être évalué par l'interpréteur et le compilateur. Avec Python, le format de chaîne doit suivre `STRING`. Les contraintes peuvent être exprimé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 sommaires décrivant la fonction. Pour les types `float64` et `int64` : `X%` (où X est une valeur de centile comprise entre 1 et 99. Plusieurs valeurs de centile peuvent être saisies.) `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 fonction.
`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`	Obligatoire	Type de données Pandas des données. Par exemple : `int64 float category datettime`
`domain.dtype`	`STRING`	Obligatoire	Type de fonction 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 artifact_introspection_test dans votre 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 de vos artefacts et installez les tests d'introspection d'artefact.
```
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 des résultats de tests 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.

Utilisation d'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 déclenchée automatiquement 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 l'étape de préparation de l'artefact de modèle. Toutefois, si vous réglez ignore_introspection à False, l'introspection du modèle est effectuée lors de l'opération d'enregistrement.

Documentation sur Oracle Cloud Infrastructure

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

Métadonnées de provenance du 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 de 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

Utilisation d'ADS pour les tests d'introspection