Hugging Face 于 2026-09-24 发布 huggingface_hub v2.0.0：底层 HTTP 依赖从 httpx/httpcore 切换为 httpx2/httpcore2，自定义 client factory 与异常捕获必须改用新类型；同步删除 upload_large_folder、huggingface-cli 等 1.x 废弃 API，并提供官方迁移指南。

核心要点速览 (Key Takeaways)

  • ✓破坏性变更：HTTP 客户端/传输异常来自 `httpx2` / `httpcore2`，不再兼容旧 `httpx` 类型（Release v2.0.0）
  • ✓双版本写法：自 v1.30.0 起可用 `from huggingface_hub.utils import get_session, httpx` 统一导入，兼容 1.x 与 2.x（迁移指南）
  • ✓证书与日志：`httpx2` 默认用操作系统信任库；日志应改盯 `httpx2`/`httpcore2`；`oauth` extra 需 `authlib>=1.8.0`
  • ✓API 清理：`upload_large_folder`→`upload_folder`，`duplicate_space`→`duplicate_repo`，CLI 入口 `huggingface-cli`→`hf`，`hf repo`→`hf repos` 等（详见迁移文档）
  • ✓安装：`pip install -U "huggingface_hub>=2.0.0"`；对照 issue #4802 迁移计划
🔗

相关资源与官方项目出处

免代理直达
💡 国内无需访问 Twitter，可直接访问上述项目官方资源与文档
🐙
GitHub Release v2.0.0
github.com/huggingface/huggingface_hub/releases/tag/v2.0.0
↗
📖
Migrating to huggingface_hub v2.0
huggingface.co/docs/huggingface_hub/main/en/concepts/migration_v2
↗
🐙
Transition plan issue #4802
github.com/huggingface/huggingface_hub/issues/4802
↗
📖
httpx2 documentation
httpx2.pydantic.dev/
↗
🌐
PyPI huggingface-hub
pypi.org/project/huggingface-hub/2.0.0/
↗
🌐
httpx→httpx2 upstream
httpx2.pydantic.dev/migration/
↗
🔬

深度技术解析与实战评估

核心背景与行业痛点

几乎所有 Hugging Face 生态的 Python 工具链（transformers、数据集、Spaces、Inference、Jobs）都经由 huggingface_hub 访问 Hub API。长期并存的旧 HTTP 依赖与一长串已弃用 API，让库作者在证书、异常类型与 CLI 入口上反复踩坑。v2.0.0 把「换 HTTP 栈」与「删废弃面」一次做完，换来更干净的默认行为，也要求下游同步改代码。

架构亮点与底层机制

按 官方 Release 与 Migration v2：底层改为 [httpx2](https://httpx2.pydantic.dev/) / httpcore2；set_client_factory / set_async_client_factory 与 except 传输错误必须使用新类型。为同时支持 1.x（≥1.30.0）与 2.x，应从 huggingface_hub.utils 导入 get_session 与兼容层 httpx。httpx2 默认使用操作系统证书信任库（SSL_CERT_FILE/SSL_CERT_DIR 仍可用）；日志目标改为 httpx2/httpcore2；oauth extra 要求 authlib>=1.8.0。

权威 Benchmark 与实测跑分对比

本版本是依赖与 API 面的破坏性升级，官方未发布独立吞吐/SWE 数字。可核对事实：GitHub Release 标注 published 2026-09-24T11:35:51Z，PyPI 最新版本为 2.0.0；迁移范围覆盖 HTTP 异常类型、体积上传 API 重命名、Inference/Spaces 参数与 CLI 入口统一到 hf。性能对比需以各下游库自行回归为准。

开发者实战落地与开箱指南

  • 升级：pip install -U "huggingface_hub>=2.0.0"，先读 迁移指南。

  • 搜索替换：upload_large_folder→upload_folder，duplicate_space→duplicate_repo，list_models(model_name=)→search=，CLI 一律改 hf。

  • 自定义 HTTP：工厂与 except httpx.HTTPError 改为 utils 兼容导入或原生 httpx2。

  • 背景：transition plan #4802、httpx→httpx2 upstream。