Pirate Face：用 BitTorrent 去中心化分发 Hugging Face 模型

即插即用的 Hugging Face 模型种子下载。只需添加一个包。其他什么都不用改。

uv run --with pirateface python your_script.py

或者安装一次，之后就忘了它：

pip install pirateface

这就是全部设置。无需改代码，无需配置，无需新 API。你的脚本仍然像以前一样调用 transformers 或 huggingface_hub，而文件现在来自 Pirate Face 通过 BitTorrent 的做种者：

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("org/model")  # unchanged, now from the swarm

任何通过 huggingface_hub 下载的东西也一样：diffusers、sentence-transformers、 hf_hub_download、snapshot_download 以及 hf download CLI。

每个文件在进入正常的 Hugging Face 缓存之前，都会对照 Hugging Face 自己的指纹（大文件用 SHA-256，其余用 git SHA-1）进行校验。如果 Pirate Face 没有该模型、缺少某个 peer，或校验失败，该文件就照常从 Hugging Face 获取。卸载它，你的代码就和以前完全一样地运行。

还有一个小型 CLI：

pf download org/model [--revision REV]

它是如何接入的

该包会安装 pirateface.pth，Python 在启动时运行它。在有什么东西导入 huggingface_hub 之前它什么都不做，然后从 swarm 获取每个文件的字节。Hugging Face 仍然会告知应期待哪个 commit 和指纹，来自 swarm 的每个文件都会对照它进行校验。如果 Pirate Face 没有种子，或 30 秒内没有 peer 发送文件列表，该文件就照常从 Hugging Face 获取。缓存布局、符号链接和锁仍由 huggingface_hub 负责。

设置

变量	默认值
`PF_DISABLE`	off	关闭该 hook
`PF_QUIET`	off	不打印任何内容
`PF_NO_RESCUE`	off	不要请求 Pirate Face 添加它还没有的模型
`PF_DEBUG`	off	打印 libtorrent 的日志
`PF_CACHE`	`~/.cache/pirateface`	种子数据和文件列表的存放位置
`PF_API`	`https://pirateface.co`	Pirate Face 服务器
`PF_LISTEN`	任意空闲端口	libtorrent 监听接口
`PF_METADATA_TIMEOUT`	`30`	等待 peer 发送文件列表的秒数
`PF_STALL_TIMEOUT`	`60`	无进展多少秒后回退到 Hugging Face

除空值或 0 之外的任何值都会开启这些标志。

需要 Python 3.12 或 3.13（libtorrent 还没有 3.14 的 wheel）。uvx 会选择它拥有的最新 Python，所以要传入版本号：

uvx -p 3.13 --with pirateface --from huggingface_hub hf download org/model

开发

uv run --group dev ruff check