speechbrain.utils.fetching 模块

下载或以其他方式获取预训练模型

作者

  • Aku Rouhe 2021

  • Samuele Cornell 2021

  • Andreas Nautsch 2022, 2023

  • Sylvain de Langen 2024

  • Peter Plantinga 2024

摘要

类

FetchFrom

指定从何处获取模型/音频。

FetchSource

描述源路径及如何获取的 NamedTuple

LocalStrategy

描述在使用 fetch() 时，应选择何种策略来获取和链接本地文件。

函数

fetch

获取本地路径、远程 URL 或远程 HuggingFace 文件，如果需要则下载到本地并返回本地路径。

guess_source

根据给定的 FetchSource 或字符串源标识符，尝试猜测匹配的 FetchFrom（例如，本地或 URI）。

link_with_strategy

如果使用 LocalStrategy.COPY 或 LocalStrategy.COPY_SKIP_CACHE，则销毁 dst 处存在的文件或符号链接，并从 src 创建一个副本到 dst。

参考

class speechbrain.utils.fetching.FetchFrom(*values)[source]

基类: Enum

指定从何处获取模型/音频。

注意：如果未定义源类型，HuggingFace 仓库源和本地文件夹源可能会混淆。

LOCAL = 1
HUGGING_FACE = 2
URI = 3
class speechbrain.utils.fetching.FetchSource(FetchFrom, path)

基类: tuple

描述源路径及如何获取的 NamedTuple

FetchFrom

字段号 0 的别名

encode(*args, **kwargs)
path

字段号 1 的别名

class speechbrain.utils.fetching.LocalStrategy(*values)[source]

基类: Enum

描述在使用 fetch() 时，应选择何种策略来获取和链接本地文件。

如果文件是远程的且不在缓存中，则获取它（可能存入缓存）。

然后，如果需要，在目标文件夹中创建指向本地文件的符号链接。

警告

Windows 需要额外的配置才能启用符号链接，因为这在该平台上存在潜在的安全风险。您需要以管理员身份运行 Python，或启用开发者模式。请参阅MS 文档。此外，huggingface_hub 库对符号链接的使用是独立控制的。请参阅HF hub 文档以供参考。

COPY = 2

如果文件是远程的且不在缓存中，则获取它（可能存入缓存）。

然后，如果需要，在目标文件夹中创建本地文件的副本。

COPY_SKIP_CACHE = 3

如果文件是远程的且不在缓存中，则获取它，最好直接下载到目标目录。

然后，如果需要，在目标文件夹中创建本地文件的副本。

如果文件是远程的且不在缓存中，则获取它（可能存入缓存）。

然后，返回其本地路径，即使它不在目标文件夹中（例如，它可能位于缓存目录中）。

注意

此策略可能会破坏未预期此行为的代码，因为目标文件夹不再保证包含文件的副本或链接。

如果使用 LocalStrategy.COPY 或 LocalStrategy.COPY_SKIP_CACHE，则销毁 dst 处存在的文件或符号链接，并从 src 创建一个副本到 dst。

如果使用 LocalStrategy.SYMLINK，则销毁 dst 处存在的文件或符号链接，并从 src 创建一个符号链接到 dst。

如果传入 LocalStrategy.NO_LINK，则返回 src 路径。

参数:

  • src (pathlib.Path) – 要链接到的源文件路径。必须是有效路径。

  • dst (pathlib.Path) – 最终目标文件的路径。文件可能尚未存在，但其所在的目录必须存在。

  • local_strategy (LocalStrategy) – 链接策略。

返回:

链接/复制（如果适用）后磁盘上最终文件的路径。

返回类型:

pathlib.Path

speechbrain.utils.fetching.guess_source(source: str | FetchSource) → tuple[FetchFrom, str][source]

根据给定的 FetchSource 或字符串源标识符，尝试猜测匹配的 FetchFrom（例如，本地或 URI）。

如果 source 已经是 FetchSource，则原样返回。

参数:

source (str 或 FetchSource) –

查找文件的位置。fetch() 使用以下逻辑解释此路径：

  • 首先，如果源以“http://”或“https://”开头，则将其解释为网址并下载文件。

  • 其次，如果源是有效的目录路径，则根据本地策略，文件将被链接、复制或直接返回。

  • 否则，源将被解释为 HuggingFace 模型 Hub ID，并从中下载文件（可能带缓存）。

返回类型:

tuple 类型，包含 (FetchFrom, str)

speechbrain.utils.fetching.fetch(filename, source: str | FetchSource, savedir: str | Path | None = None, overwrite: bool = False, allow_updates: bool = False, allow_network: bool = True, save_filename: str | None = None, use_auth_token: bool = False, revision: str | None = None, huggingface_cache_dir: str | Path | None = None, local_strategy: LocalStrategy | None = LocalStrategy.SYMLINK)[source]

获取本地路径、远程 URL 或远程 HuggingFace 文件，如果需要则下载到本地并返回本地路径。

当指定了 savedir，但文件已在本地其他位置存在时，指定的 LocalStrategy 选择是复制还是符号链接。

如果 <savedir>/<save_filename> 在本地存在，则原样返回（除非使用 overwrite 或 allow_updates）。

HF_HOME 环境变量（默认：~/.cache/huggingface）选择 HF 的缓存目录。为了优先直接下载到 savedir，请指定 local_strategy=LocalStrategy.COPY_SKIP_CACHE。如果可能，总是首先查找 HF 缓存。

参数:

  • filename (str) – 文件名，包含扩展名。

  • source (str 或 FetchSource) – 文件名的本地或远程根路径。最终路径由 <source>/<filename> 确定。有关如何推断路径类型的信息，请参阅 guess_source()。

  • savedir (str, 可选) – 如果指定，文件将在此目录下可用（可能是副本或符号链接，取决于 local_strategy）。从 URL 下载时必须指定此项。

  • overwrite (bool, 默认为 False) – 允许通过复制/符号链接/获取重新创建目标。这不会跳过 HuggingFace 缓存（参见 allow_updates）。

  • allow_updates (bool, 默认为 True) – 如果为 True，对于 HF 上的远程文件，检查更新并在有新版本时下载。如果为 False，当请求的文件在本地可用时，直接加载它们，而不从 HF 获取。

  • allow_network (bool, 默认为 True) – 如果为 True，允许网络访问。如果为 False，则不会获取远程 URL 或 HF 文件，无论其他参数如何。

  • save_filename (str, 可选, 默认为 None) – 用于保存此文件的文件名。如果未提供或为 None，则默认为 filename 参数。

  • use_auth_token (bool, 默认为 False) – 如果为 True，使用 HuggingFace 的 auth_token 从 Hub 加载私有模型。

  • revision (str, 可选, 默认为 None) – HuggingFace Hub 模型修订版本（Git 分支名/标签/提交哈希），用于固定到特定版本。在更改修订版本且本地文件可能仍然存在时，allow_updates 必须为 True。

  • huggingface_cache_dir (str, 可选, 默认为 None) – HuggingFace 缓存路径；如果为 None，则假定默认缓存位置。如果使用 LocalStrategy.COPY_SKIP_CACHE，则忽略此项。请优先让用户通过环境变量自行指定缓存目录。

  • local_strategy (LocalStrategy, 可选) – 用于本地文件存储的策略 – 选项参见 LocalStrategy。除非提供了 savedir，否则此项将被忽略，默认值为 LocalStrategy.SYMLINK，它会在 savedir 中添加一个指向下载/缓存文件的链接。

返回:

本地文件系统上的文件路径。

返回类型:

pathlib.Path

引发:

ValueError – 如果未找到文件