Integrar o OneLake ao Azure Machine Learning

OneLake é a camada aberta de armazenamento do Fabric com acesso compatível com o Armazenamento do Azure. Ele expõe dados do Fabric por meio de onelake.dfs.fabric.microsoft.com para acesso ao ADLS Gen2/DFS e de onelake.blob.fabric.microsoft.com para acesso à API de Blob. Este artigo descreve como o Azure Machine Learning pode usar essas interfaces por meio de datastores do AML, entradas e saídas de endpoint de lote e acesso direto de notebooks ou scripts abfss://.

Azure Machine Learning fornece três pontos de integração primários com o OneLake:

Datastores - registre um local de Lakehouse do Fabric Files como um datastore do Azure Machine Learning e faça referência a ele em trabalhos e ativos de dados. O Azure Machine Learning também oferece suporte a link direto para tabelas do Lakehouse do Fabric, mas esse padrão envolve uma cópia para o ADLS Gen2 e não é abordado neste documento.
Endpoints em lote - invoque implantações em lote com entradas e saídas que estão no OneLake (hoje, por meio de um datastore registrado ou de um datastore Blob/ADLS baseado em atalho).
APIs do OneLake / acesso direto via ABFSS – leia e grave no OneLake diretamente de notebooks e scripts executados em ambientes de runtime do Azure Machine Learning.

Ponto de integração no Azure Machine Learning	Superfície do OneLake	superfície do Azure Machine Learning	Os dados são copiados para o ADLS Gen2?	URI primário a ser usado no Azure Machine Learning
Armazenamento de dados do OneLake	Seção Lakehouse `/Files` .	CLI/SDK (YAML)	No	`azureml://datastores/<name>/paths/<path>`
Tabela do lakehouse do OneLake (vinculada à interface do usuário)	Seção Lakehouse `/Tables` .	Estúdio do Azure Machine Learning (interface do usuário)	Sim - copiado por meio de Fabric pipeline para o ADLS Gen2 e, em seguida, registrado	`azureml://datastores/<adls_ds>/paths/<path>`
Entrada/saída do ponto de extremidade do lote	Lakehouse `/Files` (via atalho do ADLS).	CLI/SDK/REST	Optional	`azureml://datastores/<name>/paths/<path>` ou `abfss://...`
API/ABFSS do Direct OneLake	`/Files` e `/Tables`	Notebooks/scripts nos recursos de computação do Azure Machine Learning	No	`abfss://<workspace>@onelake.dfs.fabric.microsoft.com/<lakehouse>.Lakehouse/Files/...`

Note

azureml://é um esquema de URI específico Azure Machine Learning, não um protocolo de armazenamento. O plano de controle e o runtime de dados do Azure Machine Learning usam isso para resolver o local de armazenamento subjacente (Blob, ADLS Gen2, OneLake e outros) com base nos metadados de conexão e nas credenciais registradas no datastore nomeado.

OneLake como Azure Machine Learning Datastore

