speechbrain.utils.fetching 模块

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

Authors:

  • 阿库·罗赫 2021

  • 萨穆埃莱·科内尔 2021

  • 安德烈亚斯·诺茨 2022, 2023

  • Sylvain de Langen 2024

  • 彼得·普兰廷加 2024

摘要

类：

FetchFrom

指定从哪里获取模型/音频。

FetchSource

描述源路径及其获取方式的命名元组

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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[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路径。

Parameters:

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

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

  • local_strategy (LocalStrategy) – 用于链接的策略。

Returns:

磁盘上最终文件的路径，在链接/复制（如果有）之后。

Return type:

pathlib.Path

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

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

如果 source 已经是一个 FetchSource，则直接返回。

Parameters:

source (str 或 FetchSource) –

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

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

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

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

Return type:

tuple 的 (FetchFrom, str)

speechbrain.utils.fetching.fetch(filename, source: str | FetchSource, savedir: str | Path | None = None, overwrite: bool = False, allow_updates: bool = True, 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选择是复制还是创建符号链接。

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

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

Parameters:

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

  • source (str 或 FetchSource) – 文件名的本地或远程根路径。最终路径由 / 决定。 请参阅 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 中添加一个指向下载/缓存文件的链接。

Returns:

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

Return type:

pathlib.Path

Raises:

ValueError – 如果文件未找到