FileDataset 类

表示要在 Azure 机器学习中使用的数据存储或公共 URL 中的文件引用集合。

FileDataset 定义了一系列延迟求值的不可变操作,以将数据从数据源加载到文件流中。 在要求 FileDataset 传送数据之前,不会从源加载数据。

FileDataset 是使用 FileDatasetFactory 类的 from_files 方法创建的。

有关详细信息,请参阅 添加 & 注册数据集一文。 若要开始使用文件数据集,请参阅 https://aka.ms/filedataset-samplenotebook

初始化 FileDataset 对象。

不应直接调用此构造函数。 数据集旨在使用 FileDatasetFactory 类创建。

继承
FileDataset

构造函数

FileDataset()

注解

FileDataset 可用作试验运行的输入。 它还可以用指定名称注册到工作区,并在以后通过该名称进行检索。

可以通过调用此类上可用的不同子集设置方法来对 FileDataset 进行子集设置。 子集设置的结果始终是新的 FileDataset。

当要求 FileDataset 将数据传送到另一个存储机制(例如,已下载或装载到本地路径)时,将发生实际的数据加载。

方法

as_cache

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

创建映射到 datacache_store 和数据集的 DatacacheConsumptionConfig。

as_download

使用设置为下载的模式创建 DatasetConsumptionConfig。

在提交的运行中,数据集中的文件将下载到计算目标上的本地路径。 可以从运行上下文的参数值和 input_datasets 字段检索下载位置。 我们将自动生成输入名称。 如果要指定自定义输入名称,请调用 as_named_input 方法。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_download()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The download location can be retrieved from argument values
   import sys
   download_location = sys.argv[1]

   # The download location can also be retrieved from input_datasets of the run context.
   from azureml.core import Run
   download_location = Run.get_context().input_datasets['input_1']
as_hdfs

将模式设置为 hdfs。

在提交的 synapse 运行中,数据集中的文件将转换为计算目标上的本地路径。 可以从参数值和 os 环境变量检索 hdfs 路径。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_hdfs()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The hdfs path can be retrieved from argument values
   import sys
   hdfs_path = sys.argv[1]

   # The hdfs path can also be retrieved from input_datasets of the run context.
   import os
   hdfs_path = os.environ['input_<hash>']
as_mount

使用设置为装载的模式创建 DatasetConsumptionConfig。

在提交的运行中,数据集中的文件将装载到计算目标上的本地路径。 可以从运行上下文的参数值和 input_datasets 字段检索装载点。 我们将自动生成输入名称。 如果要指定自定义输入名称,请调用 as_named_input 方法。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_mount()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The mount point can be retrieved from argument values
   import sys
   mount_point = sys.argv[1]

   # The mount point can also be retrieved from input_datasets of the run context.
   from azureml.core import Run
   mount_point = Run.get_context().input_datasets['input_1']
download

下载数据集定义为本地文件的文件流。

file_metadata

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

通过指定元数据列名称获取文件元数据表达式。

支持的文件元数据列为 Size、LastModifiedTime、CreationTime、Extension 和 CanSeek

filter

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

筛选数据,仅保留与指定表达式匹配的记录。

hydrate

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

将数据集解冻到 datacache_store 指定的请求副本中。

mount

创建一个上下文管理器,用于将数据集定义的文件系统流装载为本地文件。

random_split

按指定百分比随机并大致地将数据集中的文件拆分为两个部分。

返回的第一个数据集包含大约总文件引用数的 percentage,第二个数据集包含剩余的文件引用。

skip

按指定计数跳过数据集顶部的文件流。

take

按指定的计数从数据集的顶部起获取记录示例。

take_sample

按指定的概率大致获取数据集中文件流的随机示例。

to_path

获取数据集定义的每个文件流的文件路径列表。

as_cache

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

创建映射到 datacache_store 和数据集的 DatacacheConsumptionConfig。

as_cache(datacache_store)

参数

名称 说明
datacache_store
必需

用于解冻的 datacachestore。

返回

类型 说明

描述如何在运行中具体化 datacache 的配置对象。

as_download

使用设置为下载的模式创建 DatasetConsumptionConfig。

在提交的运行中,数据集中的文件将下载到计算目标上的本地路径。 可以从运行上下文的参数值和 input_datasets 字段检索下载位置。 我们将自动生成输入名称。 如果要指定自定义输入名称,请调用 as_named_input 方法。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_download()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The download location can be retrieved from argument values
   import sys
   download_location = sys.argv[1]

   # The download location can also be retrieved from input_datasets of the run context.
   from azureml.core import Run
   download_location = Run.get_context().input_datasets['input_1']
