swift-huggingface 发行说明 / 新功能

Hugging Face 已宣布发布 swift-huggingface，这是一个新的 Swift 包，为 Hugging Face Hub 提供完整的客户端。此库解决了 Swift 生态系统中关键的可靠性和开发者体验差距，具体涉及大型模型下载、与 Python 的缓存同步以及身份验证灵活性。

可靠的模型下载和断点续传支持

swift-huggingface 使用基于 URLSession 下载任务的强大系统替换了之前不可靠的下载机制。它提供了明确的进度跟踪和恢复中断下载的能力，这对于机器学习中常见的多吉字节文件至关重要。

关键下载功能包括：

  • 断点续传：resumeDownloadFile 方法允许开发者使用保存的断点数据从中断处继续下载。
  • 快照下载：downloadSnapshot 函数管理整个模型仓库，跟踪元数据以确保后续调用仅下载已更改的文件。
  • 过滤下载：用户可以指定模式（例如 *.safetensors、*.json）仅下载仓库中必要的文件。

与 Python 兼容的缓存结构

为了消除冗余下载，swift-huggingface 实现了与 Python huggingface_hub 库兼容的缓存结构。这使得 Swift 应用程序可以共享通过 Python CLI 或 transformers 库已经下载的模型。

缓存使用内容寻址存储，文件根据其 ETag 存储在 blobs/ 目录中。快照目录使用指向这些 blob 的符号链接以最小化磁盘使用。该库遵循标准环境变量约定来确定缓存位置，检查 HF_HUB_CACHE、HF_HOME，并默认为 ~/.cache/huggingface/hub。为了防止多进程访问期间的竞争条件，该库使用 flock(2) 文件锁定。

灵活的身份验证和 OAuth 2.0

身份验证通过 TokenProvider 模式进行管理，使凭据的来源明确。该库支持多种身份验证流程：

  • 自动检测：自动在环境变量（HF_TOKEN、HUGGING_FACE_HUB_TOKEN）、令牌文件或标准 HF CLI 位置中查找令牌。
  • 静态令牌：为 CI/CD 环境显式提供的令牌。
  • Keychain 集成：通过系统 Keychain 为生产应用提供安全存储。
  • OAuth 2.0：面向用户的应用程序的完整实现，包括处理系统浏览器登录、在 Keychain 中存储令牌以及自动刷新令牌的 HuggingFaceAuthenticationManager。

全面的 Hub 和推理 API 覆盖

除了文件操作，swift-huggingface 提供了一个完整的客户端，用于与 Hugging Face Hub 和推理提供者进行交互：

  • Hub API：支持列出和管理模型、数据集、空间、集合和讨论。
  • 推理客户端：InferenceClient 允许应用通过 Hugging Face 推理提供者访问数百种模型，包括如 textToImage 等功能，用于从文本提示生成图像。

未来路线图和集成

通过拉取请求来替换现有的 HubApi 实现，swift-transformers 的集成目前正在进行中。此更新将把 swift-huggingface 的可靠性扩展到 mlx-swift-lm 和其他生态库的用户。此外，Hugging Face 正在开发对 Xet 存储后端 的支持，这将引入基于块的去重功能，以进一步加速大型模型的下载。

Sources