Integre o OneLake com Azure Machine Learning

O OneLake é a camada de armazenamento em lago aberto do Fabric com acesso compatível com o Armazenamento do Azure. Expõe os dados do Fabric através de onelake.dfs.fabric.microsoft.com para acesso ao ADLS Gen2/DFS e de onelake.blob.fabric.microsoft.com para acesso à API de Blobs. Este artigo descreve como o Azure Machine Learning pode usar estas superfícies através de datastores AML, entradas e saídas de endpoints em lote, e acesso direto abfss:// a partir de notebooks ou scripts.

O Azure Machine Learning fornece três pontos principais de integração com o OneLake:

Datastores - registar uma localização do Fabric Lakehouse Files como arquivo de dados do Azure Machine Learning e referenciá-la a partir de tarefas e ativos de dados. O Azure Machine Learning também suporta ligação direta às tabelas Fabric Lakehouse, mas esse padrão envolve uma cópia para ADLS Gen2 e não está abordado neste documento.
Pontos finais em lote - invocam implementações em lote com entradas e saídas armazenadas no OneLake (atualmente, através de um arquivo de dados registado ou de um arquivo de dados Blob/ADLS suportado por atalho).
APIs do OneLake / acesso direto ABFSS - ler e escrever no OneLake diretamente a partir 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 ADLS Gen2?	URI principal a usar no Azure Machine Learning
Armazenamento de dados OneLake	Secção Lakehouse `/Files`.	CLI / SDK (YAML)	No	`azureml://datastores/<name>/paths/<path>`
Tabela de casas de lago OneLake (ligada à interface de utilizador)	Secção Lakehouse `/Tables`.	Estúdio do Azure Machine Learning (UI)	Sim - copiado via pipeline Fabric para ADLS Gen2, depois registado	`azureml://datastores/<adls_ds>/paths/<path>`
Entrada/saída de endpoint em lote	Lakehouse `/Files` (via atalho ADLS).	CLI / SDK / REST	Optional	`azureml://datastores/<name>/paths/<path>` ou `abfss://...`
Direct OneLake API / ABFSS	`/Files` e `/Tables`	Blocos de notas / scripts nos recursos de computação do Azure Machine Learning	No	`abfss://<workspace>@onelake.dfs.fabric.microsoft.com/<lakehouse>.Lakehouse/Files/...`

Observação

azureml://é um esquema URI específico do Azure Machine Learning, não um protocolo de armazenamento. O plano de controlo e o runtime de dados do Azure Machine Learning utilizam-no para resolver a localização de armazenamento subjacente (Blob, ADLS Gen2, OneLake, entre outros) utilizando os metadados de ligação e credenciais registados no datastore nomeado.

OneLake como Azure Machine Learning Datastore

