DataWorks:Análise semântica do Data Agent

Visão geral

Para executar tarefas como NLQ e geração de SQL, o Data Agent precisa compreender a estrutura e a semântica dos dados de negócios. O recurso de análise semântica verifica automaticamente as tabelas da fonte de dados MaxCompute, extrai relacionamentos entre tabelas, definições de campos e lógicas de cálculo de métricas e gera um modelo semântico estruturado no formato YAML. O modelo apresenta os resultados da análise por meio de uma visualização dupla com gráfico e código-fonte, ajudando você a entender intuitivamente as relações entre seus ativos de dados.

Com a análise semântica, você pode:

• Organizar automaticamente as relações de ativos de dados: O sistema identifica estruturas de tabelas, semântica de campos e relacionamentos entre tabelas sem necessidade de esforço manual.

• Gerar gráficos semânticos visuais: Exibe as relações entre conjuntos de dados e métricas em formato de gráfico, com navegação em painel duplo entre o gráfico e o código-fonte YAML.

• Melhorar a precisão das consultas de IA: Carregue o modelo semântico no contexto da sessão do Data Agent (usando o comando /dataworks-semantic) para que a IA gere SQL mais preciso com base na semântica de negócios.

• Permitir correções e iterações manuais: Edite e salve os resultados da análise online. As alterações entram em vigor imediatamente, sem necessidade de reexecutar a tarefa.

Da fonte de dados MaxCompute até a consulta precisa de dados, a análise semântica abrange cinco etapas principais:

Pré-requisitos

• O Data Agent deve estar ativado. Caso contrário, consulte Activation process para concluir a ativação.

• Uma fonte de dados MaxCompute disponível deve estar configurada em seu workspace.

• Um grupo de recursos disponível deve estar pronto. Recomendamos uma especificação de pelo menos 4 CU.

Etapa 1: Criar uma tarefa de análise semântica

1. Acesse Data Agent Settings. No painel de navegação à esquerda, clique em Semantic Analysis.

2. Na página de lista Semantic Analysis, clique em Create Task.

3. Na caixa de diálogo Create Task, configure os seguintes parâmetros:

   Parameter	Description
   Name	Obrigatório. O formato deve obedecer aos requisitos descritos nos limites de uso.
   Data Source Type	Obrigatório. Atualmente, apenas o MaxCompute é suportado.
   Business Domain & Focus	Obrigatório. Use linguagem natural para descrever o domínio de negócios e a camada de tabela que você deseja que a análise foque. Por exemplo, "Domínio de livestream de e-commerce, cobrindo dimensões de vendas de âncoras e vendas de produtos, camadas DWD a ADS." Este parâmetro tem uma dupla finalidade: Orienta a direção da análise: Indica à IA quais dimensões de negócios priorizar, guiando-a na extração de métricas e relacionamentos relevantes. Define o escopo da varredura de código: A IA usa a descrição do domínio de negócios para localizar códigos e tarefas de agendamento relevantes por meio da estrutura de pastas do DataWorks no workspace. Por exemplo, se você escrever "domínio de livestream de e-commerce", a IA focará na análise de nós nas pastas "e-commerce" e "livestream", em vez de verificar todo o workspace. Descrições mais detalhadas resultam em uma análise de tabelas mais precisa e uma varredura de código mais focada.
   Workspace	Obrigatório. Selecione um workspace do DataWorks na lista suspensa. Este workspace não é apenas um ambiente de execução, mas também a fonte de conhecimento de negócios da IA. A IA lê scripts SQL, tarefas de agendamento e estruturas de pastas de código deste workspace para interpretar a lógica real de cálculo de métricas. Por exemplo, ela extrai expressões como SUM(CASE WHEN order_status='paid' THEN pay_amount END) do código SQL para entender como as métricas são realmente calculadas. Importante Certifique-se de selecionar o workspace que contém seu código de processamento de dados. Se você selecionar o workspace errado, a IA não conseguirá ler o código de processamento real e só poderá inferir os significados das métricas a partir dos comentários dos campos, levando a inconsistências entre o modelo e os cálculos reais.
   Resource Group	Obrigatório. Selecione o grupo de recursos usado para executar a tarefa.
   Pinned Tables	Obrigatório. No seletor em cascata, expanda um projeto MaxCompute no painel esquerdo e selecione tabelas específicas no painel direito. É possível selecionar tabelas em vários projetos, até 30 tabelas no total. O modelo focará na análise das estruturas e relacionamentos dessas tabelas.
   Reference Files	Opcional. Faça upload de arquivos ou insira URLs de arquivos para fornecer materiais de referência externos.

