DataWorks:Analyse sémantique de Data Agent

Vue d'ensemble

Pour exécuter des tâches telles que la NLQ et la génération SQL, Data Agent doit comprendre la structure et la sémantique des données métier. La fonctionnalité d'analyse sémantique analyse automatiquement les tables de la source de données MaxCompute, extrait les relations entre les tables, les définitions des champs et la logique de calcul des métriques, puis génère un modèle sémantique structuré au format YAML. Le modèle présente les résultats d'analyse via une vue graphique visuelle et un panneau de code source, vous aidant à comprendre intuitivement les relations entre vos actifs de données.

Grâce à l'analyse sémantique, vous pouvez :

• Organiser automatiquement les relations entre les actifs de données : Le système identifie automatiquement les structures de table, la sémantique des champs et les relations inter-tables sans intervention manuelle.

• Générer des graphes sémantiques visuels : Affichez les relations entre les ensembles de données et les métriques sous forme de graphe, avec une navigation bidirectionnelle entre le graphe et le code source YAML.

• Améliorer la précision des requêtes IA : Chargez le modèle sémantique dans le contexte d'une session Data Agent (à l'aide de la commande /dataworks-semantic) afin que l'IA puisse générer du SQL plus précis basé sur la sémantique métier.

• Prendre en charge les corrections et itérations manuelles : Les résultats d'analyse peuvent être modifiés et enregistrés en ligne. Les modifications prennent effet immédiatement sans nécessiter de réexécution de la tâche.

De la source de données MaxCompute à la requête de données précise, l'analyse sémantique couvre cinq étapes clés :

Prérequis

• Vous avez activé Data Agent. Si ce n'est pas le cas, consultez le Processus d'activation pour finaliser l'activation.

• Une source de données MaxCompute disponible est configurée dans votre espace de travail.

• Un groupe de ressources disponible est prêt. Nous recommandons une spécification d'au moins 4 CU.

Étape 1 : Créer une tâche d'analyse sémantique

1. Accédez aux Paramètres de Data Agent. Dans le volet de navigation de gauche, cliquez sur Semantic Analysis.

2. Sur la page de liste Semantic Analysis, cliquez sur Create Task.

3. Dans la boîte de dialogue Create Task, configurez les paramètres suivants :

   Parameter	Description
   Name	Obligatoire. Le format doit respecter les exigences décrites dans les limites d'utilisation.
   Data Source Type	Obligatoire. Actuellement, seul MaxCompute est pris en charge.
   Business Domain & Focus	Obligatoire. Décrivez en langage naturel le domaine métier et la couche de table sur lesquels l'analyse doit se concentrer. Par exemple : « Domaine du livestream e-commerce, couvrant les dimensions des ventes des animateurs et des ventes de produits, couches DWD à ADS. » Ce paramètre a une double utilité : Guide la direction de l'analyse : Indique à l'IA quelles dimensions métier prioriser, l'orientant vers l'extraction des métriques et relations pertinentes. Définit la portée de l'analyse du code : L'IA utilise la description du domaine métier pour localiser le code pertinent et les tâches de planification via la structure des dossiers DataWorks dans l'espace de travail. Par exemple, si vous indiquez « domaine du livestream e-commerce », l'IA se concentre sur l'analyse des nœuds situés sous les dossiers « e-commerce » et « livestream » plutôt que d'analyser l'intégralité de l'espace de travail. Des descriptions plus détaillées conduisent à une analyse des tables plus précise et à une analyse du code plus ciblée.
   Workspace	Obligatoire. Sélectionnez un espace de travail DataWorks dans la liste déroulante. Cet espace de travail n'est pas seulement un environnement d'exécution, mais aussi la source de connaissances métier de l'IA. L'IA lit les scripts SQL, les tâches de planification et les structures de dossiers de code depuis cet espace de travail pour interpréter la logique réelle de calcul des métriques. Par exemple, elle extrait des expressions telles que SUM(CASE WHEN order_status='paid' THEN pay_amount END) du code SQL pour comprendre comment les métriques sont réellement calculées. Important Assurez-vous de sélectionner l'espace de travail contenant votre code de traitement des données. Si vous sélectionnez le mauvais espace de travail, l'IA ne peut pas lire le code de traitement réel et ne peut déduire la signification des métriques qu'à partir des commentaires de champ, ce qui entraîne des incohérences entre le modèle et les calculs réels.
   Resource Group	Obligatoire. Sélectionnez le groupe de ressources utilisé pour exécuter la tâche.
   Pinned Tables	Obligatoire. Dans le sélecteur en cascade, développez un projet MaxCompute dans le panneau de gauche et sélectionnez des tables spécifiques dans le panneau de droite. Vous pouvez sélectionner des tables provenant de différents projets, jusqu'à 30 tables au total. Le modèle se concentrera sur l'analyse des structures et des relations de ces tables.
   Reference Files	Facultatif. Téléchargez des fichiers ou saisissez des URL de fichiers pour fournir des documents de référence externes.

