Controle do código-fonte, CI/CD e ALM para agente de dados de malha (visualização)

Este artigo descreve como gerenciar agentes de dados do Fabric usando pipelines de integração e implantação do Git como parte dos recursos do Application Lifecycle Management (ALM) do Microsoft Fabric. Você aprende a conectar um espaço de trabalho a um repositório Git. Você também aprenderá como controlar e formatar as configurações do agente de dados. Finalmente, você aprenderá como promover atualizações em ambientes de desenvolvimento, teste e produção. Os pipelines de integração e implantação do Git permitem a integração contínua e a implantação contínua (CI/CD) de alterações no agente de dados, permitindo que as atualizações sejam testadas e promovidas automaticamente como parte do seu fluxo de trabalho de ALM. O controle do código-fonte para agentes de dados do Fabric está atualmente em visualização.

Você pode usar duas abordagens complementares para dar suporte a agentes de dados ALM for Fabric:

• Integração com Git: sincronize um espaço de trabalho inteiro com um repositório Git (Azure DevOps ou GitHub como um provedor Git) para habilitar o controle de versão, a colaboração por meio de ramificações e o rastreamento de histórico para itens individuais, incluindo agentes de dados do Fabric.
• Pipelines de implantação: promova conteúdo entre espaços de trabalho separados que representam estágios de desenvolvimento, teste e produção usando pipelines internos.

Esses recursos juntos fornecem suporte ALM completo para agentes de dados Fabric.

Pré-requisitos

• Uma capacidade paga de Fabric F2 ou superior ou uma capacidade do Power BI Premium por capacidade (P1 ou superior) com o Microsoft Fabric ativado
• As configurações do locatário do agente de dados de infraestrutura estão habilitadas.
• O processamento geográfico cruzado para IA está habilitado.
• O armazenamento geográfico cruzado para IA está habilitado.
• Pelo menos um destes, com dados: um armazém, uma casa de lago, um ou mais modelos semânticos Power BI, uma base de dados KQL ou uma ontologia.
• Os modelos semânticos do Power BI por meio da opção de locatário de pontos de extremidade XMLA estão habilitados para fontes de dados de modelo semântico do Power BI.

Integração Git

A integração do Microsoft Fabric Git sincroniza um espaço de trabalho do Fabric com um repositório Git, permitindo que você use seus processos de desenvolvimento, ferramentas e práticas recomendadas existentes diretamente na plataforma Fabric. Ele dá suporte ao Azure DevOps e ao GitHub e está disponível no nível do espaço de trabalho. Quando você confirma alterações do Fabric, incluindo atualizações na configuração do agente de dados, essas alterações são salvas como arquivos no repositório Git conectado. As suas principais capacidades incluem:

• Backup completo e controle de versão de itens do espaço de trabalho
• A estrutura de pastas no Git espelha a estrutura do espaço de trabalho
• As configurações do agente de dados (seleção de esquema, instruções de IA, instruções de fonte de dados, consultas de exemplo) são armazenadas em arquivos estruturados em pastas dedicadas
• Capacidade de visualizar diferenças, revisar o histórico e reverter para estados anteriores por meio do histórico para diferentes itens do espaço de trabalho, incluindo agentes de dados
• Colaboração baseada em ramificações (ramificações de funcionalidades, ramo principal)

Para obter mais informações sobre o processo de integração do Git, consulte os seguintes recursos.

• O que é a integração do Microsoft Fabric Git?
• Conceitos básicos em integração Git
• Introdução à integração com o Git

Configurar uma conexão com o controle do código-fonte

Você pode conectar seu espaço de trabalho do Fabric a um repositório Git na página Configurações do espaço de trabalho . Essa conexão permite confirmar e sincronizar alterações diretamente do Fabric.

1. Consulte Introdução à integração do Git para obter etapas detalhadas para se conectar a um repositório Git no Azure DevOps ou no GitHub.

2. Depois de se conectar ao repositório Git, os itens do espaço de trabalho, incluindo os agentes de dados do Fabric, aparecem no painel de controle Origem. Na barra de status no canto inferior esquerdo, você pode ver o nome da ramificação conectada, a hora da última sincronização e o ID de confirmação do Git.

3. O repositório Git vinculado exibe uma estrutura de pastas que representa os itens do espaço de trabalho, incluindo agentes de dados do Fabric e seus arquivos de configuração. Cada agente de dados é armazenado em sua própria pasta, permitindo que você revise as alterações, acompanhe o histórico de versões e use fluxos de trabalho do Git, como a criação de solicitações pull para mesclar atualizações em sua ramificação principal.