4. Após concluir a configuração, clique no botão ok na parte inferior da caixa de diálogo. Depois que o sistema exibir a mensagem "Task created", a lista será atualizada automaticamente.

Etapa 2: Executar uma tarefa de análise semântica

Após criar uma tarefa, execute-a da seguinte forma:

1. Na página de lista Semantic Analysis, localize a tarefa desejada e clique em Run na coluna Actions.

2. O sistema exibe uma mensagem "Run submitted" e abre automaticamente a caixa de diálogo de detalhes da tarefa.

Depois que a tarefa é enviada, o sistema executa a análise semântica em segundo plano. O tempo de execução depende da quantidade e do volume das tabelas analisadas, levando geralmente alguns minutos. O mecanismo de IA realiza a análise a partir de duas dimensões simultaneamente:

• Dimensão 1: Leitura de scripts SQL e tarefas de agendamento do workspace. Com base na descrição do domínio de negócios, a IA localiza o código relevante através da estrutura de pastas do DataWorks e interpreta a lógica real de cálculo de métricas e os relacionamentos de processamento entre tabelas a partir do SQL.

• Dimensão 2: Varredura de metadados das tabelas fixadas. A IA extrai a semântica de negócios de cada campo, sinônimos, relacionamentos de camadas entre tabelas, definições de métricas de negócios, fórmulas de métricas derivadas e pares de perguntas e respostas de exemplo.

Os resultados da análise de ambas as dimensões são validados cruzadamente e mesclados em um único modelo semântico abrangente.

Etapa 3: Visualizar detalhes da tarefa e status de execução

Clique no nome de uma tarefa na lista de tarefas para abrir a caixa de diálogo de detalhes da tarefa. Os detalhes contêm as seguintes abas:

Etapa 4: Visualizar e editar o modelo semântico

Acesse a aba Run History e clique em View Results em um registro de execução com status "Success" para abrir o visualizador de resultados do modelo semântico.

O visualizador de resultados fornece uma visualização em painel duplo do gráfico e do código-fonte:

• Gráfico do modelo semântico: Exibe as relações entre conjuntos de dados em formato visual. Os nós no gráfico representam conjuntos de dados ou métricas, e as arestas representam as relações entre eles. Ao clicar em um nó ou aresta no gráfico, o editor de código-fonte à direita rola automaticamente até a linha correspondente e a destaca.

• Editor de código-fonte YAML: Exibe o código-fonte YAML do modelo semântico. A estrutura de nível superior inclui definições de conjuntos de dados, descrições de campos, ai_context e outras informações. Conforme você navega pelo código-fonte, o gráfico à esquerda destaca e centraliza automaticamente o nó ou aresta correspondente.

O visualizador de resultados também oferece suporte aos seguintes recursos:

• Visualização em tela cheia: Clique no botão Fullscreen para visualizar o gráfico ou o código-fonte em modo de tela cheia.

• Editar e salvar: Clique em Edit para entrar no modo de edição. Após modificar o conteúdo YAML, clique em Save para gravar as alterações no back-end. As alterações entram em vigor imediatamente após o salvamento, sem necessidade de reexecutar a tarefa. Para descartar alterações, clique em Reset para restaurar a última versão salva. Você também pode usar Compare Changes para visualizar as diferenças.

Estrutura YAML do modelo semântico

O modelo semântico gerado pelo mecanismo de IA usa o formato YAML com quatro módulos principais no nível superior:

A seguir, um exemplo simplificado de código-fonte 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]

Etapa 5: Carregar e usar o modelo semântico no Data Agent

Após gerar um modelo semântico YAML pelas etapas anteriores, o modelo reside no lado do servidor. As sessões de chat do Data Agent não o acessam automaticamente. Você deve carregar explicitamente o modelo semântico em uma sessão do Agent para que a IA possa referenciar o conhecimento de negócios nele contido ao responder perguntas.

Procedimento:

1. Abra Data Agent e entre na janela de chat.

2. Digite /dataworks-semantic na caixa de entrada do chat e envie.

3. O Agent executa automaticamente: verificação de ambiente → lista de tarefas disponíveis → download da saída YAML → injeção no contexto de IA da sessão atual.