4. Une fois la configuration terminée, cliquez sur le bouton ok en bas de la boîte de dialogue. Après l'affichage du message « Task created » par le système, la liste s'actualise automatiquement.

Étape 2 : Exécuter une tâche d'analyse sémantique

Après la création d'une tâche, exécutez-la comme suit :

1. Sur la page de liste Semantic Analysis, repérez la tâche cible et cliquez sur Run dans la colonne Actions.

2. Le système affiche un message « Run submitted » et ouvre automatiquement la boîte de dialogue des détails de la tâche.

Une fois la tâche soumise, le système exécute l'analyse sémantique en arrière-plan. Le temps d'exécution dépend du nombre et du volume des tables analysées, et prend généralement plusieurs minutes. Le moteur IA effectue l'analyse selon deux dimensions simultanément :

• Dimension 1 : Lecture des scripts SQL et des tâches de planification depuis l'espace de travail. Sur la base de la description du domaine métier, l'IA localise le code pertinent via la structure des dossiers DataWorks et interprète la logique réelle de calcul des métriques et les relations de traitement entre les tables à partir du SQL.

• Dimension 2 : Analyse des métadonnées des tables épinglées. L'IA extrait la sémantique métier de chaque champ, les synonymes, les relations entre les couches de tables, les définitions des métriques métier, les formules de métriques dérivées et des exemples de paires questions-réponses.

Les résultats d'analyse des deux dimensions sont recoupés et fusionnés en un seul modèle sémantique complet.

Étape 3 : Consulter les détails de la tâche et l'état d'exécution

Cliquez sur un nom de tâche dans la liste des tâches pour ouvrir la boîte de dialogue des détails de la tâche. Les détails de la tâche contiennent les onglets suivants :

Étape 4 : Consulter et modifier le modèle sémantique

Accédez à l'onglet Run History et cliquez sur View Results pour un enregistrement d'exécution dont l'état est « Success » afin d'ouvrir la visionneuse de résultats du modèle sémantique.

La visionneuse de résultats offre une vue bidirectionnelle du graphe et du code source :

• Graphe du modèle sémantique : Affiche les relations entre les ensembles de données sous forme visuelle. Les nœuds du graphe représentent des ensembles de données ou des métriques, et les arêtes représentent les relations entre eux. Cliquez sur un nœud ou une arête dans le graphe, et l'éditeur de code source à droite fait défiler automatiquement la vue jusqu'à la ligne correspondante et la met en surbrillance.

• Éditeur de code source YAML : Affiche le code source YAML du modèle sémantique. La structure de niveau supérieur comprend les définitions des ensembles de données, les descriptions des champs, ai_context et d'autres informations. Lorsque vous parcourez le code source, le graphe à gauche met automatiquement en surbrillance et centre la vue sur le nœud ou l'arête correspondant.

La visionneuse de résultats prend également en charge les fonctionnalités suivantes :

• Vue plein écran : Cliquez sur le bouton Fullscreen pour afficher le graphe ou le code source en mode plein écran.

