Standardize DLC DSW EAS service tagging in PAI - Platform For AI

Les règles de tag permettent aux administrateurs d'espace de travail d'imposer un balisage cohérent sur DLC, DSW et EAS. Les administrateurs définissent les clés de tag requises, les valeurs prédéfinies, les descriptions et la portée des produits concernés. Lorsqu'une règle est active, les développeurs en machine learning doivent ajouter des tags aux jobs DLC, aux instances DSW et aux services EAS lors de leur création ; la validation s'effectue automatiquement. Un balisage uniforme facilite l'allocation des coûts, l'analyse de la répartition des jobs et le reporting de la consommation des ressources.

Définir des règles de tag

Remarque

Seuls les propriétaires et les administrateurs de l'espace de travail peuvent modifier les règles de tag.

Accédez à la page des détails de l'espace de travail, puis dans le coin supérieur droit, cliquez sur Configure Workspace > General Configurations.
Faites défiler jusqu'à la section Tag Configuration, puis cliquez sur Modify Configuration pour passer en mode édition.
Ajoutez les règles de tag selon vos besoins, puis cliquez sur Save. Les règles configurées s'appliquent à la portée de produit sélectionnée. Sur les pages des sous-produits correspondants, ces tags sont requis par défaut. Si un tag est manquant ou non conforme, la soumission échoue. Les développeurs en machine learning peuvent également ajouter des tags personnalisés en plus des tags obligatoires, à condition que les exigences relatives à la clé et à la valeur du tag soient respectées.
- Exigences relatives à la clé de tag Tag Key : ne doit pas commencer par aliyun ni par acs:, ne doit pas contenir http:// ni https://, et ne doit pas dépasser 128 caractères. Seules les lettres, les chiffres, les traits d'union (-), les caractères chinois et les points (.) sont autorisés ; les traits de soulignement (_) ne le sont pas.
- Exigences relatives à la valeur : ne doit pas contenir http:// ni https://, et ne doit pas dépasser 256 caractères. Séparez plusieurs valeurs énumérées par des virgules.
- Value Constraints : lorsque cette option est activée, les utilisateurs doivent sélectionner parmi les valeurs prédéfinies et ne peuvent pas saisir de valeurs personnalisées. Activez cette option pour garantir un balisage cohérent au sein de l'équipe.
- Applicable Services : sélectionnez les sous-produits (DLC, DSW ou EAS) auxquels cette règle s'applique. Au moins un sous-produit doit être sélectionné.

Appliquer des tags

Appliquez des tags conformément aux règles de tag de l'espace de travail lors de la soumission d'un job DLC ou de la création d'une instance DSW ou EAS. Les étapes suivantes utilisent la soumission d'un job DLC comme exemple :

Accédez à la console DLC et cliquez sur Create Job.
Sur la page de configuration du job, localisez la section Tag et renseignez les paires clé-valeur conformément aux règles de tag de l'espace de travail.

Vous pouvez également ajouter des tags personnalisés lors de la création du job.
Une fois tous les tags requis renseignés, soumettez le job.

Important

Les règles de tag sont validées lors de la soumission. Si un tag obligatoire est manquant ou si la valeur ne correspond pas à la règle, la soumission échoue avec un message d'erreur.

Filtrer les jobs par tag

Utilisez le filtrage par tag dans la liste des jobs DLC pour ventiler la répartition des jobs et l'utilisation des ressources par scénario, type de modèle ou autres critères.

Accédez à la page de liste des jobs de la console DLC.
Dans la barre de recherche, sélectionnez Tag comme condition de filtre, saisissez la clé et la valeur du tag, puis lancez la recherche. La liste affiche uniquement les jobs correspondant aux critères.

Annexe

Référence API

Pour configurer des règles de tag en masse ou les intégrer à des pipelines d'automatisation, utilisez les exemples de code suivants. Remplacez la région, l'ID de l'espace de travail ainsi que les valeurs AccessKey ID et Secret avant d'exécuter le code.

Configurer des règles de tag en masse

L'API UpdateConfigs prend en charge la configuration en masse des règles de tag prédéfinies et convient pour appliquer la même configuration de tag à plusieurs espaces de travail.