Um datastore é uma abstração, no escopo de um workspace do Azure Machine Learning, para um local de armazenamento externo (OneLake, Azure Blob, ADLS Gen2, Arquivos do Azure). Ele armazena os metadados de conexão para um recurso de armazenamento existente, o ponto de extremidade, o contêiner/sistema de arquivos/item e as credenciais ou a configuração de identidade, sem provisionar ou copiar os próprios dados. Várias experiências em Azure Machine Learning podem referenciar armazenamentos de dados usando um URI estável (azureml://datastores/<name>/paths/<path>).

Note

Estúdio do Azure Machine Learning atualmente não lista o OneLake como um tipo de armazenamento de dados na interface do usuário, mas a CLI e o SDK dão suporte à criação e ao gerenciamento de armazenamentos de dados OneLake por meio da definição de YAML.

Metadados de conexão necessários do Microsoft Fabric

Na página Propriedades do item lakehouse em Fabric, capture:

Ponto de extremidade – para o OneLake, use onelake.dfs.fabric.microsoft.com ou onelake.blob.fabric.microsoft.com dependendo do protocolo que você deseja usar.
Workspace GUID
GUID do item (o GUID do lakehouse)

Criar o armazenamento de dados no Azure Machine Learning

onelake-datastore.yml:

$schema: https://azuremlschemas.azureedge.net/latest/oneLakeDatastore.schema.json
name: <name_of_datastore>
type: onelake
description: Datastore pointing to a Microsoft Fabric lakehouse.
onelake_workspace_name: <workspace_guid>
endpoint: onelake.dfs.fabric.microsoft.com
artifact:
  type: lakehouse
  name: <item_guid>/Files   # Include /Files in the name to point at the lakehouse Files layer; omit it to point at the root of the item.

Usando CLI do Azure, crie o armazenamento de dados no workspace de Azure Machine Learning de destino. Substitua os marcadores <name_of_AML_workspace> e <name_of_datastore> pelos valores apropriados.

az ml datastore create --file ./onelake-datastore.yml \
    --resource-group rg-amlonelake \
    --workspace-name <name_of_AML_workspace>

Usar um armazenamento de dados em trabalhos do Azure Machine Learning

Depois que um datastore do Azure Machine Learning for registrado, seu URI azureml:// ficará disponível para uso por meio de várias interfaces. O exemplo aqui demonstra como referenciar um armazenamento de dados do OneLake em um trabalho de Azure Machine Learning. O URI a seguir é válido como um URI de trabalho Input/Output, em definições de ativos de dados e em qualquer lugar em que o Azure Machine Learning aceite um caminho de datastore, exceto para endpoints em lote, que atualmente não oferecem suporte ao OneLake como tipo de datastore para entrada ou saída.

O exemplo de trabalho a seguir copia um arquivo de um local para outro no mesmo armazenamento de dados do OneLake. Você pode usar uma combinação de vários destinos de armazenamento com suporte (Blob, ADLS Gen2, OneLake) como entradas e saídas no mesmo trabalho.

type: command
command: cp ${{inputs.input_data}} ${{outputs.output_data}}
compute: azureml:<replace_with_aml_compute_target>
environment: azureml://registries/azureml/environments/sklearn-1.1/versions/4
inputs:
  input_data:
    mode: ro_mount
    path: azureml://datastores/<name_of_datastore>/paths/<folder-path>/<file-name> # Do not include /Files in the <file-name> portion of the path. Reason being that the datastore is already pointed at the /Files layer of the lakehouse via the artifact name in the datastore definition.
    type: uri_file
outputs:
  output_data:
    mode: rw_mount
    path: azureml://datastores/<name_of_datastore>/paths/<folder-path>/<file-name> # Do not include /Files in the <file-name> portion of the path. Reason being that the datastore is already pointed at the /Files layer of the lakehouse via the artifact name in the datastore definition.
    type: uri_file
    # optional: if you want to create a data asset from the output, 
    # then uncomment `name` (`name` can be set without setting `version`, and in this way, we will set `version` automatically for you)
    # name: <name_of_data_asset> # use `name` and `version` to create a data asset from the output
    # version: <version_of_data_asset>

Recursos do Azure Machine Learning que podem fazer referência diretamente a um armazenamento de dados do OneLake

#	interface do Azure Machine Learning	Direction	Endereçamento do OneLake	Source
1	Tarefas do Azure Machine Learning - `Input` / `Output` (CLI v2, SDK v2 `command`, `pipeline`, `sweep`)	R / W	`azureml://datastores/<onelake_ds>/paths/...`	Acessar dados em um trabalho
2	Ativos de dados (`uri_file`, `uri_folder`) registrados em um caminho de armazenamento de dados do OneLake	R (os ativos são referências de somente leitura)	`azureml://datastores/<onelake_ds>/paths/...` encapsulado com controle de versão	Criar ativos de dados
3	runtime de dados do Azure Machine Learning via `azureml-fsspec` em notebooks/scripts na computação do Azure Machine Learning	R / W	`azureml://datastores/<onelake_ds>/paths/...` aberto usando `fsspec.open(...)` ou `AzureMachineLearningFileSystem`	Acessar dados do OneLake durante o desenvolvimento interativo

OneLake com pontos de extremidade em lote

O Azure Machine Learning permite usar o Fabric para acessar pontos de extremidade em lote de implantação de modelo para inferência assíncrona de longa duração com modelos e pipelines de machine learning.

Nesse padrão, a meta arquitetônica é manter uma única cópia física dos dados do recurso de entrada e das previsões de saída acessíveis para ambas as plataformas – Fabric e Azure Machine Learning. Um arquivo no ADLS carrega dois endereços válidos - um azureml://datastores/... URI que os endpoints batch do Azure Machine Learning aceitam como entrada/saída, e um caminho lakehouse (habilitado por atalho ADLS) que notebooks, pipelines e endpoints de análise SQL do Fabric podem consultar. Esse padrão não envolve cópia, nenhuma sincronização agendada, nenhuma segunda fonte de verdade. A visualização do lakehouse e a visualização do Azure Machine Learning são projeções da mesma conta de armazenamento.

Os endpoints em lote se situam entre duas pastas visíveis no OneLake:

Entradas - um local selecionado /Files (área bruta de landing, solicitações classificadas, partições diárias) preparado pela engenharia de dados do Fabric. O Azure Machine Learning o lê por meio de um datastore do ADLS Gen2 que aponta para o mesmo armazenamento usado pelo atalho.
Saídas - um local de armazenamento de previsões /Files gravado pelo trabalho em lote na mesma conta do ADLS Gen2, que aparece no lakehouse por meio de um atalho e fica imediatamente disponível para notebooks do Fabric, fluxos de dados ou uma etapa de carregamento de tabela Delta.

Mais amplamente, esse padrão é adequado para cenários em que você já tem dados desembarcados no ADLS Gen2. Por exemplo, um data lake existente que alimenta cargas de trabalho de análise ou de ML. Em vez de migrar ou duplicar esses dados no OneLake, um atalho do OneLake exibe a localização existente do ADLS dentro de um Fabric lakehouse, enquanto a mesma conta permanece registrada como um armazenamento de dados.

Acesso ao SDK ou à API do OneLake em notebooks e scripts do Azure Machine Learning

Quando o código é executado em um recurso de computação do Azure Machine Learning (instância de computação, cluster de computação ou computação sem servidor), ele pode ler e gravar no OneLake diretamente por meio do caminho abfss:// ou do caminho do datastore do OneLake. O SDK e as APIs do OneLake oferecem um ponto de integração flexível e podem ser usados para exploração orientada por notebooks, scripts de treinamento personalizados e componentes que precisam de acesso a /Files e /Tables por meio da computação do Azure Machine Learning.

O OneLake usa um URI abfss:// para arquivos no OneLake, e ele pode ser usado como um caminho de entrada de trabalho válido para autenticação baseada em identidade ou em entidade de serviço:

abfss://<workspace_guid>@<endpoint>/<item_guid>/Files/<path>

Desempenho e escalabilidade – escolhendo o leitor certo no Azure Machine Learning

fsspec (e o backend do OneLake adlfs que ele envolve) é uma abstração de sistema de arquivos em nível de Python. É conveniente para notebooks, mas não é em si um mecanismo de dados paralelo - sua simultaneidade é limitada por um único processo de Python. O desempenho, portanto, depende do leitor e do motor que estão sobre ele. A documentação do Azure Machine Learning data runtime recomenda explicitamente usar o Azure Machine Learning data runtime nos downloads de Python do lado do cliente para dados de treinamento, observando restrições de taxa de transferência de armazenamento observadas "quando o código do cliente usa Python para baixar dados do armazenamento, devido a problemas de GIL (Bloqueio de Interpretador Global).".

Usar Azure Machine Learning Spark para processamento de dados em larga escala no OneLake

O OneLake foi projetado como um data lake analítico, e o endpoint abfss:// foi desenvolvido para os padrões de leitura paralela e particionada usados pelo Spark. Para ETL em escala de TB, engenharia de atributos ou preparação de dados de treinamento distribuído, use Azure Machine Learning Spark over fsspec, idealmente em um cluster com vários nós:

Spark sem servidor no Azure Machine Learning ou um pool do Spark anexado do Synapse - execute trabalhos/notebooks do Spark no Azure Machine Learning e leia o OneLake diretamente via abfss://. Consulte o Apache Spark em Azure Machine Learning.
Fabric Spark - notebooks/tarefas do Spark em execução no Fabric têm acesso nativo ao mesmo lakehouse e podem entregar resultados selecionados ao Azure Machine Learning por meio do armazenamento de dados OneLake.

O exemplo a seguir demonstra como ler uma tabela Delta de um lakehouse a partir de uma sessão do Spark em um recurso de computação do Azure Machine Learning:

df = (
    spark.read.format("delta")
        .load(
            "abfss://<workspace_guid>@onelake.dfs.fabric.microsoft.com/"
            "<item_guid>/Tables/<table-name>"
        )
)

OneLake e Azure Machine Learning `mltable`

Atualmente, a leitura de dados baseados no OneLake por meio de mltable falha durante a transmissão do arquivo em streaming. Os erros observados incluem ScriptExecution.StreamAccess.NotFound e Invalid argument (os error 22). A computação do Azure Machine Learning pode resolver e ler o OneLake por meio de azureml-fsspec, pyarrow ou do SDK do Armazenamento do Azure Data Lake, usando o mesmo datastore e a mesma identidade.

No lugar da Tabela ML, considere uma das seguintes alternativas:

Para leituras do OneLake, dê preferência aos ativos de dados uri_file / uri_folder e carregue-os com azureml-fsspec + pyarrow / pandas / polars / DuckDB (nó único) ou com Spark no abfss:// (distribuído). A documentação do Microsoft Learn mltable em si observa que, para uma pasta Parquet simples ou um arquivo CSV, uri_file / uri_folder são a opção recomendada.
Se a semântica de mltable for realmente necessária - mais comumente como entrada para o AutoML, que exige type: mltable - prepare os dados em uma conta do ADLS Gen2 primeiro e crie o mltable com base nesse local. mltable funciona de forma confiável no ADLS Gen2 atualmente.
O padrão de atalho do OneLake (discutido como parte dos endpoints em lote) é uma opção natural para o ML Table — o mesmo arquivo físico reside no ADLS Gen2 (onde mltable funciona) e fica disponível no lakehouse do Fabric por meio de um atalho (onde as ferramentas do Fabric o reconhecem), sem necessidade de cópia.

mltable reúne vários recursos que uri_file / uri_folder não fornecem nativamente. A tabela a seguir lista o equivalente mais próximo quando você lê o OneLake diretamente.

`mltable` Capacidade	Alternativa
Modelo declarativo e portátil de leitura (delimitador, codificação, cabeçalho, tamanho da partição, tipos de coluna) armazenado em um arquivo `MLTable` junto com os dados	Fixe as configurações de leitura em Python (`pyarrow.parquet.ParquetDataset`, `pandas.read_csv(...)`, , `polars.scan_parquet(...)duckdb.read_parquet(...)`) e mantenha esse módulo do carregador sob controle do código-fonte
Transformações integradas no momento da leitura (`filter`, `drop_columns`, `convert_column_types`, `take_random_sample`)	Aplique os equivalentes no mecanismo escolhido – `polars` / `duckdb` quadros lentos efetuam push de filtros e projeções da mesma forma; O Spark on `abfss://` faz o mesmo em escala
Composição de caminho de múltiplas fontes - uma tabela que se estende por vários arquivos, pastas, padrões glob e até contas de armazenamento	Use `fs.glob(...)` de `azureml-fsspec`, `pyarrow.dataset.dataset(paths)` ou `spark.read.parquet(*paths)` do Spark para ler uma lista de caminhos como um único conjunto de dados lógico
`eval_mount` / `eval_download` modos em trabalhos do Azure Machine Learning (resolver os caminhos do arquivo `MLTable` no envio do trabalho, montar somente o que é referenciado)	Materialize, upstream, um subconjunto selecionado (um notebook do Fabric ou um trabalho de pré-processamento do Azure Machine Learning grava em uma pasta dedicada `/Files/curated/...`) e aponte para `uri_folder`
Versionamento da receita de leitura (não apenas dos dados) por meio de um ativo de dados do tipo `mltable`	Versione o script de carregamento com o código do modelo no Git ou associe um recurso de dados `uri_folder` a um pequeno módulo de carregamento versionado junto ao script de treinamento
**Entrada do AutoML — o AutoML exige `type: mltable` (Configurar o treinamento do AutoML)	Preparar os dados para o ADLS Gen2 (o atalho do lakehouse mantém uma única cópia física) e criar o `mltable` lá

Para treinamento personalizado e pontuação no OneLake, use uri_file / uri_folder mais um mecanismo de sua escolha (pyarrow / polars / duckdbnó único ou Spark distribuído em Azure Machine Learning). Essas opções oferecem as mesmas capacidades funcionais de mltable e taxa de transferência comparável ou superior. Para o AutoML, rote pelo ADLS Gen2 até que haja suporte para mltable o OneLake. Você pode usar um atalho para o OneLake para evitar a duplicação de dados e ainda ter os dados disponíveis em Fabric para outros casos de uso.

Considerações

Modelo de identidade. O OneLake usa o modelo de identidade SaaS, para que ele não exponha uma ID de Assinatura. Em vez do controle de acesso baseado em função do Azure (Azure RBAC) na conta de armazenamento, o acesso é controlado pelas funções do workspace do Fabric (Administrador, Membro, Colaborador, Visualizador) no lakehouse de destino. O armazenamento de dados do OneLake dá suporte a dois modos de credencial, que são documentados em Criar armazenamentos de dados. Para configurar o armazenamento de dados e acessar o Fabric lakehouse, você precisa de um usuário com a função colaborador do workspace Fabric e a função de administrador do workspace Azure Machine Learning.
Cópia única de dados. O armazenamento de dados do OneLake e o acesso direto ao ABFSS preservam o princípio de "cópia única" do OneLake. O padrão de atalho para endpoints de lote preserva esse princípio do ponto de vista lógico, mas requer uma conta do ADLS Gen2 como armazenamento físico subjacente.
Colocalização da região. Coloque o Azure Machine Learning workspace, a computação e a capacidade Fabric ou a região do OneLake na mesma região para evitar a saída entre regiões.

Comentários

Esta página foi útil?

Última atualização em 2026-07-07