{
"canonical_name": "huggingface/huggingface_hub",
"compilation_id": "pack_c13cfe6a479b43c5ac1e9bbd7fe113ee",
"created_at": "2026-05-17T01:12:23.621255+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install huggingface_hub` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install huggingface_hub",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_fb3ae0309eda4738b4051dd47cd25cc1"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_f6edd893af6a8f46a2e3bf6e9645495b",
"canonical_name": "huggingface/huggingface_hub",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/huggingface/huggingface_hub",
"slug": "huggingface-hub",
"source_packet_id": "phit_79a1f8aacd7e47309932e6a4b65d1036",
"source_validation_id": "dval_b3b445b409d74eaab79686c890805f7c"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1023,
"github_stars": 3597,
"one_liner_en": "The official Python client for the Hugging Face Hub.",
"one_liner_zh": "The official Python client for the Hugging Face Hub.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "huggingface_hub",
"title_zh": "huggingface_hub 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"type": "selection_signal"
}
]
},
"packet_id": "phit_79a1f8aacd7e47309932e6a4b65d1036",
"page_model": {
"artifacts": {
"artifact_slug": "huggingface-hub",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install huggingface_hub",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/huggingface/huggingface_hub#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"结构化数据提取",
"断点恢复流程",
"开源工具"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The official Python client for the Hugging Face Hub."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to stop hf models ls from truncating the results in the table?",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_bb213b3feddd4ea09912922699b6b822 | https://github.com/huggingface/huggingface_hub/issues/4207 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：How to stop hf models ls from truncating the results in the table?",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.13.0] new CLI commands and formatting, and HF URI parsing",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8873fa5438804ce5af82d7acf73d7e90 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.13.0] new CLI commands and formatting, and HF URI parsing",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5d18ece8e9bf4111aa4a07b5d120f412 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.10.0] Instant file copy and new Kernel repo type",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ff686b653d2644649473ac1a7be8cb46 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.10.0] Instant file copy and new Kernel repo type",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.11.0] Semantic Spaces search, Space logs, and more",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_149c8633eb8447b080e00977ea43f541 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.11.0] Semantic Spaces search, Space logs, and more",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.12.0] Unified CLI output, bucket search, and more",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_66340c89abfe48459796695dee8aebb9 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.12.0] Unified CLI output, bucket search, and more",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7501a96be8144e2fbc85bfab477f54e1 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：How to stop hf models ls from truncating the results in the table?。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 325,
"forks": 1023,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3597
},
"source_url": "https://github.com/huggingface/huggingface_hub",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The official Python client for the Hugging Face Hub.",
"title": "huggingface_hub 能力包",
"trial_prompt": "# huggingface_hub - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for huggingface/huggingface_hub.\n\nProject:\n- Name: huggingface_hub\n- Repository: https://github.com/huggingface/huggingface_hub\n- Summary: The official Python client for the Hugging Face Hub.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: The official Python client for the Hugging Face Hub.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview and Architecture. Produce one small intermediate artifact and wait for confirmation.\n2. authentication: Authentication System. Produce one small intermediate artifact and wait for confirmation.\n3. file-download: File Download Operations. Produce one small intermediate artifact and wait for confirmation.\n4. file-upload: File Upload Operations. Produce one small intermediate artifact and wait for confirmation.\n5. repository-api: Repository Management API. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/huggingface/huggingface_hub\n- https://github.com/huggingface/huggingface_hub#readme\n- .opencode/skills/hf-release-notes/SKILL.md\n- src/huggingface_hub/__init__.py\n- src/huggingface_hub/hf_api.py\n- README.md\n- src/huggingface_hub/_login.py\n- src/huggingface_hub/_oauth.py\n- src/huggingface_hub/utils/_auth.py\n- src/huggingface_hub/utils/_git_credential.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: How to stop hf models ls from truncating the results in the table?（https://github.com/huggingface/huggingface_hub/issues/4207）；github/github_release: [v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI h（https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0）；github/github_release: [v1.14.0] Handle Spaces secrets & variables from CLI and other improveme（https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0）；github/github_release: [v1.13.0] new CLI commands and formatting, and HF URI parsing（https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0）；github/github_release: [v1.12.0] Unified CLI output, bucket search, and more（https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0）；github/github_release: [v1.11.0] Semantic Spaces search, Space logs, and more（https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0）；github/github_release: [v1.10.2] Fix reference cycle in hf_raise_for_status（https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.2）；github/github_release: [v1.10.1] Fix copy file to folder（https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.1）；github/github_release: [v1.10.0] Instant file copy and new Kernel repo type（https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0）；github/github_release: [v1.9.2] Fix set_space_volume / delete_space_volume return types（https://github.com/huggingface/huggingface_hub/releases/tag/v1.9.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "How to stop hf models ls from truncating the results in the table?",
"url": "https://github.com/huggingface/huggingface_hub/issues/4207"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI h",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.14.0] Handle Spaces secrets & variables from CLI and other improveme",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.13.0] new CLI commands and formatting, and HF URI parsing",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.12.0] Unified CLI output, bucket search, and more",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.11.0] Semantic Spaces search, Space logs, and more",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.10.2] Fix reference cycle in hf_raise_for_status",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.2"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.10.1] Fix copy file to folder",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.1"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.10.0] Instant file copy and new Kernel repo type",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0"
},
{
"kind": "github_release",
"source": "github",
"title": "[v1.9.2] Fix set_space_volume / delete_space_volume return types",
"url": "https://github.com/huggingface/huggingface_hub/releases/tag/v1.9.2"
}
],
"status": "已收录 10 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "The official Python client for the Hugging Face Hub.",
"effort": "安装已验证",
"forks": 1023,
"icon": "code",
"name": "huggingface_hub 能力包",
"risk": "可发布",
"slug": "huggingface-hub",
"stars": 3597,
"tags": [
"MCP 工具",
"知识库问答",
"结构化数据提取",
"断点恢复流程",
"开源工具"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/huggingface/huggingface_hub 项目说明书\n\n生成时间：2026-05-17 01:05:09 UTC\n\n## 目录\n\n- [Overview and Architecture](#overview)\n- [Installation and Setup](#installation)\n- [Authentication System](#authentication)\n- [File Download Operations](#file-download)\n- [File Upload Operations](#file-upload)\n- [Git LFS Large File Handling](#lfs-handling)\n- [Repository Management API](#repository-api)\n- [Cache Management System](#cache-management)\n- [Inference Client and Providers](#inference-client)\n- [HuggingFace File System (HfFileSystem)](#hf-file-system)\n\n\n\n## Overview and Architecture\n\n### 相关页面\n\n相关主题：[Installation and Setup](#installation), [File Download Operations](#file-download), [File Upload Operations](#file-upload)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/__init__.py)\n- [src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n- [README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n- [src/huggingface_hub/_snapshot_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n- [src/huggingface_hub/hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n- [src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n \n\n# Overview and Architecture\n\n## Introduction\n\nThe `huggingface_hub` is a Python client library developed by Hugging Face to interact with the Hugging Face Hub, enabling developers to download, upload, and manage machine learning models, datasets, and other repositories programmatically. The library provides a unified interface for interacting with Hugging Face's model hosting, version control, and collaboration infrastructure.\n\n**Primary Purpose:**\n- Download models, datasets, and Spaces from the Hub\n- Upload files and folders to the Hub\n- Manage repository metadata and model cards\n- Execute inference on deployed models\n- Handle authentication and access control\n\n**资料来源：**[README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n---\n\n## High-Level Architecture\n\nThe library follows a modular architecture with clear separation of concerns across multiple functional layers.\n\n```mermaid\ngraph TD\n A[Public API Layer] --> B[High-Level API]\n A --> C[File System Layer]\n A --> D[Inference Layer]\n B --> E[HfApi - Core Operations]\n B --> F[ModelHubMixin - ML Framework Integration]\n E --> G[HTTP Client / Requests]\n F --> G\n C --> H[HfFileSystem - fsspec]\n D --> I[Inference Client]\n G --> J[Hugging Face API]\n I --> J\n H --> J\n J --> K[Hub Backend]\n```\n\n### Module Organization\n\nThe source code is organized in `src/huggingface_hub/` with each module handling specific responsibilities:\n\n| Module | Purpose |\n|--------|---------|\n| `__init__.py` | Public API surface with auto-generated static imports |\n| `hf_api.py` | Main `HfApi` class with ~11k lines covering repo CRUD, uploads, downloads, discussions, PRs, collections |\n| `file_download.py` | `hf_hub_download` with caching logic, ETag resolution, xet download support |\n| `_snapshot_download.py` | `snapshot_download` for downloading entire repositories |\n| `_commit_api.py` | Low-level commit operations (`CommitOperationAdd`, `CommitOperationDelete`, `CommitOperationCopy`), LFS upload handling |\n| `hf_file_system.py` | `HfFileSystem` - fsspec-based POSIX-like filesystem for Hub repos |\n| `hub_mixin.py` | `ModelHubMixin` base class for ML framework integration |\n| `repocard.py` / `repocard_data.py` | `RepoCard`, `ModelCard`, `DatasetCard` and their metadata classes |\n| `community.py` | `Discussion`, `DiscussionComment` and event deserialization |\n| `lfs.py` | Git LFS batch upload utilities |\n| `_login.py` | `login()`, `logout()`, `notebook_login()`, token management |\n| `_inference_endpoints.py` | Inference endpoint CRUD and scaling |\n| `_jobs_api.py` | Training jobs API |\n| `_space_api.py` | Space runtime management |\n| `utils/_hf_uris.py` | URI parsing for `hf://` protocol support |\n\n**资料来源：**[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n---\n\n## Core Components\n\n### HfApi - Central API Class\n\nThe `HfApi` class serves as the primary interface for all Hub operations, implemented in `hf_api.py`. It provides methods for:\n\n- **Repository Management:** Create, list, delete, and update repositories\n- **File Operations:** Upload and download files\n- **Discussion & PRs:** Manage discussions and pull requests\n- **Collections:** Create and manage collections\n- **Metadata:** Update repository metadata and model cards\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n# List models\nmodels = api.list_models()\n# Upload a file\napi.upload_file(path_or_fileobj=\"model.bin\", path_in_repo=\"pytorch_model.bin\", repo_id=\"user/model\")\n```\n\n**资料来源：**[src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### HfFileSystem - Filesystem Interface\n\nThe `HfFileSystem` provides a POSIX-like filesystem interface using the fsspec specification, allowing standard file operations on Hub repositories:\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n# List files in a repository\nfiles = fs.ls(\"user/model\")\n# Read a file\nwith fs.open(\"user/model/config.json\", \"r\") as f:\n content = f.read()\n```\n\nThe filesystem is registered as an fsspec spec via the entry point `hf=huggingface_hub.HfFileSystem` defined in `setup.py`.\n\n**资料来源：**[setup.py:28](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L28), [src/huggingface_hub/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n\n### Repository Cards\n\nThe library provides structured classes for repository documentation:\n\n| Class | Purpose | File |\n|-------|---------|------|\n| `RepoCard` | Base class for all cards | `repocard.py` |\n| `ModelCard` | Model documentation with training metadata | `repocard.py` |\n| `DatasetCard` | Dataset documentation with annotations info | `repocard.py` |\n| `SpaceCard` | Space configuration and documentation | `repocard.py` |\n\nEach card contains:\n- **YAML Block:** Structured metadata via `CardData` classes\n- **Markdown Body:** Human-readable documentation\n\n**资料来源：**[src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py), [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n\n### ModelHubMixin - ML Framework Integration\n\nThe `ModelHubMixin` provides a base class for integrating Hub operations into ML frameworks. It enables:\n\n- Saving models directly to the Hub\n- Loading models from the Hub\n- Automatic model card generation\n\nThe mixin supports customizable parameters for model card generation including `library_name`, `license`, `pipeline_tag`, and `tags`.\n\n**资料来源：**[src/huggingface_hub/hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n\n---\n\n## Download Architecture\n\n### File Download Flow\n\n```mermaid\ngraph TD\n A[hf_hub_download / snapshot_download] --> B{Cache Check}\n B -->|Cached| C[Return Cached Path]\n B -->|Not Cached| D[Resolve ETag / Metadata]\n D --> E{Storage Backend}\n E -->|Standard| F[HTTP Download]\n E -->|Large File| G[LFS Download]\n E -->|Xet Support| H[Xet Download]\n F --> I[Store in Cache]\n G --> I\n H --> I\n I --> C\n```\n\n### Caching System\n\nThe library implements a sophisticated caching system that:\n\n1. Stores downloaded files in a local cache folder\n2. Uses ETag headers for efficient re-validation\n3. Supports conditional downloads to reduce bandwidth\n4. Handles large files through Git LFS\n\n**Key Components:**\n- `hf_hub_download()`: Downloads a single file\n- `snapshot_download()`: Downloads an entire repository\n\n**资料来源：**[src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py), [src/huggingface_hub/_snapshot_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py)\n\n---\n\n## Upload Architecture\n\n### Commit Operations\n\nThe library uses a commit-based model for uploads with three operation types:\n\n| Operation | Class | Purpose |\n|-----------|-------|---------|\n| Add | `CommitOperationAdd` | Upload a file |\n| Delete | `CommitOperationDelete` | Remove a file |\n| Copy | `CommitOperationCopy` | Duplicate a file |\n\n```python\nfrom huggingface_hub import CommitOperationAdd, HfApi\n\noperations = [\n CommitOperationAdd(path_or_fileobj=\"model.bin\", path_in_repo=\"pytorch_model.bin\"),\n CommitOperationAdd(path_or_fileobj=\"config.json\", path_in_repo=\"config.json\"),\n]\n\napi = HfApi()\napi.create_commit(repo_id=\"user/model\", operations=operations, commit_message=\"Add model files\")\n```\n\n### Large Folder Upload\n\nFor repositories with many files, `_upload_large_folder.py` provides chunked upload functionality to handle:\n- Large directory structures\n- Progress tracking\n- Error recovery\n\n**资料来源：**[src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py), [src/huggingface_hub/_upload_large_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_upload_large_folder.py)\n\n---\n\n## URI Parsing System\n\nThe library supports a custom `hf://` URI protocol for referencing Hub resources:\n\n```\nhf://[/][@][/]\n```\n\n**Type Prefixes:**\n| Type | Prefix | Example |\n|------|--------|---------|\n| Model | (default) | `hf://my-org/my-model` |\n| Dataset | `datasets/` | `hf://datasets/my-org/my-dataset` |\n| Space | `spaces/` | `hf://spaces/my-org/my-space` |\n| Bucket | `bucket/` | `hf://bucket/my-path` |\n\nThe `_hf_uris.py` module parses these URIs into structured `HfUri` objects, supporting special revision formats like `refs/pr/3` for pull requests.\n\n**资料来源：**[src/huggingface_hub/utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n\n---\n\n## Authentication System\n\nThe authentication flow uses token-based authentication:\n\n```mermaid\ngraph LR\n A[User] -->|hf login| B[CLI Login]\n B --> C[Token Storage]\n C --> D[~/.cache/huggingface/token]\n D --> E[API Requests]\n E --> F[Hub API]\n F -->|Valid Token| G[Authenticated Access]\n F -->|Invalid Token| H[Error Response]\n```\n\n**Available Methods:**\n- `login()`: Authenticate via command line\n- `logout()`: Remove stored credentials\n- `notebook_login()`: Interactive login for Jupyter notebooks\n\n**资料来源：**[src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n## Package Structure\n\n### Dependencies\n\nThe library has minimal core dependencies and optional extras:\n\n**Core Dependencies:**\n```python\nfilelock>=3.13.0\nfsspec>=2023.9.0\nhuggingface_hub>=0.24.0\npackaging>=20.9\npyyaml>=5.3\nrequests>=2.32.0\ntqdm>=4.64.0\ntyping-extensions>=3.7.4.1\n```\n\n**Optional Extras:**\n| Extra | Dependencies |\n|-------|-------------|\n| `inference` | Inference client for model deployment |\n| `testing` | pytest, pytest-cov, pytest-asyncio |\n| `quality` | black, ruff |\n| `typing` | mypy, libcst |\n| `dev` | All testing + quality + typing |\n\n**资料来源：**[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n---\n\n## Entry Points\n\nThe library registers several console entry points:\n\n| Command | Module | Purpose |\n|---------|--------|---------|\n| `hf` | `huggingface_hub.cli.hf` | Main CLI |\n| `huggingface-cli` | `huggingface_hub.cli.deprecated_cli` | Legacy CLI |\n| `tiny-agents` | `huggingface_hub.inference._mcp.cli` | Agent CLI |\n| `hf` (fsspec) | `huggingface_hub.HfFileSystem` | Filesystem spec |\n\n**资料来源：**[setup.py:25-31](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L25-L31)\n\n---\n\n## Design Patterns\n\n### Public API Surface\n\nThe public API in `__init__.py` is auto-generated by `utils/check_static_imports.py`. Developers should run `make style` to update static imports after making changes.\n\n### Async Support\n\nThe library provides both synchronous and asynchronous clients:\n- `InferenceClient` - Synchronous inference operations\n- `AsyncInferenceClient` - Asynchronous inference with async/await support\n\n### Type Safety\n\nThe library uses:\n- Python type hints throughout\n- Dataclasses for structured data\n- Frozen dataclasses for immutable objects (e.g., `HfUri`)\n\n---\n\n## Summary\n\nThe `huggingface_hub` library architecture is designed around:\n\n1. **Modularity:** Each functional area (download, upload, filesystem, inference) is isolated in its own module\n2. **Extensibility:** Entry points allow integration with external systems like fsspec\n3. **Performance:** Caching, ETag validation, and LFS support optimize network usage\n4. **Usability:** High-level APIs like `ModelHubMixin` simplify common workflows\n5. **Standards:** Following Python typing standards and fsspec specifications\n\nThis architecture enables the library to serve as the foundation for Hugging Face's ecosystem integration, supporting everything from simple file downloads to complex ML workflow automation.\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Overview and Architecture](#overview), [Authentication System](#authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/huggingface/huggingface_hub/blob/main/pyproject.toml)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [docs/source/en/installation.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/installation.md)\n \n\n# Installation and Setup\n\n## Overview\n\nThe `huggingface_hub` package is a Python client library that enables interaction with the Hugging Face Hub, providing functionality to download and publish models, datasets, and other repositories. This page covers all aspects of installing and setting up the library across different environments and use cases.\n\n## System Requirements\n\n### Python Version\n\n| Requirement | Version |\n|-------------|---------|\n| Minimum Python | 3.10.0 |\n| Package Manager | pip, conda |\n\n资料来源：[setup.py:52](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n### Supported Platforms\n\nThe library supports installation on all major operating systems including Linux, macOS, and Windows.\n\n## Installation Methods\n\n### Standard Installation (pip)\n\nThe primary installation method uses pip:\n\n```bash\npip install huggingface_hub\n```\n\n资料来源：[README.md:30](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Installation with Optional Dependencies\n\nThe library provides extras that install optional dependencies for specific use cases:\n\n| Extra | Description | Command |\n|-------|-------------|---------|\n| `inference` | Inference-related functionality | `pip install huggingface_hub[inference]` |\n| `mcp` | MCP (Model Context Protocol) module | `pip install huggingface_hub[mcp]` |\n\n资料来源：[README.md:36-42](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Development Installation\n\nFor contributing to the project or testing the latest features:\n\n```bash\npip install -e \".[dev]\"\n```\n\nThis installs the package in editable mode with all development dependencies.\n\n资料来源：[CONTRIBUTING.md:24-26](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)\n\n### Conda Installation\n\nFor conda environments:\n\n```bash\nconda install -c conda-forge huggingface_hub\n```\n\n资料来源：[README.md:22-24](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## Dependency Architecture\n\n```mermaid\ngraph TD\n A[huggingface_hub] --> B[Core Dependencies]\n A --> C[Optional: inference]\n A --> D[Optional: mcp]\n A --> E[Dev Dependencies]\n \n B --> B1[requests]\n B --> B2[fsspec]\n B --> B3[httpx]\n B --> B4[tqdm]\n B --> B5[packaging]\n B --> B6[filelock]\n B --> B7[pyyaml]\n \n C --> C1[inference-client]\n C --> C2[pillow]\n \n D --> D1[mcp]\n \n E --> E1[pytest]\n E --> E2[pytest-asyncio]\n E --> E3[pytest-cov]\n E --> E4[ruff]\n E --> E5[mypy]\n E --> E6[ty]\n```\n\n## Core Dependencies\n\nThe following table lists the required dependencies installed by default:\n\n| Package | Purpose |\n|---------|---------|\n| `requests` | HTTP client for API calls |\n| `fsspec` | Filesystem specification |\n| `httpx` | Async HTTP client |\n| `tqdm` | Progress bars |\n| `packaging` | Package version handling |\n| `filelock` | File locking mechanism |\n| `pyyaml` | YAML parsing |\n| `typing-extensions` | Type hint support |\n\n资料来源：[setup.py:1-16](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Optional Dependency Groups\n\n### Testing Dependencies\n\n```python\nextras[\"testing\"] = [\n \"pytest\",\n \"pytest-asyncio\",\n \"pytest-cov\",\n \"pytest-xdist\",\n \"DianaEye\",\n \"aiohttp\",\n \"asynctest\",\n \"Paramiko\",\n]\n```\n\n### Quality Assurance Dependencies\n\n```python\nextras[\"quality\"] = [\n \"ruff\",\n \"踩\",\n]\n```\n\n### Type Checking Dependencies\n\n```python\nextras[\"typing\"] = [\n \"mypy==1.15.0\",\n \"libcst>=1.4.0\",\n \"ty\",\n]\n```\n\n### All-Inclusive Meta-Group\n\n```python\nextras[\"all\"] = extras[\"testing\"] + extras[\"quality\"] + extras[\"typing\"]\nextras[\"dev\"] = extras[\"all\"]\n```\n\n资料来源：[setup.py:36-51](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[Start Installation] --> B{Installation Method}\n \n B -->|pip| C[Basic Install]\n B -->|conda| D[Conda Forge Install]\n B -->|editable| E[Development Install]\n \n C --> F{Use Case}\n F -->|Minimal| G[Core Only]\n F -->|Inference| H[Add inference extra]\n F -->|MCP| I[Add mcp extra]\n \n G --> J[Installation Complete]\n H --> J\n I --> J\n \n D --> J\n E --> J\n \n J --> K[Verify Installation]\n K --> L[Import huggingface_hub]\n```\n\n## Verification\n\nAfter installation, verify the package is correctly installed:\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# Test basic functionality\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n```\n\n资料来源：[README.md:48-52](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## Post-Installation Configuration\n\n### Authentication Setup\n\nTo authenticate with the Hugging Face Hub:\n\n```bash\n# Interactive login\nhf auth login\n\n# Non-interactive with token\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n资料来源：[README.md:61-65](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Cache Configuration\n\nFiles are downloaded to a local cache folder. See the [cache management guide](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache) for configuration options.\n\n## Entry Points\n\nThe installation registers the following console scripts:\n\n| Command | Module | Purpose |\n|---------|--------|---------|\n| `hf` | `huggingface_hub.cli.hf` | Main CLI interface |\n| `huggingface-cli` | `huggingface_hub.cli.deprecated_cli` | Legacy CLI (deprecated) |\n| `tiny-agents` | `huggingface_hub.inference._mcp.cli` | MCP CLI application |\n| `hf` (fsspec) | `huggingface_hub.HfFileSystem` | Filesystem specification |\n\n资料来源：[setup.py:53-60](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| ImportError | Ensure Python >= 3.10 |\n| Authentication failed | Run `hf auth login` |\n| Download timeout | Check network connection |\n| Permission denied | Use virtual environment |\n\n### Development Setup Issues\n\nIf installing in development mode:\n\n```bash\npip uninstall huggingface_hub\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md:24](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Name | `huggingface_hub` |\n| License | Apache-2.0 |\n| Author | Hugging Face, Inc. |\n| Author Email | julien@huggingface.co |\n| URL | https://github.com/huggingface/huggingface_hub |\n\n资料来源：[setup.py:18-22](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[Installation and Setup](#installation), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n- [src/huggingface_hub/_oauth.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py)\n- [src/huggingface_hub/utils/_auth.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_auth.py)\n- [src/huggingface_hub/utils/_git_credential.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_git_credential.py)\n \n\n# Authentication System\n\n## Overview\n\nThe `huggingface_hub` library provides a comprehensive authentication system that enables secure access to Hugging Face Hub resources including models, datasets, and Spaces. The authentication system supports multiple authentication methods including token-based authentication and OAuth 2.0, with seamless integration into both CLI environments and Jupyter notebooks.\n\nThe authentication infrastructure consists of four primary modules that handle different aspects of the authentication lifecycle:\n\n| Module | Purpose |\n|--------|---------|\n| `_login.py` | User login operations and token management |\n| `_oauth.py` | OAuth 2.0 authentication flow |\n| `_auth.py` | Core authentication utilities and token refresh |\n| `_git_credential.py` | Git credential handling for repository operations |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User] --> B[Login Methods]\n B --> C[Token-based Auth]\n B --> D[OAuth 2.0 Auth]\n C --> E[hf_hub_download]\n C --> F[upload_file]\n D --> E\n D --> F\n E --> G[Token Cache]\n F --> G\n G --> H[Hugging Face Hub API]\n H --> I[Model/Dataset/Space]\n \n C --> J[CLI: hf auth login]\n C --> K[Python: login function]\n C --> L[Notebook: notebook_login]\n```\n\n## Token-Based Authentication\n\n### Login Functionality\n\nThe library provides three primary interfaces for user authentication:\n\n#### CLI Login\n\nUsers can authenticate via the command-line interface using the `hf` command:\n\n```bash\nhf auth login\n# or with environment variable\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n#### Python API Login\n\nThe `login()` function provides programmatic authentication within Python scripts:\n\n```python\nfrom huggingface_hub import login\n\n# Direct token login\nlogin(token=\"hf_xxxxx\")\n\n# Using environment variable\nlogin()\n```\n\n#### Notebook Login Widget\n\nFor Jupyter notebook environments, `notebook_login()` displays an interactive widget for token entry:\n\n```python\nfrom huggingface_hub import notebook_login\n\nnotebook_login()\n```\n\nThe notebook login function accepts the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `skip_if_logged_in` | `bool` | `True` | Skip prompt if user already logged in |\n\n```python\n# Force re-login even if already authenticated\nnotebook_login(skip_if_logged_in=False)\n```\n\n### Token Storage and Management\n\nTokens are securely stored in the local configuration directory. The system automatically retrieves stored tokens when making API requests, eliminating the need for repeated authentication. Token validation occurs automatically before any authenticated operation, ensuring expired or invalid tokens are detected early.\n\n## OAuth 2.0 Authentication\n\nThe OAuth 2.0 authentication flow provides an alternative to token-based authentication, enabling more sophisticated authorization scenarios. This is particularly useful for applications that need to access resources on behalf of users with specific permission scopes.\n\nOAuth tokens are automatically refreshed when they expire, maintaining continuous access without requiring user intervention. The system handles token revocation and supports scopes that limit access to specific resources or operations.\n\n## Git Credential Integration\n\nThe authentication system integrates with Git's credential infrastructure to provide seamless authentication for Git operations such as cloning and pushing to repositories. This integration ensures that Git operations respect the same authentication state as the Python API.\n\n```mermaid\ngraph LR\n A[Git Operation] --> B[Git Credential Helper]\n B --> C{huggingface_hub _git_credential}\n C --> D{Cached Token?}\n D -->|Yes| E[Use Cached Token]\n D -->|No| F[Prompt for Token]\n E --> G[Execute Git Operation]\n F --> G\n```\n\nThe Git credential helper manages:\n- Secure storage of credentials\n- Credential retrieval for specific hosts\n- Credential cleanup after operations\n\n## Authentication Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Application\n participant AuthSystem\n participant HubAPI\n participant TokenStore\n\n User->>Application: Initiate request\n Application->>AuthSystem: Authenticate\n AuthSystem->>TokenStore: Check stored token\n TokenStore-->>AuthSystem: Token found\n AuthSystem->>HubAPI: Authenticated request\n HubAPI-->>Application: Response\n Note over AuthSystem,TokenStore: Token expired or invalid\n AuthSystem->>AuthSystem: Refresh token\n AuthSystem->>TokenStore: Update token\n AuthSystem->>HubAPI: Retry with new token\n```\n\n## Configuration\n\nAuthentication behavior can be configured through environment variables and configuration files:\n\n| Variable | Description |\n|----------|-------------|\n| `HUGGINGFACE_TOKEN` | Default authentication token |\n| `HF_HOME` | Configuration directory location |\n| `HF_TOKEN` | Alternative token environment variable |\n\n## Security Considerations\n\nThe authentication system implements several security best practices:\n\n1. **Secure Token Storage**: Tokens are stored with appropriate file permissions to prevent unauthorized access\n2. **Token Validation**: All tokens are validated before use in API requests\n3. **Automatic Refresh**: OAuth tokens are automatically refreshed to maintain session continuity\n4. **Notebook Security Warning**: The `notebook_login` widget displays a warning about token exposure in notebook files\n\n## Related Components\n\nThe authentication system interacts with several other library components:\n\n| Component | Interaction |\n|-----------|-------------|\n| `InferenceClient` | Uses authentication for inference API calls |\n| `HfFileSystem` | Uses authentication for file system operations |\n| `snapshot_download` | Uses authentication for repository downloads |\n| `upload_file` | Uses authentication for repository uploads |\n\n## Quick Reference\n\n```python\n# CLI\nhf auth login --token hf_xxxxx\n\n# Python script\nfrom huggingface_hub import login\nlogin(token=\"hf_xxxxx\")\n\n# Jupyter notebook\nfrom huggingface_hub import notebook_login\nnotebook_login()\n\n# Check if logged in\nfrom huggingface_hub import whoami\nuser = whoami()\n\n---\n\n\n\n## File Download Operations\n\n### 相关页面\n\n相关主题：[Cache Management System](#cache-management), [Git LFS Large File Handling](#lfs-handling), [Overview and Architecture](#overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n- [src/huggingface_hub/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n- [src/huggingface_hub/_snapshot_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py)\n- [src/huggingface_hub/cli/download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/download.py)\n- [src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n- [src/huggingface_hub/errors.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py)\n \n\n# File Download Operations\n\nThe `huggingface_hub` library provides a comprehensive file download system that enables clients to fetch models, datasets, and other artifacts from the Hugging Face Hub. This document covers the architecture, API, caching mechanisms, and usage patterns for download operations.\n\n## Overview\n\nFile download operations in `huggingface_hub` handle the retrieval of individual files or entire repository snapshots from Hugging Face's infrastructure. The system implements intelligent caching, supports offline mode, provides progress tracking, and handles authentication seamlessly.\n\n**Key responsibilities:**\n\n- Download files with proper caching and deduplication\n- Support partial content retrieval for LFS (Large File Storage) files\n- Manage metadata for cache validation and freshness checks\n- Handle authentication tokens transparently\n- Support offline scenarios with local-only file access\n- Provide dry-run capabilities for previewing downloads\n\n资料来源：[src/huggingface_hub/file_download.py:1-100]()\n\n## Architecture\n\n### Component Overview\n\n```mermaid\ngraph TD\n A[Public API: hf_hub_download] --> B[Route Decision]\n B --> C{single file?}\n C -->|Yes| D[_hf_hub_download_to_cache_dir]\n C -->|No| E[snapshot_download]\n \n D --> F[Get Metadata / ETag]\n F --> G{Cached?}\n G -->|Yes, valid| H[Return cached path]\n G -->|No| I[Download from remote]\n I --> J[Write metadata]\n J --> H\n \n E --> K[Iterate files]\n K --> L[Download each file]\n L --> F\n \n H --> M[Local file path]\n I --> M\n```\n\n### Module Structure\n\n| Module | Purpose |\n|--------|---------|\n| `file_download.py` | Core download functions (`hf_hub_download`, `_hf_hub_download_to_cache_dir`) |\n| `_local_folder.py` | Local cache and metadata management |\n| `_snapshot_download.py` | Full repository snapshot downloads |\n| `cli/download.py` | Command-line interface for downloads |\n| `errors.py` | Exception hierarchy for download failures |\n\n资料来源：[src/huggingface_hub/file_download.py:1-50]()\n\n## Core API Functions\n\n### hf_hub_download\n\nThe primary function for downloading a single file from the Hub.\n\n```python\nfrom huggingface_hub import hf_hub_download\n\npath = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n repo_type=\"model\",\n revision=\"main\",\n cache_dir=\"./hf_cache\",\n token=True,\n)\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | `str` | Required | Repository identifier (e.g., \"bert-base-cased\") |\n| `filename` | `str` | Required | Path to the file within the repository |\n| `repo_type` | `str` | `\"model\"` | Type of repository: \"model\", \"dataset\", or \"space\" |\n| `revision` | `str` | `\"main\"` | Git revision (branch, tag, or commit hash) |\n| `cache_dir` | `str \\| Path` | `None` | Custom cache directory location |\n| `local_dir` | `str \\| Path` | `None` | Directory to place the file without caching structure |\n| `force_download` | `bool` | `False` | Force re-download even if cached |\n| `local_files_only` | `bool` | `False` | Only return local files, fail if not cached |\n| `token` | `str \\| bool` | `None` | Authentication token (`True` reads from config) |\n| `etag_timeout` | `float` | `10` | Timeout in seconds for ETag fetch |\n| `tqdm_class` | `type` | `None` | Custom tqdm class for progress bars |\n\n资料来源：[src/huggingface_hub/file_download.py:100-200]()\n\n### snapshot_download\n\nDownloads an entire repository to a local cache.\n\n```python\nfrom huggingface_hub import snapshot_download\n\nlocal_path = snapshot_download(\n repo_id=\"stabilityai/stable-diffusion-2-1\",\n repo_type=\"model\",\n cache_dir=\"./models\",\n ignore_patterns=[\"*.md\", \".gitattributes\"],\n)\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | `str` | Required | Repository identifier |\n| `repo_type` | `str` | `\"model\"` | Type of repository |\n| `revision` | `str` | `None` | Git revision to download |\n| `cache_dir` | `str \\| Path` | `None` | Cache directory location |\n| `local_dir` | `str \\| Path` | `None` | Mirror directory without cache structure |\n| `allow_patterns` | `list[str]` | `None` | Glob patterns to include |\n| `ignore_patterns` | `list[str]` | `None` | Glob patterns to exclude |\n| `force_download` | `bool` | `False` | Force re-download of all files |\n| `local_files_only` | `bool` | `False` | Only use local cache |\n| `token` | `str \\| bool` | `None` | Authentication token |\n\n资料来源：[src/huggingface_hub/_snapshot_download.py:1-150]()\n\n## Caching Mechanism\n\n### Cache Directory Structure\n\n```\ncache_dir/\n├── .locks/ # Lock files for concurrent access\n│ └── {repo_id}/\n│ └── {filename}.lock\n└── {repo_type}s/\n └── {namespace}/\n └── {repo_name}/\n ├── .cache/ # Metadata\n │ └── huggingface/\n │ └── info/\n │ └── files/ # Download metadata\n ├── {revision}/\n │ └── {filename} # Actual downloaded files\n └── refs/\n └── {branch} # Git references\n```\n\n### Download Metadata\n\nMetadata is stored alongside cached files to track freshness:\n\n```python\n# Stored in: {cache_dir}/.cache/huggingface/info/files/{filename}\n{commit_hash}\n{etag}\n{timestamp}\n```\n\nThe system validates cached files by:\n\n1. Comparing local ETag with remote ETag\n2. Checking commit hash consistency\n3. Verifying file modification timestamps\n\n资料来源：[src/huggingface_hub/_local_folder.py:50-120]()\n\n### Lock File Management\n\nThe library uses `WeakFileLock` to handle concurrent downloads safely:\n\n```python\nlocks_dir = os.path.join(cache_dir, \".locks\")\nstorage_folder = os.path.join(cache_dir, repo_folder_name(...))\npaths = RepoFileDownloadPaths(...)\n# Lock acquired before writing to cache\nwith WeakFileLock(paths.lock_path):\n # Critical section: write file or metadata\n```\n\n资料来源：[src/huggingface_hub/file_download.py:300-350]()\n\n## Download Workflow\n\n### Sequence Diagram\n\n```mermaid\nsequenceDiagram\n participant Client\n participant hf_hub_download\n participant Cache\n participant Server\n participant Metadata\n\n Client->>hf_hub_download: Call with repo_id, filename\n hf_hub_download->>Cache: Check cached file + metadata\n Cache-->>hf_hub_download: metadata (if exists)\n \n alt Cached file exists\n hf_hub_download->>Metadata: Validate ETag\n Metadata-->>hf_hub_download: is_valid\n alt Valid ETag\n hf_hub_download-->>Client: Return cached path\n else Invalid ETag\n hf_hub_download->>Server: HEAD request for ETag\n end\n else No cache\n hf_hub_download->>Server: HEAD request for ETag\n end\n \n Server-->>hf_hub_download: ETag, commit_hash, size\n hf_hub_download->>Cache: Check if file exists\n \n alt File not in cache\n hf_hub_download->>Server: GET request\n Server-->>hf_hub_download: File content\n hf_hub_download->>Cache: Write file + metadata\n end\n \n hf_hub_download-->>Client: Return file path\n```\n\n### ETag Validation Process\n\nThe download system implements a three-tier validation strategy:\n\n1. **ETag Match**: Compare server ETag with local metadata\n2. **SHA256 Hash**: For LFS files, compute and compare SHA256\n3. **Timestamp Check**: Verify file hasn't been modified since metadata save\n\n```python\n# ETag-based validation\nif local_metadata is not None and local_metadata.etag == etag:\n write_download_metadata(...)\n return str(paths.file_path)\n\n# SHA256-based validation (for LFS files)\nif local_metadata is None and REGEX_SHA256.match(etag) is not None:\n with open(paths.file_path, \"rb\") as f:\n file_hash = sha_fileobj(f).hex()\n if file_hash == etag:\n write_download_metadata(...)\n return str(paths.file_path)\n```\n\n资料来源：[src/huggingface_hub/file_download.py:400-480]()\n\n## Error Handling\n\n### Exception Hierarchy\n\n```mermaid\ngraph TD\n A[Exception]\n A --> B[HfHubHTTPError]\n B --> C[RevisionNotFoundError]\n B --> D[EntryNotFoundError]\n B --> E[LocalEntryNotFoundError]\n D --> F[RemoteEntryNotFoundError]\n \n A --> G[EntryNotFoundError]\n G --> H[LocalEntryNotFoundError]\n```\n\n### Common Errors\n\n| Exception | Trigger Condition |\n|-----------|-------------------|\n| `RevisionNotFoundError` | Invalid Git revision (branch, tag, commit) |\n| `RemoteEntryNotFoundError` | File not found on remote server |\n| `LocalEntryNotFoundError` | File not in cache with `local_files_only=True` |\n| `HfHubHTTPError` | Generic HTTP errors (401, 403, 404, 500, etc.) |\n\n```python\n# Example: Handling download errors\ntry:\n path = hf_hub_download('bert-base-cased', 'config.json')\nexcept RevisionNotFoundError as e:\n print(f\"Revision not found: {e}\")\nexcept RemoteEntryNotFoundError as e:\n print(f\"File not on server: {e}\")\nexcept LocalEntryNotFoundError as e:\n print(\"File not in cache. Set local_files_only=True and cache it first.\")\n```\n\n资料来源：[src/huggingface_hub/errors.py:100-180]()\n\n## Command-Line Interface\n\n### CLI Download Command\n\nThe `huggingface-cli` tool provides download functionality:\n\n```bash\n# Download single file\nhuggingface-cli download bert-base-cased config.json\n\n# Download entire repo\nhuggingface-cli download stabilityai/stable-diffusion-2-1\n\n# With patterns\nhuggingface-cli download meta-llama/Llama-2-7b --include \"*.safetensors\"\n\n# Dry run\nhuggingface-cli download bigscience/bloom-7b1 --dry-run\n```\n\n### CLI Implementation\n\nThe CLI wraps the core download functions and adds:\n\n- Pretty-printed output formatting\n- Dry-run mode for previewing downloads\n- Pattern-based file selection\n- Progress indication\n\n```python\n# From cli/download.py\ndef run(self):\n if len(regular_filenames) == 1:\n # Single file: use hf_hub_download\n return hf_hub_download(\n repo_id=repo_id,\n filename=regular_filenames[0],\n ...\n )\n else:\n # Multiple files or patterns: use snapshot_download\n return snapshot_download(\n repo_id=repo_id,\n allow_patterns=allow_patterns,\n ...\n )\n```\n\n资料来源：[src/huggingface_hub/cli/download.py:50-120]()\n\n## Advanced Usage\n\n### Dry Run Mode\n\nPreview what would be downloaded without actually downloading:\n\n```python\nfrom huggingface_hub import hf_hub_download, DryRunFileInfo\n\nresult = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n dry_run=True,\n)\n\nif isinstance(result, DryRunFileInfo):\n print(f\"Will download: {result.filename}\")\n print(f\"Size: {result.file_size} bytes\")\n print(f\"Cached: {result.is_cached}\")\n print(f\"Commit: {result.commit_hash}\")\n```\n\n### Progress Tracking\n\nCustomize progress bar behavior:\n\n```python\nfrom tqdm import tqdm\nfrom huggingface_hub import hf_hub_download\n\nclass CustomProgress(tqdm):\n def set_postfix(self, **kwargs):\n self.set_postfix_str(f\"ETA: {kwargs.get('eta', 'N/A')}\")\n\nhf_hub_download(\n repo_id=\"bigscience/bloom-7b1\",\n filename=\"pytorch_model.bin\",\n tqdm_class=CustomProgress,\n)\n```\n\n### Offline Mode\n\nWork exclusively with cached files:\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# Will fail if file not cached\npath = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n local_files_only=True,\n)\n```\n\n资料来源：[src/huggingface_hub/file_download.py:450-500]()\n\n## Repository Types\n\nThe download system supports multiple repository types:\n\n| Repo Type | Description | Typical Contents |\n|-----------|-------------|------------------|\n| `model` | Model repositories | PyTorch/TensorFlow models, configs, tokenizer files |\n| `dataset` | Dataset repositories | Data files, dataset card, scripts |\n| `space` | Gradio Spaces | Application code, models, requirements |\n\nRepository types affect URL construction:\n\n```python\n# URL prefixes from constants\nREPO_TYPES_URL_PREFIXES = {\n \"model\": \"\",\n \"dataset\": \"datasets/\",\n \"space\": \"spaces/\",\n}\n```\n\n资料来源：[src/huggingface_hub/lfs.py:30-60]()\n\n## Best Practices\n\n1. **Use caching**: Files are cached automatically; reuse cached files for subsequent runs\n2. **Specify revisions**: Pin specific commits for reproducible downloads\n3. **Handle authentication**: Use `token=True` to auto-read from config, or pass explicit tokens\n4. **Prefer single file downloads**: Use `hf_hub_download` for specific files instead of full snapshots\n5. **Use patterns wisely**: Combine `allow_patterns` and `ignore_patterns` for selective downloads\n\n## Summary\n\nThe file download system in `huggingface_hub` provides a robust, cached, and authenticated mechanism for retrieving files from the Hugging Face Hub. Key functions include:\n\n- `hf_hub_download`: Single file downloads with full validation\n- `snapshot_download`: Complete repository downloads with pattern filtering\n- CLI integration via `huggingface-cli download`\n\nThe system handles caching, metadata validation, concurrent access, and error recovery transparently, making it suitable for production workloads requiring reliable artifact retrieval.\n\n---\n\n\n\n## File Upload Operations\n\n### 相关页面\n\n相关主题：[Git LFS Large File Handling](#lfs-handling), [File Download Operations](#file-download), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/lfs.py)\n- [src/huggingface_hub/_upload_large_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_upload_large_folder.py)\n- [src/huggingface_hub/_local_folder.py](https://github.com/huggingface/hub-mixin/blob/main/src/huggingface_hub/_local_folder.py)\n- [docs/source/en/guides/upload.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/upload.md)\n \n\n# File Upload Operations\n\n## Overview\n\nFile upload operations in `huggingface_hub` enable developers to publish and manage files on the Hugging Face Hub. The library provides a comprehensive set of tools for uploading individual files, entire folders, and handling large files through Git Large File Storage (LFS) integration.\n\nThe upload system is built on top of the Hub's git-based infrastructure, ensuring file versioning and integrity for all uploaded content. This architecture supports repositories of type `model`, `dataset`, and `space`. 资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User Code] --> B[upload_file / upload_folder]\n B --> C[CommitOperation Classes]\n C --> D{Hub API}\n D --> E[Regular Files
Direct Upload]\n D --> F[Large Files
LFS Required]\n F --> G[lfs.py
Batch Operations]\n G --> H[LFS Server]\n E --> I[Regular Git Server]\n H --> I\n```\n\n## Core Components\n\n### CommitOperation Classes\n\nThe foundation of all upload operations is built on three operation classes defined in `_commit_api.py`:\n\n| Class | Purpose | Key Attributes |\n|-------|--------|----------------|\n| `CommitOperationAdd` | Add a file to a commit | `path_or_fileobj`, `path_in_repo`, `rethrow` |\n| `CommitOperationDelete` | Delete a file from a repository | `path_in_repo` |\n| `CommitOperationCopy` | Copy a file within a repository | `src_path_in_repo`, `path_in_repo` |\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n### CommitOperationAdd Details\n\n```python\nclass CommitOperationAdd:\n def __init__(\n self,\n path_or_fileobj: Union[str, Path, bytes, BinaryIO],\n path_in_repo: str,\n *,\n rfilename: Optional[str] = None,\n rethrow: bool = True,\n upload_info: Optional[\"CommitOperationAdd.UploadInfo\"] = None,\n ):\n```\n\nThe `CommitOperationAdd` class supports multiple input types:\n\n| Input Type | Behavior |\n|------------|----------|\n| `str` / `Path` | File path - reads file content for upload |\n| `bytes` | Raw byte content |\n| `BinaryIO` | File-like object with `read()` method |\n\nThe class provides an `as_file()` method for iterating over file content with optional progress bar support:\n\n```python\ndef as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]:\n if isinstance(self.path_or_fileobj, str) or isinstance(self.path_or_fileobj, Path):\n if with_tqdm:\n with tqdm_stream_file(self.path_or_fileobj) as file:\n yield file\n else:\n with open(self.path_or_fileobj, \"rb\") as file:\n yield file\n elif isinstance(self.path_or_fileobj, bytes):\n yield io.BytesIO(self.path_or_fileobj)\n elif isinstance(self.path_or_fileobj, io.BufferedIOBase):\n prev_pos = self.path_or_fileobj.tell()\n yield self.path_or_fileobj\n self.path_or_fileobj.seek(prev_pos, io.SEEK_SET)\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py:200-280]()\n\n## Upload Functions\n\n### upload_file\n\nUploads a single file to a repository on the Hub.\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/home/lysandre/dummy-test/README.md\",\n path_in_repo=\"README.md\",\n repo_id=\"lysandre/test-model\",\n)\n```\n\n资料来源：[README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### upload_folder\n\nUploads an entire folder to a repository. Handles nested directory structures and file filtering.\n\n```python\nfrom huggingface_hub import upload_folder\n\nupload_folder(\n folder_path=\"/path/to/local/space\",\n repo_id=\"username/my-cool-space\",\n repo_type=\"space\",\n)\n```\n\n资料来源：[README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## LFS Integration\n\n### Git LFS Overview\n\nLarge files (typically files larger than 10MB) are handled through Git LFS. The library provides batch upload utilities in `lfs.py` for efficient LFS operations.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Hub API\n participant LFS Server\n \n Client->>Hub API: POST /lfs/objects/batch\n Note over Hub API: Check file sizes\n Hub API->>Client: Upload instructions\n alt Large Files\n Client->>LFS Server: Upload LFS objects\n LFS Server-->>Client: Success\n end\n Client->>Hub API: Complete commit\n Hub API-->>Client: Commit SHA\n```\n\n### LFS Batch Upload Process\n\nThe `lfs.py` module provides `upload_files_lfs_instances()` which handles the LFS batch protocol:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `commit_operations` | List[CommitOperationAdd] | Files to upload |\n| `repo_type` | str | Repository type: \"model\", \"dataset\", \"space\" |\n| `repo_id` | str | Repository identifier |\n| `revision` | str | Git revision (default: \"main\") |\n| `endpoint` | str | API endpoint URL |\n| `transfer_adapters` | List[str] | Transfer methods: \"basic\", \"multipart\", \"xet\" |\n\n资料来源：[src/huggingface_hub/lfs.py:50-150]()\n\n### LFS Batch Info Response\n\nThe `LfsBatchInfo` dataclass contains three elements:\n\n```python\n@dataclass\nclass LfsBatchInfo:\n instructions: List[\"LfsUploadInfo\"]\n errors: List[\"LfsError\"]\n transfer_mode: \"TransferMethod\"\n```\n\nThe upload process automatically determines which files require LFS handling based on file size thresholds configured by the Hub.\n\n## Large Folder Upload\n\nFor repositories with many files or very large folder structures, `_upload_large_folder.py` provides chunked upload capabilities:\n\n```python\n# Internal chunked upload for large repositories\nupload_folder(\n folder_path=\"/path/to/large/repo\",\n repo_id=\"user/large-model\",\n allow_patterns=[\"*.bin\", \"*.safetensors\", \"config.json\"],\n ignore_patterns=[\"*.git*\", \"__pycache__/*\"],\n)\n```\n\n资料来源：[src/huggingface_hub/_upload_large_folder.py]()\n\n## Upload Workflow\n\n```mermaid\ngraph TD\n A[Start Upload] --> B{File Size Check}\n B -->|Small File| C[Direct Git Upload]\n B -->|Large File| D[LFS Upload Required]\n C --> E[Create Commit]\n D --> F[Batch Request to LFS]\n F --> G[Get Upload Instructions]\n G --> H[Upload to LFS Server]\n H --> E\n E --> I[Commit to Hub]\n I --> J[Return Commit SHA]\n```\n\n## Configuration Options\n\n### Repository Types\n\n| Type | Description | Typical Use |\n|------|-------------|-------------|\n| `model` | Model repositories | Trained weights, configs |\n| `dataset` | Dataset repositories | Data files, metadata |\n| `space` | Space repositories | Demo applications |\n\n### Common Parameters\n\n| Parameter | Required | Default | Description |\n|-----------|----------|---------|-------------|\n| `repo_id` | Yes | - | Namespace/repo name |\n| `repo_type` | No | \"model\" | Type of repository |\n| `revision` | No | \"main\" | Git branch/tag |\n| `token` | No | None | HF token for auth |\n| `create_pr` | No | False | Create PR instead of commit |\n\n## Error Handling\n\n### CommitOperationAdd Error Handling\n\nThe `rethrow` parameter controls error behavior:\n\n```python\n# Default: raises exception on failure\noperation = CommitOperationAdd(path_or_fileobj=\"file.bin\", path_in_repo=\"model.bin\")\n\n# With error suppression\noperation = CommitOperationAdd(path_or_fileobj=\"file.bin\", path_in_repo=\"model.bin\", rethrow=False)\n```\n\n### Upload Errors\n\n| Error Type | Cause | Resolution |\n|------------|-------|------------|\n| `HfHubHTTPError` | Server rejection | Check token permissions |\n| `ValueError` | Invalid parameters | Validate repo_id, path_in_repo |\n| `LocalUploadNotImplementedError` | Unsupported local upload | Use file path instead |\n\n## Best Practices\n\n1. **Use `upload_folder`** for multiple files to ensure atomic commits\n2. **Token Authentication**: Always authenticate before uploading private repositories\n3. **File Filtering**: Use `allow_patterns` and `ignore_patterns` for large repos\n4. **Progress Tracking**: Enable tqdm for long uploads\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\napi.upload_folder(\n folder_path=\"./model\",\n repo_id=\"username/my-model\",\n repo_type=\"model\",\n token=True, # Prompt for token if needed\n)\n```\n\n## Related Documentation\n\n- [Upload Guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload) - Detailed upload instructions\n- [Repository Management](https://huggingface.co/docs/huggingface_hub/main/en/guides/repository) - Repository operations\n- [Manage Cache](https://huggingface.co/docs/huggingface_hub/main/en/guides/manage-cache) - Cache configuration\n\n## Module Structure Summary\n\n| File | Responsibility |\n|------|----------------|\n| `_commit_api.py` | Core commit operations and operation classes |\n| `_upload_large_folder.py` | Chunked folder uploads |\n| `lfs.py` | Git LFS batch upload protocol implementation |\n| `_local_folder.py` | Local folder scanning and filtering |\n| `hf_api.py` | High-level HfApi methods for upload |\n\n---\n\n\n\n## Git LFS Large File Handling\n\n### 相关页面\n\n相关主题：[File Upload Operations](#file-upload), [File Download Operations](#file-download)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/lfs.py)\n- [src/huggingface_hub/utils/_lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_lfs.py)\n- [docs/source/en/concepts/git_vs_http.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/concepts/git_vs_http.md)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n \n\n# Git LFS Large File Handling\n\n## Overview\n\nGit LFS (Large File Storage) is a Git extension that handles large files by storing binary content outside the Git repository while maintaining a lightweight pointer file within it. The `huggingface_hub` library implements comprehensive LFS support to manage large model weights, datasets, and other binary assets on the Hugging Face Hub.\n\nIn the huggingface_hub ecosystem, LFS files are distinguished from regular Git-tracked files through their content addressing:\n\n| File Type | Storage Method | Identifier | Location in Cache |\n|-----------|---------------|------------|-------------------|\n| Regular Git Blob | Git commit SHA | 40-char hex string | `blobs/` |\n| LFS File | SHA256 hash | 64-char hex string | `blobs/` |\n\n资料来源：[src/huggingface_hub/lfs.py:1-50]()\n\n## Architecture\n\n### Cache Directory Structure\n\nWhen files are downloaded from the Hub, they are stored in a hierarchical cache structure:\n\n```mermaid\ngraph TD\n A[\"Cache Root
~/.cache/huggingface/hub/\"] --> B[\"models--{repo_id}\"]\n A --> C[\"datasets--{repo_id}\"]\n A --> D[\"spaces--{repo_id}\"]\n \n B --> E[\"blobs/\"]\n B --> F[\"refs/\"]\n B --> G[\"snapshots/\"]\n \n E --> H[\"git-sha
40-char\"]\n E --> I[\"sha256
64-char (LFS)\"]\n \n G --> J[\"{commit_hash}/\"]\n J --> K[\"filename → symlink → blob\"]\n```\n\n资料来源：[src/huggingface_hub/file_download.py:1-30]()\n\n### LFS Upload Workflow\n\nThe upload process follows a batch-oriented approach using the LFS Batch API:\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Hub as HF Hub API\n participant LFS as LFS Server\n \n Client->>Hub: POST /{repo_type}/{repo_id}.git/info/lfs/objects/batch\n Note over Hub,LFS: Batch request includes
upload instructions request\n Hub->>LFS: Check upload eligibility\n LFS-->>Hub: Upload instructions (presigned URLs)\n Hub-->>Client: LfsBatchInfo with actions\n \n alt basic/multipart transfer\n Client->>LFS: PUT file content directly\n LFS-->>Client: 200 OK\n else xet transfer\n Client->>Hub: Use custom xet protocol\n end\n \n Client->>Hub: POST /{repo_type}/{repo_id}.git/info/lfs/objects/batch\n Note over Client: Confirm upload completion\n Hub->>LFS: Verify file content\n LFS-->>Hub: Verification result\n Hub-->>Client: Commit ready\n```\n\n资料来源：[src/huggingface_hub/lfs.py:60-120]()\n\n## Core Components\n\n### LFS Module (`src/huggingface_hub/lfs.py`)\n\nThe main LFS module provides type definitions and utilities for handling LFS operations.\n\n#### Constants\n\n| Constant | Value | Purpose |\n|----------|-------|---------|\n| `LFS_MULTIPART_UPLOAD_COMMAND` | `\"lfs-multipart-upload\"` | Identifier for multipart upload operations |\n| `OID_REGEX` | `^[0-9a-f]{40}$` | Pattern for validating Git object identifiers |\n| `LFS_HEADERS` | Dict | Accept and content type headers for LFS API |\n\n资料来源：[src/huggingface_hub/lfs.py:40-55]()\n\n#### LFS Headers\n\n```python\nLFS_HEADERS = {\n \"Accept\": \"application/vnd.git-lfs+json\",\n \"Content-Type\": \"application/vnd.git-lfs+json\",\n}\n```\n\nThese headers indicate that all LFS API communications use JSON with the `vnd.git-lfs+json` media type, following the LFS specification.\n\n资料来源：[src/huggingface_hub/lfs.py:50-55]()\n\n### LFS Utilities (`src/huggingface_hub/utils/_lfs.py`)\n\nUtility functions for LFS operations include:\n\n| Function | Purpose |\n|----------|---------|\n| `SliceFileObj` | Context manager for slicing file objects during multipart uploads |\n| SHA utilities | Calculate SHA256 for LFS file content verification |\n| Content range handling | Manage byte ranges for resumable uploads |\n\n资料来源：[src/huggingface_hub/utils/_lfs.py]()\n\n## API Reference\n\n### LfsBatchInfo\n\nThe `LfsBatchInfo` dataclass encapsulates the server response from the LFS Batch API:\n\n```python\n@dataclass\nclass LfsBatchInfo:\n \"\"\"Information returned by the LFS batch API.\"\"\"\n \n actions: dict\n \"\"\"Dictionary of available actions (upload, verify).\"\"\"\n \n objects: list[dict]\n \"\"\"List of objects with their metadata.\"\"\"\n \n transfers: list[str]\n \"\"\"Supported transfer adapters (e.g., 'basic', 'multipart', 'xet').\"\"\"\n```\n\n资料来源：[src/huggingface_hub/lfs.py:55-80]()\n\n### Upload Information Classes\n\nThe library uses dataclasses to represent different types of upload information:\n\n| Class | Inheritance | Purpose |\n|-------|-------------|---------|\n| `UploadInfo` | Base | Abstract base for all upload info types |\n| `LfsUploadFileInfo` | `UploadInfo` | Standard LFS file upload with size and SHA256 |\n| `LfsUploadTtHubInfo` | `UploadInfo` | TtHub-specific upload info |\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n## Transfer Adapters\n\nThe Hugging Face Hub supports multiple LFS transfer methods, negotiated during the batch API handshake:\n\n### Supported Transfer Methods\n\n| Transfer Method | Description | Use Case |\n|-----------------|-------------|----------|\n| `basic` | Direct HTTP PUT upload | Small to medium files |\n| `multipart` | Chunked upload for very large files | Files > 100MB |\n| `xet` | Custom xet protocol for optimized transfers | High-performance scenarios |\n\n资料来源：[src/huggingface_hub/lfs.py:60-100]()\n\n### Transfer Method Selection\n\nThe client sends supported transfer methods in the batch request:\n\n```python\npayload: dict = {\n \"operation\": \"upload\",\n \"transfers\": transfers if transfers is not None else [\"basic\", \"multipart\"],\n ...\n}\n```\n\nThe server responds with the transfer adapter it will use, which the client then employs for the actual upload.\n\n资料来源：[src/huggingface_hub/lfs.py:85-95]()\n\n## Large File Identification\n\n### Size Thresholds\n\nFiles are treated as LFS content when they exceed certain thresholds:\n\n| Threshold | Action |\n|-----------|--------|\n| < 5MB | Stored as regular Git blob |\n| >= 5MB | Redirected to LFS storage |\n\n### OID (Object Identifier) Format\n\nLFS files are identified by their SHA256 hash, represented as a 64-character hexadecimal string:\n\n```\nPattern: ^[0-9a-f]{64}$\nExample: 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd\n```\n\nRegular Git blobs use 40-character SHA1 identifiers, while LFS files use 64-character SHA256 identifiers.\n\n资料来源：[src/huggingface_hub/lfs.py:45]()\n\n## Multipart Upload for Large Files\n\n### Upload Process\n\n```mermaid\ngraph LR\n A[File] --> B{Split into chunks}\n B --> C[Chunk 1]\n B --> D[Chunk 2]\n B --> E[Chunk N]\n \n C --> F[Upload Part 1]\n D --> G[Upload Part 2]\n E --> H[Upload Part N]\n \n F --> I{All parts
complete?}\n G --> I\n H --> I\n \n I -->|Yes| J[Complete multipart
upload]\n```\n\n### Chunk Size Calculation\n\nThe library calculates optimal chunk sizes based on file size:\n\n```python\nfrom math import ceil\n\nchunk_size = ceil(file_size / total_parts)\n```\n\nThis ensures even distribution of work across all chunks.\n\n资料来源：[src/huggingface_hub/lfs.py:30-35]()\n\n## Integration with Commit API\n\n### CommitOperationAdd with LFS\n\nThe `CommitOperationAdd` class handles both regular and LFS file uploads:\n\n```python\nclass CommitOperationAdd(TypedDict):\n path_in_repo: str\n id: str # OID (git-sha or sha256 for LFS)\n size: int\n filepath: str\n upload_info: UploadInfo\n```\n\nThe `upload_info` attribute contains the LFS-specific upload metadata, which determines whether the file goes through LFS or regular Git upload.\n\n资料来源：[src/huggingface_hub/_commit_api.py:100-150]()\n\n### Upload Flow\n\n```mermaid\nflowchart TD\n A[Create CommitOperationAdd] --> B{File size
> threshold?}\n \n B -->|Yes| C[Create LfsUploadFileInfo]\n B -->|No| D[Create UploadInfo for Git]\n \n C --> E[Upload via LFS Batch API]\n D --> F[Upload via Git HTTP API]\n \n E --> G{LFS transfer
method}\n G -->|basic| H[Single PUT request]\n G -->|multipart| I[Chunked upload]\n G -->|xet| J[Custom xet protocol]\n \n H --> K[Verify upload]\n I --> K\n J --> K\n \n K --> L[Commit confirmation]\n F --> L\n```\n\n## Error Handling\n\n### Validation Errors\n\n| Error | Condition | Handling |\n|-------|-----------|----------|\n| Invalid OID | Not matching `OID_REGEX` | Raise `ValueError` |\n| Missing upload info | `upload_info` not set | Raise `ValueError` |\n| Malformed batch response | Missing required fields | Raise `HfHubHTTPError` |\n\n### Network Errors\n\nThe library implements automatic retry with exponential backoff for failed LFS operations:\n\n```python\nfrom huggingface_hub.utils import http_backoff\n\n# Wrapped in http_backoff for resilience\nhf_raise_for_status(response)\n```\n\n资料来源：[src/huggingface_hub/lfs.py:50-80]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Effect |\n|----------|--------|\n| `HF_ENDPOINT` | Override default `https://huggingface.co` |\n| `HF_TOKEN` | Authentication token for private repos |\n\n### Upload Options\n\nWhen uploading files, the following options control LFS behavior:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `transfers` | `list[str]` | `[\"basic\", \"multipart\"]` | Allowed transfer methods |\n| `endpoint` | `str` | Hub endpoint | LFS server endpoint |\n| `repo_type` | `str` | `\"model\"` | Repository type |\n| `repo_id` | `str` | Required | Repository identifier |\n\n资料来源：[src/huggingface_hub/lfs.py:60-110]()\n\n## Best Practices\n\n### File Organization\n\n1. **Group large binary files** - Store model weights and dataset files separately from code\n2. **Use consistent file sizes** - Avoid extremely small LFS files (< 5MB overhead)\n3. **Leverage symlinks** - The snapshot directory uses symlinks to avoid duplication\n\n### Upload Optimization\n\n1. **Prefer multipart for files > 100MB** - Enables parallel uploads and resumability\n2. **Enable xet for frequent transfers** - Custom protocol reduces bandwidth\n3. **Batch operations** - Use `CommitOperationAdd` batching to minimize round trips\n\n### Caching Strategy\n\n```\n~/.cache/huggingface/hub/\n└── models--{repo_id}/\n ├── blobs/ # Physical file storage (SHA256 for LFS)\n ├── refs/ # Revision pointers\n └── snapshots/ # Virtual files pointing to blobs\n```\n\nThe snapshot layer provides deduplication - the same blob referenced by multiple commits is stored only once.\n\n资料来源：[src/huggingface_hub/file_download.py:10-30]()\n\n## See Also\n\n- [Git vs HTTP Protocol](https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http) - Understanding when LFS is used\n- [hf_hub_download](https://huggingface.co/docs/huggingface_hub/package_reference/file_download) - File downloading with LFS support\n- [Commit API Reference](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api) - Uploading with commits\n\n---\n\n\n\n## Repository Management API\n\n### 相关页面\n\n相关主题：[File Upload Operations](#file-upload), [Authentication System](#authentication), [Cache Management System](#cache-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n- [src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [docs/source/en/guides/repository.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/repository.md)\n \n\n# Repository Management API\n\nThe Repository Management API in `huggingface_hub` provides a comprehensive interface for creating, configuring, and managing Hugging Face repositories (models, datasets, and Spaces) directly from Python code or via the command-line interface.\n\n## Overview\n\nThe Repository Management API serves as the core layer for all Hub repository operations, enabling developers to programmatically:\n\n- Create and delete repositories\n- Configure repository settings\n- Upload and download files\n- Manage repository metadata\n- Handle commit operations with Git LFS support\n\n资料来源：[src/huggingface_hub/README.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/README.md)\n\n## Architecture\n\nThe repository management functionality is distributed across multiple modules:\n\n```mermaid\ngraph TD\n A[Repository Management API] --> B[hf_api.py]\n A --> C[_commit_api.py]\n A --> D[_buckets.py]\n B --> E[REST API Client]\n C --> E\n B --> F[CLI Interface]\n F --> G[hf CLI Command]\n```\n\n### Core Components\n\n| Module | Purpose |\n|--------|---------|\n| `hf_api.py` | Main `HfApi` class with all CRUD operations |\n| `_commit_api.py` | Low-level commit operations, LFS handling |\n| `_buckets.py` | Bucket/S3-compatible storage management |\n| `cli/` | Command-line interface implementation |\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## Repository Types\n\nThe API supports three primary repository types:\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `model` | Model repositories | Storing and sharing ML model weights |\n| `dataset` | Dataset repositories | Hosting and versioning datasets |\n| `space` | Space repositories | Hosting Gradio/Streamlit demos |\n\n## Core Operations\n\n### Repository Lifecycle\n\n```mermaid\ngraph LR\n A[create_repo] --> B[Update Settings]\n B --> C[Upload Files]\n C --> D[Manage Commits]\n D --> E[delete_repo]\n```\n\n#### Creating a Repository\n\n```python\nfrom huggingface_hub import create_repo, HfApi\n\n# Using HfApi class\napi = HfApi()\napi.create_repo(\n repo_id=\"username/my-model\",\n repo_type=\"model\",\n exist_ok=False\n)\n\n# Using convenience function\ncreate_repo(\n repo_id=\"super-cool-model\",\n token=\"hf_xxxxx\"\n)\n```\n\n#### Deleting a Repository\n\n```python\napi.delete_repo(repo_id=\"username/my-model\", repo_type=\"model\")\n```\n\n资料来源：[src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### Repository Settings\n\nUpdate repository configuration after creation:\n\n```python\napi.update_repo_settings(\n repo_id=\"username/my-model\",\n private=True,\n repo_type=\"model\",\n gated=True # Enable gated access\n)\n```\n\n### Listing Repository Contents\n\n```python\n# List all files in a repository\nfiles = api.list_repo_files(repo_id=\"tiiuae/falcon-7b-instruct\")\n\n# List repo objects with pagination\nobjects = api.list_repo_objects(\n repo_id=\"my-org/my-dataset\",\n repo_type=\"dataset\"\n)\n```\n\n## Commit Operations\n\n### Commit Operation Classes\n\nThe `_commit_api.py` module provides low-level commit primitives:\n\n| Class | Purpose |\n|-------|---------|\n| `CommitOperationAdd` | Add a file to the repository |\n| `CommitOperationDelete` | Remove a file from the repository |\n| `CommitOperationCopy` | Copy a file within the repository |\n\n```python\nfrom huggingface_hub import CommitOperationAdd, HfApi\n\noperations = [\n CommitOperationAdd(\n path_in_repo=\"config.json\",\n path_or_fileobj=\"/local/path/config.json\"\n ),\n]\n\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Add config file\"\n)\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n\n### Large File Upload (Git LFS)\n\nLarge files are automatically handled via Git LFS:\n\n```mermaid\ngraph TD\n A[File > 10MB] --> B{LFS Required?}\n B -->|Yes| C[Upload to LFS Storage]\n B -->|No| D[Upload as Regular File]\n C --> E[Create LFS Pointer]\n E --> F[Commit Pointer to Repo]\n D --> F\n```\n\n## File Upload Operations\n\n### Single File Upload\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/home/user/model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"username/my-model\",\n)\n```\n\n### Folder Upload\n\n```python\nfrom huggingface_hub import upload_folder\n\nupload_folder(\n folder_path=\"/path/to/local/space\",\n repo_id=\"username/my-cool-space\",\n repo_type=\"space\",\n commit_message=\"Update space files\"\n)\n```\n\nFor very large folders, the library provides chunked upload:\n\n```python\nfrom huggingface_hub import _upload_large_folder\n\n_upload_large_folder(\n repo_id=\"username/large-dataset\",\n folder_path=\"/data/large-folder\",\n repo_type=\"dataset\"\n)\n```\n\n资料来源：[src/huggingface_hub/README.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/README.md)\n\n## File Deletion Operations\n\n```python\n# Delete a single file\napi.delete_file(\n path_in_repo=\"old-model.bin\",\n repo_id=\"username/my-model\",\n commit_message=\"Remove deprecated file\"\n)\n\n# Delete a folder\napi.delete_folder(\n path_in_repo=\"old-folder/\",\n repo_id=\"username/my-model\",\n commit_message=\"Clean up old directory\"\n)\n```\n\n## CLI Interface\n\nThe repository management features are exposed through the `hf` CLI:\n\n```bash\n# Authentication\nhf auth login\nhf auth logout\nhf auth whoami\n\n# Repository operations\nhf repos create username/my-model --type model\nhf repos create username/my-dataset --type dataset\n```\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Configuration Parameters\n\n### Repository Creation Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | str | Required | Repository identifier (user/name or org/name) |\n| `repo_type` | str | \"model\" | Type: \"model\", \"dataset\", or \"space\" |\n| `exist_ok` | bool | False | Allow overwriting existing repo |\n| `private` | bool | False | Make repository private |\n| `token` | str | None | Hugging Face authentication token |\n| `space_sdk` | str | None | Space SDK: \"gradio\", \"streamlit\", \"docker\", \"docker_leaf\", \"static\", \"nextjs\" |\n| `space_hardware` | str | None | Space hardware tier |\n\n### Commit Operation Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `operations` | list[CommitOperation] | Required | List of file operations |\n| `commit_message` | str | Required | Description of changes |\n| `commit_description` | str | None | Extended commit description |\n| `parent_commit` | str | None | Parent commit SHA for incremental updates |\n| `create_pr` | bool | False | Create a Pull Request instead of committing to main |\n\n## Error Handling\n\nThe repository management API raises specific exception types:\n\n| Exception | Cause |\n|-----------|-------|\n| `RepositoryNotFoundError` | Repository does not exist or user lacks access |\n| `RevisionNotFoundError` | Specified git revision not found |\n| `EntryNotFoundError` | File or folder not found in repository |\n| `HfHubHTTPError` | HTTP error from the Hub API |\n\n```python\nfrom huggingface_hub import hf_hub_download\nfrom huggingface_hub.errors import RevisionNotFoundError\n\ntry:\n hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n revision=\"\"\n )\nexcept RevisionNotFoundError as e:\n print(f\"Revision not found: {e}\")\n```\n\n资料来源：[src/huggingface_hub/errors.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py)\n\n## Common Usage Patterns\n\n### Model Publishing Workflow\n\n```mermaid\ngraph TD\n A[Create Repo] --> B[Upload Model Files]\n B --> C[Create Model Card]\n C --> D[Set Metadata/Tags]\n D --> E[Publish to Hub]\n```\n\n```python\nfrom huggingface_hub import HfApi, upload_file, RepoCard, ModelCardData\n\napi = HfApi()\n\n# 1. Create repository\napi.create_repo(repo_id=\"my-org/my-model\", exist_ok=True)\n\n# 2. Upload model files\nupload_file(\n path_or_fileobj=\"./model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"my-org/my-model\"\n)\n\n# 3. Create and upload model card\ncard = RepoCard.from_template(\n ModelCardData(\n language=\"en\",\n license=\"apache-2.0\",\n model_name=\"My Custom Model\",\n tags=[\"pytorch\", \"image-classification\"]\n ),\n text=\"This is a custom model trained on...\"\n)\ncard.save(\".gitattributes\")\n```\n\n### Dataset Versioning Workflow\n\n```python\nfrom huggingface_hub import create_commit, CommitOperationAdd\n\noperations = [\n CommitOperationAdd(\n path_in_repo=\"data/train.parquet\",\n path_or_fileobj=\"./train.parquet\"\n ),\n CommitOperationAdd(\n path_in_repo=\"data/validation.parquet\", \n path_or_fileobj=\"./validation.parquet\"\n ),\n]\n\napi.create_commit(\n repo_id=\"username/my-dataset\",\n operations=operations,\n commit_message=\"Add training and validation splits\",\n commit_description=\"Initial dataset release with train/validation split\"\n)\n```\n\n## Best Practices\n\n1. **Use `exist_ok=True`** when creating repositories in automated pipelines\n2. **Include commit messages** for better version control history\n3. **Use `parent_commit`** parameter when making sequential updates to prevent race conditions\n4. **Enable LFS** automatically for files larger than 10MB\n5. **Use `create_pr=True`** for reviewing changes before merging to main branch\n\n## See Also\n\n- [Upload Guide](https://huggingface.co/docs/huggingface_hub/en/guides/upload)\n- [Download Guide](https://huggingface.co/docs/huggingface_hub/main/ko/guides/download)\n- [Manage Cache](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)\n- [HfFileSystem](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py) for filesystem-style access\n\n---\n\n\n\n## Cache Management System\n\n### 相关页面\n\n相关主题：[File Download Operations](#file-download), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/utils/_cache_manager.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_cache_manager.py)\n- [src/huggingface_hub/constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py)\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n- [src/huggingface_hub/cli/cache.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/cache.py)\n- [src/huggingface_hub/hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n \n\n# Cache Management System\n\n## Overview\n\nThe Cache Management System in `huggingface_hub` provides comprehensive utilities for managing locally cached models, datasets, and Spaces downloaded from the Hugging Face Hub. The system handles automatic caching of downloaded content, tracks cache metadata, and offers programmatic and CLI interfaces for inspecting and managing cached resources.\n\nThe cache system is designed to:\n- Store downloaded files efficiently with deduplication via blob storage\n- Track repository metadata including revisions, commit hashes, and file information\n- Provide safe deletion strategies that don't corrupt cache state\n- Handle corrupted cache entries gracefully with warnings\n\n## Cache Directory Structure\n\nThe Hugging Face cache follows a specific directory structure to organize cached content:\n\n```\nHF_HUB_CACHE/\n├── .locks/ # Lock files for concurrent access\n│ └── ...\n├── CACHEDIR.TAG # OS-native cache directory marker\n├── models--owner/\n│ └── repo_name/\n│ ├── .cache/ # Metadata and tracking\n│ ├── blobs/ # Actual file content (deduplicated)\n│ ├── refs/ # Branch and tag references\n│ ├── snapshots/ # Symlinks to blobs\n│ └── ...\n├── datasets--org/\n│ └── dataset_name/\n│ └── ...\n└── spaces--user/\n └── space_name/\n └── ...\n```\n\nCache directories follow the naming convention `type--repo_id` where:\n- `type` is singular (e.g., `model`, `dataset`, `space`)\n- `repo_id` slashes are converted to hyphens (e.g., `google/fleurs` becomes `google--fleurs`)\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## Core Data Models\n\n### HFCacheInfo\n\nThe main container class for cache information returned by scan operations:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `repos` | `frozenset[CachedRepoInfo]` | All cached repositories |\n| `size_on_disk` | `int` | Total size of all cached content in bytes |\n| `warnings` | `list[CorruptedCacheException]` | Issues encountered during scanning |\n\n### CachedRepoInfo\n\nRepresents a single cached repository:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `repo_id` | `str` | Repository identifier (e.g., `google/gemma-3-4b-it`) |\n| `repo_type` | `str` | Type: `model`, `dataset`, or `space` |\n| `size_on_disk` | `int` | Total size of cached revisions |\n| `revisions` | `frozenset[CachedRevisionInfo]` | All cached revisions |\n| `snapshot_path` | `Path` | Path to the snapshot directory |\n\n### CachedRevisionInfo\n\nRepresents a specific revision within a cached repository:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `commit_hash` | `str` | Git commit hash (40-character hex string) |\n| `size_on_disk` | `int` | Size of this specific revision |\n| `files` | `frozenset[CachedFileInfo]` | Files in this revision |\n| `last_modified` | `datetime` | Last modification timestamp |\n\n### CachedFileInfo\n\nRepresents an individual cached file:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `file_name` | `str` | Name of the file |\n| `size_on_disk` | `int` | Size of the file in bytes |\n| `file_path` | `Path` | Path to the symlinked file in snapshots |\n| `blob_path` | `Path` | Path to the actual blob storage |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## Key API Functions\n\n### scan_cache_dir()\n\nScans the cache directory and returns information about all cached repositories.\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\nprint(f\"Total size: {cache_info.size_on_disk / 1024 / 1024:.2f} MB\")\nfor repo in cache_info.repos:\n print(f\"{repo.repo_type}/{repo.repo_id}\")\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | `HF_HUB_CACHE` env var | Cache directory to scan |\n\n**Returns:** `HFCacheInfo` object containing repository information\n\n**Raises:**\n- `CacheNotFound` if the cache directory doesn't exist\n- `ValueError` if cache_dir is a file instead of a directory\n\n### try_to_load_from_cache()\n\nChecks if a file exists in the local cache without downloading.\n\n```python\nfrom huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST\n\nfilepath = try_to_load_from_cache(\n repo_id=\"tiiuae/falcon-7b-instruct\",\n filename=\"config.json\",\n revision=\"main\",\n repo_type=\"model\"\n)\n\nif isinstance(filepath, str):\n print(f\"File cached at: {filepath}\")\nelif filepath is _CACHED_NO_EXIST:\n print(\"File confirmed to not exist at this revision\")\nelse:\n print(\"File not in cache\")\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | None | Cache directory path |\n| `repo_id` | `str` | Required | Repository identifier |\n| `filename` | `str` | Required | Filename to look for |\n| `revision` | `str` | `\"main\"` | Specific revision to check |\n| `repo_type` | `str` | `\"model\"` | Type of repository |\n\n**Returns:** `str` (file path), `_CACHED_NO_EXIST`, or `None`\n\n资料来源：[src/huggingface_hub/file_download.py:1-100]()\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## DeleteCacheStrategy\n\nThe deletion system uses a two-phase approach: create a strategy, then execute it. This prevents accidental data loss and allows for dry-run validation.\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\n\n# Create deletion strategy (doesn't delete yet)\ndelete_strategy = cache_info.delete_revisions(\n \"81fd1d6e7847c99f5862c9fb81387956d99ec7aa\",\n \"e2983b237dccf3ab4937c97fa717319a9ca1a96d\",\n)\n\n# Preview what will be deleted\nprint(f\"Will free: {delete_strategy.expected_free_space / 1024 / 1024:.2f} MB\")\n\n# Execute the deletion\ndelete_strategy.execute()\n```\n\n### Deletion Workflow\n\n```mermaid\ngraph TD\n A[scan_cache_dir] --> B[Get HFCacheInfo]\n B --> C[Call delete_revisions with commit hashes]\n C --> D[Create DeleteCacheStrategy]\n D --> E{Preview/Dry Run}\n E -->|Inspect| F[Review expected_free_space]\n E -->|Confirm| G[execute]\n G --> H[Delete blobs and refs]\n H --> I[Cache deletion done]\n F --> G\n```\n\n### DeleteCacheStrategy Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `repos_to_delete` | `dict[CachedRepoInfo, set[CachedRevisionInfo]]` | Repos and revisions marked for deletion |\n| `blobs_to_delete` | `set[Path]` | Blob file paths to remove |\n| `expected_free_space` | `int` | Estimated bytes to be freed |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## CLI Interface\n\nThe `hf` command provides cache management through the `cache` subcommand.\n\n### List Cached Repositories\n\n```bash\nhf cache ls\n```\n\n**Output format:**\n```\nID SIZE LAST_ACCESSED LAST_MODIFIED REFS\n--------------------------- -------- ------------- ------------- -----------\ndataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script\nmodel/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main\nmodel/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main\n\nDone in 0.0s. Scanned 6 repo(s) for a total of 3.4G.\n```\n\n### Filtering Options\n\n| Filter Key | Operators | Example |\n|------------|-----------|---------|\n| `type` | `==`, `!=` | `--filter type==model` |\n| `size` | `>`, `<`, `>=`, `<=`, `=` | `--filter size>=1G` |\n| `accessed` | `>`, `<`, `>=`, `<=` | `--filter accessed<7d` |\n| `modified` | `>`, `<`, `>=`, `<=` | `--filter modified>30d` |\n| `refs` | `==`, `!=` | `--filter refs==main` |\n\n**Examples:**\n```bash\n# Filter large models\nhf cache ls --filter type==model --filter size>=5G\n\n# Find recently accessed datasets\nhf cache ls --filter type==dataset --filter accessed<7d\n\n# Filter by modification time\nhf cache ls --filter modified>30d\n```\n\n### Sorting Options\n\n| Sort Key | Default Order | Ascending Option |\n|----------|---------------|------------------|\n| `name` | `asc` | `name:asc` |\n| `size` | `desc` | `size:asc` |\n| `accessed` | `desc` | `accessed:asc` |\n| `modified` | `desc` | `modified:asc` |\n\n**Examples:**\n```bash\n# Sort by size descending (largest first)\nhf cache ls --sort size\n\n# Sort by name ascending, then size descending\nhf cache ls --sort name:asc --sort size:desc\n```\n\n### Delete Specific Revisions\n\n```bash\nhf cache delete [...]\n```\n\nThe CLI will prompt for confirmation before deletion.\n\n资料来源：[src/huggingface_hub/cli/cache.py:1-100]()\n\n## Cache Scanning Process\n\nThe cache scanning process validates the cache directory structure and handles corrupted entries gracefully.\n\n```mermaid\ngraph TD\n A[Start scan_cache_dir] --> B{Is cache_dir set?}\n B -->|No| C[Use HF_HUB_CACHE env var]\n B -->|Yes| D[Use provided path]\n C --> E{Does directory exist?}\n D --> E\n E -->|No| F[Raise CacheNotFound]\n E -->|Yes| G{Is it a file?}\n G -->|Yes| H[Raise ValueError]\n G -->|No| I[Iterate subdirectories]\n I --> J{Skip .locks and CACHEDIR.TAG?}\n J -->|Yes| K[Next directory]\n J -->|No| L[_scan_cached_repo]\n L --> M{Valid format?}\n M -->|No| N[Log CorruptedCacheException]\n M -->|Yes| O[Create CachedRepoInfo]\n N --> P[Add to warnings list]\n O --> Q[Add to repos set]\n P --> K\n Q --> K\n K --> R{More directories?}\n R -->|Yes| I\n R -->|No| S[Return HFCacheInfo]\n```\n\n### Validation Rules\n\n1. Each subdirectory must follow the `type--repo_id` naming convention\n2. The `type` must be one of: `model`, `dataset`, `space`\n3. Directories must contain expected subdirectories (snapshots, blobs, refs)\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:100-200]()\n\n## HubMixin Integration\n\nThe `HubMixin` class integrates with the cache system for model loading:\n\n```python\nfrom huggingface_hub import HubMixin\n\nclass MyModel(HubMixin, torch.nn.Module):\n pass\n\n# Load model - uses cache automatically\nmodel = MyModel.from_pretrained(\"bert-base-uncased\")\n\n# Cache behavior:\n# 1. Check if model exists locally\n# 2. If local_files_only=True, use cached version or raise error\n# 3. Otherwise, download and cache from Hub\n# 4. Store in cache_dir or default HF_HUB_CACHE location\n```\n\n**HubMixin Parameters Related to Caching:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | None | Custom cache location |\n| `force_download` | `bool` | `False` | Force re-download |\n| `local_files_only` | `bool` | `False` | Only use cached files |\n| `token` | `str` or `bool` | None | HuggingFace token |\n\n资料来源：[src/huggingface_hub/hub_mixin.py:1-100]()\n\n## Exception Handling\n\n### CorruptedCacheException\n\nRaised when cache directory structure is invalid or expected files are missing.\n\n```python\nclass CorruptedCacheException(Exception):\n \"\"\"Exception raised when a cache entry is corrupted.\"\"\"\n def __init__(self, message: str):\n self.message = message\n super().__init__(self.message)\n```\n\nCommon corruption scenarios:\n- Snapshots directory doesn't exist\n- Invalid repository directory naming\n- Missing expected cache metadata\n\n### CacheNotFound\n\nRaised when the cache directory cannot be located.\n\n```python\nraise CacheNotFound(\n f\"Cache directory not found: {cache_dir}. \"\n \"Please use `cache_dir` argument or set `HF_HUB_CACHE` environment variable.\",\n cache_dir=cache_dir,\n)\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HF_HUB_CACHE` | Primary cache directory | `~/.cache/huggingface/hub` |\n| `HF_HUB_DOWNLOAD_TIMEOUT` | Download timeout in seconds | 10 |\n\n资料来源：[src/huggingface_hub/constants.py]()\n\n## Best Practices\n\n### Efficient Cache Usage\n\n1. **Reuse cached content**: Multiple models sharing the same base weights will reference the same blobs\n2. **Use revision pinning**: Specify exact commit hashes for reproducible builds\n3. **Monitor cache size**: Regularly run `hf cache ls` to identify large repositories\n\n### Safe Deletion\n\n1. Always use `scan_cache_dir()` to inspect before deletion\n2. Check `warnings` in `HFCacheInfo` for corrupted entries\n3. Use `expected_free_space` property to estimate space recovery\n4. Execute deletion only after confirming the strategy\n\n### Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| CacheNotFound error | Set `HF_HUB_CACHE` or use `cache_dir` parameter |\n| CorruptedCacheException | Manually delete the corrupted cache entry |\n| Large cache size | Use `delete_revisions()` to remove old/unused revisions |\n| Permission denied | Check file permissions on cache directory |\n\n## Complete Usage Example\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# Scan cache and get overview\ncache_info = scan_cache_dir()\n\nprint(f\"Total cached repos: {len(cache_info.repos)}\")\nprint(f\"Total size: {cache_info.size_on_disk / 1024**3:.2f} GB\")\n\n# Find specific repo\ntarget_repo = \"stabilityai/stable-diffusion-2-1\"\nfor repo in cache_info.repos:\n if repo.repo_id == target_repo:\n print(f\"\\nFound {target_repo}:\")\n print(f\" Type: {repo.repo_type}\")\n print(f\" Revisions: {len(repo.revisions)}\")\n for revision in repo.revisions:\n print(f\" - {revision.commit_hash[:8]}\")\n print(f\" Size: {revision.size_on_disk / 1024**2:.2f} MB\")\n print(f\" Files: {len(revision.files)}\")\n\n# Clean up old revisions\nif cache_info.repos:\n first_repo = next(iter(cache_info.repos))\n if len(first_repo.revisions) > 1:\n # Keep only the latest revision\n revisions_to_delete = [\n rev.commit_hash \n for rev in list(first_repo.revisions)[1:]\n ]\n strategy = cache_info.delete_revisions(*revisions_to_delete)\n print(f\"\\nWould free: {strategy.expected_free_space / 1024**2:.2f} MB\")\n # strategy.execute() # Uncomment to actually delete\n\n---\n\n\n\n## Inference Client and Providers\n\n### 相关页面\n\n相关主题：[HuggingFace File System (HfFileSystem)](#hf-file-system), [Overview and Architecture](#overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py)\n- [src/huggingface_hub/inference/_generated/_async_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_generated/_async_client.py)\n- [src/huggingface_hub/inference/_providers](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers)\n- [src/huggingface_hub/inference/_common.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_common.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n \n\n# Inference Client and Providers\n\n## Overview\n\nThe Inference Client and Providers system provides a unified interface for performing inference with machine learning models hosted on Hugging Face or third-party inference providers. This system abstracts the complexity of interacting with various inference backends, allowing developers to make inference calls through a consistent Python API.\n\nThe `InferenceClient` class serves as the primary entry point for synchronous inference operations, while `AsyncInferenceClient` provides asynchronous alternatives for non-blocking workflows. Both clients leverage a provider system that normalizes API differences between various inference services like Replicate, Together AI, Fal.ai, and Sambanova. 资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n## Architecture\n\nThe inference system follows a layered architecture where the client exposes a high-level API while delegating provider-specific details to helper classes.\n\n```mermaid\ngraph TD\n User[User Code] --> Client[InferenceClient]\n Client --> ProviderHelper[Provider Helper]\n ProviderHelper --> ProviderAPI[Third-party Provider API]\n ProviderHelper --> HFRouting[Hugging Face Routing]\n \n subgraph \"InferenceClient\"\n Methods[text_generation, chat_completion,
text_to_image, etc.]\n end\n \n subgraph \"Provider Layer\"\n get_provider_helper[get_provider_helper]\n prepare_request[prepare_request]\n get_response[get_response]\n end\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|--------------|---------|\n| `InferenceClient` | `inference/_client.py` | Synchronous inference operations |\n| `AsyncInferenceClient` | `inference/_generated/_async_client.py` | Asynchronous inference operations |\n| Provider Helpers | `inference/_providers/*.py` | Provider-specific request/response handling |\n| Provider Registry | `inference/_providers/__init__.py` | Provider discovery and initialization |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-50]()\n\n## Supported Inference Tasks\n\nThe InferenceClient supports a comprehensive set of inference tasks through method-based API calls.\n\n### Task Categories and Methods\n\n| Category | Method | Description |\n|----------|--------|-------------|\n| **Text Generation** | `text_generation()` | Generate text from prompts with streaming support |\n| **Chat** | `chat_completion()` | Multi-turn conversation with message history |\n| **Image Generation** | `text_to_image()` | Generate images from text prompts |\n| **Video Generation** | `text_to_video()` | Generate videos from text descriptions |\n| **Text Analysis** | `summarization()` | Summarize long text documents |\n| **Text Analysis** | `fill_mask()` | Fill masked tokens in text |\n| **Text Analysis** | `zero_shot_classification()` | Classify text with arbitrary labels |\n| **Table Operations** | `table_question_answering()` | Answer questions from tabular data |\n| **Table Operations** | `tabular_classification()` | Classify tabular data rows |\n| **Embeddings** | `sentence_similarity()` | Compute semantic similarity between sentences |\n| **Vision** | `image_classification()` | Classify images into categories |\n\n资料来源：[src/huggingface_hub/inference/_client.py:200-500]()\n\n## Client Configuration\n\n### Initialization Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `str \\| None` | `None` | Default model identifier for all requests |\n| `provider` | `str \\| None` | `None` | Inference provider to use (replicate, together, fal-ai, etc.) |\n| `api_key` | `str \\| None` | `None` | API key for authentication |\n| `token` | `str \\| bool \\| None` | `True` | Hugging Face token for authentication |\n| `timeout` | `float \\| None` | `None` | Request timeout in seconds |\n| `headers` | `dict[str, str]` | `{}` | Additional HTTP headers |\n\n```python\nfrom huggingface_hub import InferenceClient\n\n# Basic usage with default provider\nclient = InferenceClient()\n\n# Using a specific provider\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_...\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\"\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:50-150]()\n\n## Provider System\n\n### Provider Architecture\n\nThe provider system normalizes differences between inference services by abstracting request preparation and response parsing.\n\n```mermaid\ngraph LR\n A[InferenceClient] -->|task + model| B[get_provider_helper]\n B --> C{Provider Type}\n C -->|Built-in| D[Internal Provider Helper]\n C -->|Third-party| E[Provider API Helper]\n \n D --> F[Provider.prepare_request]\n E --> G[External API Call]\n \n F --> H[Normalized Response]\n G --> H\n```\n\n### Supported Providers\n\n| Provider | Description | Authentication |\n|----------|-------------|----------------|\n| `replicate` | Replicate hosted models | API key |\n| `together` | Together AI inference | API key |\n| `fal-ai` | Fal.ai generation services | API key |\n| `sambanova` | SambaNova Cloud | API key |\n| `default` | Hugging Face inference API | HF token |\n\n资料来源：[src/huggingface_hub/inference/_providers/__init__.py]()\n\n### Provider Helper Functions\n\nEach provider helper implements two key methods:\n\n- **`prepare_request()`**: Transforms inputs and parameters into provider-specific API format\n- **`get_response()`**: Parses provider response into normalized output format\n\n```python\nprovider_helper = get_provider_helper(\n provider=\"replicate\",\n task=\"text-generation\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\"\n)\n\nrequest_parameters = provider_helper.prepare_request(\n inputs=prompt,\n parameters={\"max_new_tokens\": 100},\n headers=client.headers,\n model=model_id,\n api_key=client.token,\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:150-200]()\n\n## Usage Examples\n\n### Text Generation\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\n# Basic text generation\noutput = client.text_generation(\n prompt=\"The capital of France is\",\n model=\"gpt2\"\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:300-400]()\n\n### Chat Completion\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\n provider=\"sambanova\",\n api_key=\"hf_...\"\n)\n\noutput = client.chat_completion(\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\",\n messages=[\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n ]\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:400-500]()\n\n### Image Generation\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_...\"\n)\n\nimage = client.text_to_image(\n \"An astronaut riding a horse on the moon.\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n extra_body={\"output_quality\": 100}\n)\nimage.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:500-600]()\n\n### Text-to-Video\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\nvideo = client.text_to_video(\n prompt=\"A cat playing piano\",\n num_inference_steps=50,\n guidance_scale=7.5\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:600-700]()\n\n### Sentence Similarity\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\nsimilarities = client.sentence_similarity(\n \"Machine learning is so easy.\",\n other_sentences=[\n \"Deep learning is so straightforward.\",\n \"This is so difficult, like rocket science.\",\n ]\n)\n# Output: [0.7785726189613342, 0.45876261591911316]\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:700-800]()\n\n### Zero-Shot Classification\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\ntext = \"A new model offers an explanation for how the Galilean satellites formed.\"\nlabels = [\"space & cosmos\", \"scientific discovery\", \"microbiology\", \"robots\"]\n\nresult = client.zero_shot_classification(text, labels)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:350-450]()\n\n## AsyncInferenceClient\n\nFor asynchronous workflows, the `AsyncInferenceClient` provides non-blocking equivalents of all synchronous methods.\n\n```python\nfrom huggingface_hub import AsyncInferenceClient\n\nasync def main():\n client = AsyncInferenceClient()\n \n # Async chat completion\n output = await client.chat_completion(\n model=\"meta-llama/Meta-Llama-3-70B-Instruct\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n )\n \n # Async image generation\n image = await client.text_to_image(\n prompt=\"A beautiful sunset over mountains\",\n model=\"black-forest-labs/FLUX.1-schnell\"\n )\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-200]()\n\n## Error Handling\n\nThe inference system defines specific exception types for common error conditions:\n\n| Exception | Description |\n|-----------|-------------|\n| `InferenceTimeoutError` | Request exceeded timeout threshold |\n| `HfHubHTTPError` | HTTP error from the inference provider |\n\n```python\nfrom huggingface_hub import InferenceClient, InferenceTimeoutError\n\nclient = InferenceClient(timeout=30)\n\ntry:\n result = client.text_generation(\"Hello world\")\nexcept InferenceTimeoutError:\n print(\"Request timed out\")\nexcept HfHubHTTPError as e:\n print(f\"HTTP error: {e}\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:250-300]()\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Client\n participant ProviderHelper\n participant API\n \n User->>Client: text_generation(prompt, model)\n Client->>ProviderHelper: get_provider_helper(provider, task, model)\n Client->>ProviderHelper: prepare_request(inputs, parameters)\n ProviderHelper-->>Client: request_parameters\n Client->>Client: _inner_post(request_parameters)\n Client->>API: HTTP POST\n API-->>Client: response\n Client->>ProviderHelper: get_response(response)\n ProviderHelper-->>Client: normalized_output\n Client-->>User: InferenceOutput\n```\n\n## Output Models\n\nThe inference client returns typed output objects for each task:\n\n| Task | Output Type |\n|------|-------------|\n| Text Generation | `TextGenerationOutput` or `TextGenerationStreamOutput` |\n| Chat Completion | `ChatCompletionOutput` |\n| Image Generation | `PIL.Image.Image` |\n| Video Generation | `bytes` |\n| Summarization | `SummarizationOutput` |\n| Fill Mask | `list[FillMaskOutputElement]` |\n| Zero-Shot Classification | `list[ZeroShotClassificationOutputElement]` |\n| Table Question Answering | `TableQuestionAnsweringOutputElement` |\n| Tabular Classification | `list[str]` |\n| Sentence Similarity | `list[float]` |\n| Image Classification | `list[ImageClassificationOutputElement]` |\n\n资料来源：[src/huggingface_hub/inference/_client.py:200-600]()\n\n## CLI Integration\n\nThe CLI provides command-line access to inference functionality:\n\n```bash\n# Install inference dependencies\npip install huggingface_hub[inference]\n\n# Run inference via CLI\nhf inference --model gpt2 --text \"The capital of France is\"\n```\n\n资料来源：[setup.py:1-30]()\n\n## Advanced Configuration\n\n### Extra Body Parameters\n\nMany inference methods accept `extra_body` for provider-specific parameters:\n\n```python\nclient = InferenceClient(provider=\"replicate\", api_key=\"hf_...\")\n\nimage = client.text_to_image(\n \"A majestic lion\",\n model=\"black-forest-labs/FLUX.1-dev\",\n extra_body={\n \"output_quality\": 100,\n \"guidance_scale\": 3.5\n }\n)\n```\n\n### Generate Parameters\n\nThe `generate_parameters` argument allows fine-tuning of generation behavior:\n\n```python\nclient.text_generation(\n prompt=\"Write a story\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\",\n generate_parameters={\n \"temperature\": 0.7,\n \"top_p\": 0.9,\n \"repetition_penalty\": 1.2\n }\n)\n```\n\n## Summary\n\nThe Inference Client and Providers system provides:\n\n1. **Unified API**: Consistent interface across all inference tasks\n2. **Multi-Provider Support**: Seamless integration with Replicate, Together AI, Fal.ai, and Sambanova\n3. **Type-Safe Outputs**: Well-defined output models for each task\n4. **Async Support**: Full async/await compatibility via AsyncInferenceClient\n5. **Error Handling**: Specific exceptions for timeout and HTTP errors\n6. **Extensible Design**: Provider helper system for adding new inference backends\n\nThis architecture enables developers to switch between providers and models without modifying application code, providing flexibility in deployment while maintaining a clean, Pythonic API.\n\n---\n\n\n\n## HuggingFace File System (HfFileSystem)\n\n### 相关页面\n\n相关主题：[File Download Operations](#file-download), [File Upload Operations](#file-upload)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n- [src/huggingface_hub/utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/huggingface/huggingface_hub/blob/main/AGENTS.md)\n \n\n# HuggingFace File System (HfFileSystem)\n\n## Overview\n\nThe HuggingFace File System (HfFileSystem) is an fsspec-based POSIX-like filesystem implementation that provides seamless access to Hugging Face Hub repositories. It enables developers to interact with models, datasets, and Spaces using familiar filesystem operations, abstracting away the complexity of HTTP API calls and caching mechanisms.\n\n**Key Characteristics:**\n\n| Property | Value |\n|----------|-------|\n| Base Class | `fsspec.spec.AbstractFileSystem` |\n| Protocol | `hf://` |\n| Python Version | >= 3.10.0 |\n| Entry Point | `hf=huggingface_hub.HfFileSystem` |\n\n资料来源：[setup.py:48](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L48)\n\n---\n\n## Architecture\n\nHfFileSystem is built as a wrapper around the Hugging Face Hub's higher-level APIs, providing a filesystem abstraction layer that translates standard filesystem operations into HTTP requests to the Hugging Face Hub API.\n\n```mermaid\ngraph TD\n A[User Code] --> B[fsspec Compatible Operations]\n B --> C[HfFileSystem]\n C --> D[Cache Layer]\n C --> E[HfApi Methods]\n E --> F[Hugging Face Hub API]\n D --> F\n G[Local Cache] --> D\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `HfFileSystem` | Main filesystem implementation extending fsspec |\n| Cache Layer | Manages local caching of downloaded files |\n| URI Parser | Parses `hf://` protocol URIs into structured components |\n| HTTP Client | Handles communication with Hugging Face Hub API |\n\n资料来源：[CLAUDE.md:10]()\n\n---\n\n## URI Schemes\n\nHfFileSystem supports multiple URI formats for accessing different resource types on the Hugging Face Hub.\n\n### Repository Paths\n\n**Models, Datasets, and Spaces:**\n\n```\nhf://[@]/\nhf://models/[@]/\nhf://datasets/[@]/\nhf://spaces/[@]/\n```\n\n**Buckets (Generic Storage):**\n\n```\nhf://buckets//\n```\n\n资料来源：[src/huggingface_hub/hf_file_system.py:27-41]()\n\n### URI Structure\n\nThe `hf://` protocol follows a defined grammar:\n\n```\nhf://[/][@][/]:[:ro|:rw]\n```\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| `TYPE` | Repository type (models, datasets, spaces) | `models` |\n| `ID` | Repository identifier | `my-org/my-model` |\n| `REVISION` | Git revision (branch, commit hash, or tag) | `refs/pr/3` |\n| `PATH` | Path within the repository | `data/train.json` |\n| `MOUNT_PATH` | Local mount point for bucket operations | `/mnt/data` |\n| `ACCESS_MODE` | Read-only (`ro`) or read-write (`rw`) | `ro` |\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:1-20]()\n\n---\n\n## API Reference\n\n### Initialization Parameters\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem(\n endpoint: str = None,\n token: bool | str = None,\n block_size: int = None,\n expand_info: bool = False,\n **storage_options\n)\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `endpoint` | `str` | `https://huggingface.co` | Hub API endpoint URL |\n| `token` | `bool` or `str` | `None` (uses saved token) | Authentication token. Set `False` to disable auth |\n| `block_size` | `int` | `None` | Block size for reading/writing files |\n| `expand_info` | `bool` | `False` | Whether to expand file information |\n| `**storage_options` | `dict` | `{}` | Additional storage options |\n\n资料来源：[src/huggingface_hub/hf_file_system.py:42-65]()\n\n### Authentication\n\nHfFileSystem uses token-based authentication:\n\n- **Default behavior**: Uses locally saved token from `~/.huggingface/token`\n- **Explicit token**: Pass a string token directly\n- **Disable auth**: Set `token=False`\n\n```python\n# Uses saved token (recommended)\nfs = HfFileSystem()\n\n# Explicit token\nfs = HfFileSystem(token=\"hf_xxxxx\")\n\n# Disable authentication\nfs = HfFileSystem(token=False)\n```\n\n### Special Revision Handling\n\nSpecial git refs containing slashes are handled specially:\n\n```python\n# Patterns matched:\n# - refs/pr/ (Pull Request refs)\n# - refs/convert/ (Conversion refs like parquet-v2)\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:25-32]()\n\n---\n\n## Usage Examples\n\n### Basic File Operations\n\n```python\nfrom huggingface_hub import HfFileSystem\n\n# Initialize filesystem\nfs = HfFileSystem()\n\n# Read a file\nwith fs.open(\"hf://datasets/squad/train.json\", \"r\") as f:\n content = f.read()\n\n# List directory contents\nfiles = fs.ls(\"hf://my-org/my-model/data\")\n\n# Check if path exists\nexists = fs.exists(\"hf://my-org/my-model/config.json\")\n\n# Get file info\ninfo = fs.info(\"hf://my-org/my-model/model.safetensors\")\n```\n\n### Using with Pandas\n\nHfFileSystem enables direct reading of datasets with libraries like pandas:\n\n```python\nimport pandas as pd\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# Read CSV file directly from Hub\ndf = pd.read_csv(\n \"hf://datasets/mnist/train.csv\",\n storage_options={\"token\": \"hf_xxxxx\"}\n)\n```\n\n> [!TIP]\n> This compatibility layer introduces additional overhead. For better performance and reliability, prefer using `HfApi` methods directly when possible.\n\n资料来源：[src/huggingface_hub/hf_file_system.py:8-22]()\n\n### Mount Operations\n\nFor bucket storage with mount points:\n\n```python\nfrom huggingface_hub.utils import parse_hf_mount\n\nmount_info = parse_hf_mount(\"hf://my-org/my-model:/data:ro\")\n# Returns HfMount with source, mount_path, and read_only attributes\n```\n\n### URI Parsing\n\n```python\nfrom huggingface_hub.utils import parse_hf_uri\n\n# Parse model URI\nuri = parse_hf_uri(\"hf://my-org/my-model\")\n# HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')\n\n# Parse dataset with revision\nuri = parse_hf_uri(\"hf://datasets/my-org/my-dataset@refs/pr/3/train.json\")\n# HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:100-130]()\n\n---\n\n## Error Handling\n\n### HfUriError\n\nRaised when URI parsing fails due to malformed input:\n\n```python\nfrom huggingface_hub.errors import HfUriError\n\ntry:\n parse_hf_uri(\"hf://\")\nexcept HfUriError as e:\n print(e.msg) # \"Empty body after 'hf://'.\"\n```\n\n### Validation Errors\n\nRepository IDs and paths are validated:\n\n```python\nfrom huggingface_hub.errors import HFValidationError\n\n# Invalid repo ID format raises HFValidationError\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:8-10]()\n\n---\n\n## Integration Points\n\n### fsspec Integration\n\nHfFileSystem registers as an fsspec filesystem via entry points:\n\n```python\n# In setup.py\nentry_points={\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\nThis enables usage with any fsspec-compatible library:\n\n```python\nimport fsspec\n\nfs = fsspec.filesystem(\"hf\", token=\"hf_xxxxx\")\n```\n\n### CLI Download Command\n\nThe CLI uses HfFileSystem internally for download operations:\n\n```python\n# From src/huggingface_hub/cli/download.py\n# Supports include/exclude patterns\n# Uses snapshot_download for multi-file downloads\n```\n\n资料来源：[setup.py:48](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L48), [src/huggingface_hub/cli/download.py:1-100]()\n\n---\n\n## Performance Considerations\n\n| Aspect | Recommendation |\n|--------|----------------|\n| Large File Downloads | Use `HfApi` methods directly |\n| Cached Access | HfFileSystem automatically caches files |\n| Batch Operations | Use `snapshot_download` for entire repos |\n| Authentication | Always use saved tokens when possible |\n\n> [!WARNING]\n> While HfFileSystem provides compatibility with pandas and other libraries, it introduces additional overhead due to the fsspec compatibility layer. For production workloads requiring optimal performance and reliability, prefer using `HfApi` methods directly.\n\n---\n\n## Related Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `HfApi` | `hf_api.py` | Primary API for all Hub operations |\n| `hf_hub_download` | `file_download.py` | Single file download with caching |\n| `snapshot_download` | `_snapshot_download.py` | Full repository download |\n| `parse_hf_uri` | `utils/_hf_uris.py` | URI parsing utilities |\n| `RepoCard` | `repocard.py` | Repository metadata cards |\n\n资料来源：[CLAUDE.md:3-15](), [AGENTS.md:3-15]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：huggingface/huggingface_hub\n\n摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：How to stop hf models ls from truncating the results in the table?。\n\n## 1. 安全/权限坑 · 来源证据：How to stop hf models ls from truncating the results in the table?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to stop hf models ls from truncating the results in the table?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb213b3feddd4ea09912922699b6b822 | https://github.com/huggingface/huggingface_hub/issues/4207 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8873fa5438804ce5af82d7acf73d7e90 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d18ece8e9bf4111aa4a07b5d120f412 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：[v1.10.0] Instant file copy and new Kernel repo type\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.10.0] Instant file copy and new Kernel repo type\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff686b653d2644649473ac1a7be8cb46 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：[v1.11.0] Semantic Spaces search, Space logs, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.11.0] Semantic Spaces search, Space logs, and more\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_149c8633eb8447b080e00977ea43f541 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：[v1.12.0] Unified CLI output, bucket search, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.12.0] Unified CLI output, bucket search, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66340c89abfe48459796695dee8aebb9 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7501a96be8144e2fbc85bfab477f54e1 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | release_recency=unknown\n\n\n",
"markdown_key": "huggingface-hub",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:323591830",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/huggingface/huggingface_hub"
},
{
"evidence_id": "art_8b14b47a895846d7a69199616178a079",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/huggingface/huggingface_hub#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "huggingface_hub 说明书",
"toc": [
"https://github.com/huggingface/huggingface_hub 项目说明书",
"目录",
"Overview and Architecture",
"Introduction",
"High-Level Architecture",
"Core Components",
"List models",
"Upload a file",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "6b652b06dda7b8b555280cbb011ae4da94153878",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"docs/TRANSLATING.md",
"docs/README.md",
"docs/dev/release.md",
"docs/source/de/index.md",
"docs/source/de/quick-start.md",
"docs/source/de/installation.md",
"docs/source/de/_toctree.yml",
"docs/source/fr/index.md",
"docs/source/fr/quick-start.md",
"docs/source/fr/installation.md",
"docs/source/fr/_toctree.yml",
"docs/source/en/_redirects.yml",
"docs/source/en/index.md",
"docs/source/en/quick-start.md",
"docs/source/en/installation.md",
"docs/source/en/_toctree.yml",
"docs/source/hi/index.md",
"docs/source/hi/quick-start.md",
"docs/source/hi/installation.md",
"docs/source/hi/_toctree.yml",
"docs/source/tm/index.md",
"docs/source/tm/installation.md",
"docs/source/tm/_toctree.yml",
"docs/source/ko/index.md",
"docs/source/ko/quick-start.md",
"docs/source/ko/installation.md",
"docs/source/ko/_toctree.yml",
"docs/source/cn/index.md",
"docs/source/cn/quick-start.md",
"docs/source/cn/installation.md",
"docs/source/cn/_toctree.yml",
"docs/source/de/guides/repository.md",
"docs/source/de/guides/manage-cache.md",
"docs/source/de/guides/integrations.md",
"docs/source/de/guides/overview.md",
"docs/source/de/guides/manage-spaces.md",
"docs/source/de/guides/inference.md",
"docs/source/de/guides/upload.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# huggingface-hub - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 huggingface-hub 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.opencode/skills/hf-release-notes/SKILL.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.opencode/skills/hf-release-notes/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install huggingface_hub` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86\n- `pip install \"huggingface_hub[mcp]\"` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.opencode/skills/hf-release-notes/SKILL.md` Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.opencode/skills/hf-release-notes/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.opencode/skills/hf-release-notes/SKILL.md`, `AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.opencode/skills/hf-release-notes/SKILL.md`, `AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.opencode/skills/hf-release-notes/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：475\n- 重要文件覆盖：40/475\n- 证据索引条目：80\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 huggingface-hub 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 huggingface-hub 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 huggingface-hub 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **hf-release-notes**（skill）：Generate Hugging Face Hub huggingface hub release notes from cached PR JSON files. Use when asked to draft release notes from PR files. 激活提示：当用户任务与“hf-release-notes”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.opencode/skills/hf-release-notes/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Generating the documentation**（documentation）： B[High-Level API]\n A --> C[File System Layer]\n A --> D[Inference Layer]\n B --> E[HfApi - Core Operations]\n B --> F[ModelHubMixin - ML Framework Integration]\n E --> G[HTTP Client / Requests]\n F --> G\n C --> H[HfFileSystem - fsspec]\n D --> I[Inference Client]\n G --> J[Hugging Face API]\n I --> J\n H --> J\n J --> K[Hub Backend]\n```\n\n### Module Organization\n\nThe source code is organized in `src/huggingface_hub/` with each module handling specific responsibilities:\n\n| Module | Purpose |\n|--------|---------|\n| `__init__.py` | Public API surface with auto-generated static imports |\n| `hf_api.py` | Main `HfApi` class with ~11k lines covering repo CRUD, uploads, downloads, discussions, PRs, collections |\n| `file_download.py` | `hf_hub_download` with caching logic, ETag resolution, xet download support |\n| `_snapshot_download.py` | `snapshot_download` for downloading entire repositories |\n| `_commit_api.py` | Low-level commit operations (`CommitOperationAdd`, `CommitOperationDelete`, `CommitOperationCopy`), LFS upload handling |\n| `hf_file_system.py` | `HfFileSystem` - fsspec-based POSIX-like filesystem for Hub repos |\n| `hub_mixin.py` | `ModelHubMixin` base class for ML framework integration |\n| `repocard.py` / `repocard_data.py` | `RepoCard`, `ModelCard`, `DatasetCard` and their metadata classes |\n| `community.py` | `Discussion`, `DiscussionComment` and event deserialization |\n| `lfs.py` | Git LFS batch upload utilities |\n| `_login.py` | `login()`, `logout()`, `notebook_login()`, token management |\n| `_inference_endpoints.py` | Inference endpoint CRUD and scaling |\n| `_jobs_api.py` | Training jobs API |\n| `_space_api.py` | Space runtime management |\n| `utils/_hf_uris.py` | URI parsing for `hf://` protocol support |\n\n**资料来源：**[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n---\n\n## Core Components\n\n### HfApi - Central API Class\n\nThe `HfApi` class serves as the primary interface for all Hub operations, implemented in `hf_api.py`. It provides methods for:\n\n- **Repository Management:** Create, list, delete, and update repositories\n- **File Operations:** Upload and download files\n- **Discussion & PRs:** Manage discussions and pull requests\n- **Collections:** Create and manage collections\n- **Metadata:** Update repository metadata and model cards\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n# List models\nmodels = api.list_models()\n# Upload a file\napi.upload_file(path_or_fileobj=\"model.bin\", path_in_repo=\"pytorch_model.bin\", repo_id=\"user/model\")\n```\n\n**资料来源：**[src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### HfFileSystem - Filesystem Interface\n\nThe `HfFileSystem` provides a POSIX-like filesystem interface using the fsspec specification, allowing standard file operations on Hub repositories:\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n# List files in a repository\nfiles = fs.ls(\"user/model\")\n# Read a file\nwith fs.open(\"user/model/config.json\", \"r\") as f:\n content = f.read()\n```\n\nThe filesystem is registered as an fsspec spec via the entry point `hf=huggingface_hub.HfFileSystem` defined in `setup.py`.\n\n**资料来源：**[setup.py:28](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L28), [src/huggingface_hub/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n\n### Repository Cards\n\nThe library provides structured classes for repository documentation:\n\n| Class | Purpose | File |\n|-------|---------|------|\n| `RepoCard` | Base class for all cards | `repocard.py` |\n| `ModelCard` | Model documentation with training metadata | `repocard.py` |\n| `DatasetCard` | Dataset documentation with annotations info | `repocard.py` |\n| `SpaceCard` | Space configuration and documentation | `repocard.py` |\n\nEach card contains:\n- **YAML Block:** Structured metadata via `CardData` classes\n- **Markdown Body:** Human-readable documentation\n\n**资料来源：**[src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py), [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n\n### ModelHubMixin - ML Framework Integration\n\nThe `ModelHubMixin` provides a base class for integrating Hub operations into ML frameworks. It enables:\n\n- Saving models directly to the Hub\n- Loading models from the Hub\n- Automatic model card generation\n\nThe mixin supports customizable parameters for model card generation including `library_name`, `license`, `pipeline_tag`, and `tags`.\n\n**资料来源：**[src/huggingface_hub/hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n\n---\n\n## Download Architecture\n\n### File Download Flow\n\n```mermaid\ngraph TD\n A[hf_hub_download / snapshot_download] --> B{Cache Check}\n B -->|Cached| C[Return Cached Path]\n B -->|Not Cached| D[Resolve ETag / Metadata]\n D --> E{Storage Backend}\n E -->|Standard| F[HTTP Download]\n E -->|Large File| G[LFS Download]\n E -->|Xet Support| H[Xet Download]\n F --> I[Store in Cache]\n G --> I\n H --> I\n I --> C\n```\n\n### Caching System\n\nThe library implements a sophisticated caching system that:\n\n1. Stores downloaded files in a local cache folder\n2. Uses ETag headers for efficient re-validation\n3. Supports conditional downloads to reduce bandwidth\n4. Handles large files through Git LFS\n\n**Key Components:**\n- `hf_hub_download()`: Downloads a single file\n- `snapshot_download()`: Downloads an entire repository\n\n**资料来源：**[src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py), [src/huggingface_hub/_snapshot_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py)\n\n---\n\n## Upload Architecture\n\n### Commit Operations\n\nThe library uses a commit-based model for uploads with three operation types:\n\n| Operation | Class | Purpose |\n|-----------|-------|---------|\n| Add | `CommitOperationAdd` | Upload a file |\n| Delete | `CommitOperationDelete` | Remove a file |\n| Copy | `CommitOperationCopy` | Duplicate a file |\n\n```python\nfrom huggingface_hub import CommitOperationAdd, HfApi\n\noperations = [\n CommitOperationAdd(path_or_fileobj=\"model.bin\", path_in_repo=\"pytorch_model.bin\"),\n CommitOperationAdd(path_or_fileobj=\"config.json\", path_in_repo=\"config.json\"),\n]\n\napi = HfApi()\napi.create_commit(repo_id=\"user/model\", operations=operations, commit_message=\"Add model files\")\n```\n\n### Large Folder Upload\n\nFor repositories with many files, `_upload_large_folder.py` provides chunked upload functionality to handle:\n- Large directory structures\n- Progress tracking\n- Error recovery\n\n**资料来源：**[src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py), [src/huggingface_hub/_upload_large_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_upload_large_folder.py)\n\n---\n\n## URI Parsing System\n\nThe library supports a custom `hf://` URI protocol for referencing Hub resources:\n\n```\nhf://[/][@][/]\n```\n\n**Type Prefixes:**\n| Type | Prefix | Example |\n|------|--------|---------|\n| Model | (default) | `hf://my-org/my-model` |\n| Dataset | `datasets/` | `hf://datasets/my-org/my-dataset` |\n| Space | `spaces/` | `hf://spaces/my-org/my-space` |\n| Bucket | `bucket/` | `hf://bucket/my-path` |\n\nThe `_hf_uris.py` module parses these URIs into structured `HfUri` objects, supporting special revision formats like `refs/pr/3` for pull requests.\n\n**资料来源：**[src/huggingface_hub/utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n\n---\n\n## Authentication System\n\nThe authentication flow uses token-based authentication:\n\n```mermaid\ngraph LR\n A[User] -->|hf login| B[CLI Login]\n B --> C[Token Storage]\n C --> D[~/.cache/huggingface/token]\n D --> E[API Requests]\n E --> F[Hub API]\n F -->|Valid Token| G[Authenticated Access]\n F -->|Invalid Token| H[Error Response]\n```\n\n**Available Methods:**\n- `login()`: Authenticate via command line\n- `logout()`: Remove stored credentials\n- `notebook_login()`: Interactive login for Jupyter notebooks\n\n**资料来源：**[src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n## Package Structure\n\n### Dependencies\n\nThe library has minimal core dependencies and optional extras:\n\n**Core Dependencies:**\n```python\nfilelock>=3.13.0\nfsspec>=2023.9.0\nhuggingface_hub>=0.24.0\npackaging>=20.9\npyyaml>=5.3\nrequests>=2.32.0\ntqdm>=4.64.0\ntyping-extensions>=3.7.4.1\n```\n\n**Optional Extras:**\n| Extra | Dependencies |\n|-------|-------------|\n| `inference` | Inference client for model deployment |\n| `testing` | pytest, pytest-cov, pytest-asyncio |\n| `quality` | black, ruff |\n| `typing` | mypy, libcst |\n| `dev` | All testing + quality + typing |\n\n**资料来源：**[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n---\n\n## Entry Points\n\nThe library registers several console entry points:\n\n| Command | Module | Purpose |\n|---------|--------|---------|\n| `hf` | `huggingface_hub.cli.hf` | Main CLI |\n| `huggingface-cli` | `huggingface_hub.cli.deprecated_cli` | Legacy CLI |\n| `tiny-agents` | `huggingface_hub.inference._mcp.cli` | Agent CLI |\n| `hf` (fsspec) | `huggingface_hub.HfFileSystem` | Filesystem spec |\n\n**资料来源：**[setup.py:25-31](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L25-L31)\n\n---\n\n## Design Patterns\n\n### Public API Surface\n\nThe public API in `__init__.py` is auto-generated by `utils/check_static_imports.py`. Developers should run `make style` to update static imports after making changes.\n\n### Async Support\n\nThe library provides both synchronous and asynchronous clients:\n- `InferenceClient` - Synchronous inference operations\n- `AsyncInferenceClient` - Asynchronous inference with async/await support\n\n### Type Safety\n\nThe library uses:\n- Python type hints throughout\n- Dataclasses for structured data\n- Frozen dataclasses for immutable objects (e.g., `HfUri`)\n\n---\n\n## Summary\n\nThe `huggingface_hub` library architecture is designed around:\n\n1. **Modularity:** Each functional area (download, upload, filesystem, inference) is isolated in its own module\n2. **Extensibility:** Entry points allow integration with external systems like fsspec\n3. **Performance:** Caching, ETag validation, and LFS support optimize network usage\n4. **Usability:** High-level APIs like `ModelHubMixin` simplify common workflows\n5. **Standards:** Following Python typing standards and fsspec specifications\n\nThis architecture enables the library to serve as the foundation for Hugging Face's ecosystem integration, supporting everything from simple file downloads to complex ML workflow automation.\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Overview and Architecture](#overview), [Authentication System](#authentication)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/huggingface/huggingface_hub/blob/main/pyproject.toml)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [docs/source/en/installation.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/installation.md)\n \n\n# Installation and Setup\n\n## Overview\n\nThe `huggingface_hub` package is a Python client library that enables interaction with the Hugging Face Hub, providing functionality to download and publish models, datasets, and other repositories. This page covers all aspects of installing and setting up the library across different environments and use cases.\n\n## System Requirements\n\n### Python Version\n\n| Requirement | Version |\n|-------------|---------|\n| Minimum Python | 3.10.0 |\n| Package Manager | pip, conda |\n\n资料来源：[setup.py:52](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n### Supported Platforms\n\nThe library supports installation on all major operating systems including Linux, macOS, and Windows.\n\n## Installation Methods\n\n### Standard Installation (pip)\n\nThe primary installation method uses pip:\n\n```bash\npip install huggingface_hub\n```\n\n资料来源：[README.md:30](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Installation with Optional Dependencies\n\nThe library provides extras that install optional dependencies for specific use cases:\n\n| Extra | Description | Command |\n|-------|-------------|---------|\n| `inference` | Inference-related functionality | `pip install huggingface_hub[inference]` |\n| `mcp` | MCP (Model Context Protocol) module | `pip install huggingface_hub[mcp]` |\n\n资料来源：[README.md:36-42](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Development Installation\n\nFor contributing to the project or testing the latest features:\n\n```bash\npip install -e \".[dev]\"\n```\n\nThis installs the package in editable mode with all development dependencies.\n\n资料来源：[CONTRIBUTING.md:24-26](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)\n\n### Conda Installation\n\nFor conda environments:\n\n```bash\nconda install -c conda-forge huggingface_hub\n```\n\n资料来源：[README.md:22-24](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## Dependency Architecture\n\n```mermaid\ngraph TD\n A[huggingface_hub] --> B[Core Dependencies]\n A --> C[Optional: inference]\n A --> D[Optional: mcp]\n A --> E[Dev Dependencies]\n \n B --> B1[requests]\n B --> B2[fsspec]\n B --> B3[httpx]\n B --> B4[tqdm]\n B --> B5[packaging]\n B --> B6[filelock]\n B --> B7[pyyaml]\n \n C --> C1[inference-client]\n C --> C2[pillow]\n \n D --> D1[mcp]\n \n E --> E1[pytest]\n E --> E2[pytest-asyncio]\n E --> E3[pytest-cov]\n E --> E4[ruff]\n E --> E5[mypy]\n E --> E6[ty]\n```\n\n## Core Dependencies\n\nThe following table lists the required dependencies installed by default:\n\n| Package | Purpose |\n|---------|---------|\n| `requests` | HTTP client for API calls |\n| `fsspec` | Filesystem specification |\n| `httpx` | Async HTTP client |\n| `tqdm` | Progress bars |\n| `packaging` | Package version handling |\n| `filelock` | File locking mechanism |\n| `pyyaml` | YAML parsing |\n| `typing-extensions` | Type hint support |\n\n资料来源：[setup.py:1-16](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Optional Dependency Groups\n\n### Testing Dependencies\n\n```python\nextras[\"testing\"] = [\n \"pytest\",\n \"pytest-asyncio\",\n \"pytest-cov\",\n \"pytest-xdist\",\n \"DianaEye\",\n \"aiohttp\",\n \"asynctest\",\n \"Paramiko\",\n]\n```\n\n### Quality Assurance Dependencies\n\n```python\nextras[\"quality\"] = [\n \"ruff\",\n \"踩\",\n]\n```\n\n### Type Checking Dependencies\n\n```python\nextras[\"typing\"] = [\n \"mypy==1.15.0\",\n \"libcst>=1.4.0\",\n \"ty\",\n]\n```\n\n### All-Inclusive Meta-Group\n\n```python\nextras[\"all\"] = extras[\"testing\"] + extras[\"quality\"] + extras[\"typing\"]\nextras[\"dev\"] = extras[\"all\"]\n```\n\n资料来源：[setup.py:36-51](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Installation Workflow\n\n```mermaid\ngraph TD\n A[Start Installation] --> B{Installation Method}\n \n B -->|pip| C[Basic Install]\n B -->|conda| D[Conda Forge Install]\n B -->|editable| E[Development Install]\n \n C --> F{Use Case}\n F -->|Minimal| G[Core Only]\n F -->|Inference| H[Add inference extra]\n F -->|MCP| I[Add mcp extra]\n \n G --> J[Installation Complete]\n H --> J\n I --> J\n \n D --> J\n E --> J\n \n J --> K[Verify Installation]\n K --> L[Import huggingface_hub]\n```\n\n## Verification\n\nAfter installation, verify the package is correctly installed:\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# Test basic functionality\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n```\n\n资料来源：[README.md:48-52](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## Post-Installation Configuration\n\n### Authentication Setup\n\nTo authenticate with the Hugging Face Hub:\n\n```bash\n# Interactive login\nhf auth login\n\n# Non-interactive with token\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n资料来源：[README.md:61-65](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### Cache Configuration\n\nFiles are downloaded to a local cache folder. See the [cache management guide](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache) for configuration options.\n\n## Entry Points\n\nThe installation registers the following console scripts:\n\n| Command | Module | Purpose |\n|---------|--------|---------|\n| `hf` | `huggingface_hub.cli.hf` | Main CLI interface |\n| `huggingface-cli` | `huggingface_hub.cli.deprecated_cli` | Legacy CLI (deprecated) |\n| `tiny-agents` | `huggingface_hub.inference._mcp.cli` | MCP CLI application |\n| `hf` (fsspec) | `huggingface_hub.HfFileSystem` | Filesystem specification |\n\n资料来源：[setup.py:53-60](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| ImportError | Ensure Python >= 3.10 |\n| Authentication failed | Run `hf auth login` |\n| Download timeout | Check network connection |\n| Permission denied | Use virtual environment |\n\n### Development Setup Issues\n\nIf installing in development mode:\n\n```bash\npip uninstall huggingface_hub\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md:24](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Name | `huggingface_hub` |\n| License | Apache-2.0 |\n| Author | Hugging Face, Inc. |\n| Author Email | julien@huggingface.co |\n| URL | https://github.com/huggingface/huggingface_hub |\n\n资料来源：[setup.py:18-22](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[Installation and Setup](#installation), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n- [src/huggingface_hub/_oauth.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py)\n- [src/huggingface_hub/utils/_auth.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_auth.py)\n- [src/huggingface_hub/utils/_git_credential.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_git_credential.py)\n \n\n# Authentication System\n\n## Overview\n\nThe `huggingface_hub` library provides a comprehensive authentication system that enables secure access to Hugging Face Hub resources including models, datasets, and Spaces. The authentication system supports multiple authentication methods including token-based authentication and OAuth 2.0, with seamless integration into both CLI environments and Jupyter notebooks.\n\nThe authentication infrastructure consists of four primary modules that handle different aspects of the authentication lifecycle:\n\n| Module | Purpose |\n|--------|---------|\n| `_login.py` | User login operations and token management |\n| `_oauth.py` | OAuth 2.0 authentication flow |\n| `_auth.py` | Core authentication utilities and token refresh |\n| `_git_credential.py` | Git credential handling for repository operations |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User] --> B[Login Methods]\n B --> C[Token-based Auth]\n B --> D[OAuth 2.0 Auth]\n C --> E[hf_hub_download]\n C --> F[upload_file]\n D --> E\n D --> F\n E --> G[Token Cache]\n F --> G\n G --> H[Hugging Face Hub API]\n H --> I[Model/Dataset/Space]\n \n C --> J[CLI: hf auth login]\n C --> K[Python: login function]\n C --> L[Notebook: notebook_login]\n```\n\n## Token-Based Authentication\n\n### Login Functionality\n\nThe library provides three primary interfaces for user authentication:\n\n#### CLI Login\n\nUsers can authenticate via the command-line interface using the `hf` command:\n\n```bash\nhf auth login\n# or with environment variable\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n#### Python API Login\n\nThe `login()` function provides programmatic authentication within Python scripts:\n\n```python\nfrom huggingface_hub import login\n\n# Direct token login\nlogin(token=\"hf_xxxxx\")\n\n# Using environment variable\nlogin()\n```\n\n#### Notebook Login Widget\n\nFor Jupyter notebook environments, `notebook_login()` displays an interactive widget for token entry:\n\n```python\nfrom huggingface_hub import notebook_login\n\nnotebook_login()\n```\n\nThe notebook login function accepts the following parameters:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `skip_if_logged_in` | `bool` | `True` | Skip prompt if user already logged in |\n\n```python\n# Force re-login even if already authenticated\nnotebook_login(skip_if_logged_in=False)\n```\n\n### Token Storage and Management\n\nTokens are securely stored in the local configuration directory. The system automatically retrieves stored tokens when making API requests, eliminating the need for repeated authentication. Token validation occurs automatically before any authenticated operation, ensuring expired or invalid tokens are detected early.\n\n## OAuth 2.0 Authentication\n\nThe OAuth 2.0 authentication flow provides an alternative to token-based authentication, enabling more sophisticated authorization scenarios. This is particularly useful for applications that need to access resources on behalf of users with specific permission scopes.\n\nOAuth tokens are automatically refreshed when they expire, maintaining continuous access without requiring user intervention. The system handles token revocation and supports scopes that limit access to specific resources or operations.\n\n## Git Credential Integration\n\nThe authentication system integrates with Git's credential infrastructure to provide seamless authentication for Git operations such as cloning and pushing to repositories. This integration ensures that Git operations respect the same authentication state as the Python API.\n\n```mermaid\ngraph LR\n A[Git Operation] --> B[Git Credential Helper]\n B --> C{huggingface_hub _git_credential}\n C --> D{Cached Token?}\n D -->|Yes| E[Use Cached Token]\n D -->|No| F[Prompt for Token]\n E --> G[Execute Git Operation]\n F --> G\n```\n\nThe Git credential helper manages:\n- Secure storage of credentials\n- Credential retrieval for specific hosts\n- Credential cleanup after operations\n\n## Authentication Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Application\n participant AuthSystem\n participant HubAPI\n participant TokenStore\n\n User->>Application: Initiate request\n Application->>AuthSystem: Authenticate\n AuthSystem->>TokenStore: Check stored token\n TokenStore-->>AuthSystem: Token found\n AuthSystem->>HubAPI: Authenticated request\n HubAPI-->>Application: Response\n Note over AuthSystem,TokenStore: Token expired or invalid\n AuthSystem->>AuthSystem: Refresh token\n AuthSystem->>TokenStore: Update token\n AuthSystem->>HubAPI: Retry with new token\n```\n\n## Configuration\n\nAuthentication behavior can be configured through environment variables and configuration files:\n\n| Variable | Description |\n|----------|-------------|\n| `HUGGINGFACE_TOKEN` | Default authentication token |\n| `HF_HOME` | Configuration directory location |\n| `HF_TOKEN` | Alternative token environment variable |\n\n## Security Considerations\n\nThe authentication system implements several security best practices:\n\n1. **Secure Token Storage**: Tokens are stored with appropriate file permissions to prevent unauthorized access\n2. **Token Validation**: All tokens are validated before use in API requests\n3. **Automatic Refresh**: OAuth tokens are automatically refreshed to maintain session continuity\n4. **Notebook Security Warning**: The `notebook_login` widget displays a warning about token exposure in notebook files\n\n## Related Components\n\nThe authentication system interacts with several other library components:\n\n| Component | Interaction |\n|-----------|-------------|\n| `InferenceClient` | Uses authentication for inference API calls |\n| `HfFileSystem` | Uses authentication for file system operations |\n| `snapshot_download` | Uses authentication for repository downloads |\n| `upload_file` | Uses authentication for repository uploads |\n\n## Quick Reference\n\n```python\n# CLI\nhf auth login --token hf_xxxxx\n\n# Python script\nfrom huggingface_hub import login\nlogin(token=\"hf_xxxxx\")\n\n# Jupyter notebook\nfrom huggingface_hub import notebook_login\nnotebook_login()\n\n# Check if logged in\nfrom huggingface_hub import whoami\nuser = whoami()\n\n---\n\n\n\n## File Download Operations\n\n### 相关页面\n\n相关主题：[Cache Management System](#cache-management), [Git LFS Large File Handling](#lfs-handling), [Overview and Architecture](#overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n- [src/huggingface_hub/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n- [src/huggingface_hub/_snapshot_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_snapshot_download.py)\n- [src/huggingface_hub/cli/download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/download.py)\n- [src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n- [src/huggingface_hub/errors.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py)\n \n\n# File Download Operations\n\nThe `huggingface_hub` library provides a comprehensive file download system that enables clients to fetch models, datasets, and other artifacts from the Hugging Face Hub. This document covers the architecture, API, caching mechanisms, and usage patterns for download operations.\n\n## Overview\n\nFile download operations in `huggingface_hub` handle the retrieval of individual files or entire repository snapshots from Hugging Face's infrastructure. The system implements intelligent caching, supports offline mode, provides progress tracking, and handles authentication seamlessly.\n\n**Key responsibilities:**\n\n- Download files with proper caching and deduplication\n- Support partial content retrieval for LFS (Large File Storage) files\n- Manage metadata for cache validation and freshness checks\n- Handle authentication tokens transparently\n- Support offline scenarios with local-only file access\n- Provide dry-run capabilities for previewing downloads\n\n资料来源：[src/huggingface_hub/file_download.py:1-100]()\n\n## Architecture\n\n### Component Overview\n\n```mermaid\ngraph TD\n A[Public API: hf_hub_download] --> B[Route Decision]\n B --> C{single file?}\n C -->|Yes| D[_hf_hub_download_to_cache_dir]\n C -->|No| E[snapshot_download]\n \n D --> F[Get Metadata / ETag]\n F --> G{Cached?}\n G -->|Yes, valid| H[Return cached path]\n G -->|No| I[Download from remote]\n I --> J[Write metadata]\n J --> H\n \n E --> K[Iterate files]\n K --> L[Download each file]\n L --> F\n \n H --> M[Local file path]\n I --> M\n```\n\n### Module Structure\n\n| Module | Purpose |\n|--------|---------|\n| `file_download.py` | Core download functions (`hf_hub_download`, `_hf_hub_download_to_cache_dir`) |\n| `_local_folder.py` | Local cache and metadata management |\n| `_snapshot_download.py` | Full repository snapshot downloads |\n| `cli/download.py` | Command-line interface for downloads |\n| `errors.py` | Exception hierarchy for download failures |\n\n资料来源：[src/huggingface_hub/file_download.py:1-50]()\n\n## Core API Functions\n\n### hf_hub_download\n\nThe primary function for downloading a single file from the Hub.\n\n```python\nfrom huggingface_hub import hf_hub_download\n\npath = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n repo_type=\"model\",\n revision=\"main\",\n cache_dir=\"./hf_cache\",\n token=True,\n)\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | `str` | Required | Repository identifier (e.g., \"bert-base-cased\") |\n| `filename` | `str` | Required | Path to the file within the repository |\n| `repo_type` | `str` | `\"model\"` | Type of repository: \"model\", \"dataset\", or \"space\" |\n| `revision` | `str` | `\"main\"` | Git revision (branch, tag, or commit hash) |\n| `cache_dir` | `str \\| Path` | `None` | Custom cache directory location |\n| `local_dir` | `str \\| Path` | `None` | Directory to place the file without caching structure |\n| `force_download` | `bool` | `False` | Force re-download even if cached |\n| `local_files_only` | `bool` | `False` | Only return local files, fail if not cached |\n| `token` | `str \\| bool` | `None` | Authentication token (`True` reads from config) |\n| `etag_timeout` | `float` | `10` | Timeout in seconds for ETag fetch |\n| `tqdm_class` | `type` | `None` | Custom tqdm class for progress bars |\n\n资料来源：[src/huggingface_hub/file_download.py:100-200]()\n\n### snapshot_download\n\nDownloads an entire repository to a local cache.\n\n```python\nfrom huggingface_hub import snapshot_download\n\nlocal_path = snapshot_download(\n repo_id=\"stabilityai/stable-diffusion-2-1\",\n repo_type=\"model\",\n cache_dir=\"./models\",\n ignore_patterns=[\"*.md\", \".gitattributes\"],\n)\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | `str` | Required | Repository identifier |\n| `repo_type` | `str` | `\"model\"` | Type of repository |\n| `revision` | `str` | `None` | Git revision to download |\n| `cache_dir` | `str \\| Path` | `None` | Cache directory location |\n| `local_dir` | `str \\| Path` | `None` | Mirror directory without cache structure |\n| `allow_patterns` | `list[str]` | `None` | Glob patterns to include |\n| `ignore_patterns` | `list[str]` | `None` | Glob patterns to exclude |\n| `force_download` | `bool` | `False` | Force re-download of all files |\n| `local_files_only` | `bool` | `False` | Only use local cache |\n| `token` | `str \\| bool` | `None` | Authentication token |\n\n资料来源：[src/huggingface_hub/_snapshot_download.py:1-150]()\n\n## Caching Mechanism\n\n### Cache Directory Structure\n\n```\ncache_dir/\n├── .locks/ # Lock files for concurrent access\n│ └── {repo_id}/\n│ └── {filename}.lock\n└── {repo_type}s/\n └── {namespace}/\n └── {repo_name}/\n ├── .cache/ # Metadata\n │ └── huggingface/\n │ └── info/\n │ └── files/ # Download metadata\n ├── {revision}/\n │ └── {filename} # Actual downloaded files\n └── refs/\n └── {branch} # Git references\n```\n\n### Download Metadata\n\nMetadata is stored alongside cached files to track freshness:\n\n```python\n# Stored in: {cache_dir}/.cache/huggingface/info/files/{filename}\n{commit_hash}\n{etag}\n{timestamp}\n```\n\nThe system validates cached files by:\n\n1. Comparing local ETag with remote ETag\n2. Checking commit hash consistency\n3. Verifying file modification timestamps\n\n资料来源：[src/huggingface_hub/_local_folder.py:50-120]()\n\n### Lock File Management\n\nThe library uses `WeakFileLock` to handle concurrent downloads safely:\n\n```python\nlocks_dir = os.path.join(cache_dir, \".locks\")\nstorage_folder = os.path.join(cache_dir, repo_folder_name(...))\npaths = RepoFileDownloadPaths(...)\n# Lock acquired before writing to cache\nwith WeakFileLock(paths.lock_path):\n # Critical section: write file or metadata\n```\n\n资料来源：[src/huggingface_hub/file_download.py:300-350]()\n\n## Download Workflow\n\n### Sequence Diagram\n\n```mermaid\nsequenceDiagram\n participant Client\n participant hf_hub_download\n participant Cache\n participant Server\n participant Metadata\n\n Client->>hf_hub_download: Call with repo_id, filename\n hf_hub_download->>Cache: Check cached file + metadata\n Cache-->>hf_hub_download: metadata (if exists)\n \n alt Cached file exists\n hf_hub_download->>Metadata: Validate ETag\n Metadata-->>hf_hub_download: is_valid\n alt Valid ETag\n hf_hub_download-->>Client: Return cached path\n else Invalid ETag\n hf_hub_download->>Server: HEAD request for ETag\n end\n else No cache\n hf_hub_download->>Server: HEAD request for ETag\n end\n \n Server-->>hf_hub_download: ETag, commit_hash, size\n hf_hub_download->>Cache: Check if file exists\n \n alt File not in cache\n hf_hub_download->>Server: GET request\n Server-->>hf_hub_download: File content\n hf_hub_download->>Cache: Write file + metadata\n end\n \n hf_hub_download-->>Client: Return file path\n```\n\n### ETag Validation Process\n\nThe download system implements a three-tier validation strategy:\n\n1. **ETag Match**: Compare server ETag with local metadata\n2. **SHA256 Hash**: For LFS files, compute and compare SHA256\n3. **Timestamp Check**: Verify file hasn't been modified since metadata save\n\n```python\n# ETag-based validation\nif local_metadata is not None and local_metadata.etag == etag:\n write_download_metadata(...)\n return str(paths.file_path)\n\n# SHA256-based validation (for LFS files)\nif local_metadata is None and REGEX_SHA256.match(etag) is not None:\n with open(paths.file_path, \"rb\") as f:\n file_hash = sha_fileobj(f).hex()\n if file_hash == etag:\n write_download_metadata(...)\n return str(paths.file_path)\n```\n\n资料来源：[src/huggingface_hub/file_download.py:400-480]()\n\n## Error Handling\n\n### Exception Hierarchy\n\n```mermaid\ngraph TD\n A[Exception]\n A --> B[HfHubHTTPError]\n B --> C[RevisionNotFoundError]\n B --> D[EntryNotFoundError]\n B --> E[LocalEntryNotFoundError]\n D --> F[RemoteEntryNotFoundError]\n \n A --> G[EntryNotFoundError]\n G --> H[LocalEntryNotFoundError]\n```\n\n### Common Errors\n\n| Exception | Trigger Condition |\n|-----------|-------------------|\n| `RevisionNotFoundError` | Invalid Git revision (branch, tag, commit) |\n| `RemoteEntryNotFoundError` | File not found on remote server |\n| `LocalEntryNotFoundError` | File not in cache with `local_files_only=True` |\n| `HfHubHTTPError` | Generic HTTP errors (401, 403, 404, 500, etc.) |\n\n```python\n# Example: Handling download errors\ntry:\n path = hf_hub_download('bert-base-cased', 'config.json')\nexcept RevisionNotFoundError as e:\n print(f\"Revision not found: {e}\")\nexcept RemoteEntryNotFoundError as e:\n print(f\"File not on server: {e}\")\nexcept LocalEntryNotFoundError as e:\n print(\"File not in cache. Set local_files_only=True and cache it first.\")\n```\n\n资料来源：[src/huggingface_hub/errors.py:100-180]()\n\n## Command-Line Interface\n\n### CLI Download Command\n\nThe `huggingface-cli` tool provides download functionality:\n\n```bash\n# Download single file\nhuggingface-cli download bert-base-cased config.json\n\n# Download entire repo\nhuggingface-cli download stabilityai/stable-diffusion-2-1\n\n# With patterns\nhuggingface-cli download meta-llama/Llama-2-7b --include \"*.safetensors\"\n\n# Dry run\nhuggingface-cli download bigscience/bloom-7b1 --dry-run\n```\n\n### CLI Implementation\n\nThe CLI wraps the core download functions and adds:\n\n- Pretty-printed output formatting\n- Dry-run mode for previewing downloads\n- Pattern-based file selection\n- Progress indication\n\n```python\n# From cli/download.py\ndef run(self):\n if len(regular_filenames) == 1:\n # Single file: use hf_hub_download\n return hf_hub_download(\n repo_id=repo_id,\n filename=regular_filenames[0],\n ...\n )\n else:\n # Multiple files or patterns: use snapshot_download\n return snapshot_download(\n repo_id=repo_id,\n allow_patterns=allow_patterns,\n ...\n )\n```\n\n资料来源：[src/huggingface_hub/cli/download.py:50-120]()\n\n## Advanced Usage\n\n### Dry Run Mode\n\nPreview what would be downloaded without actually downloading:\n\n```python\nfrom huggingface_hub import hf_hub_download, DryRunFileInfo\n\nresult = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n dry_run=True,\n)\n\nif isinstance(result, DryRunFileInfo):\n print(f\"Will download: {result.filename}\")\n print(f\"Size: {result.file_size} bytes\")\n print(f\"Cached: {result.is_cached}\")\n print(f\"Commit: {result.commit_hash}\")\n```\n\n### Progress Tracking\n\nCustomize progress bar behavior:\n\n```python\nfrom tqdm import tqdm\nfrom huggingface_hub import hf_hub_download\n\nclass CustomProgress(tqdm):\n def set_postfix(self, **kwargs):\n self.set_postfix_str(f\"ETA: {kwargs.get('eta', 'N/A')}\")\n\nhf_hub_download(\n repo_id=\"bigscience/bloom-7b1\",\n filename=\"pytorch_model.bin\",\n tqdm_class=CustomProgress,\n)\n```\n\n### Offline Mode\n\nWork exclusively with cached files:\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# Will fail if file not cached\npath = hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n local_files_only=True,\n)\n```\n\n资料来源：[src/huggingface_hub/file_download.py:450-500]()\n\n## Repository Types\n\nThe download system supports multiple repository types:\n\n| Repo Type | Description | Typical Contents |\n|-----------|-------------|------------------|\n| `model` | Model repositories | PyTorch/TensorFlow models, configs, tokenizer files |\n| `dataset` | Dataset repositories | Data files, dataset card, scripts |\n| `space` | Gradio Spaces | Application code, models, requirements |\n\nRepository types affect URL construction:\n\n```python\n# URL prefixes from constants\nREPO_TYPES_URL_PREFIXES = {\n \"model\": \"\",\n \"dataset\": \"datasets/\",\n \"space\": \"spaces/\",\n}\n```\n\n资料来源：[src/huggingface_hub/lfs.py:30-60]()\n\n## Best Practices\n\n1. **Use caching**: Files are cached automatically; reuse cached files for subsequent runs\n2. **Specify revisions**: Pin specific commits for reproducible downloads\n3. **Handle authentication**: Use `token=True` to auto-read from config, or pass explicit tokens\n4. **Prefer single file downloads**: Use `hf_hub_download` for specific files instead of full snapshots\n5. **Use patterns wisely**: Combine `allow_patterns` and `ignore_patterns` for selective downloads\n\n## Summary\n\nThe file download system in `huggingface_hub` provides a robust, cached, and authenticated mechanism for retrieving files from the Hugging Face Hub. Key functions include:\n\n- `hf_hub_download`: Single file downloads with full validation\n- `snapshot_download`: Complete repository downloads with pattern filtering\n- CLI integration via `huggingface-cli download`\n\nThe system handles caching, metadata validation, concurrent access, and error recovery transparently, making it suitable for production workloads requiring reliable artifact retrieval.\n\n---\n\n\n\n## File Upload Operations\n\n### 相关页面\n\n相关主题：[Git LFS Large File Handling](#lfs-handling), [File Download Operations](#file-download), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/lfs.py)\n- [src/huggingface_hub/_upload_large_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_upload_large_folder.py)\n- [src/huggingface_hub/_local_folder.py](https://github.com/huggingface/hub-mixin/blob/main/src/huggingface_hub/_local_folder.py)\n- [docs/source/en/guides/upload.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/upload.md)\n \n\n# File Upload Operations\n\n## Overview\n\nFile upload operations in `huggingface_hub` enable developers to publish and manage files on the Hugging Face Hub. The library provides a comprehensive set of tools for uploading individual files, entire folders, and handling large files through Git Large File Storage (LFS) integration.\n\nThe upload system is built on top of the Hub's git-based infrastructure, ensuring file versioning and integrity for all uploaded content. This architecture supports repositories of type `model`, `dataset`, and `space`. 资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User Code] --> B[upload_file / upload_folder]\n B --> C[CommitOperation Classes]\n C --> D{Hub API}\n D --> E[Regular Files
Direct Upload]\n D --> F[Large Files
LFS Required]\n F --> G[lfs.py
Batch Operations]\n G --> H[LFS Server]\n E --> I[Regular Git Server]\n H --> I\n```\n\n## Core Components\n\n### CommitOperation Classes\n\nThe foundation of all upload operations is built on three operation classes defined in `_commit_api.py`:\n\n| Class | Purpose | Key Attributes |\n|-------|--------|----------------|\n| `CommitOperationAdd` | Add a file to a commit | `path_or_fileobj`, `path_in_repo`, `rethrow` |\n| `CommitOperationDelete` | Delete a file from a repository | `path_in_repo` |\n| `CommitOperationCopy` | Copy a file within a repository | `src_path_in_repo`, `path_in_repo` |\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n### CommitOperationAdd Details\n\n```python\nclass CommitOperationAdd:\n def __init__(\n self,\n path_or_fileobj: Union[str, Path, bytes, BinaryIO],\n path_in_repo: str,\n *,\n rfilename: Optional[str] = None,\n rethrow: bool = True,\n upload_info: Optional[\"CommitOperationAdd.UploadInfo\"] = None,\n ):\n```\n\nThe `CommitOperationAdd` class supports multiple input types:\n\n| Input Type | Behavior |\n|------------|----------|\n| `str` / `Path` | File path - reads file content for upload |\n| `bytes` | Raw byte content |\n| `BinaryIO` | File-like object with `read()` method |\n\nThe class provides an `as_file()` method for iterating over file content with optional progress bar support:\n\n```python\ndef as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]:\n if isinstance(self.path_or_fileobj, str) or isinstance(self.path_or_fileobj, Path):\n if with_tqdm:\n with tqdm_stream_file(self.path_or_fileobj) as file:\n yield file\n else:\n with open(self.path_or_fileobj, \"rb\") as file:\n yield file\n elif isinstance(self.path_or_fileobj, bytes):\n yield io.BytesIO(self.path_or_fileobj)\n elif isinstance(self.path_or_fileobj, io.BufferedIOBase):\n prev_pos = self.path_or_fileobj.tell()\n yield self.path_or_fileobj\n self.path_or_fileobj.seek(prev_pos, io.SEEK_SET)\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py:200-280]()\n\n## Upload Functions\n\n### upload_file\n\nUploads a single file to a repository on the Hub.\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/home/lysandre/dummy-test/README.md\",\n path_in_repo=\"README.md\",\n repo_id=\"lysandre/test-model\",\n)\n```\n\n资料来源：[README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n### upload_folder\n\nUploads an entire folder to a repository. Handles nested directory structures and file filtering.\n\n```python\nfrom huggingface_hub import upload_folder\n\nupload_folder(\n folder_path=\"/path/to/local/space\",\n repo_id=\"username/my-cool-space\",\n repo_type=\"space\",\n)\n```\n\n资料来源：[README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md)\n\n## LFS Integration\n\n### Git LFS Overview\n\nLarge files (typically files larger than 10MB) are handled through Git LFS. The library provides batch upload utilities in `lfs.py` for efficient LFS operations.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Hub API\n participant LFS Server\n \n Client->>Hub API: POST /lfs/objects/batch\n Note over Hub API: Check file sizes\n Hub API->>Client: Upload instructions\n alt Large Files\n Client->>LFS Server: Upload LFS objects\n LFS Server-->>Client: Success\n end\n Client->>Hub API: Complete commit\n Hub API-->>Client: Commit SHA\n```\n\n### LFS Batch Upload Process\n\nThe `lfs.py` module provides `upload_files_lfs_instances()` which handles the LFS batch protocol:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `commit_operations` | List[CommitOperationAdd] | Files to upload |\n| `repo_type` | str | Repository type: \"model\", \"dataset\", \"space\" |\n| `repo_id` | str | Repository identifier |\n| `revision` | str | Git revision (default: \"main\") |\n| `endpoint` | str | API endpoint URL |\n| `transfer_adapters` | List[str] | Transfer methods: \"basic\", \"multipart\", \"xet\" |\n\n资料来源：[src/huggingface_hub/lfs.py:50-150]()\n\n### LFS Batch Info Response\n\nThe `LfsBatchInfo` dataclass contains three elements:\n\n```python\n@dataclass\nclass LfsBatchInfo:\n instructions: List[\"LfsUploadInfo\"]\n errors: List[\"LfsError\"]\n transfer_mode: \"TransferMethod\"\n```\n\nThe upload process automatically determines which files require LFS handling based on file size thresholds configured by the Hub.\n\n## Large Folder Upload\n\nFor repositories with many files or very large folder structures, `_upload_large_folder.py` provides chunked upload capabilities:\n\n```python\n# Internal chunked upload for large repositories\nupload_folder(\n folder_path=\"/path/to/large/repo\",\n repo_id=\"user/large-model\",\n allow_patterns=[\"*.bin\", \"*.safetensors\", \"config.json\"],\n ignore_patterns=[\"*.git*\", \"__pycache__/*\"],\n)\n```\n\n资料来源：[src/huggingface_hub/_upload_large_folder.py]()\n\n## Upload Workflow\n\n```mermaid\ngraph TD\n A[Start Upload] --> B{File Size Check}\n B -->|Small File| C[Direct Git Upload]\n B -->|Large File| D[LFS Upload Required]\n C --> E[Create Commit]\n D --> F[Batch Request to LFS]\n F --> G[Get Upload Instructions]\n G --> H[Upload to LFS Server]\n H --> E\n E --> I[Commit to Hub]\n I --> J[Return Commit SHA]\n```\n\n## Configuration Options\n\n### Repository Types\n\n| Type | Description | Typical Use |\n|------|-------------|-------------|\n| `model` | Model repositories | Trained weights, configs |\n| `dataset` | Dataset repositories | Data files, metadata |\n| `space` | Space repositories | Demo applications |\n\n### Common Parameters\n\n| Parameter | Required | Default | Description |\n|-----------|----------|---------|-------------|\n| `repo_id` | Yes | - | Namespace/repo name |\n| `repo_type` | No | \"model\" | Type of repository |\n| `revision` | No | \"main\" | Git branch/tag |\n| `token` | No | None | HF token for auth |\n| `create_pr` | No | False | Create PR instead of commit |\n\n## Error Handling\n\n### CommitOperationAdd Error Handling\n\nThe `rethrow` parameter controls error behavior:\n\n```python\n# Default: raises exception on failure\noperation = CommitOperationAdd(path_or_fileobj=\"file.bin\", path_in_repo=\"model.bin\")\n\n# With error suppression\noperation = CommitOperationAdd(path_or_fileobj=\"file.bin\", path_in_repo=\"model.bin\", rethrow=False)\n```\n\n### Upload Errors\n\n| Error Type | Cause | Resolution |\n|------------|-------|------------|\n| `HfHubHTTPError` | Server rejection | Check token permissions |\n| `ValueError` | Invalid parameters | Validate repo_id, path_in_repo |\n| `LocalUploadNotImplementedError` | Unsupported local upload | Use file path instead |\n\n## Best Practices\n\n1. **Use `upload_folder`** for multiple files to ensure atomic commits\n2. **Token Authentication**: Always authenticate before uploading private repositories\n3. **File Filtering**: Use `allow_patterns` and `ignore_patterns` for large repos\n4. **Progress Tracking**: Enable tqdm for long uploads\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\napi.upload_folder(\n folder_path=\"./model\",\n repo_id=\"username/my-model\",\n repo_type=\"model\",\n token=True, # Prompt for token if needed\n)\n```\n\n## Related Documentation\n\n- [Upload Guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload) - Detailed upload instructions\n- [Repository Management](https://huggingface.co/docs/huggingface_hub/main/en/guides/repository) - Repository operations\n- [Manage Cache](https://huggingface.co/docs/huggingface_hub/main/en/guides/manage-cache) - Cache configuration\n\n## Module Structure Summary\n\n| File | Responsibility |\n|------|----------------|\n| `_commit_api.py` | Core commit operations and operation classes |\n| `_upload_large_folder.py` | Chunked folder uploads |\n| `lfs.py` | Git LFS batch upload protocol implementation |\n| `_local_folder.py` | Local folder scanning and filtering |\n| `hf_api.py` | High-level HfApi methods for upload |\n\n---\n\n\n\n## Git LFS Large File Handling\n\n### 相关页面\n\n相关主题：[File Upload Operations](#file-upload), [File Download Operations](#file-download)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/lfs.py)\n- [src/huggingface_hub/utils/_lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_lfs.py)\n- [docs/source/en/concepts/git_vs_http.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/concepts/git_vs_http.md)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n \n\n# Git LFS Large File Handling\n\n## Overview\n\nGit LFS (Large File Storage) is a Git extension that handles large files by storing binary content outside the Git repository while maintaining a lightweight pointer file within it. The `huggingface_hub` library implements comprehensive LFS support to manage large model weights, datasets, and other binary assets on the Hugging Face Hub.\n\nIn the huggingface_hub ecosystem, LFS files are distinguished from regular Git-tracked files through their content addressing:\n\n| File Type | Storage Method | Identifier | Location in Cache |\n|-----------|---------------|------------|-------------------|\n| Regular Git Blob | Git commit SHA | 40-char hex string | `blobs/` |\n| LFS File | SHA256 hash | 64-char hex string | `blobs/` |\n\n资料来源：[src/huggingface_hub/lfs.py:1-50]()\n\n## Architecture\n\n### Cache Directory Structure\n\nWhen files are downloaded from the Hub, they are stored in a hierarchical cache structure:\n\n```mermaid\ngraph TD\n A[\"Cache Root
~/.cache/huggingface/hub/\"] --> B[\"models--{repo_id}\"]\n A --> C[\"datasets--{repo_id}\"]\n A --> D[\"spaces--{repo_id}\"]\n \n B --> E[\"blobs/\"]\n B --> F[\"refs/\"]\n B --> G[\"snapshots/\"]\n \n E --> H[\"git-sha
40-char\"]\n E --> I[\"sha256
64-char (LFS)\"]\n \n G --> J[\"{commit_hash}/\"]\n J --> K[\"filename → symlink → blob\"]\n```\n\n资料来源：[src/huggingface_hub/file_download.py:1-30]()\n\n### LFS Upload Workflow\n\nThe upload process follows a batch-oriented approach using the LFS Batch API:\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Hub as HF Hub API\n participant LFS as LFS Server\n \n Client->>Hub: POST /{repo_type}/{repo_id}.git/info/lfs/objects/batch\n Note over Hub,LFS: Batch request includes
upload instructions request\n Hub->>LFS: Check upload eligibility\n LFS-->>Hub: Upload instructions (presigned URLs)\n Hub-->>Client: LfsBatchInfo with actions\n \n alt basic/multipart transfer\n Client->>LFS: PUT file content directly\n LFS-->>Client: 200 OK\n else xet transfer\n Client->>Hub: Use custom xet protocol\n end\n \n Client->>Hub: POST /{repo_type}/{repo_id}.git/info/lfs/objects/batch\n Note over Client: Confirm upload completion\n Hub->>LFS: Verify file content\n LFS-->>Hub: Verification result\n Hub-->>Client: Commit ready\n```\n\n资料来源：[src/huggingface_hub/lfs.py:60-120]()\n\n## Core Components\n\n### LFS Module (`src/huggingface_hub/lfs.py`)\n\nThe main LFS module provides type definitions and utilities for handling LFS operations.\n\n#### Constants\n\n| Constant | Value | Purpose |\n|----------|-------|---------|\n| `LFS_MULTIPART_UPLOAD_COMMAND` | `\"lfs-multipart-upload\"` | Identifier for multipart upload operations |\n| `OID_REGEX` | `^[0-9a-f]{40}$` | Pattern for validating Git object identifiers |\n| `LFS_HEADERS` | Dict | Accept and content type headers for LFS API |\n\n资料来源：[src/huggingface_hub/lfs.py:40-55]()\n\n#### LFS Headers\n\n```python\nLFS_HEADERS = {\n \"Accept\": \"application/vnd.git-lfs+json\",\n \"Content-Type\": \"application/vnd.git-lfs+json\",\n}\n```\n\nThese headers indicate that all LFS API communications use JSON with the `vnd.git-lfs+json` media type, following the LFS specification.\n\n资料来源：[src/huggingface_hub/lfs.py:50-55]()\n\n### LFS Utilities (`src/huggingface_hub/utils/_lfs.py`)\n\nUtility functions for LFS operations include:\n\n| Function | Purpose |\n|----------|---------|\n| `SliceFileObj` | Context manager for slicing file objects during multipart uploads |\n| SHA utilities | Calculate SHA256 for LFS file content verification |\n| Content range handling | Manage byte ranges for resumable uploads |\n\n资料来源：[src/huggingface_hub/utils/_lfs.py]()\n\n## API Reference\n\n### LfsBatchInfo\n\nThe `LfsBatchInfo` dataclass encapsulates the server response from the LFS Batch API:\n\n```python\n@dataclass\nclass LfsBatchInfo:\n \"\"\"Information returned by the LFS batch API.\"\"\"\n \n actions: dict\n \"\"\"Dictionary of available actions (upload, verify).\"\"\"\n \n objects: list[dict]\n \"\"\"List of objects with their metadata.\"\"\"\n \n transfers: list[str]\n \"\"\"Supported transfer adapters (e.g., 'basic', 'multipart', 'xet').\"\"\"\n```\n\n资料来源：[src/huggingface_hub/lfs.py:55-80]()\n\n### Upload Information Classes\n\nThe library uses dataclasses to represent different types of upload information:\n\n| Class | Inheritance | Purpose |\n|-------|-------------|---------|\n| `UploadInfo` | Base | Abstract base for all upload info types |\n| `LfsUploadFileInfo` | `UploadInfo` | Standard LFS file upload with size and SHA256 |\n| `LfsUploadTtHubInfo` | `UploadInfo` | TtHub-specific upload info |\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n## Transfer Adapters\n\nThe Hugging Face Hub supports multiple LFS transfer methods, negotiated during the batch API handshake:\n\n### Supported Transfer Methods\n\n| Transfer Method | Description | Use Case |\n|-----------------|-------------|----------|\n| `basic` | Direct HTTP PUT upload | Small to medium files |\n| `multipart` | Chunked upload for very large files | Files > 100MB |\n| `xet` | Custom xet protocol for optimized transfers | High-performance scenarios |\n\n资料来源：[src/huggingface_hub/lfs.py:60-100]()\n\n### Transfer Method Selection\n\nThe client sends supported transfer methods in the batch request:\n\n```python\npayload: dict = {\n \"operation\": \"upload\",\n \"transfers\": transfers if transfers is not None else [\"basic\", \"multipart\"],\n ...\n}\n```\n\nThe server responds with the transfer adapter it will use, which the client then employs for the actual upload.\n\n资料来源：[src/huggingface_hub/lfs.py:85-95]()\n\n## Large File Identification\n\n### Size Thresholds\n\nFiles are treated as LFS content when they exceed certain thresholds:\n\n| Threshold | Action |\n|-----------|--------|\n| < 5MB | Stored as regular Git blob |\n| >= 5MB | Redirected to LFS storage |\n\n### OID (Object Identifier) Format\n\nLFS files are identified by their SHA256 hash, represented as a 64-character hexadecimal string:\n\n```\nPattern: ^[0-9a-f]{64}$\nExample: 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd\n```\n\nRegular Git blobs use 40-character SHA1 identifiers, while LFS files use 64-character SHA256 identifiers.\n\n资料来源：[src/huggingface_hub/lfs.py:45]()\n\n## Multipart Upload for Large Files\n\n### Upload Process\n\n```mermaid\ngraph LR\n A[File] --> B{Split into chunks}\n B --> C[Chunk 1]\n B --> D[Chunk 2]\n B --> E[Chunk N]\n \n C --> F[Upload Part 1]\n D --> G[Upload Part 2]\n E --> H[Upload Part N]\n \n F --> I{All parts
complete?}\n G --> I\n H --> I\n \n I -->|Yes| J[Complete multipart
upload]\n```\n\n### Chunk Size Calculation\n\nThe library calculates optimal chunk sizes based on file size:\n\n```python\nfrom math import ceil\n\nchunk_size = ceil(file_size / total_parts)\n```\n\nThis ensures even distribution of work across all chunks.\n\n资料来源：[src/huggingface_hub/lfs.py:30-35]()\n\n## Integration with Commit API\n\n### CommitOperationAdd with LFS\n\nThe `CommitOperationAdd` class handles both regular and LFS file uploads:\n\n```python\nclass CommitOperationAdd(TypedDict):\n path_in_repo: str\n id: str # OID (git-sha or sha256 for LFS)\n size: int\n filepath: str\n upload_info: UploadInfo\n```\n\nThe `upload_info` attribute contains the LFS-specific upload metadata, which determines whether the file goes through LFS or regular Git upload.\n\n资料来源：[src/huggingface_hub/_commit_api.py:100-150]()\n\n### Upload Flow\n\n```mermaid\nflowchart TD\n A[Create CommitOperationAdd] --> B{File size
> threshold?}\n \n B -->|Yes| C[Create LfsUploadFileInfo]\n B -->|No| D[Create UploadInfo for Git]\n \n C --> E[Upload via LFS Batch API]\n D --> F[Upload via Git HTTP API]\n \n E --> G{LFS transfer
method}\n G -->|basic| H[Single PUT request]\n G -->|multipart| I[Chunked upload]\n G -->|xet| J[Custom xet protocol]\n \n H --> K[Verify upload]\n I --> K\n J --> K\n \n K --> L[Commit confirmation]\n F --> L\n```\n\n## Error Handling\n\n### Validation Errors\n\n| Error | Condition | Handling |\n|-------|-----------|----------|\n| Invalid OID | Not matching `OID_REGEX` | Raise `ValueError` |\n| Missing upload info | `upload_info` not set | Raise `ValueError` |\n| Malformed batch response | Missing required fields | Raise `HfHubHTTPError` |\n\n### Network Errors\n\nThe library implements automatic retry with exponential backoff for failed LFS operations:\n\n```python\nfrom huggingface_hub.utils import http_backoff\n\n# Wrapped in http_backoff for resilience\nhf_raise_for_status(response)\n```\n\n资料来源：[src/huggingface_hub/lfs.py:50-80]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Effect |\n|----------|--------|\n| `HF_ENDPOINT` | Override default `https://huggingface.co` |\n| `HF_TOKEN` | Authentication token for private repos |\n\n### Upload Options\n\nWhen uploading files, the following options control LFS behavior:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `transfers` | `list[str]` | `[\"basic\", \"multipart\"]` | Allowed transfer methods |\n| `endpoint` | `str` | Hub endpoint | LFS server endpoint |\n| `repo_type` | `str` | `\"model\"` | Repository type |\n| `repo_id` | `str` | Required | Repository identifier |\n\n资料来源：[src/huggingface_hub/lfs.py:60-110]()\n\n## Best Practices\n\n### File Organization\n\n1. **Group large binary files** - Store model weights and dataset files separately from code\n2. **Use consistent file sizes** - Avoid extremely small LFS files (< 5MB overhead)\n3. **Leverage symlinks** - The snapshot directory uses symlinks to avoid duplication\n\n### Upload Optimization\n\n1. **Prefer multipart for files > 100MB** - Enables parallel uploads and resumability\n2. **Enable xet for frequent transfers** - Custom protocol reduces bandwidth\n3. **Batch operations** - Use `CommitOperationAdd` batching to minimize round trips\n\n### Caching Strategy\n\n```\n~/.cache/huggingface/hub/\n└── models--{repo_id}/\n ├── blobs/ # Physical file storage (SHA256 for LFS)\n ├── refs/ # Revision pointers\n └── snapshots/ # Virtual files pointing to blobs\n```\n\nThe snapshot layer provides deduplication - the same blob referenced by multiple commits is stored only once.\n\n资料来源：[src/huggingface_hub/file_download.py:10-30]()\n\n## See Also\n\n- [Git vs HTTP Protocol](https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http) - Understanding when LFS is used\n- [hf_hub_download](https://huggingface.co/docs/huggingface_hub/package_reference/file_download) - File downloading with LFS support\n- [Commit API Reference](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api) - Uploading with commits\n\n---\n\n\n\n## Repository Management API\n\n### 相关页面\n\n相关主题：[File Upload Operations](#file-upload), [Authentication System](#authentication), [Cache Management System](#cache-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n- [src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [docs/source/en/guides/repository.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/repository.md)\n \n\n# Repository Management API\n\nThe Repository Management API in `huggingface_hub` provides a comprehensive interface for creating, configuring, and managing Hugging Face repositories (models, datasets, and Spaces) directly from Python code or via the command-line interface.\n\n## Overview\n\nThe Repository Management API serves as the core layer for all Hub repository operations, enabling developers to programmatically:\n\n- Create and delete repositories\n- Configure repository settings\n- Upload and download files\n- Manage repository metadata\n- Handle commit operations with Git LFS support\n\n资料来源：[src/huggingface_hub/README.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/README.md)\n\n## Architecture\n\nThe repository management functionality is distributed across multiple modules:\n\n```mermaid\ngraph TD\n A[Repository Management API] --> B[hf_api.py]\n A --> C[_commit_api.py]\n A --> D[_buckets.py]\n B --> E[REST API Client]\n C --> E\n B --> F[CLI Interface]\n F --> G[hf CLI Command]\n```\n\n### Core Components\n\n| Module | Purpose |\n|--------|---------|\n| `hf_api.py` | Main `HfApi` class with all CRUD operations |\n| `_commit_api.py` | Low-level commit operations, LFS handling |\n| `_buckets.py` | Bucket/S3-compatible storage management |\n| `cli/` | Command-line interface implementation |\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## Repository Types\n\nThe API supports three primary repository types:\n\n| Type | Description | Use Case |\n|------|-------------|----------|\n| `model` | Model repositories | Storing and sharing ML model weights |\n| `dataset` | Dataset repositories | Hosting and versioning datasets |\n| `space` | Space repositories | Hosting Gradio/Streamlit demos |\n\n## Core Operations\n\n### Repository Lifecycle\n\n```mermaid\ngraph LR\n A[create_repo] --> B[Update Settings]\n B --> C[Upload Files]\n C --> D[Manage Commits]\n D --> E[delete_repo]\n```\n\n#### Creating a Repository\n\n```python\nfrom huggingface_hub import create_repo, HfApi\n\n# Using HfApi class\napi = HfApi()\napi.create_repo(\n repo_id=\"username/my-model\",\n repo_type=\"model\",\n exist_ok=False\n)\n\n# Using convenience function\ncreate_repo(\n repo_id=\"super-cool-model\",\n token=\"hf_xxxxx\"\n)\n```\n\n#### Deleting a Repository\n\n```python\napi.delete_repo(repo_id=\"username/my-model\", repo_type=\"model\")\n```\n\n资料来源：[src/huggingface_hub/hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### Repository Settings\n\nUpdate repository configuration after creation:\n\n```python\napi.update_repo_settings(\n repo_id=\"username/my-model\",\n private=True,\n repo_type=\"model\",\n gated=True # Enable gated access\n)\n```\n\n### Listing Repository Contents\n\n```python\n# List all files in a repository\nfiles = api.list_repo_files(repo_id=\"tiiuae/falcon-7b-instruct\")\n\n# List repo objects with pagination\nobjects = api.list_repo_objects(\n repo_id=\"my-org/my-dataset\",\n repo_type=\"dataset\"\n)\n```\n\n## Commit Operations\n\n### Commit Operation Classes\n\nThe `_commit_api.py` module provides low-level commit primitives:\n\n| Class | Purpose |\n|-------|---------|\n| `CommitOperationAdd` | Add a file to the repository |\n| `CommitOperationDelete` | Remove a file from the repository |\n| `CommitOperationCopy` | Copy a file within the repository |\n\n```python\nfrom huggingface_hub import CommitOperationAdd, HfApi\n\noperations = [\n CommitOperationAdd(\n path_in_repo=\"config.json\",\n path_or_fileobj=\"/local/path/config.json\"\n ),\n]\n\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Add config file\"\n)\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n\n### Large File Upload (Git LFS)\n\nLarge files are automatically handled via Git LFS:\n\n```mermaid\ngraph TD\n A[File > 10MB] --> B{LFS Required?}\n B -->|Yes| C[Upload to LFS Storage]\n B -->|No| D[Upload as Regular File]\n C --> E[Create LFS Pointer]\n E --> F[Commit Pointer to Repo]\n D --> F\n```\n\n## File Upload Operations\n\n### Single File Upload\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/home/user/model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"username/my-model\",\n)\n```\n\n### Folder Upload\n\n```python\nfrom huggingface_hub import upload_folder\n\nupload_folder(\n folder_path=\"/path/to/local/space\",\n repo_id=\"username/my-cool-space\",\n repo_type=\"space\",\n commit_message=\"Update space files\"\n)\n```\n\nFor very large folders, the library provides chunked upload:\n\n```python\nfrom huggingface_hub import _upload_large_folder\n\n_upload_large_folder(\n repo_id=\"username/large-dataset\",\n folder_path=\"/data/large-folder\",\n repo_type=\"dataset\"\n)\n```\n\n资料来源：[src/huggingface_hub/README.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/README.md)\n\n## File Deletion Operations\n\n```python\n# Delete a single file\napi.delete_file(\n path_in_repo=\"old-model.bin\",\n repo_id=\"username/my-model\",\n commit_message=\"Remove deprecated file\"\n)\n\n# Delete a folder\napi.delete_folder(\n path_in_repo=\"old-folder/\",\n repo_id=\"username/my-model\",\n commit_message=\"Clean up old directory\"\n)\n```\n\n## CLI Interface\n\nThe repository management features are exposed through the `hf` CLI:\n\n```bash\n# Authentication\nhf auth login\nhf auth logout\nhf auth whoami\n\n# Repository operations\nhf repos create username/my-model --type model\nhf repos create username/my-dataset --type dataset\n```\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## Configuration Parameters\n\n### Repository Creation Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `repo_id` | str | Required | Repository identifier (user/name or org/name) |\n| `repo_type` | str | \"model\" | Type: \"model\", \"dataset\", or \"space\" |\n| `exist_ok` | bool | False | Allow overwriting existing repo |\n| `private` | bool | False | Make repository private |\n| `token` | str | None | Hugging Face authentication token |\n| `space_sdk` | str | None | Space SDK: \"gradio\", \"streamlit\", \"docker\", \"docker_leaf\", \"static\", \"nextjs\" |\n| `space_hardware` | str | None | Space hardware tier |\n\n### Commit Operation Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `operations` | list[CommitOperation] | Required | List of file operations |\n| `commit_message` | str | Required | Description of changes |\n| `commit_description` | str | None | Extended commit description |\n| `parent_commit` | str | None | Parent commit SHA for incremental updates |\n| `create_pr` | bool | False | Create a Pull Request instead of committing to main |\n\n## Error Handling\n\nThe repository management API raises specific exception types:\n\n| Exception | Cause |\n|-----------|-------|\n| `RepositoryNotFoundError` | Repository does not exist or user lacks access |\n| `RevisionNotFoundError` | Specified git revision not found |\n| `EntryNotFoundError` | File or folder not found in repository |\n| `HfHubHTTPError` | HTTP error from the Hub API |\n\n```python\nfrom huggingface_hub import hf_hub_download\nfrom huggingface_hub.errors import RevisionNotFoundError\n\ntry:\n hf_hub_download(\n repo_id=\"bert-base-cased\",\n filename=\"config.json\",\n revision=\"\"\n )\nexcept RevisionNotFoundError as e:\n print(f\"Revision not found: {e}\")\n```\n\n资料来源：[src/huggingface_hub/errors.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py)\n\n## Common Usage Patterns\n\n### Model Publishing Workflow\n\n```mermaid\ngraph TD\n A[Create Repo] --> B[Upload Model Files]\n B --> C[Create Model Card]\n C --> D[Set Metadata/Tags]\n D --> E[Publish to Hub]\n```\n\n```python\nfrom huggingface_hub import HfApi, upload_file, RepoCard, ModelCardData\n\napi = HfApi()\n\n# 1. Create repository\napi.create_repo(repo_id=\"my-org/my-model\", exist_ok=True)\n\n# 2. Upload model files\nupload_file(\n path_or_fileobj=\"./model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"my-org/my-model\"\n)\n\n# 3. Create and upload model card\ncard = RepoCard.from_template(\n ModelCardData(\n language=\"en\",\n license=\"apache-2.0\",\n model_name=\"My Custom Model\",\n tags=[\"pytorch\", \"image-classification\"]\n ),\n text=\"This is a custom model trained on...\"\n)\ncard.save(\".gitattributes\")\n```\n\n### Dataset Versioning Workflow\n\n```python\nfrom huggingface_hub import create_commit, CommitOperationAdd\n\noperations = [\n CommitOperationAdd(\n path_in_repo=\"data/train.parquet\",\n path_or_fileobj=\"./train.parquet\"\n ),\n CommitOperationAdd(\n path_in_repo=\"data/validation.parquet\", \n path_or_fileobj=\"./validation.parquet\"\n ),\n]\n\napi.create_commit(\n repo_id=\"username/my-dataset\",\n operations=operations,\n commit_message=\"Add training and validation splits\",\n commit_description=\"Initial dataset release with train/validation split\"\n)\n```\n\n## Best Practices\n\n1. **Use `exist_ok=True`** when creating repositories in automated pipelines\n2. **Include commit messages** for better version control history\n3. **Use `parent_commit`** parameter when making sequential updates to prevent race conditions\n4. **Enable LFS** automatically for files larger than 10MB\n5. **Use `create_pr=True`** for reviewing changes before merging to main branch\n\n## See Also\n\n- [Upload Guide](https://huggingface.co/docs/huggingface_hub/en/guides/upload)\n- [Download Guide](https://huggingface.co/docs/huggingface_hub/main/ko/guides/download)\n- [Manage Cache](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)\n- [HfFileSystem](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py) for filesystem-style access\n\n---\n\n\n\n## Cache Management System\n\n### 相关页面\n\n相关主题：[File Download Operations](#file-download), [Repository Management API](#repository-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/utils/_cache_manager.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_cache_manager.py)\n- [src/huggingface_hub/constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py)\n- [src/huggingface_hub/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_download.py)\n- [src/huggingface_hub/cli/cache.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/cache.py)\n- [src/huggingface_hub/hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n \n\n# Cache Management System\n\n## Overview\n\nThe Cache Management System in `huggingface_hub` provides comprehensive utilities for managing locally cached models, datasets, and Spaces downloaded from the Hugging Face Hub. The system handles automatic caching of downloaded content, tracks cache metadata, and offers programmatic and CLI interfaces for inspecting and managing cached resources.\n\nThe cache system is designed to:\n- Store downloaded files efficiently with deduplication via blob storage\n- Track repository metadata including revisions, commit hashes, and file information\n- Provide safe deletion strategies that don't corrupt cache state\n- Handle corrupted cache entries gracefully with warnings\n\n## Cache Directory Structure\n\nThe Hugging Face cache follows a specific directory structure to organize cached content:\n\n```\nHF_HUB_CACHE/\n├── .locks/ # Lock files for concurrent access\n│ └── ...\n├── CACHEDIR.TAG # OS-native cache directory marker\n├── models--owner/\n│ └── repo_name/\n│ ├── .cache/ # Metadata and tracking\n│ ├── blobs/ # Actual file content (deduplicated)\n│ ├── refs/ # Branch and tag references\n│ ├── snapshots/ # Symlinks to blobs\n│ └── ...\n├── datasets--org/\n│ └── dataset_name/\n│ └── ...\n└── spaces--user/\n └── space_name/\n └── ...\n```\n\nCache directories follow the naming convention `type--repo_id` where:\n- `type` is singular (e.g., `model`, `dataset`, `space`)\n- `repo_id` slashes are converted to hyphens (e.g., `google/fleurs` becomes `google--fleurs`)\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## Core Data Models\n\n### HFCacheInfo\n\nThe main container class for cache information returned by scan operations:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `repos` | `frozenset[CachedRepoInfo]` | All cached repositories |\n| `size_on_disk` | `int` | Total size of all cached content in bytes |\n| `warnings` | `list[CorruptedCacheException]` | Issues encountered during scanning |\n\n### CachedRepoInfo\n\nRepresents a single cached repository:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `repo_id` | `str` | Repository identifier (e.g., `google/gemma-3-4b-it`) |\n| `repo_type` | `str` | Type: `model`, `dataset`, or `space` |\n| `size_on_disk` | `int` | Total size of cached revisions |\n| `revisions` | `frozenset[CachedRevisionInfo]` | All cached revisions |\n| `snapshot_path` | `Path` | Path to the snapshot directory |\n\n### CachedRevisionInfo\n\nRepresents a specific revision within a cached repository:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `commit_hash` | `str` | Git commit hash (40-character hex string) |\n| `size_on_disk` | `int` | Size of this specific revision |\n| `files` | `frozenset[CachedFileInfo]` | Files in this revision |\n| `last_modified` | `datetime` | Last modification timestamp |\n\n### CachedFileInfo\n\nRepresents an individual cached file:\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `file_name` | `str` | Name of the file |\n| `size_on_disk` | `int` | Size of the file in bytes |\n| `file_path` | `Path` | Path to the symlinked file in snapshots |\n| `blob_path` | `Path` | Path to the actual blob storage |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## Key API Functions\n\n### scan_cache_dir()\n\nScans the cache directory and returns information about all cached repositories.\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\nprint(f\"Total size: {cache_info.size_on_disk / 1024 / 1024:.2f} MB\")\nfor repo in cache_info.repos:\n print(f\"{repo.repo_type}/{repo.repo_id}\")\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | `HF_HUB_CACHE` env var | Cache directory to scan |\n\n**Returns:** `HFCacheInfo` object containing repository information\n\n**Raises:**\n- `CacheNotFound` if the cache directory doesn't exist\n- `ValueError` if cache_dir is a file instead of a directory\n\n### try_to_load_from_cache()\n\nChecks if a file exists in the local cache without downloading.\n\n```python\nfrom huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST\n\nfilepath = try_to_load_from_cache(\n repo_id=\"tiiuae/falcon-7b-instruct\",\n filename=\"config.json\",\n revision=\"main\",\n repo_type=\"model\"\n)\n\nif isinstance(filepath, str):\n print(f\"File cached at: {filepath}\")\nelif filepath is _CACHED_NO_EXIST:\n print(\"File confirmed to not exist at this revision\")\nelse:\n print(\"File not in cache\")\n```\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | None | Cache directory path |\n| `repo_id` | `str` | Required | Repository identifier |\n| `filename` | `str` | Required | Filename to look for |\n| `revision` | `str` | `\"main\"` | Specific revision to check |\n| `repo_type` | `str` | `\"model\"` | Type of repository |\n\n**Returns:** `str` (file path), `_CACHED_NO_EXIST`, or `None`\n\n资料来源：[src/huggingface_hub/file_download.py:1-100]()\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## DeleteCacheStrategy\n\nThe deletion system uses a two-phase approach: create a strategy, then execute it. This prevents accidental data loss and allows for dry-run validation.\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\n\n# Create deletion strategy (doesn't delete yet)\ndelete_strategy = cache_info.delete_revisions(\n \"81fd1d6e7847c99f5862c9fb81387956d99ec7aa\",\n \"e2983b237dccf3ab4937c97fa717319a9ca1a96d\",\n)\n\n# Preview what will be deleted\nprint(f\"Will free: {delete_strategy.expected_free_space / 1024 / 1024:.2f} MB\")\n\n# Execute the deletion\ndelete_strategy.execute()\n```\n\n### Deletion Workflow\n\n```mermaid\ngraph TD\n A[scan_cache_dir] --> B[Get HFCacheInfo]\n B --> C[Call delete_revisions with commit hashes]\n C --> D[Create DeleteCacheStrategy]\n D --> E{Preview/Dry Run}\n E -->|Inspect| F[Review expected_free_space]\n E -->|Confirm| G[execute]\n G --> H[Delete blobs and refs]\n H --> I[Cache deletion done]\n F --> G\n```\n\n### DeleteCacheStrategy Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `repos_to_delete` | `dict[CachedRepoInfo, set[CachedRevisionInfo]]` | Repos and revisions marked for deletion |\n| `blobs_to_delete` | `set[Path]` | Blob file paths to remove |\n| `expected_free_space` | `int` | Estimated bytes to be freed |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-100]()\n\n## CLI Interface\n\nThe `hf` command provides cache management through the `cache` subcommand.\n\n### List Cached Repositories\n\n```bash\nhf cache ls\n```\n\n**Output format:**\n```\nID SIZE LAST_ACCESSED LAST_MODIFIED REFS\n--------------------------- -------- ------------- ------------- -----------\ndataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script\nmodel/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main\nmodel/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main\n\nDone in 0.0s. Scanned 6 repo(s) for a total of 3.4G.\n```\n\n### Filtering Options\n\n| Filter Key | Operators | Example |\n|------------|-----------|---------|\n| `type` | `==`, `!=` | `--filter type==model` |\n| `size` | `>`, `<`, `>=`, `<=`, `=` | `--filter size>=1G` |\n| `accessed` | `>`, `<`, `>=`, `<=` | `--filter accessed<7d` |\n| `modified` | `>`, `<`, `>=`, `<=` | `--filter modified>30d` |\n| `refs` | `==`, `!=` | `--filter refs==main` |\n\n**Examples:**\n```bash\n# Filter large models\nhf cache ls --filter type==model --filter size>=5G\n\n# Find recently accessed datasets\nhf cache ls --filter type==dataset --filter accessed<7d\n\n# Filter by modification time\nhf cache ls --filter modified>30d\n```\n\n### Sorting Options\n\n| Sort Key | Default Order | Ascending Option |\n|----------|---------------|------------------|\n| `name` | `asc` | `name:asc` |\n| `size` | `desc` | `size:asc` |\n| `accessed` | `desc` | `accessed:asc` |\n| `modified` | `desc` | `modified:asc` |\n\n**Examples:**\n```bash\n# Sort by size descending (largest first)\nhf cache ls --sort size\n\n# Sort by name ascending, then size descending\nhf cache ls --sort name:asc --sort size:desc\n```\n\n### Delete Specific Revisions\n\n```bash\nhf cache delete [...]\n```\n\nThe CLI will prompt for confirmation before deletion.\n\n资料来源：[src/huggingface_hub/cli/cache.py:1-100]()\n\n## Cache Scanning Process\n\nThe cache scanning process validates the cache directory structure and handles corrupted entries gracefully.\n\n```mermaid\ngraph TD\n A[Start scan_cache_dir] --> B{Is cache_dir set?}\n B -->|No| C[Use HF_HUB_CACHE env var]\n B -->|Yes| D[Use provided path]\n C --> E{Does directory exist?}\n D --> E\n E -->|No| F[Raise CacheNotFound]\n E -->|Yes| G{Is it a file?}\n G -->|Yes| H[Raise ValueError]\n G -->|No| I[Iterate subdirectories]\n I --> J{Skip .locks and CACHEDIR.TAG?}\n J -->|Yes| K[Next directory]\n J -->|No| L[_scan_cached_repo]\n L --> M{Valid format?}\n M -->|No| N[Log CorruptedCacheException]\n M -->|Yes| O[Create CachedRepoInfo]\n N --> P[Add to warnings list]\n O --> Q[Add to repos set]\n P --> K\n Q --> K\n K --> R{More directories?}\n R -->|Yes| I\n R -->|No| S[Return HFCacheInfo]\n```\n\n### Validation Rules\n\n1. Each subdirectory must follow the `type--repo_id` naming convention\n2. The `type` must be one of: `model`, `dataset`, `space`\n3. Directories must contain expected subdirectories (snapshots, blobs, refs)\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:100-200]()\n\n## HubMixin Integration\n\nThe `HubMixin` class integrates with the cache system for model loading:\n\n```python\nfrom huggingface_hub import HubMixin\n\nclass MyModel(HubMixin, torch.nn.Module):\n pass\n\n# Load model - uses cache automatically\nmodel = MyModel.from_pretrained(\"bert-base-uncased\")\n\n# Cache behavior:\n# 1. Check if model exists locally\n# 2. If local_files_only=True, use cached version or raise error\n# 3. Otherwise, download and cache from Hub\n# 4. Store in cache_dir or default HF_HUB_CACHE location\n```\n\n**HubMixin Parameters Related to Caching:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cache_dir` | `str` or `Path` | None | Custom cache location |\n| `force_download` | `bool` | `False` | Force re-download |\n| `local_files_only` | `bool` | `False` | Only use cached files |\n| `token` | `str` or `bool` | None | HuggingFace token |\n\n资料来源：[src/huggingface_hub/hub_mixin.py:1-100]()\n\n## Exception Handling\n\n### CorruptedCacheException\n\nRaised when cache directory structure is invalid or expected files are missing.\n\n```python\nclass CorruptedCacheException(Exception):\n \"\"\"Exception raised when a cache entry is corrupted.\"\"\"\n def __init__(self, message: str):\n self.message = message\n super().__init__(self.message)\n```\n\nCommon corruption scenarios:\n- Snapshots directory doesn't exist\n- Invalid repository directory naming\n- Missing expected cache metadata\n\n### CacheNotFound\n\nRaised when the cache directory cannot be located.\n\n```python\nraise CacheNotFound(\n f\"Cache directory not found: {cache_dir}. \"\n \"Please use `cache_dir` argument or set `HF_HUB_CACHE` environment variable.\",\n cache_dir=cache_dir,\n)\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HF_HUB_CACHE` | Primary cache directory | `~/.cache/huggingface/hub` |\n| `HF_HUB_DOWNLOAD_TIMEOUT` | Download timeout in seconds | 10 |\n\n资料来源：[src/huggingface_hub/constants.py]()\n\n## Best Practices\n\n### Efficient Cache Usage\n\n1. **Reuse cached content**: Multiple models sharing the same base weights will reference the same blobs\n2. **Use revision pinning**: Specify exact commit hashes for reproducible builds\n3. **Monitor cache size**: Regularly run `hf cache ls` to identify large repositories\n\n### Safe Deletion\n\n1. Always use `scan_cache_dir()` to inspect before deletion\n2. Check `warnings` in `HFCacheInfo` for corrupted entries\n3. Use `expected_free_space` property to estimate space recovery\n4. Execute deletion only after confirming the strategy\n\n### Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| CacheNotFound error | Set `HF_HUB_CACHE` or use `cache_dir` parameter |\n| CorruptedCacheException | Manually delete the corrupted cache entry |\n| Large cache size | Use `delete_revisions()` to remove old/unused revisions |\n| Permission denied | Check file permissions on cache directory |\n\n## Complete Usage Example\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# Scan cache and get overview\ncache_info = scan_cache_dir()\n\nprint(f\"Total cached repos: {len(cache_info.repos)}\")\nprint(f\"Total size: {cache_info.size_on_disk / 1024**3:.2f} GB\")\n\n# Find specific repo\ntarget_repo = \"stabilityai/stable-diffusion-2-1\"\nfor repo in cache_info.repos:\n if repo.repo_id == target_repo:\n print(f\"\\nFound {target_repo}:\")\n print(f\" Type: {repo.repo_type}\")\n print(f\" Revisions: {len(repo.revisions)}\")\n for revision in repo.revisions:\n print(f\" - {revision.commit_hash[:8]}\")\n print(f\" Size: {revision.size_on_disk / 1024**2:.2f} MB\")\n print(f\" Files: {len(revision.files)}\")\n\n# Clean up old revisions\nif cache_info.repos:\n first_repo = next(iter(cache_info.repos))\n if len(first_repo.revisions) > 1:\n # Keep only the latest revision\n revisions_to_delete = [\n rev.commit_hash \n for rev in list(first_repo.revisions)[1:]\n ]\n strategy = cache_info.delete_revisions(*revisions_to_delete)\n print(f\"\\nWould free: {strategy.expected_free_space / 1024**2:.2f} MB\")\n # strategy.execute() # Uncomment to actually delete\n\n---\n\n\n\n## Inference Client and Providers\n\n### 相关页面\n\n相关主题：[HuggingFace File System (HfFileSystem)](#hf-file-system), [Overview and Architecture](#overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py)\n- [src/huggingface_hub/inference/_generated/_async_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_generated/_async_client.py)\n- [src/huggingface_hub/inference/_providers](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers)\n- [src/huggingface_hub/inference/_common.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_common.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n \n\n# Inference Client and Providers\n\n## Overview\n\nThe Inference Client and Providers system provides a unified interface for performing inference with machine learning models hosted on Hugging Face or third-party inference providers. This system abstracts the complexity of interacting with various inference backends, allowing developers to make inference calls through a consistent Python API.\n\nThe `InferenceClient` class serves as the primary entry point for synchronous inference operations, while `AsyncInferenceClient` provides asynchronous alternatives for non-blocking workflows. Both clients leverage a provider system that normalizes API differences between various inference services like Replicate, Together AI, Fal.ai, and Sambanova. 资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n## Architecture\n\nThe inference system follows a layered architecture where the client exposes a high-level API while delegating provider-specific details to helper classes.\n\n```mermaid\ngraph TD\n User[User Code] --> Client[InferenceClient]\n Client --> ProviderHelper[Provider Helper]\n ProviderHelper --> ProviderAPI[Third-party Provider API]\n ProviderHelper --> HFRouting[Hugging Face Routing]\n \n subgraph \"InferenceClient\"\n Methods[text_generation, chat_completion,
text_to_image, etc.]\n end\n \n subgraph \"Provider Layer\"\n get_provider_helper[get_provider_helper]\n prepare_request[prepare_request]\n get_response[get_response]\n end\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|--------------|---------|\n| `InferenceClient` | `inference/_client.py` | Synchronous inference operations |\n| `AsyncInferenceClient` | `inference/_generated/_async_client.py` | Asynchronous inference operations |\n| Provider Helpers | `inference/_providers/*.py` | Provider-specific request/response handling |\n| Provider Registry | `inference/_providers/__init__.py` | Provider discovery and initialization |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-50]()\n\n## Supported Inference Tasks\n\nThe InferenceClient supports a comprehensive set of inference tasks through method-based API calls.\n\n### Task Categories and Methods\n\n| Category | Method | Description |\n|----------|--------|-------------|\n| **Text Generation** | `text_generation()` | Generate text from prompts with streaming support |\n| **Chat** | `chat_completion()` | Multi-turn conversation with message history |\n| **Image Generation** | `text_to_image()` | Generate images from text prompts |\n| **Video Generation** | `text_to_video()` | Generate videos from text descriptions |\n| **Text Analysis** | `summarization()` | Summarize long text documents |\n| **Text Analysis** | `fill_mask()` | Fill masked tokens in text |\n| **Text Analysis** | `zero_shot_classification()` | Classify text with arbitrary labels |\n| **Table Operations** | `table_question_answering()` | Answer questions from tabular data |\n| **Table Operations** | `tabular_classification()` | Classify tabular data rows |\n| **Embeddings** | `sentence_similarity()` | Compute semantic similarity between sentences |\n| **Vision** | `image_classification()` | Classify images into categories |\n\n资料来源：[src/huggingface_hub/inference/_client.py:200-500]()\n\n## Client Configuration\n\n### Initialization Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model` | `str \\| None` | `None` | Default model identifier for all requests |\n| `provider` | `str \\| None` | `None` | Inference provider to use (replicate, together, fal-ai, etc.) |\n| `api_key` | `str \\| None` | `None` | API key for authentication |\n| `token` | `str \\| bool \\| None` | `True` | Hugging Face token for authentication |\n| `timeout` | `float \\| None` | `None` | Request timeout in seconds |\n| `headers` | `dict[str, str]` | `{}` | Additional HTTP headers |\n\n```python\nfrom huggingface_hub import InferenceClient\n\n# Basic usage with default provider\nclient = InferenceClient()\n\n# Using a specific provider\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_...\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\"\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:50-150]()\n\n## Provider System\n\n### Provider Architecture\n\nThe provider system normalizes differences between inference services by abstracting request preparation and response parsing.\n\n```mermaid\ngraph LR\n A[InferenceClient] -->|task + model| B[get_provider_helper]\n B --> C{Provider Type}\n C -->|Built-in| D[Internal Provider Helper]\n C -->|Third-party| E[Provider API Helper]\n \n D --> F[Provider.prepare_request]\n E --> G[External API Call]\n \n F --> H[Normalized Response]\n G --> H\n```\n\n### Supported Providers\n\n| Provider | Description | Authentication |\n|----------|-------------|----------------|\n| `replicate` | Replicate hosted models | API key |\n| `together` | Together AI inference | API key |\n| `fal-ai` | Fal.ai generation services | API key |\n| `sambanova` | SambaNova Cloud | API key |\n| `default` | Hugging Face inference API | HF token |\n\n资料来源：[src/huggingface_hub/inference/_providers/__init__.py]()\n\n### Provider Helper Functions\n\nEach provider helper implements two key methods:\n\n- **`prepare_request()`**: Transforms inputs and parameters into provider-specific API format\n- **`get_response()`**: Parses provider response into normalized output format\n\n```python\nprovider_helper = get_provider_helper(\n provider=\"replicate\",\n task=\"text-generation\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\"\n)\n\nrequest_parameters = provider_helper.prepare_request(\n inputs=prompt,\n parameters={\"max_new_tokens\": 100},\n headers=client.headers,\n model=model_id,\n api_key=client.token,\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:150-200]()\n\n## Usage Examples\n\n### Text Generation\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\n# Basic text generation\noutput = client.text_generation(\n prompt=\"The capital of France is\",\n model=\"gpt2\"\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:300-400]()\n\n### Chat Completion\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\n provider=\"sambanova\",\n api_key=\"hf_...\"\n)\n\noutput = client.chat_completion(\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\",\n messages=[\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n ]\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:400-500]()\n\n### Image Generation\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_...\"\n)\n\nimage = client.text_to_image(\n \"An astronaut riding a horse on the moon.\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n extra_body={\"output_quality\": 100}\n)\nimage.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:500-600]()\n\n### Text-to-Video\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\nvideo = client.text_to_video(\n prompt=\"A cat playing piano\",\n num_inference_steps=50,\n guidance_scale=7.5\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:600-700]()\n\n### Sentence Similarity\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\nsimilarities = client.sentence_similarity(\n \"Machine learning is so easy.\",\n other_sentences=[\n \"Deep learning is so straightforward.\",\n \"This is so difficult, like rocket science.\",\n ]\n)\n# Output: [0.7785726189613342, 0.45876261591911316]\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:700-800]()\n\n### Zero-Shot Classification\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient()\n\ntext = \"A new model offers an explanation for how the Galilean satellites formed.\"\nlabels = [\"space & cosmos\", \"scientific discovery\", \"microbiology\", \"robots\"]\n\nresult = client.zero_shot_classification(text, labels)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:350-450]()\n\n## AsyncInferenceClient\n\nFor asynchronous workflows, the `AsyncInferenceClient` provides non-blocking equivalents of all synchronous methods.\n\n```python\nfrom huggingface_hub import AsyncInferenceClient\n\nasync def main():\n client = AsyncInferenceClient()\n \n # Async chat completion\n output = await client.chat_completion(\n model=\"meta-llama/Meta-Llama-3-70B-Instruct\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n )\n \n # Async image generation\n image = await client.text_to_image(\n prompt=\"A beautiful sunset over mountains\",\n model=\"black-forest-labs/FLUX.1-schnell\"\n )\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-200]()\n\n## Error Handling\n\nThe inference system defines specific exception types for common error conditions:\n\n| Exception | Description |\n|-----------|-------------|\n| `InferenceTimeoutError` | Request exceeded timeout threshold |\n| `HfHubHTTPError` | HTTP error from the inference provider |\n\n```python\nfrom huggingface_hub import InferenceClient, InferenceTimeoutError\n\nclient = InferenceClient(timeout=30)\n\ntry:\n result = client.text_generation(\"Hello world\")\nexcept InferenceTimeoutError:\n print(\"Request timed out\")\nexcept HfHubHTTPError as e:\n print(f\"HTTP error: {e}\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:250-300]()\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Client\n participant ProviderHelper\n participant API\n \n User->>Client: text_generation(prompt, model)\n Client->>ProviderHelper: get_provider_helper(provider, task, model)\n Client->>ProviderHelper: prepare_request(inputs, parameters)\n ProviderHelper-->>Client: request_parameters\n Client->>Client: _inner_post(request_parameters)\n Client->>API: HTTP POST\n API-->>Client: response\n Client->>ProviderHelper: get_response(response)\n ProviderHelper-->>Client: normalized_output\n Client-->>User: InferenceOutput\n```\n\n## Output Models\n\nThe inference client returns typed output objects for each task:\n\n| Task | Output Type |\n|------|-------------|\n| Text Generation | `TextGenerationOutput` or `TextGenerationStreamOutput` |\n| Chat Completion | `ChatCompletionOutput` |\n| Image Generation | `PIL.Image.Image` |\n| Video Generation | `bytes` |\n| Summarization | `SummarizationOutput` |\n| Fill Mask | `list[FillMaskOutputElement]` |\n| Zero-Shot Classification | `list[ZeroShotClassificationOutputElement]` |\n| Table Question Answering | `TableQuestionAnsweringOutputElement` |\n| Tabular Classification | `list[str]` |\n| Sentence Similarity | `list[float]` |\n| Image Classification | `list[ImageClassificationOutputElement]` |\n\n资料来源：[src/huggingface_hub/inference/_client.py:200-600]()\n\n## CLI Integration\n\nThe CLI provides command-line access to inference functionality:\n\n```bash\n# Install inference dependencies\npip install huggingface_hub[inference]\n\n# Run inference via CLI\nhf inference --model gpt2 --text \"The capital of France is\"\n```\n\n资料来源：[setup.py:1-30]()\n\n## Advanced Configuration\n\n### Extra Body Parameters\n\nMany inference methods accept `extra_body` for provider-specific parameters:\n\n```python\nclient = InferenceClient(provider=\"replicate\", api_key=\"hf_...\")\n\nimage = client.text_to_image(\n \"A majestic lion\",\n model=\"black-forest-labs/FLUX.1-dev\",\n extra_body={\n \"output_quality\": 100,\n \"guidance_scale\": 3.5\n }\n)\n```\n\n### Generate Parameters\n\nThe `generate_parameters` argument allows fine-tuning of generation behavior:\n\n```python\nclient.text_generation(\n prompt=\"Write a story\",\n model=\"meta-llama/Meta-Llama-3-8B-Instruct\",\n generate_parameters={\n \"temperature\": 0.7,\n \"top_p\": 0.9,\n \"repetition_penalty\": 1.2\n }\n)\n```\n\n## Summary\n\nThe Inference Client and Providers system provides:\n\n1. **Unified API**: Consistent interface across all inference tasks\n2. **Multi-Provider Support**: Seamless integration with Replicate, Together AI, Fal.ai, and Sambanova\n3. **Type-Safe Outputs**: Well-defined output models for each task\n4. **Async Support**: Full async/await compatibility via AsyncInferenceClient\n5. **Error Handling**: Specific exceptions for timeout and HTTP errors\n6. **Extensible Design**: Provider helper system for adding new inference backends\n\nThis architecture enables developers to switch between providers and models without modifying application code, providing flexibility in deployment while maintaining a clean, Pythonic API.\n\n---\n\n\n\n## HuggingFace File System (HfFileSystem)\n\n### 相关页面\n\n相关主题：[File Download Operations](#file-download), [File Upload Operations](#file-upload)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n- [src/huggingface_hub/utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/huggingface/huggingface_hub/blob/main/AGENTS.md)\n \n\n# HuggingFace File System (HfFileSystem)\n\n## Overview\n\nThe HuggingFace File System (HfFileSystem) is an fsspec-based POSIX-like filesystem implementation that provides seamless access to Hugging Face Hub repositories. It enables developers to interact with models, datasets, and Spaces using familiar filesystem operations, abstracting away the complexity of HTTP API calls and caching mechanisms.\n\n**Key Characteristics:**\n\n| Property | Value |\n|----------|-------|\n| Base Class | `fsspec.spec.AbstractFileSystem` |\n| Protocol | `hf://` |\n| Python Version | >= 3.10.0 |\n| Entry Point | `hf=huggingface_hub.HfFileSystem` |\n\n资料来源：[setup.py:48](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L48)\n\n---\n\n## Architecture\n\nHfFileSystem is built as a wrapper around the Hugging Face Hub's higher-level APIs, providing a filesystem abstraction layer that translates standard filesystem operations into HTTP requests to the Hugging Face Hub API.\n\n```mermaid\ngraph TD\n A[User Code] --> B[fsspec Compatible Operations]\n B --> C[HfFileSystem]\n C --> D[Cache Layer]\n C --> E[HfApi Methods]\n E --> F[Hugging Face Hub API]\n D --> F\n G[Local Cache] --> D\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `HfFileSystem` | Main filesystem implementation extending fsspec |\n| Cache Layer | Manages local caching of downloaded files |\n| URI Parser | Parses `hf://` protocol URIs into structured components |\n| HTTP Client | Handles communication with Hugging Face Hub API |\n\n资料来源：[CLAUDE.md:10]()\n\n---\n\n## URI Schemes\n\nHfFileSystem supports multiple URI formats for accessing different resource types on the Hugging Face Hub.\n\n### Repository Paths\n\n**Models, Datasets, and Spaces:**\n\n```\nhf://[@]/\nhf://models/[@]/\nhf://datasets/[@]/\nhf://spaces/[@]/\n```\n\n**Buckets (Generic Storage):**\n\n```\nhf://buckets//\n```\n\n资料来源：[src/huggingface_hub/hf_file_system.py:27-41]()\n\n### URI Structure\n\nThe `hf://` protocol follows a defined grammar:\n\n```\nhf://[/][@][/]:[:ro|:rw]\n```\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| `TYPE` | Repository type (models, datasets, spaces) | `models` |\n| `ID` | Repository identifier | `my-org/my-model` |\n| `REVISION` | Git revision (branch, commit hash, or tag) | `refs/pr/3` |\n| `PATH` | Path within the repository | `data/train.json` |\n| `MOUNT_PATH` | Local mount point for bucket operations | `/mnt/data` |\n| `ACCESS_MODE` | Read-only (`ro`) or read-write (`rw`) | `ro` |\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:1-20]()\n\n---\n\n## API Reference\n\n### Initialization Parameters\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem(\n endpoint: str = None,\n token: bool | str = None,\n block_size: int = None,\n expand_info: bool = False,\n **storage_options\n)\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `endpoint` | `str` | `https://huggingface.co` | Hub API endpoint URL |\n| `token` | `bool` or `str` | `None` (uses saved token) | Authentication token. Set `False` to disable auth |\n| `block_size` | `int` | `None` | Block size for reading/writing files |\n| `expand_info` | `bool` | `False` | Whether to expand file information |\n| `**storage_options` | `dict` | `{}` | Additional storage options |\n\n资料来源：[src/huggingface_hub/hf_file_system.py:42-65]()\n\n### Authentication\n\nHfFileSystem uses token-based authentication:\n\n- **Default behavior**: Uses locally saved token from `~/.huggingface/token`\n- **Explicit token**: Pass a string token directly\n- **Disable auth**: Set `token=False`\n\n```python\n# Uses saved token (recommended)\nfs = HfFileSystem()\n\n# Explicit token\nfs = HfFileSystem(token=\"hf_xxxxx\")\n\n# Disable authentication\nfs = HfFileSystem(token=False)\n```\n\n### Special Revision Handling\n\nSpecial git refs containing slashes are handled specially:\n\n```python\n# Patterns matched:\n# - refs/pr/ (Pull Request refs)\n# - refs/convert/ (Conversion refs like parquet-v2)\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:25-32]()\n\n---\n\n## Usage Examples\n\n### Basic File Operations\n\n```python\nfrom huggingface_hub import HfFileSystem\n\n# Initialize filesystem\nfs = HfFileSystem()\n\n# Read a file\nwith fs.open(\"hf://datasets/squad/train.json\", \"r\") as f:\n content = f.read()\n\n# List directory contents\nfiles = fs.ls(\"hf://my-org/my-model/data\")\n\n# Check if path exists\nexists = fs.exists(\"hf://my-org/my-model/config.json\")\n\n# Get file info\ninfo = fs.info(\"hf://my-org/my-model/model.safetensors\")\n```\n\n### Using with Pandas\n\nHfFileSystem enables direct reading of datasets with libraries like pandas:\n\n```python\nimport pandas as pd\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# Read CSV file directly from Hub\ndf = pd.read_csv(\n \"hf://datasets/mnist/train.csv\",\n storage_options={\"token\": \"hf_xxxxx\"}\n)\n```\n\n> [!TIP]\n> This compatibility layer introduces additional overhead. For better performance and reliability, prefer using `HfApi` methods directly when possible.\n\n资料来源：[src/huggingface_hub/hf_file_system.py:8-22]()\n\n### Mount Operations\n\nFor bucket storage with mount points:\n\n```python\nfrom huggingface_hub.utils import parse_hf_mount\n\nmount_info = parse_hf_mount(\"hf://my-org/my-model:/data:ro\")\n# Returns HfMount with source, mount_path, and read_only attributes\n```\n\n### URI Parsing\n\n```python\nfrom huggingface_hub.utils import parse_hf_uri\n\n# Parse model URI\nuri = parse_hf_uri(\"hf://my-org/my-model\")\n# HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')\n\n# Parse dataset with revision\nuri = parse_hf_uri(\"hf://datasets/my-org/my-dataset@refs/pr/3/train.json\")\n# HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:100-130]()\n\n---\n\n## Error Handling\n\n### HfUriError\n\nRaised when URI parsing fails due to malformed input:\n\n```python\nfrom huggingface_hub.errors import HfUriError\n\ntry:\n parse_hf_uri(\"hf://\")\nexcept HfUriError as e:\n print(e.msg) # \"Empty body after 'hf://'.\"\n```\n\n### Validation Errors\n\nRepository IDs and paths are validated:\n\n```python\nfrom huggingface_hub.errors import HFValidationError\n\n# Invalid repo ID format raises HFValidationError\n```\n\n资料来源：[src/huggingface_hub/utils/_hf_uris.py:8-10]()\n\n---\n\n## Integration Points\n\n### fsspec Integration\n\nHfFileSystem registers as an fsspec filesystem via entry points:\n\n```python\n# In setup.py\nentry_points={\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\nThis enables usage with any fsspec-compatible library:\n\n```python\nimport fsspec\n\nfs = fsspec.filesystem(\"hf\", token=\"hf_xxxxx\")\n```\n\n### CLI Download Command\n\nThe CLI uses HfFileSystem internally for download operations:\n\n```python\n# From src/huggingface_hub/cli/download.py\n# Supports include/exclude patterns\n# Uses snapshot_download for multi-file downloads\n```\n\n资料来源：[setup.py:48](https://github.com/huggingface/huggingface_hub/blob/main/setup.py#L48), [src/huggingface_hub/cli/download.py:1-100]()\n\n---\n\n## Performance Considerations\n\n| Aspect | Recommendation |\n|--------|----------------|\n| Large File Downloads | Use `HfApi` methods directly |\n| Cached Access | HfFileSystem automatically caches files |\n| Batch Operations | Use `snapshot_download` for entire repos |\n| Authentication | Always use saved tokens when possible |\n\n> [!WARNING]\n> While HfFileSystem provides compatibility with pandas and other libraries, it introduces additional overhead due to the fsspec compatibility layer. For production workloads requiring optimal performance and reliability, prefer using `HfApi` methods directly.\n\n---\n\n## Related Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `HfApi` | `hf_api.py` | Primary API for all Hub operations |\n| `hf_hub_download` | `file_download.py` | Single file download with caching |\n| `snapshot_download` | `_snapshot_download.py` | Full repository download |\n| `parse_hf_uri` | `utils/_hf_uris.py` | URI parsing utilities |\n| `RepoCard` | `repocard.py` | Repository metadata cards |\n\n资料来源：[CLAUDE.md:3-15](), [AGENTS.md:3-15]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：huggingface/huggingface_hub\n\n摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：How to stop hf models ls from truncating the results in the table?。\n\n## 1. 安全/权限坑 · 来源证据：How to stop hf models ls from truncating the results in the table?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to stop hf models ls from truncating the results in the table?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb213b3feddd4ea09912922699b6b822 | https://github.com/huggingface/huggingface_hub/issues/4207 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8873fa5438804ce5af82d7acf73d7e90 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d18ece8e9bf4111aa4a07b5d120f412 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：[v1.10.0] Instant file copy and new Kernel repo type\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.10.0] Instant file copy and new Kernel repo type\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff686b653d2644649473ac1a7be8cb46 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：[v1.11.0] Semantic Spaces search, Space logs, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.11.0] Semantic Spaces search, Space logs, and more\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_149c8633eb8447b080e00977ea43f541 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：[v1.12.0] Unified CLI output, bucket search, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.12.0] Unified CLI output, bucket search, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66340c89abfe48459796695dee8aebb9 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7501a96be8144e2fbc85bfab477f54e1 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：huggingface/huggingface_hub\n\n摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：How to stop hf models ls from truncating the results in the table?。\n\n## 1. 安全/权限坑 · 来源证据：How to stop hf models ls from truncating the results in the table?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to stop hf models ls from truncating the results in the table?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb213b3feddd4ea09912922699b6b822 | https://github.com/huggingface/huggingface_hub/issues/4207 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.13.0] new CLI commands and formatting, and HF URI parsing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8873fa5438804ce5af82d7acf73d7e90 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[v1.15.0] Region-aware buckets & repos, `hf skills list`, polished CLI help and more\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d18ece8e9bf4111aa4a07b5d120f412 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：[v1.10.0] Instant file copy and new Kernel repo type\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.10.0] Instant file copy and new Kernel repo type\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff686b653d2644649473ac1a7be8cb46 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：[v1.11.0] Semantic Spaces search, Space logs, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.11.0] Semantic Spaces search, Space logs, and more\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_149c8633eb8447b080e00977ea43f541 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：[v1.12.0] Unified CLI output, bucket search, and more\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.12.0] Unified CLI output, bucket search, and more\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66340c89abfe48459796695dee8aebb9 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7501a96be8144e2fbc85bfab477f54e1 | https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:323591830 | https://github.com/huggingface/huggingface_hub | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# huggingface_hub - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for huggingface/huggingface_hub.\n\nProject:\n- Name: huggingface_hub\n- Repository: https://github.com/huggingface/huggingface_hub\n- Summary: The official Python client for the Hugging Face Hub.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: The official Python client for the Hugging Face Hub.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview and Architecture. Produce one small intermediate artifact and wait for confirmation.\n2. authentication: Authentication System. Produce one small intermediate artifact and wait for confirmation.\n3. file-download: File Download Operations. Produce one small intermediate artifact and wait for confirmation.\n4. file-upload: File Upload Operations. Produce one small intermediate artifact and wait for confirmation.\n5. repository-api: Repository Management API. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/huggingface/huggingface_hub\n- https://github.com/huggingface/huggingface_hub#readme\n- .opencode/skills/hf-release-notes/SKILL.md\n- src/huggingface_hub/__init__.py\n- src/huggingface_hub/hf_api.py\n- README.md\n- src/huggingface_hub/_login.py\n- src/huggingface_hub/_oauth.py\n- src/huggingface_hub/utils/_auth.py\n- src/huggingface_hub/utils/_git_credential.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：huggingface/huggingface_hub\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install huggingface_hub\n```\n\n来源：https://github.com/huggingface/huggingface_hub#readme\n\n## 来源\n\n- repo: https://github.com/huggingface/huggingface_hub\n- docs: https://github.com/huggingface/huggingface_hub#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_b3b445b409d74eaab79686c890805f7c"
}