• Modifier et enregistrer : Cliquez sur Edit pour entrer en mode édition. Après avoir modifié le contenu YAML, cliquez sur Save pour écrire les modifications dans le backend. Les modifications prennent effet immédiatement après l'enregistrement, sans nécessiter de réexécution de la tâche. Pour annuler les modifications, cliquez sur Reset pour restaurer la dernière version enregistrée. Vous pouvez également utiliser Compare Changes pour visualiser les différences.

Structure YAML du modèle sémantique

Le modèle sémantique généré par le moteur IA utilise le format YAML avec quatre modules principaux au niveau supérieur :

Voici un exemple simplifié de code source YAML :

semantic_model:
  - ai_context:
      instructions: |
        E-commerce livestream data analysis domain. Covers anchor sales
        and product sales dimensions.
        Data layers: ODS → DWD → DWS → ADS
        Partition field: dt. Currency: CNY.
      few_shots:
        - question: Who are the top 10 anchors by GMV yesterday?
          sql: |
            SELECT anchor_name, gmv
            FROM ads_ctlive_anchor_stats
            WHERE stat_period = '1d'
            ORDER BY gmv DESC LIMIT 10;

    metrics:
      - name: GMV
        description: Total transaction amount (CNY)
        ai_context:
          synonyms: [sales amount, transaction volume, revenue]
        expression:
          dialects:
            - dialect: MaxCompute
              expression: SUM(gmv)

    metric_formulas:
      - name: Average Order Value
        description: Average transaction amount per order (CNY)
        formula: GMV / Order Count

    datasets:
      - source: ads_ctlive_anchor_stats
        description: ADS - Anchor transaction statistics
        fields:
          - name: anchor_name
            type: string
            description: Anchor nickname
            synonyms: [anchor, streamer, host]
          - name: gmv
            type: double
            description: Total transaction amount (CNY)
            metric: true
            synonyms: [sales amount, GMV, revenue]

Étape 5 : Charger et utiliser le modèle sémantique dans Data Agent

Après avoir généré un modèle sémantique YAML via les étapes précédentes, le modèle réside côté serveur. Les sessions de chat Data Agent n'y accèdent pas automatiquement. Vous devez charger explicitement le modèle sémantique dans une session Agent afin que l'IA puisse référencer les connaissances métier qu'il contient lors de la réponse aux questions.

Procédure :

1. Ouvrez Data Agent et accédez à la fenêtre de chat.

2. Saisissez /dataworks-semantic dans la zone de saisie du chat et envoyez-le.

3. L'Agent exécute automatiquement les opérations suivantes : vérification de l'environnement → liste des tâches disponibles → téléchargement de la sortie YAML → injection dans le contexte IA de la session actuelle.

4. Après avoir confirmé le chargement réussi, commencez à interroger et à générer du SQL basé sur le modèle sémantique.

Pour télécharger manuellement les fichiers de résultats, accédez à l'onglet Run History dans la console et cliquez sur Download Results pour un enregistrement d'exécution réussi afin d'obtenir les fichiers de sortie YAML.

Les scénarios suivants voient leur qualité s'améliorer considérablement après le chargement d'un modèle sémantique :

Exemple de scénario : Parcours complet du livestream e-commerce

Ce qui suit décrit le flux de travail complet, de la création de la tâche à la requête précise, en utilisant un scénario de livestream e-commerce.

1. Créer une tâche (Étape 1)

Sur la page Semantic Analysis, cliquez sur Create Task et remplissez la configuration suivante :

2. Exécuter la tâche (Étape 2)

Cliquez sur Run. Le moteur sémantique IA effectue automatiquement l'analyse suivante : il localise les dossiers de l'espace de travail correspondant au « domaine du livestream e-commerce » et lit les scripts SQL → extrait la logique réelle de calcul des métriques à partir du code (par exemple, découvre que gmv = SUM(CASE WHEN order_status='paid' THEN pay_amount END)) → analyse les métadonnées et les relations entre les champs des 4 tables → identifie les hiérarchies des couches ADS/DWS → génère un modèle YAML structuré contenant les définitions de métriques, les formules dérivées et des exemples SQL.

3. Consulter et modifier le modèle (Étapes 3 et 4)