4. Quando o utilizador faz modificações no Fabric data agent em um espaço de trabalho conectado ao Git, as alterações são detetadas e o estado do agente de dados no painel de controlo de origem muda para Alterações não submetidas. Essas modificações podem incluir:

   • Modificando a seleção de esquema.
   • Atualização de instruções de IA ou instruções de fonte de dados.
   • Edição de consultas de exemplo.
   • Publicar o agente de dados ou atualizar sua descrição de publicação.

Qualquer alteração, seja funcional ou descritiva, faz com que o agente de dados fique fora de sincronia com o repositório Git vinculado. Os itens do espaço de trabalho com alterações aparecerão na guia Alterações no painel Controle do código-fonte. Você pode revisar essas alterações, compará-las com a versão confirmada e confirmá-las de volta ao repositório Git para sincronização.

5. Quando as atualizações são feitas diretamente no repositório Git vinculado (Azure DevOps ou GitHub), elas podem incluir ações como modificar instruções de IA, alterar consultas de exemplo ou editar descrições de publicação. Em seguida, você pode confirmar e enviar essas alterações por push para o repositório. Depois que as atualizações são enviadas por push e estão disponíveis no repositório, o espaço de trabalho Fabric as deteta e exibe uma notificação de atualizações disponíveis no painel de controlo de origem. Os itens atualizados, como o agente de dados, aparecem na guia Atualizações, onde você pode revisá-los e aceitá-los. Aceitar essas atualizações aplica as alterações do repositório aos itens do seu espaço de trabalho, garantindo que o espaço de trabalho reflita a versão confirmada mais recente no Git.

Estrutura de pastas e arquivos no repositório Git

A seguir, você analisa a estrutura de como a configuração de um agente de dados é armazenada em um repositório Git. Entender essa estrutura é importante para gerenciar mudanças e seguir as melhores práticas.

Estrutura radicular

Na raiz, o conteúdo do agente de dados é armazenado na pasta de arquivos . Dentro de arquivos, você encontra uma pasta de configuração , que contém data_agent.json, publish_info.json, pasta de rascunho e pasta publicada.

Dentro da pasta config , o publish_info.json contém a descrição de publicação para o agente de dados. Esse arquivo pode ser atualizado para alterar a descrição que aparece quando o agente de dados é publicado.

A pasta de rascunho contém os arquivos de configuração correspondentes à versão de rascunho do agente de dados e a pasta publicada contém os arquivos de configuração para a versão publicada do agente de dados. A pasta de rascunho contém:

• Pastas de fonte de dados onde há uma pasta para cada fonte de dados usada pelo agente de dados.
  • Lakehouse ou fontes de dados de Warehouse: Os nomes das pastas começam com lakehouse-tables- ou warehouse-tables-, seguidos pelo nome do lakehouse ou warehouse.
  • Fontes de dados do modelo semântico: os nomes das pastas começam com semantic-model-, seguido pelo nome do modelo semântico.
  • Fontes de dados do banco de dados KQL: Os nomes das pastas começam com kusto-, seguido pelo nome do banco de dados KQL.
  • Fontes de dados ontológicas: Os nomes das pastas começam por ontology-, seguido do nome da ontologia.

• stage_config.json que contém aiInstructions, que se refere às instruções do agente.

Cada pasta de fonte de dados contém datasource.json e fewshots.json. No entanto, se a fonte de dados for um modelo semântico, ela não oferece suporte a consultas de exemplo, portanto, sua pasta contém apenas datasource.json.

O datasource.json define a configuração dessa fonte de dados, incluindo:

• dataSourceInstructions, que representa as instruções fornecidas para essa fonte de dados.

• displayName, que mostra o nome da fonte de dados.

• elements, que se refere ao mapa de esquema e inclui uma lista completa de tabelas e colunas da fonte de dados.

  • Cada mesa tem uma is_selected propriedade. Se true, a tabela estiver incluída e se false, significa que a tabela não está selecionada e não será usada pelo agente de dados.
  • As entradas de coluna também mostram is_selected, mas a seleção em nível de coluna não é suportada no momento. Se uma tabela for selecionada, todas as suas colunas serão incluídas, independentemente do valor da coluna is_selected . Se uma tabela não for selecionada (is_selected: false no nível da tabela), nenhuma das colunas será considerada, apesar de estar is_selected definida como true no nível da coluna.

• Convenções de tipo:

  • Se o tipo for uma fonte de dados, é simplesmente o tipo de fonte de dados (por exemplo: "type": "lakehouse_tables").
  • Se o tipo for uma tabela, termina com .table (por exemplo: "type": "lakehouse_tables.table").
  • Se o tipo for uma coluna, termina com .column (por exemplo: "type": "lakehouse_tables.column").

