filesystem
最后更新
luxonis_ml.utils.filesystem类
FSType
属性
FSSPEC
MLFLOW
LuxonisFileSystem
Pycon
1file://<path>
2s3://<bucket>/<path>
3gcs://<bucket>/<path>
4mlflow://<experiment_id>/<run_id>/<artifact_path><artifact_path> 是可选的,默认为运行的工件根目录,因此 mlflow://<experiment_id>/<run_id> 本身就是一个有效的目的地。裸 mlflow:// 将文件系统绑定到当前活动的运行,并且需要 allow_active_mlflow_run=True。MLflow 工件无法删除,因此 delete_* 方法会为它们引发 NotImplementedError。为了获得更大的灵活性,用户可以在 PUT_FILE_REGISTRY 中注册 put_file 方法的自定义实现。然后,在初始化 LuxonisFileSystem 时,可以将其名称作为 put_file_plugin 参数传递。这允许自定义上传逻辑,例如上传前的额外处理或与其他服务的集成。示例
Pycon
1>>> @PUT_FILE_REGISTRY.register()
2... def put_file_plugin(*args, **kwargs) -> str:
3... print("Custom put_file called!")
4... return "remote_path"
5>>> fs = LuxonisFileSystem(
6... "file:///tmp/luxonis-ml",
7... put_file_plugin="put_file_plugin",
8... )
9>>> remote_path = fs.put_file("local/file.txt", "remote/file.txt")
10Custom put_file called!
11>>> print(remote_path)
12remote_pathPycon
1fs = LuxonisFileSystem(
2 "mlflow://12/abc123/checkpoints",
3 tracking_uri="http://localhost:5000",
4)
5fs.put_file("model.ckpt", "best.ckpt")
6# -> "mlflow://12/abc123/checkpoints/best.ckpt"方法
init
Python
1def __init__(path: str, allow_active_mlflow_run: bool | None = False, allow_local: bool | None = True, cache_storage: str | None = None, put_file_plugin: str | None = None, tracking_uri: str | None = None):LuxonisFileSystem。参数path(str): 输入路径,由协议和路径组成,或仅由本地文件的路径组成。MLflow 路径的形式为mlflow://<experiment_id>/<run_id>/<artifact_path>,其中工件路径是可选的,或者是一个裸mlflow://以使用活动运行。allow_active_mlflow_run(bool | None): 是否允许对活动 MLflow 运行进行操作。allow_local(bool | None): 是否允许对本地文件系统进行操作。cache_storage(str | None):fsspecfilecache目录的路径,仅由s3://和gcs://后端使用。如果未设置,则不使用缓存,并且对于file://和mlflow://,会发出警告并忽略。put_file_plugin(str | None): PUT_FILE_REGISTRY 中注册函数的名称,用于代替 LuxonisFileSystem.put_file。注册函数必须符合 PutFile 协议。tracking_uri(str | None): 要使用的 MLflow 跟踪 URI。如果省略,则使用环境中的MLFLOW_TRACKING_URI。
ValueError:- 如果协议不受支持。
- 如果协议是
"file"但不允许本地文件。
如果协议是"mlflow"但未指定 MLflow 路径:并且不允许使用活动 MLflow 运行。
如果协议是"mlflow"但环境变量中没有:"MLFLOW_TRACKING_URI"。
delete_dir
Python
1def delete_dir(remote_dir: PosixPathType = '', allow_delete_parent: bool = False):remote_dir(PosixPathType): 远程目录的相对路径。allow_delete_parent(bool): 是否允许删除父目录。
ValueError: 如果未指定目录且不允许删除父目录。NotImplementedError: 如果使用 MLflow,其工件无法删除。
delete_file
Python
1def delete_file(remote_path: PosixPathType):remote_path(PosixPathType): 远程文件的相对路径。
NotImplementedError: 如果使用 MLflow,其工件无法删除。
delete_files
Python
1def delete_files(remote_paths: list[PosixPathType]):remote_paths(list[PosixPathType]): 远程文件的相对路径。
NotImplementedError: 如果使用 MLflow,其工件无法删除。
download
Python
1def download(url: str, dest: PathType | None, tracking_uri: str | None = None) -> Path:LuxonisFileSystem 实例。参数url(str): 文件或目录的 URL。dest(PathType | None): 目标目录。如果为None,则使用当前工作目录。tracking_uri(str | None): 用于mlflow://URL 的 MLflow 跟踪 URI。
Path: 下载的文件或目录的路径。当目标已存在时,数据嵌套在其中并返回嵌套路径。
exists
Python
1def exists(remote_path: PosixPathType = '') -> bool:remote_path(PosixPathType): 远程文件的相对路径。默认为空字符串,表示文件系统的根路径。
bool: 如果路径存在,则为True,否则为False。
MlflowException: 如果查找本身失败,例如连接、身份验证或服务器错误。只有 MLflow 明确的“此不存在”答案才报告为False。
get_dir
Python
1def get_dir(remote_paths: PosixPathType | Iterable[PosixPathType], local_dir: PathType, mlflow_instance: ModuleType | None = None) -> Path:注意
MLflow 下载在目标旁边进行暂存,因此大型工件需要在目标自己的文件系统而不是
$TMPDIR 中有可用空间。remote_paths(PosixPathType | Iterable[PosixPathType]): 指定要遍历的目录的路径,或可能位于不同目录中的文件的可迭代对象。local_dir(PathType): 本地目录的路径。mlflow_instance(ModuleType | None): 从活动运行下载时要使用的 MLflow 实例。
Path: 下载的目录的路径。
ValueError: 如果使用 MLflow 且无法解析运行。
get_file
Python
1def get_file(remote_path: PosixPathType, local_path: PathType, mlflow_instance: ModuleType | None = None) -> Path:注意
MLflow 下载在目标旁边进行暂存,因此大型工件需要在目标自己的文件系统而不是
$TMPDIR 中有可用空间。remote_path(PosixPathType): 远程文件的相对路径。local_path(PathType): 本地文件的路径。mlflow_instance(ModuleType | None): 从活动运行下载时要使用的 MLflow 实例。
Path: 下载的文件路径。
ValueError: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。
get_file_uuid
Python
1def get_file_uuid(path: PathType, local: bool = False) -> str:注意
文件分块哈希,因此内存使用量不会随其大小而增长。MLflow 是一个例外:其工件通过
read_to_byte_buffer 下载,该方法在哈希开始之前将整个文件保存在内存中。path(PathType): 远程文件的相对路径,或当local为True时的本地路径。local(bool): 指定本地路径而不是远程路径。
str: 从文件字节生成的 UUID。
ValueError: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。
get_file_uuids
Python
1def get_file_uuids(paths: Iterable[PathType], local: bool = False) -> dict[str, str]:注意
文件并发哈希,因此
get_file_uuid 的内存限制在池中的每个线程上应用一次。paths(Iterable[PathType]): 相对远程路径,或当local为True时的本地路径。local(bool): 指定本地路径而不是远程路径。
dict[str, str]: 将路径映射到其 UUID 的字典。
get_protocol
Python
1def get_protocol(path: str) -> str:path(str): 可选包含协议的路径。
str: 检测到的协议。如果未指定协议,则默认为"file"。
init_fsspec_filesystem
Python
1def init_fsspec_filesystem(self) -> fsspec.AbstractFileSystem:fsspec 文件系统。返回fsspec.AbstractFileSystem: 初始化的fsspec文件系统。
NotImplementedError: 如果协议不受fsspec支持。RuntimeError: 如果协议的凭据未在环境变量中正确设置。
is_directory
Python
1def is_directory(remote_path: PosixPathType) -> bool:remote_path(PosixPathType): 远程路径的相对路径。
bool: 如果路径是目录,则为True,否则为False。
FileNotFoundError: 如果无法在fsspec文件系统上检查路径。MlflowException: 如果无法检查 MLflow 运行,例如因为它不存在。
put_bytes
Python
1def put_bytes(file_bytes: bytes, remote_path: PosixPathType, mlflow_instance: ModuleType | None = None):file_bytes(bytes): 要上传的文件内容。remote_path(PosixPathType): 远程文件的相对路径。mlflow_instance(ModuleType | None): 上传到活动运行时要使用的 MLflow 实例。
ValueError: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。
put_dir
Python
1def put_dir(local_paths: PathType | Iterable[PathType], remote_dir: PosixPathType, uuid_dict: dict[str, str] | None = None, mlflow_instance: ModuleType | None = None, copy_contents: bool = False) -> dict[str, str] | None:注意
目录在一次调用中上传到 MLflow,并且从不暂存。传递单个文件会通过
put_file 一个接一个地上传它们,因此如果设置了 uuid_dict,则其中描述的暂存适用于每个文件。local_paths(PathType | Iterable[PathType]): 指定要遍历的目录的路径,或可能位于不同目录中的文件的可迭代对象。remote_dir(PosixPathType): 远程目录的相对路径。uuid_dict(dict[str, str] | None): 将路径存储为键,将相应的 UUID 存储为值以替换文件基本名称。mlflow_instance(ModuleType | None): 上传到活动运行时要使用的 MLflow 实例。copy_contents(bool): 如果为True,则仅复制local_paths中指定的文件夹内容。
dict[str, str] | None: 如果local_paths是文件的可迭代对象,则为本地路径到远程路径的映射,否则为None。
ValueError: 1.如果local_paths是单个路径但不是:目录。
如果上传到活动 MLflow 运行但没有:MLflow 实例。
put_file
Python
1def put_file(local_path: PathType, remote_path: PosixPathType, mlflow_instance: ModuleType | None = None) -> str:注意
MLflow 将文件存储在其本地基本名称下,因此以不同名称上传会通过临时副本进行暂存。它放置在源旁边,这意味着大型工件需要在源自己的文件系统而不是
$TMPDIR 中有可用空间。如果该目录不可写,则暂存会回退到 $TMPDIR,这在大多数 Linux 发行版上是 RAM 支持的 tmpfs,因此大型工件可能会因 No space left on device 而失败。local_path(PathType): 本地文件的路径。remote_path(PosixPathType): 远程文件的相对路径。mlflow_instance(ModuleType | None): 上传到活动运行时要使用的 MLflow 实例。
str: 上传文件的完整远程路径。
ValueError: 如果使用 MLflow 且没有活动运行或未提供 MLflow 实例。
read_text
Python
1def read_text(remote_path: PosixPathType) -> str | bytes:remote_path(PosixPathType): 远程文件的相对路径。
str | bytes: 文件内容。
ValueError: 如果使用 MLflow 且未指定相对工件路径或无法解析运行。
read_to_byte_buffer
Python
1def read_to_byte_buffer(remote_path: PosixPathType | None = None) -> BytesIO:remote_path(PosixPathType | None): 远程文件的相对路径。如果省略,则从self.path读取。
BytesIO: 包含文件内容的字节缓冲区。
ValueError:- 如果使用 MLflow 但未指定相对工件路径。
- 如果使用 MLflow 但无法解析运行。
split_full_path
Python
1def split_full_path(path: PathType) -> tuple[str, str]:path(PathType): 可选包含协议的完整路径。
tuple[str, str]: 使用的协议和绝对路径。
upload
Python
1def upload(local_path: PathType, url: str, tracking_uri: str | None = None):local_path(PathType): 本地文件或目录的路径。url(str): 远程文件或目录的 URL。tracking_uri(str | None): 用于mlflow://URL 的 MLflow 跟踪 URI。
walk_dir
Python
1def walk_dir(remote_dir: PosixPathType, recursive: bool = True, typ: Literal['file', 'directory', 'all'] = 'file') -> Iterator[str]:remote_dir(PosixPathType): 远程目录的相对路径。recursive(bool): 如果为 True,则递归遍历目录。默认为 True。typ(Literal['file', 'directory', 'all']): 要生成的条目类型。对应于 fsspec 的 ls 输出中的"type"字段。默认为"file"。
Iterator[str]
- 远程目录中文件的相对路径。
属性
artifact_path
- 相对于运行工件根目录的工件路径,如果文件系统不是 MLflow 文件系统或未给出工件路径,则为
None。
experiment_id
- 实验 ID,如果文件系统不是 MLflow 文件系统或实验未知,则为
None。
full_path
- 以协议为前缀的完整远程路径。
is_fsspec
- 如果文件系统使用 fsspec,则为
True。
is_mlflow
- 如果文件系统是 MLflow 文件系统,则为
True。
protocol
run_id
- 运行 ID,如果文件系统不是 MLflow 文件系统或运行未知,则为
None。
tracking_uri
- 跟踪 URI,如果文件系统不是 MLflow 文件系统,则为
None。
PutFile
put_file 插件的协议。