Une fois la tâche terminée, ouvrez l'onglet Semantic Model sur la page des détails de la tâche. Utilisez la vue graphique pour vérifier les relations entre les tables, et ajustez les définitions de métriques ou ajoutez du contexte métier dans l'éditeur YAML. Enregistrez vos modifications une fois satisfait.

4. Charger dans Data Agent (Étape 5)

Dans une session Data Agent, exécutez /dataworks-semantic download <job-name> suivi de /dataworks-semantic index <job-name> pour télécharger le modèle localement et construire l'index. Toutes les requêtes ultérieures dans cette session tireront parti du modèle sémantique pour des réponses précises.

5. Vérifier les résultats

Après le chargement, comparez la qualité des réponses de l'Agent pour les mêmes questions avant et après :

Question de l'utilisateur : « Qui étaient les 10 meilleurs animateurs par GMV hier ? »

-- AI guesses table and field names
SELECT host_name, total_amount
FROM live_stream_sales
WHERE date = '2026-07-27'
ORDER BY total_amount DESC
LIMIT 10;

-- Generated based on semantic model
    SELECT anchor_name, gmv
    FROM ads_ctlive_anchor_stats
    WHERE stat_period = '1d'
    ORDER BY gmv DESC
    LIMIT 10;

Question de l'utilisateur : « Quelle est la valeur moyenne de commande par catégorie au cours des 30 derniers jours ? »

-- AI misunderstands "average order value"
SELECT category, AVG(price) AS avg_price
FROM products
GROUP BY category;

-- Model knows: avg order value = GMV / order count
    SELECT cate_level1_name,
      SUM(gmv) / SUM(order_cnt) AS avg_order_value
    FROM ads_ctlive_item_stats
    WHERE stat_period = '30d'
    GROUP BY cate_level1_name
    ORDER BY avg_order_value DESC;

Après le chargement d'un modèle sémantique, l'IA référence automatiquement ai_context (instructions métier), metrics (définitions et synonymes), metric_formulas (formules dérivées) et datasets (mappages de tables et de champs), passant de la « supposition » à la « génération précise basée sur les connaissances ».

FAQ

Q : Quelles sont les causes possibles d'un échec de tâche ?

R : Les échecs de tâche sont généralement causés par les raisons suivantes :

• Spécification insuffisante du groupe de ressources : Les tâches peuvent échouer en raison de ressources insuffisantes lorsque la spécification du groupe de ressources est inférieure à 4 CU. Nous vous recommandons de sélectionner un groupe de ressources avec une spécification d'au moins 4 CU.

• Autorisations insuffisantes sur le projet MaxCompute : L'espace de travail qui exécute la tâche d'analyse sémantique doit disposer d'autorisations de lecture sur le projet MaxCompute cible. Vérifiez la relation de liaison et la configuration des autorisations entre l'espace de travail et le projet MaxCompute.

• Volume de données excessif : Un nombre trop élevé de tables ou un volume de données trop important lors d'une seule exécution d'analyse peut provoquer un délai d'expiration. Nous vous recommandons de réduire le nombre de tables épinglées et de réessayer.

Q : Dois-je réexécuter la tâche après avoir modifié le YAML ?

R : Non. Après avoir modifié et enregistré le YAML dans la visionneuse de résultats, les modifications prennent effet immédiatement. La prochaine fois que vous effectuerez un téléchargement via /dataworks-semantic, la dernière version sera automatiquement récupérée.

Q : J'obtiens une erreur d'expiration de jeton lors de l'utilisation du modèle sémantique dans Data Agent.

R : Exécutez /dataworks-semantic check pour vérifier l'environnement. Si des erreurs liées à l'authentification apparaissent, actualisez vos identifiants d'authentification et réessayez.

Q : Je vois « local edits detected » lors du téléchargement. Que dois-je faire ?

R : Cela signifie que le fichier YAML a été modifié après le dernier téléchargement (incompatibilité de hachage). Pour écraser les modifications locales, ajoutez l'indicateur --force pour forcer le téléchargement. Nous vous recommandons de sauvegarder vos modifications locales au préalable.

Documentation connexe

• Facturation de Data Agent

• Data Agent