O fewshots.json armazena consultas de exemplo para a fonte de dados. Cada entrada inclui:

• id como o identificador exclusivo para a consulta de exemplo.
• question, que se refere à questão da linguagem natural.
• query mostra o texto da consulta, que pode ser SQL ou KQL, dependendo do tipo de fonte de dados.

A pasta publicada espelha a estrutura da pasta de rascunho, mas representa a versão publicada do agente de dados. É uma prática recomendada não modificar arquivos diretamente na pasta publicada. As alterações devem ser feitas na pasta de rascunho. Uma vez que o agente de dados é publicado, essas alterações são refletidas na pasta publicada. Isso garante que a versão publicada seja sempre gerada a partir de um estado de rascunho controlado.

Pipelines de implantação para agentes de dados

Os pipelines de implantação fornecem uma maneira controlada de mover agentes de dados entre espaços de trabalho mapeados para diferentes estágios do ciclo de vida. Por exemplo:

1. Desenvolva um novo agente de dados ou atualize um existente no espaço de trabalho de desenvolvimento.
2. Promova as alterações no espaço de trabalho de teste para validação.
3. Promova as alterações testadas no espaço de trabalho de produção onde ele está disponível para os usuários finais.

Antes de implantar, você precisa atribuir um espaço de trabalho a cada estágio do pipeline de implantação: desenvolvimento, teste e produção. Se você não atribuir um espaço de trabalho ao estágio de teste ou produção, os espaços de trabalho serão criados automaticamente. Os espaços de trabalho criados automaticamente são nomeados após o espaço de trabalho de desenvolvimento, com [test] ou [prod] anexado.

Para implantar alterações:

• No pipeline, vá para o estágio a partir do qual você deseja implantar (por exemplo, desenvolvimento).
• Selecione os itens no espaço de trabalho que você deseja implantar.
• Selecione Implementar para promovê-los para a próxima etapa.

Você pode revisar um plano de implantação antes de aplicar as alterações, garantindo que apenas as atualizações pretendidas sejam promovidas. Para obter mais informações, consulte Introdução aos pipelines de implantação.

Publicar um agente de dados Fabric para os pipelines de implantação

A publicação de um agente de dados do Fabric o torna disponível para uso em todos os diferentes canais de consumo, incluindo Copilot para Power BI, Microsoft Copilot Studio e Azure AI Foundry Services. Para avaliar e consumir o agente de dados nesses canais, o agente de dados deve ser publicado; os agentes de dados não publicados não estão acessíveis para consumo, ainda que estejam no espaço de trabalho de produção. Para seguir as melhores práticas de acordo com o pipeline de implantação, observe que:

• A publicação a partir de um espaço de trabalho de desenvolvimento deve ser limitada apenas a usuários autorizados que estejam trabalhando no desenvolvimento de agentes de dados e queiram avaliar seu desempenho em diferentes canais de consumo. O acesso a esse espaço de trabalho deve ser restrito para que agentes de dados inacabados ou experimentais não sejam expostos a públicos mais amplos.
• Os usuários finais devem acessar os agentes de dados publicados somente a partir do espaço de trabalho de produção, garantindo que interajam com versões estáveis e aprovadas do agente de dados.

Essa abordagem suporta o requisito funcional de permitir a avaliação de consumo e desempenho, e garante o controle de acesso adequado, mantendo os ambientes de desenvolvimento e produção separados.

Melhores práticas

• Use uma ramificação dedicada para o trabalho de desenvolvimento em agentes de dados e mescle para principal após a revisão de código.
• Mantenha os recursos relacionados (fontes de dados, agentes de dados, notebooks, pipelines) no mesmo espaço de trabalho para facilitar a promoção.
• Teste as alterações do agente de dados no espaço de trabalho de teste antes de o promover para a produção.
• Use mensagens de confirmação descritivas para facilitar a compreensão do histórico.
• Não faça alterações diretamente na pasta publicada no repositório Git.

Limitações e considerações

• Somente espaços de trabalho conectados a um repositório Git podem usar recursos ALM baseados em Git.
• As entidades de serviço são suportadas no agente de dados do Fabric apenas como parte de cenários de ALM. Se você precisar interagir com um agente de dados fora dos fluxos de trabalho do ALM, a entidade de serviço não será suportada.
• Os pipelines de implementação exigem que os espaços de trabalho tanto de origem como de destino estejam no mesmo tenant.
• Um grande número de confirmações frequentes pode afetar o tamanho e o desempenho do repositório.

Conteúdo relacionado

• Introdução à integração com o Git
• Conceitos básicos em integração Git
• O que é o gerenciamento do ciclo de vida no Microsoft Fabric?