Um datastore é uma abstração delimitada ao espaço de trabalho do Azure Machine Learning de uma localização de armazenamento externa (OneLake, Azure Blob, ADLS Gen2, Ficheiros do Azure). Armazena os metadados de ligação para um recurso de armazenamento existente, o endpoint, contentor/sistema de ficheiros/item, e a configuração das credenciais ou identidade, sem provisionar ou copiar os dados em si. Várias experiências dentro do Azure Machine Learning podem referenciar datastores usando um URI estável (azureml://datastores/<name>/paths/<path>).

Observação

O Estúdio do Azure Machine Learning atualmente não lista o OneLake como tipo de datastore na interface, mas a CLI e o SDK suportam a criação e gestão de datastores OneLake via definição YAML.

Metadados de ligação necessários para o Microsoft Fabric

Na página Properties do item Lakehouse no Fabric, registe:

Endpoint - Para OneLake, use onelake.dfs.fabric.microsoft.com ou onelake.blob.fabric.microsoft.com dependendo do protocolo que pretende usar.
GUID de Espaço de Trabalho
GUID do item (o GUID da casa do lago)

Criar o datastore 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 o CLI do Azure, crie o datastore no espaço de trabalho de Azure Machine Learning de destino. Substitua os marcadores de posição <name_of_AML_workspace> e <name_of_datastore> pelos valores adequados.

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

Utilizar um datastore em trabalhos do Azure Machine Learning

Uma vez registado um Azure Machine Learning datastore, o seu azureml:// URI está disponível para utilização através de várias experiências. O exemplo aqui demonstra como referenciar um datastore OneLake num trabalho de Azure Machine Learning. O URI seguinte é válido como uma tarefa Input/Output, em definições de ativos de dados e em qualquer contexto em que o Azure Machine Learning aceite um caminho de datastore, exceto para pontos finais de lote, que atualmente não suportam o OneLake como tipo de datastore para entrada ou saída.

O exemplo de trabalho seguinte copia um ficheiro de um local para outro dentro do mesmo armazenamento de dados OneLake. Podes usar uma mistura de vários alvos de armazenamento suportados (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>

Experiências de Azure Machine Learning que podem referenciar diretamente uma loja de dados OneLake

#	superfície / interface do Azure Machine Learning	Direction	Endereçamento do OneLake	Source
1	Azure Machine Learning jobs - `Input` / `Output` (CLI v2, SDK v2 `command`, `pipeline`, `sweep`)	R / W	`azureml://datastores/<onelake_ds>/paths/...`	Aceder a dados numa tarefa
2	Ativos de dados (`uri_file`, `uri_folder`) registados contra um caminho de armazenamento de dados OneLake	R (os recursos são referências só de leitura)	`azureml://datastores/<onelake_ds>/paths/...` envolvido por controlo de versões	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 com `fsspec.open(...)` ou `AzureMachineLearningFileSystem`	Aceder aos dados do OneLake durante o desenvolvimento interativo

OneLake com endpoints em lote

O Azure Machine Learning permite-lhe utilizar o Fabric para aceder a endpoints de implementação em lote de modelos para inferência assíncrona de longa duração com modelos e pipelines de machine learning.

Neste padrão, o objetivo arquitetónico é manter acessível uma cópia física única tanto dos dados das características de entrada como das previsões de saída para ambas as plataformas - Fabric e Azure Machine Learning. Um ficheiro no ADLS tem dois endereços válidos – um URI azureml://datastores/... que os endpoints de batch do Azure Machine Learning aceitam como entrada/saída e um caminho do lakehouse (ativado através de um atalho do ADLS) que os notebooks do Fabric, pipelines e endpoints de análise SQL podem consultar. Este padrão não envolve cópia, sincronização programada, nem segunda fonte de verdade. A vista do lakehouse e a vista do Azure Machine Learning são projeções da mesma conta de armazenamento.

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

Entradas - um local selecionado /Files (aterragem bruta, pedidos pontuados, partições diárias) preparado pela engenharia de dados Fabric. O Azure Machine Learning lê-o através de um datastore ADLS Gen2 que aponta para o mesmo armazenamento para o qual o atalho aponta.
Saídas - uma localização das previsões /Files gravada pela tarefa em lote na mesma conta do ADLS Gen2, que aparece no lakehouse através de um atalho e fica imediatamente disponível para notebooks do Fabric, fluxos de dados ou uma etapa de carregamento de tabelas Delta.

De forma mais geral, este padrão é bem adequado para cenários em que já tem dados aterrados na ADLS Gen2. Por exemplo, um data lake existente que alimenta análises ou cargas de trabalho de ML. Em vez de migrar ou duplicar esses dados para o OneLake, um atalho do OneLake expõe a localização existente no ADLS dentro de um lakehouse do Fabric, enquanto a mesma conta permanece registada como repositório de dados.

Acesso ao OneLake SDK ou API a partir de cadernos e scripts do Azure Machine Learning

Quando o código é executado num recurso de computação do Azure Machine Learning (instância de computação, cluster de computação ou computação sem servidor), pode ler e escrever diretamente no OneLake através do caminho abfss:// ou do caminho do seu arquivo de dados OneLake. O SDK do OneLake e as APIs oferecem um ponto de integração flexível e podem ser utilizados para exploração orientada por notebooks, scripts personalizados de treino e componentes que necessitam de acesso a /Files e /Tables através da capacidade de computação do Azure Machine Learning.

O OneLake utiliza um URI abfss:// para ficheiros armazenados no OneLake e este pode ser utilizado como um caminho de entrada válido para tarefas com autenticação baseada em identidade ou em entidade de serviço:

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

Desempenho e escalabilidade - escolher o leitor certo no Azure Machine Learning

fsspec(e o backend OneLake adlfs que envolve) é uma abstração de sistema de ficheiros ao nível de Python. É conveniente para portáteis, mas não é um motor de dados paralelo – a sua concorrência é limitada por um único processo Python. O desempenho depende, assim, do leitor e do mecanismo que assentam sobre ele. A documentação de dados em tempo de execução do Azure Machine Learning recomenda explicitamente a utilização do tempo de execução de dados do Azure Machine Learning sobre downloads Python do lado do cliente para dados de treino, referindo as restrições de throughput de armazenamento observadas "quando o código do cliente usa Python para descarregar dados do armazenamento, devido a problemas com o Global Interpreter Lock (GIL)."

Use o Azure Machine Learning Spark para processamento de dados em grande escala no OneLake

O OneLake foi concebido como um lago analítico, e o abfss:// endpoint foi construído para os padrões paralelos e particionados de leitura que o Spark utiliza. Para ETL à escala de TB, engenharia de atributos ou preparação distribuída de dados de treino, utilize o Azure Machine Learning Spark em vez de fsspec, idealmente num cluster com vários nós:

Serverless Spark no Azure Machine Learning ou um pool do Synapse Spark anexado - execute tarefas/notebooks do Spark no Azure Machine Learning e leia o OneLake diretamente através de abfss://. Veja Apache Spark no Azure Machine Learning.
Fabric Spark - Os notebooks/jobs do Spark em execução no Fabric têm acesso nativo ao mesmo lakehouse e podem transferir resultados selecionados para o Azure Machine Learning através do datastore do OneLake.

O exemplo seguinte demonstra a leitura de uma tabela Delta de lakehouse a partir de uma sessão Spark no Azure Machine Learning compute:

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 mltable apoiados pelo OneLake falha ao transmitir o ficheiro. Os erros observados incluem ScriptExecution.StreamAccess.NotFound e Invalid argument (os error 22). Os recursos de computação do Azure Machine Learning podem resolver e ler o OneLake através de azureml-fsspec, pyarrow ou do SDK do Armazenamento do Azure Data Lake, utilizando o mesmo arquivo de dados e a mesma identidade.

Em vez da Tabela ML, considere uma das seguintes alternativas:

Para leituras do OneLake, prefira os recursos de dados uri_file / uri_folder e carregue-os com azureml-fsspec + pyarrow / pandas / polars / DuckDB (nó único), ou com o Spark em abfss:// (distribuído). A própria documentação do Microsoft Learn mltable refere que, para uma pasta simples de Parquet ou ficheiro CSV, uri_file / uri_folder são a escolha recomendada.
Se mltable as semânticas forem genuinamente necessárias — mais frequentemente como entrada para o AutoML, que exige type: mltable — prepare primeiro os dados numa conta ADLS Gen2 e crie o mltable com base nessa localização. mltable é fiável atualmente no ADLS Gen2.
O padrão de atalho do OneLake (abordado como parte dos endpoints em lote) adequa-se naturalmente à ML Table — o mesmo ficheiro físico reside no ADLS Gen2 (onde mltable funciona) e fica disponível no lakehouse do Fabric através de um atalho (onde as ferramentas do Fabric o reconhecem), sem necessidade de cópia.

mltable Inclui várias funcionalidades que uri_file / uri_folder não são oferecidas logo de fábrica. A tabela seguinte lista o equivalente mais próximo quando se lê diretamente o OneLake.

`mltable` Capacidade	Alternativa
Plano de leitura declarativo e portátil (delimitador, codificação, cabeçalho, tamanho da partição, tipos de colunas) guardado num ficheiro `MLTable` juntamente com os dados	Fixe as definições de leitura em Python (`pyarrow.parquet.ParquetDataset`, `pandas.read_csv(...)`, `polars.scan_parquet(...)`, `duckdb.read_parquet(...)`) e mantenha esse módulo de carregamento sob controlo de versão
Transformações incorporadas em tempo de leitura (`filter`, `drop_columns`, `convert_column_types`, `take_random_sample`)	Aplique os equivalentes no motor que escolher - `polars` / `duckdb` as frames preguiçosas aplicam filtros e projeções de forma semelhante; o Spark em `abfss://` faz o mesmo em escala
Composição de caminhos multi-fonte - uma tabela que abrange múltiplos ficheiros, pastas, padrões globos e até contas de armazenamento	Utilize `fs.glob(...)` de `azureml-fsspec`, `pyarrow.dataset.dataset(paths)` ou do `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 nos trabalhos do Azure Machine Learning (resolver os caminhos com base no ficheiro `MLTable` aquando da submissão do trabalho, montar apenas o que é referenciado)	Materialize um subconjunto selecionado a montante (um notebook do Fabric ou uma tarefa de pré-processamento do Azure Machine Learning escreve numa pasta dedicada `/Files/curated/...`) e aponte-o para `uri_folder`
Controlo de versões da receita de leitura (não apenas dos dados) através de um recurso de dados do tipo `mltable`	Versiona o script do loader com o código do modelo no Git, ou emparelha um `uri_folder` asset de dados com um pequeno módulo loader registado ao lado do script de treino
**Entrada do AutoML — o AutoML requer `type: mltable` (Configurar o treino do AutoML)	Preparar os dados no ADLS Gen2 (o atalho a partir do lakehouse mantém uma única cópia física) e criar aí o `mltable`

Para treino personalizado e classificação no OneLake, use uri_file / uri_folder com um motor à sua escolha (pyarrow / polars / duckdb de nó único, ou Spark distribuído no Azure Machine Learning). Estas opções oferecem as mesmas capacidades funcionais que mltable, com uma taxa de transferência comparável ou superior. Para AutoML, encaminhar através do ADLS Gen2 até haver suporte para mltable no OneLake. Podes usar um atalho para o OneLake para evitar duplicação de dados e ainda assim ter os dados disponíveis no Fabric para outros casos de uso.

Considerations

Modelo de identidade. O OneLake usa o modelo de identidade SaaS, por isso não expõe um ID de Subscrição. Em vez do controlo de acesso baseado em funções do Azure (Azure RBAC) na conta de armazenamento, o acesso é regido pelas funções da área de trabalho do Fabric (Administrador, Membro, Contribuidor, Visualizador) no lakehouse de destino. O armazenamento de dados OneLake suporta dois modos de credencial, que são documentados em Create datastores. Para configurar o armazenamento de dados e aceder ao lakehouse do Fabric, precisa de um utilizador com a função de Contribuidor na área de trabalho do Fabric e a função de administrador da área de trabalho do Azure Machine Learning.
Cópia única dos dados. O armazenamento de dados OneLake e o acesso direto ABFSS preservam o princípio da "cópia única" da OneLake. O padrão de atalho para endpoints batch preserva este princípio logicamente, mas requer uma conta ADLS Gen2 como armazenamento físico subjacente.
Colocalização regional. Coloque o espaço de trabalho do Azure Machine Learning, os recursos de computação e a capacidade do Fabric ou a região do OneLake na mesma região para evitar tráfego de saída entre regiões.

Comentários

Esta página foi útil?

Última atualização a 2026-06-26