此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 类
  • FSType
  • LuxonisFileSystem
  • PutFile
  • 属性
  • PUT_FILE_REGISTRY
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_ml.utils.filesystem

类

FSType

文件系统后端类型。

属性

FSSPEC
fsspec 兼容文件系统。
MLFLOW
MLflow 工件存储。

LuxonisFileSystem

远程和本地源的抽象。此类别为不同存储后端(包括本地文件系统、S3、GCS 和 MLflow 工件存储)的文件操作提供统一接口。后端通过 URL 协议选择:
Pycon
1file://<path>
2s3://<bucket>/<path>
3gcs://<bucket>/<path>
4mlflow://<experiment_id>/<run_id>/<artifact_path>
没有协议的路径被视为本地路径。对于 MLflow,<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 参数传递。这允许自定义上传逻辑,例如上传前的额外处理或与其他服务的集成。

方法

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): fsspec filecache 目录的路径,仅由 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:
    1. 如果协议不受支持。
    2. 如果协议是 "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:
将许多文件从远程存储复制到本地存储。参数
  • 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:
从远程存储复制单个文件。参数
  • 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:
读取文件并返回从文件字节生成的(唯一)UUID。参数
  • 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]:
计算文件系统中存储的所有文件的 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:
将文件上传到远程存储。参数
  • 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:
将单个文件复制到远程存储。参数
  • 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:
    1. 如果使用 MLflow 但未指定相对工件路径。
    2. 如果使用 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):
将文件或目录上传到远程存储。对于上传单个本地对象而无需创建 LuxonisFileSystem 实例很有用。参数
  • 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 工件路径。返回
  • 相对于运行工件根目录的工件路径,如果文件系统不是 MLflow 文件系统或未给出工件路径,则为 None。
experiment_id
MLflow 实验 ID。返回
  • 实验 ID,如果文件系统不是 MLflow 文件系统或实验未知,则为 None。
full_path
完整远程路径。返回
  • 以协议为前缀的完整远程路径。
is_fsspec
检查文件系统是否使用 fsspec。返回
  • 如果文件系统使用 fsspec,则为 True。
is_mlflow
检查文件系统是否为 MLflow 文件系统。返回
  • 如果文件系统是 MLflow 文件系统,则为 True。
protocol
返回文件系统的协议。@type: str
run_id
MLflow 运行 ID。返回
  • 运行 ID,如果文件系统不是 MLflow 文件系统或运行未知,则为 None。
tracking_uri
MLflow 跟踪 URI。返回
  • 跟踪 URI,如果文件系统不是 MLflow 文件系统,则为 None。

PutFile

put_file 插件的协议。

属性

PUT_FILE_REGISTRY