Structure type du corps de la requête :

{
  "Configs": [
    {
      "ConfigKey": "predefinedTags",
      "ConfigValue": "[{\"Type\":\"Tag\",\"Key\":\"scenario\",\"Value\":\"{\\\"Products\\\":\\\"DLC,DSW,EAS\\\",\\\"Values\\\":\\\"train,evluate,inference\\\",\\\"ValueFlexible\\\":false,\\\"Description\\\":\\\"select scenario\\\"}\"}]",
      "Labels": [
        {
          "Key": "system.categoryName",
          "Value": "CommonTagConfig"
        }
      ]
    }
  ]
}

Exemple de code Python : configurer des règles de tag en masse

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
PAI Workspace - Batch create/update predefined tag rules (CommonTagConfig)
API: PUT /api/v1/workspaces/{WorkspaceId}/configs
Before use, fill in ACCESS_KEY_ID, ACCESS_KEY_SECRET, REGION_ID, and WORKSPACE_ID,
and define tag rules in the TAGS list.
"""

import json, sys, hashlib, hmac, datetime, requests

ACCESS_KEY_ID     = "your-AccessKeyId"
ACCESS_KEY_SECRET = "your-AccessKeySecret"
REGION_ID         = "cn-hangzhou"
WORKSPACE_ID      = "your-workspace-ID"

ENDPOINT = f"aiworkspace.{REGION_ID}.aliyuncs.com"
API_PATH = f"/api/v1/workspaces/{WORKSPACE_ID}/configs"

# Tag definition: key-tag name, products-applicable products, values-allowed values, flexible-whether custom values are allowed, desc-description
TAGS = [
    {"key": "Scene",      "products": "DLC,DSW,EAS", "values": "Training,Evaluation,Inference",         "flexible": False, "desc": "Select the current use scenario"},
    {"key": "ModelType",  "products": "DLC,DSW",     "values": "NLP-Text,CV-Image,Multimodal",          "flexible": False, "desc": "Select the model type"},
    {"key": "ExpDirection","products": "DLC",         "values": "LR-Schedule,DataAugmentation,Distillation", "flexible": True, "desc": "Customize the experiment direction"},
]

def build_config_value(tags):
    arr = []
    for t in tags:
        inner = {"Products": t["products"], "Values": t["values"],
                 "ValueFlexible": t.get("flexible", False), "Description": t.get("desc", "")}
        arr.append({"Type": "Tag", "Key": t["key"], "Value": json.dumps(inner, ensure_ascii=False)})
    return json.dumps(arr, ensure_ascii=False)

def sign_request(method, path, headers, body):
    now = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
    headers.update({"x-acs-date": now, "x-acs-version": "2021-02-04",
                    "x-acs-action": "UpdateConfigs",
                    "x-acs-signature-nonce": hashlib.md5((now + body).encode()).hexdigest()})
    signed_keys = sorted(k for k in headers if k.startswith("x-acs-") or k in ("host", "content-type"))
    canonical_headers = "".join(f"{k}:{headers[k]}\n" for k in signed_keys)
    hashed_body = hashlib.sha256(body.encode("utf-8")).hexdigest()
    canonical_request = f"{method}\n{path}\n\n{canonical_headers}\n{';'.join(signed_keys)}\n{hashed_body}"
    string_to_sign = f"ACS3-HMAC-SHA256\n{hashlib.sha256(canonical_request.encode()).hexdigest()}"
    signature = hmac.new(ACCESS_KEY_SECRET.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()
    headers["Authorization"] = (f"ACS3-HMAC-SHA256 Credential={ACCESS_KEY_ID},"
                                 f"SignedHeaders={';'.join(signed_keys)},Signature={signature}")
    return headers

def main():
    config_value = build_config_value(TAGS)
    request_body = json.dumps({"Configs": [{"ConfigKey": "predefinedTags", "ConfigValue": config_value,
                                            "Labels": [{"Key": "system.categoryName", "Value": "CommonTagConfig"}]}]},
                              ensure_ascii=False)
    url = f"https://{ENDPOINT}{API_PATH}"
    headers = sign_request("PUT", API_PATH, {"host": ENDPOINT, "content-type": "application/json"}, request_body)
    resp = requests.put(url, headers=headers, data=request_body.encode("utf-8"), timeout=30)
    print(f"HTTP {resp.status_code}: {resp.text}")
    if resp.status_code != 200:
        sys.exit(1)

if __name__ == "__main__":
    main()

Spécifier des tags lors de la soumission d'un job DLC

Lors de la soumission d'un job DLC via l'API CreateJob, spécifiez les tags dans le champ Settings.Tags. Tous les tags requis doivent être renseignés. Les valeurs doivent être sélectionnées parmi les options prédéfinies, sauf pour les tags dont ValueFlexible est défini sur true, qui acceptent une saisie personnalisée.

Exemple de code Python : spécifier des tags lors de la soumission d'un job DLC

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
PAI-DLC Submit training job (with predefined tags)
API: POST /api/v1/jobs (API version 2020-12-03)
Tags are placed in Settings.Tags as a dictionary {"tag-name": "tag-value"}.
"""

