Controle do Código-Fonte, CI/CD e ALM para agente de dados do Fabric (versão prévia)

Este artigo descreve como gerenciar agentes de dados do Fabric usando pipelines de integração e implantação do Git como parte dos recursos de ALM (Gerenciamento de Ciclo de Vida de Aplicativos) do Microsoft Fabric. Você aprenderá a conectar um workspace a um repositório Git. Você também aprenderá a rastrear e versionar as configurações do agente de dados. Por fim, você aprenderá a promover atualizações em ambientes de desenvolvimento, teste e produção. Os pipelines de integração e entrega contínuas do Git permitem a integração contínua/desdobramento contínuo (CI/CD) de alterações do agente de dados, permitindo que as atualizações sejam testadas e promovidas automaticamente como parte do fluxo de trabalho de ALM. O controle do código-fonte para agentes de dados do Fabric está atualmente em versão prévia.

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

Integração do Git: sincronize um workspace 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 branches e o acompanhamento de histórico para itens individuais, incluindo agentes de dados do Fabric.
Pipelines de implantação: promova o conteúdo entre workspaces separados que representam estágios de desenvolvimento, teste e produção usando pipelines integrados.

Esses recursos juntos fornecem suporte de ALM de ponta a ponta para agentes de dados do Fabric.

Importante

Esse recurso está na versão prévia.

Pré-requisitos

Uma capacidade paga do F2 ou superior do Fabric ou uma capacidade do Power BI Premium por capacidade (P1 ou superior) com o Microsoft Fabric habilitado
As Configurações de locatário do agente de dados do Fabric estão habilitadas.
O Processamento entre áreas geográficas de IA está habilitado.
O Armazenamento entre áreas geográficas de IA está habilitado.
Pelo menos um destes, com dados: um armazém, um lakehouse, um ou mais modelos semânticos do Power BI, um banco de dados KQL ou uma ontologia.
Os Modelos semânticos do Power BI pela opção de locatário dos pontos de extremidade XMLA estão habilitados para as fontes de dados do modelo semântico do Power BI.

Integração do Git

A integração do Git do Microsoft Fabric sincroniza um workspace 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 workspace. 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. Seus principais recursos incluem:

Backup completo e controle de versão de itens de espaço de trabalho
A estrutura de pastas no Git espelha a estrutura do workspace
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 exibir diferenças, revisar o histórico e reverter para estados anteriores por meio do histórico de diferentes elementos do espaço de trabalho, incluindo agentes de dados.
Colaboração baseada em ramificação (branches de recursos, principal)

Para obter mais informações sobre o processo de integração do Git, você pode consultar os recursos a seguir.

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

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

Confira Introdução à integração do Git para obter etapas detalhadas para se conectar a um repositório Git no Azure DevOps ou no GitHub.
Depois de se conectar ao repositório Git, seus itens do espaço de trabalho, incluindo agentes de dados do Fabric, aparecem no painel de origem. Na barra de status na parte inferior esquerda, você pode ver o nome do branch conectado, a hora da última sincronização e a ID de confirmação do Git.

O repositório Git vinculado exibe uma estrutura de pastas que representa seus itens de workspace, 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ê examine as alterações, acompanhe o histórico de versões e use fluxos de trabalho do Git, como a criação de solicitações de pull para mesclar atualizações em seu branch principal.

Quando você faz modificações no agente de dados do Fabric em um workspace conectado ao Git, as alterações são detectadas e o status do agente de dados no painel controle de origem muda para alterações não confirmadas. Essas modificações podem incluir:
- Alterando a seleção de esquema.
- Atualizando instruções de IA ou instruções de fonte de dados.
- Editando consultas de exemplo.
- Publicando o agente de dados ou atualizando 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 workspace com alterações serão exibidos na guia Alterações no painel Controle do Código-fonte. Você pode examinar essas alterações, compará-las com a versão confirmada e confirmá-las novamente no repositório Git para sincronizar.

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 por push essas alterações para o repositório. Depois que as atualizações são enviadas por push e estão disponíveis no repositório, o workspace do Fabric as detecta e exibe uma notificação de Atualizações disponíveis no painel de controle de origem. Os itens atualizados, como o agente de dados, aparecem na guia Atualizações, em que você pode revisá-los e aceitá-los. Aceitar essas atualizações aplica as alterações do repositório aos itens do workspace, garantindo que o workspace reflita a versão confirmada mais recente no Git.

Estrutura de pastas e arquivos no repositório Git

No seguinte, você examinará a estrutura de como a configuração de um agente de dados é armazenada em um repositório Git. Entender essa estrutura é importante para gerenciar as alterações e seguir as práticas recomendadas.

Estrutura raiz