4. Após confirmar o carregamento bem-sucedido, comece a consultar e gerar SQL com base no modelo semântico.

Para baixar manualmente os arquivos de resultados, acesse a aba Run History no console e clique em Download Results em um registro de execução bem-sucedida para obter os arquivos de saída YAML.

Os cenários a seguir apresentam melhorias significativas de qualidade após o carregamento de um modelo semântico:

Exemplo de cenário: Passo a passo de ponta a ponta de livestream de e-commerce

O exemplo a seguir percorre o fluxo de trabalho completo, desde a criação da tarefa até a consulta precisa, usando um cenário de livestream de e-commerce.

1. Criar uma tarefa (Etapa 1)

Na página Semantic Analysis, clique em Create Task e preencha a seguinte configuração:

2. Executar a tarefa (Etapa 2)

Clique em Run. O mecanismo semântico de IA executa automaticamente a seguinte análise: localiza pastas do workspace correspondentes ao "domínio de livestream de e-commerce" e lê scripts SQL → extrai lógica real de cálculo de métricas do código (por exemplo, descobre que gmv = SUM(CASE WHEN order_status='paid' THEN pay_amount END)) → verifica metadados e relacionamentos de campos nas 4 tabelas → identifica hierarquias de camadas ADS/DWS → gera um modelo YAML estruturado contendo definições de métricas, fórmulas derivadas e SQL de exemplo.

3. Visualizar e editar o modelo (Etapas 3 e 4)

Após a conclusão da tarefa, abra a aba Semantic Model na página de detalhes da tarefa. Use a visualização de gráfico para verificar os relacionamentos entre tabelas e ajuste as definições de métricas ou adicione contexto de negócios no editor YAML. Salve suas alterações quando estiver satisfeito.

4. Carregar no Data Agent (Etapa 5)

Em uma sessão do Data Agent, execute /dataworks-semantic download <job-name> seguido por /dataworks-semantic index <job-name> para baixar o modelo localmente e construir o índice. Todas as consultas subsequentes nessa sessão aproveitarão o modelo semântico para respostas precisas.

5. Verificar os resultados

Após o carregamento, compare a qualidade das respostas do Agent para as mesmas perguntas antes e depois:

Pergunta do usuário: "Quem foram os 10 principais âncoras por GMV ontem?"

-- 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;

Pergunta do usuário: "Qual é o valor médio do pedido por categoria nos últimos 30 dias?"

-- 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;

Após carregar um modelo semântico, a IA referencia automaticamente ai_context (instruções de negócios), metrics (definições e sinônimos), metric_formulas (fórmulas derivadas) e datasets (mapeamentos de tabelas e campos), transformando a "adivinhação" em "geração precisa baseada em conhecimento".

Perguntas frequentes

P: Quais são as possíveis causas de falha na tarefa?

R: Falhas na tarefa geralmente são causadas pelos seguintes motivos:

• Especificação insuficiente do grupo de recursos: Tarefas podem falhar devido a recursos insuficientes quando a especificação do grupo de recursos é inferior a 4 CU. Recomendamos selecionar um grupo de recursos com especificação de pelo menos 4 CU.

• Permissões insuficientes no projeto MaxCompute: O workspace que executa a tarefa de análise semântica deve ter permissões de leitura no projeto MaxCompute alvo. Verifique a relação de vinculação e a configuração de permissões entre o workspace e o projeto MaxCompute.

• Volume excessivo de dados: Muitas tabelas ou muitos dados em uma única execução de análise podem causar timeout. Recomendamos reduzir o número de tabelas fixadas e tentar novamente.

P: Preciso reexecutar a tarefa após editar o YAML?

R: Não. Após editar e salvar o YAML no visualizador de resultados, as alterações entram em vigor imediatamente. Na próxima vez que você baixar via /dataworks-semantic, a versão mais recente será recuperada automaticamente.

P: Recebo um erro de expiração de token ao usar o modelo semântico no Data Agent.

R: Execute /dataworks-semantic check para verificar o ambiente. Se erros relacionados à autenticação aparecerem, atualize suas credenciais de autenticação e tente novamente.

P: Vejo "local edits detected" ao baixar. O que devo fazer?

R: Isso significa que o arquivo YAML foi modificado após o último download (incompatibilidade de hash). Para sobrescrever as alterações locais, adicione a flag --force para forçar o download. Recomendamos fazer backup de suas edições locais primeiro.

Documentação relacionada

• Data Agent billing

• Data Agent