as_download(path_on_compute=None)

参数

名称 说明
path_on_compute
str

计算上要提供数据的目标路径。

默认值: None

注解

从单个文件的路径创建数据集时,下载位置将是单个已下载文件的路径。 否则,下载位置将是所有已下载文件的封闭文件夹的路径。

如果 path_on_compute 以 / 开头,则它将被视为绝对路径。 如果未以 / 开始,则它将被视为相对于工作目录的相对路径。 如果指定了绝对路径,请确保作业有权写入该目录。

as_hdfs

将模式设置为 hdfs。

在提交的 synapse 运行中,数据集中的文件将转换为计算目标上的本地路径。 可以从参数值和 os 环境变量检索 hdfs 路径。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_hdfs()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The hdfs path can be retrieved from argument values
   import sys
   hdfs_path = sys.argv[1]

   # The hdfs path can also be retrieved from input_datasets of the run context.
   import os
   hdfs_path = os.environ['input_<hash>']
as_hdfs()

注解

从单个文件的路径创建数据集时,hdfs 路径将为单个文件的路径。 否则,hdfs 路径将是所有已装载文件的封闭文件夹的路径。

as_mount

使用设置为装载的模式创建 DatasetConsumptionConfig。

在提交的运行中,数据集中的文件将装载到计算目标上的本地路径。 可以从运行上下文的参数值和 input_datasets 字段检索装载点。 我们将自动生成输入名称。 如果要指定自定义输入名称,请调用 as_named_input 方法。


   # Given a run submitted with dataset input like this:
   dataset_input = dataset.as_mount()
   experiment.submit(ScriptRunConfig(source_directory, arguments=[dataset_input]))


   # Following are sample codes running in context of the submitted run:

   # The mount point can be retrieved from argument values
   import sys
   mount_point = sys.argv[1]

   # The mount point can also be retrieved from input_datasets of the run context.
   from azureml.core import Run
   mount_point = Run.get_context().input_datasets['input_1']
as_mount(path_on_compute=None)

参数

名称 说明
path_on_compute
str

计算上要提供数据的目标路径。

默认值: None

注解

从单个文件的路径创建数据集时,装载点将为单一已装载文件路径。 否则,装载点将是所有已装载文件的封闭文件夹的路径。

如果 path_on_compute 以 / 开头,则它将被视为绝对路径。 如果未以 / 开始,则它将被视为相对于工作目录的相对路径。 如果指定了绝对路径,请确保作业有权写入该目录。

download

下载数据集定义为本地文件的文件流。

download(target_path=None, overwrite=False, ignore_not_found=False)

参数

名称 说明
target_path
必需
str

要将文件下载到的本地目录。 如果为 None,则数据将下载到临时目录中。

overwrite
必需

指示是否覆盖现有文件。 默认值为 False。 如果覆盖设置为 True,则覆盖现有文件;否则将引发异常。

ignore_not_found
必需

指示当找不到由数据集指向的某些文件时是否使下载失败。 默认值为 False。 如果 ignore_not_found 设置为 False,则任何文件下载因任何原因失败,下载都将失败;否则,将记录未发现错误的警告,并且只要没有遇到其他错误类型,下载都将成功。

返回

类型 说明

返回下载的每个文件的文件路径数组。

注解

如果 target_path 以 / 开头,则会将它视为绝对路径。 如果它不以 / 开头,则会将它视为相对于当前工作目录的相对路径。

file_metadata

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

通过指定元数据列名称获取文件元数据表达式。

支持的文件元数据列为 Size、LastModifiedTime、CreationTime、Extension 和 CanSeek

file_metadata(col)

参数

名称 说明
col
必需
str

列的名称

返回

类型 说明
<xref:azureml.dataprep.api.expression.RecordFieldExpression>

返回一个表达式,该表达式会检索指定列中的值。

filter

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

筛选数据,仅保留与指定表达式匹配的记录。

filter(expression)

参数

名称 说明
expression
必需
<xref:azureml.dataprep.api.expression.Expression>

要计算的表达式。

返回

类型 说明

已修改的数据集(未注册)。

注解

通过使用列的名称对数据集编制索引来启动表达式。 它们支持各种函数和运算符,可以使用逻辑运算符进行组合。 当数据提取时,将对每个记录进行惰性计算,而不会对其定义。


   (dataset.file_metadata('Size') > 10000) & (dataset.file_metadata('CanSeek') == True)
   dataset.file_metadata('Extension').starts_with('j')

hydrate

注意