Na raiz, o conteúdo do agente de dados é armazenado na pasta de arquivos . Dentro dos 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 de configuração , o publish_info.json contém a descrição de publicação do 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 rascunhos contém:

Pastas de fontes de dados em que há uma pasta para cada fonte de dados usada pelo agente de dados.
- Fontes de dados do lakehouse ou warehouse: os nomes das pastas começam com lakehouse-tables- ou warehouse-tables-, seguidos pelo nome do lakehouse ou warehouse.
- Fontes de dados semânticas do modelo: os nomes das pastas começam com semantic-model-, seguidos pelo nome do modelo semântico.
- Fontes de dados do banco de dados KQL: os nomes das pastas começam com kusto-, seguidos pelo nome do banco de dados KQL.
- Fontes de dados de ontologia: os nomes das pastas começam com ontology-, seguidos pelo 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 oferecerá 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 tabela tem uma is_selected propriedade. Se true, a tabela estiver incluída e se false, isso significa que a tabela não está selecionada e não será usada pelo agente de dados.
- As entradas de coluna também são mostradas is_selected, mas a seleção no nível da coluna não é suportada atualmente. Se uma tabela estiver selecionada, todas as colunas serão incluídas independentemente do valor da coluna is_selected . Quando uma tabela não é selecionada (is_selected: false no nível da tabela), nenhuma das colunas é considerada, apesar de is_selected estar definido como true no nível da coluna.
Convenções de tipo:
- Se o tipo for uma fonte de dados, será simplesmente o tipo de fonte de dados (por exemplo: "type": "lakehouse_tables").
- Se o tipo for uma tabela, ele terminará com .table (por exemplo: "type": "lakehouse_tables.table").
- Se o tipo for uma coluna, ele terminará 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 da 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. Depois 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

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

Desenvolva um novo agente de dados ou atualize um existente no workspace de desenvolvimento.
Promova as alterações para o ambiente de teste para validação.
Promova as alterações testadas para o ambiente de produção, onde estarão disponíveis para os usuários finais.

Antes de implantar, você precisa atribuir um espaço de trabalho a cada estágio no pipeline de implantação: desenvolvimento, teste e produção. Se você não atribuir um workspace ao estágio de teste ou produção, os workspaces serão criados automaticamente. Os workspaces criados automaticamente são nomeados com base no ambiente de desenvolvimento, com [teste] ou [prod] adicionado.

Para implantar alterações:

No pipeline, vá para o estágio de onde você deseja implantar (por exemplo, desenvolvimento).
Selecione os itens no workspace que você deseja implantar.
Selecione Implantar para promovê-los ao próximo estágio.

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

Observação

As entidades de serviço têm suporte no agente de dados do Fabric apenas como parte de cenários de ALM. Esse suporte é limitado à habilitação de operações de ALM (como pipelines de integração e implantação do Git) e não se estende a outros recursos do agente de dados do Fabric. Se você precisar interagir com um agente de dados fora dos fluxos de trabalho do ALM, não há suporte para a entidade de serviço.

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

A publicação de um agente de dados do Fabric o disponibiliza para uso em todos os canais de consumo diferentes, 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 são acessíveis para consumo, mesmo que estejam no ambiente de produção. Para seguir as práticas recomendadas em conformidade com o pipeline de implantação, observe que:

A publicação de um workspace de desenvolvimento deve ser limitada apenas a usuários autorizados que estão trabalhando no desenvolvimento do agente de dados e desejam avaliar seu desempenho em diferentes canais de consumo. O acesso a este ambiente de trabalho deve ser restrito para que os agentes de dados inacabados ou experimentais não sejam expostos a audiências mais amplas.
Os usuários finais devem acessar agentes de dados publicados somente no workspace de produção, garantindo que interajam com versões estáveis e aprovadas do agente de dados.

Essa abordagem dá suporte ao requisito funcional de habilitar o consumo e a avaliação de desempenho e garante o controle de acesso adequado mantendo os ambientes de desenvolvimento e produção separados.

Práticas recomendadas

Utilize um ramo dedicado para o trabalho de desenvolvimento em agentes de dados e integre ao main após a revisão de código.
Mantenha os recursos relacionados (fontes de dados, agentes de dados, notebooks, pipelines) no mesmo workspace para facilitar a promoção.
Teste as alterações do agente de dados no ambiente de teste antes de promovê-las para 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 workspaces conectados a um repositório Git podem usar recursos de ALM baseados em Git.
Os principais de serviço têm suporte 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, não há suporte para a entidade de serviço.
Os pipelines de implantação exigem que os workspaces de origem e de destino estejam no mesmo tenant.
Um grande número de confirmações frequentes pode afetar o tamanho e o desempenho do repositório.

Comentários

Esta página foi útil?

Last updated on 2025-10-04