import json, sys, hashlib, hmac, datetime, time, requests

ACCESS_KEY_ID     = "your-AccessKeyId"
ACCESS_KEY_SECRET = "your-AccessKeySecret"
REGION_ID         = "cn-hangzhou"
WORKSPACE_ID      = "your-workspace-ID"
RESOURCE_ID       = ""  # Resource quota ID; leave empty to use public resources

DLC_ENDPOINT = f"pai-dlc.{REGION_ID}.aliyuncs.com"
DLC_API_PATH = "/api/v1/jobs"

# Fill in according to the workspace predefined tags; all predefined tags must be provided
TAGS = {
    "Scene":        "Training",
    "ModelType":    "NLP-Text",
    "ExpDirection": "Fine-grained-DataProcessing",
}

def sign_request(method, path, headers, body, action="CreateJob"):
    now = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
    headers.update({"x-acs-date": now, "x-acs-version": "2020-12-03", "x-acs-action": action,
                    "x-acs-signature-nonce": hashlib.md5((now + body).encode()).hexdigest()})
    signed_keys = sorted(k for k in headers if k.startswith("x-acs-") or k in ("host", "content-type"))
    canonical_headers = "".join(f"{k}:{headers[k]}\n" for k in signed_keys)
    hashed_body = hashlib.sha256(body.encode("utf-8")).hexdigest()
    canonical_request = f"{method}\n{path}\n\n{canonical_headers}\n{';'.join(signed_keys)}\n{hashed_body}"
    string_to_sign = f"ACS3-HMAC-SHA256\n{hashlib.sha256(canonical_request.encode()).hexdigest()}"
    signature = hmac.new(ACCESS_KEY_SECRET.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()
    headers["Authorization"] = (f"ACS3-HMAC-SHA256 Credential={ACCESS_KEY_ID},"
                                 f"SignedHeaders={';'.join(signed_keys)},Signature={signature}")
    return headers

def main():
    job = {
        "DisplayName": f"my-training-job-{int(time.time())}",
        "JobType": "PyTorchJob",
        "WorkspaceId": WORKSPACE_ID,
        "UserCommand": "echo hello && sleep 5",
        "JobSpecs": [{"Type": "Worker",
                      "Image": "registry.cn-hangzhou.aliyuncs.com/pai-dlc/pytorch-training:1.12-gpu-py39-cu116-ubuntu20.04",
                      "PodCount": 1, "EcsSpec": "ecs.g6.large"}],
        "Settings": {"Tags": TAGS},  # Tags are placed in Settings.Tags
    }
    if RESOURCE_ID:
        job["ResourceId"] = RESOURCE_ID
    request_body = json.dumps(job, ensure_ascii=False)
    url = f"https://{DLC_ENDPOINT}{DLC_API_PATH}"
    headers = sign_request("POST", DLC_API_PATH, {"host": DLC_ENDPOINT, "content-type": "application/json"}, request_body)
    resp = requests.post(url, headers=headers, data=request_body.encode("utf-8"), timeout=30)
    print(f"HTTP {resp.status_code}: {resp.text}")
    if resp.status_code != 200:
        sys.exit(1)

if __name__ == "__main__":
    main()

Filtrer les jobs DLC par tag

L'API ListJobs prend en charge le filtrage par tag via le paramètre de requête Tags (au format chaîne JSON). Plusieurs tags utilisent une logique ET : tous les tags spécifiés doivent correspondre pour qu'un job apparaisse dans les résultats.

Exemple de code Python : filtrer les jobs DLC par tag

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import json
import sys
import hashlib
import hmac
import datetime
import requests
from urllib.parse import urlencode

ACCESS_KEY_ID     = "your-AccessKeyId"
ACCESS_KEY_SECRET = "your-AccessKeySecret"
REGION_ID         = "cn-hangzhou"
WORKSPACE_ID      = "your-workspace-ID"

ENDPOINT = f"pai-dlc.{REGION_ID}.aliyuncs.com"
API_PATH = "/api/v1/jobs"

def build_query_params(workspace_id, filter_tags, page_size=50, page_number=1):
    query_params = {
        "WorkspaceId": workspace_id,
        "PageSize": str(page_size),
        "PageNumber": str(page_number),
        "SortBy": "GmtCreateTime",
        "Order": "desc",
    }

    if filter_tags:
        query_params["Tags"] = json.dumps(
            filter_tags, ensure_ascii=False, separators=(",", ":")
        )

    return query_params

def sign_request(method, path, query_string, headers, body=""):
    now = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
    headers.update({
        "x-acs-date": now,
        "x-acs-version": "2020-12-03",
        "x-acs-action": "ListJobs",
        "x-acs-signature-nonce": hashlib.md5((now + query_string + body).encode()).hexdigest(),
    })

    normalized_headers = {k.lower(): v for k, v in headers.items()}
    signed_keys = sorted(
        k for k in normalized_headers
        if k.startswith("x-acs-") or k in ("host", "content-type")
    )

    canonical_headers = "".join(f"{k}:{normalized_headers[k]}\n" for k in signed_keys)
    hashed_body = hashlib.sha256(body.encode("utf-8")).hexdigest()

    canonical_request = (
        f"{method}\n"
        f"{path}\n"
        f"{query_string}\n"
        f"{canonical_headers}\n"
        f"{';'.join(signed_keys)}\n"
        f"{hashed_body}"
    )

    string_to_sign = f"ACS3-HMAC-SHA256\n{hashlib.sha256(canonical_request.encode()).hexdigest()}"
    signature = hmac.new(
        ACCESS_KEY_SECRET.encode(),
        string_to_sign.encode(),
        hashlib.sha256
    ).hexdigest()

    headers["Authorization"] = (
        f"ACS3-HMAC-SHA256 Credential={ACCESS_KEY_ID},"
        f"SignedHeaders={';'.join(signed_keys)},"
        f"Signature={signature}"
    )
    return headers

def list_jobs_by_tags(filter_tags, page_size=50, page_number=1):
    query_params = build_query_params(WORKSPACE_ID, filter_tags, page_size, page_number)
    query_string = urlencode(sorted(query_params.items()))
    url = f"https://{ENDPOINT}{API_PATH}?{query_string}"

    headers = {
        "host": ENDPOINT,
        "content-type": "application/json",
    }
    headers = sign_request("GET", API_PATH, query_string, headers, body="")

    resp = requests.get(url, headers=headers, timeout=30)
    print(f"HTTP {resp.status_code}")
    print(resp.text)

    if resp.status_code != 200:
        sys.exit(1)

    return resp.json()

def main():
    filter_tags = {"Scene": "Training"}
    list_jobs_by_tags(filter_tags)

if __name__ == "__main__":
    main()

Consulter l'historique des modifications de tag

ActionTrail enregistre toutes les modifications apportées aux règles de tag, y compris l'opérateur, l'horodatage et les éléments modifiés.

Connectez-vous à la console ActionTrail, accédez à Advanced query, définissez le nom du service sur PAI et le nom de l'événement sur UpdateConfigs, puis filtrez les enregistrements dont ConfigKey est predefinedTags pour consulter l'historique des modifications des règles de tag.