这是一个实验性的方法,可能会在任何时候更改。 有关详细信息,请参阅 https://aka.ms/azuremlexperimental

将数据集解冻到 datacache_store 指定的请求副本中。

hydrate(datacache_store, replica_count=None)

参数

名称 说明
datacache_store
必需

用于解冻的 datacachestore。

replica_count
必需
<xref:Int>, <xref:optional>

要解冻的副本数。

返回

类型 说明

描述如何在运行中具体化 datacache 的配置对象。

mount

创建一个上下文管理器,用于将数据集定义的文件系统流装载为本地文件。

mount(mount_point=None, **kwargs)

参数

名称 说明
mount_point
必需
str

要将文件装载到的本地目录。 如果为 None,则数据将装载到临时目录中,可以通过调用 MountContext.mount_point 实例方法找到该目录。

返回

类型 说明
<xref:MountContext>: <xref:the> <xref:context> <xref:manager.> <xref:Upon> <xref:entering> <xref:the> <xref:context> <xref:manager>, <xref:the> <xref:dataflow> <xref:will> <xref:be> <xref:mounted> <xref:to> <xref:the> <xref:mount_point.> <xref:Upon> exit, <xref:it> <xref:will> <xref:remove> <xref:the> mount <xref:point> <xref:and> clean <xref:up> <xref:the> <xref:daemon> <xref:process> <xref:used> <xref:to> mount <xref:the> <xref:dataflow.>

返回用于管理装载生命周期的上下文管理器。

注解

将返回上下文管理器来管理装载的生命周期。 若要装载,需要输入上下文管理器,若要卸载,请退出上下文管理器。

仅在安装了本地包 libfuse 的 Unix 或 Unix 类操作系统上支持装载。 如果在 Docker 容器中运行,则必须使用 -privileged 标志启动 Docker 容器,或从 -cap-add SYS_ADMIN -device /dev/fuse 开始。


   datastore = Datastore.get(workspace, 'workspaceblobstore')
   dataset = Dataset.File.from_files((datastore, 'animals/dog/year-*/*.jpg'))

   with dataset.mount() as mount_context:
       # list top level mounted files and folders in the dataset
       os.listdir(mount_context.mount_point)

   # You can also use the start and stop methods
   mount_context = dataset.mount()
   mount_context.start()  # this will mount the file streams
   mount_context.stop()  # this will unmount the file streams

如果 target_path 以 / 开头,则会将它视为绝对路径。 如果它不以 / 开头,则会将它视为相对于当前工作目录的相对路径。

random_split

按指定百分比随机并大致地将数据集中的文件拆分为两个部分。

返回的第一个数据集包含大约总文件引用数的 percentage,第二个数据集包含剩余的文件引用。

random_split(percentage, seed=None)

参数

名称 说明
percentage
必需

要拆分数据集的大致百分比。 这必须是介于 0.0 和 1.0 之间的数字。

seed
必需
int

用于随机生成器的可选种子。

返回

类型 说明

返回表示拆分后的两个数据集的新 FileDataset 对象的元组。

skip

按指定计数跳过数据集顶部的文件流。

skip(count)

参数

名称 说明
count
必需
int

要跳过的文件流数。

返回

类型 说明

返回一个新的 FileDataset 对象,该对象表示跳过了文件流的数据集。

take

按指定的计数从数据集的顶部起获取记录示例。

take(count)

参数

名称 说明
count
必需
int

要接受的文件流数。

返回

类型 说明

返回表示采样数据集的新 FileDataset 对象。

take_sample

按指定的概率大致获取数据集中文件流的随机示例。

take_sample(probability, seed=None)

参数

名称 说明
probability
必需

包含在示例中的文件流的概率。

seed
必需
int

用于随机生成器的可选种子。

返回

类型 说明

返回表示采样数据集的新 FileDataset 对象。

to_path

获取数据集定义的每个文件流的文件路径列表。

to_path()

返回

类型 说明

返回文件路径的数组。

注解

文件路径是下载或装载文件流时本地文件的相对路径。

根据数据源的指定方式,将从文件路径中删除通用前缀以创建数据集。 例如:


   datastore = Datastore.get(workspace, 'workspaceblobstore')
   dataset = Dataset.File.from_files((datastore, 'animals/dog/year-*/*.jpg'))
   print(dataset.to_path())

   # ['year-2018/1.jpg'
   #  'year-2018/2.jpg'
   #  'year-2019/1.jpg']

   dataset = Dataset.File.from_files('https://dprepdata.blob.core.windows.net/demo/green-small/*.csv')

   print(dataset.to_path())
   # ['/green_tripdata_2013-08.csv']