{
"canonical_name": "huggingface/huggingface_hub",
"compilation_id": "pack_de5b2cebe21c49ca8c18224cff0b7c22",
"created_at": "2026-05-17T00:47:17.771387+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": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"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": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 huggingface_hub 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. file-operations：文件操作。围绕“文件操作”模拟一次用户任务，不展示安装或运行结果。\n4. inference：推理系统。围绕“推理系统”模拟一次用户任务，不展示安装或运行结果。\n5. repository-management：仓库管理。围绕“仓库管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. file-operations\n输入：用户提供的“文件操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. inference\n输入：用户提供的“推理系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. repository-management\n输入：用户提供的“仓库管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / file-operations：Step 3 必须围绕“文件操作”形成一个小中间产物，并等待用户确认。\n- Step 4 / inference：Step 4 必须围绕“推理系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / repository-management：Step 5 必须围绕“仓库管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/huggingface/huggingface_hub\n- https://github.com/huggingface/huggingface_hub#readme\n- .opencode/skills/hf-release-notes/SKILL.md\n- README.md\n- src/huggingface_hub/__init__.py\n- src/huggingface_hub/hf_api.py\n- src/huggingface_hub/constants.py\n- src/huggingface_hub/file_download.py\n- src/huggingface_hub/_snapshot_download.py\n- src/huggingface_hub/_commit_api.py\n- src/huggingface_hub/hf_file_system.py\n- src/huggingface_hub/inference/_client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 huggingface_hub 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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 00:33:11 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [安装指南](#installation)\n- [系统架构](#architecture)\n- [模块结构详解](#module-structure)\n- [文件操作](#file-operations)\n- [推理系统](#inference)\n- [仓库管理](#repository-management)\n- [命令行工具](#cli-commands)\n- [缓存系统](#cache-system)\n- [Git LFS 集成](#lfs-integration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [i18n/README_ko.md](https://github.com/huggingface/huggingface_hub/blob/main/i18n/README_ko.md)\n- [i18n/README_hi.md](https://github.com/huggingface/huggingface_hub/blob/main/i18n/README_hi.md)\n- [i18n/README_fr.md](https://github.com/huggingface/huggingface_hub/blob/main/i18n/README_fr.md)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\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_endpoints.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_inference_endpoints.py)\n- [src/huggingface_hub/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n \n\n# 项目介绍\n\n## 概述\n\n`huggingface_hub` 是由 Hugging Face 公司开发的 Python 客户端库，用于与 [huggingface.co](https://huggingface.co) Hub 进行交互。该库提供了下载和发布模型、数据集以及其他类型仓库的完整功能支持。\n\n资料来源：[setup.py:1-10]()\n\n## 核心功能\n\nhuggingface_hub 的主要功能涵盖以下几个方面：\n\n| 功能模块 | 说明 |\n|---------|------|\n| 文件下载 | 从 Hub 下载单个文件或整个仓库 |\n| 文件上传 | 将文件或文件夹上传至 Hub |\n| 仓库管理 | 创建和管理模型、数据集、Space 仓库 |\n| 推理执行 | 在部署的模型上执行推理任务 |\n| 仓库搜索 | 搜索模型、数据集和 Space |\n| 模型卡片 | 创建和共享模型卡片文档 |\n\n资料来源：[i18n/README_ko.md:1-20]()\n\n## 安装方式\n\n### 基础安装\n\n```bash\npip install huggingface_hub\n```\n\n### 包含推理功能的完整安装\n\n```bash\npip install huggingface_hub[inference]\n```\n\n资料来源：[i18n/README_ko.md:1-10]()\n\n## 核心模块架构\n\n```mermaid\ngraph TD\n A[huggingface_hub] --> B[文件操作]\n A --> C[仓库管理]\n A --> D[推理服务]\n A --> E[卡片系统]\n \n B --> B1[hf_hub_download]\n B --> B2[snapshot_download]\n B --> B3[upload_file]\n B --> B4[upload_folder]\n \n C --> C1[create_repo]\n C --> C2[delete_repo]\n C --> C3[list_models]\n C --> C4[list_datasets]\n \n D --> D1[InferenceClient]\n D --> D2[AsyncInferenceClient]\n D --> D3[InferenceEndpoint]\n \n E --> E1[RepoCard]\n E --> E2[ModelCard]\n E --> E3[DatasetCard]\n E --> E4[SpaceCard]\n```\n\n## 主要 API 组件\n\n### 推理客户端 (InferenceClient)\n\n`InferenceClient` 是用于与托管模型进行交互的核心类，支持多种推理任务。\n\n**支持的推理任务：**\n\n- 文本生成 (text_generation)\n- 对话完成 (chat_completion)\n- 图像生成 (text_to_image)\n- 视频生成 (text_to_video)\n- 图像描述 (image_to_text)\n- 自动语音识别 (automatic_speech_recognition)\n- 文本转语音 (text_to_speech)\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n**基础使用示例：**\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\"meta-llama/Meta-Llama-3-70B-Instruct\")\n\n# 文本生成\noutput = client.text_generation(\"The huggingface_hub library is \", max_new_tokens=12)\n\n# 对话完成\noutput = client.chat_completion(\n messages=[\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n ]\n)\n```\n\n**图像生成示例：**\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(provider=\"replicate\", api_key=\"hf_...\")\nimage = client.text_to_image(\n \"An astronaut riding a horse on the moon.\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n)\nimage.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:100-200]()\n\n### 推理端点 (InferenceEndpoint)\n\n`InferenceEndpoint` 提供了专用推理端点的管理功能，支持部署自定义推理服务。\n\n**端点状态：**\n\n```mermaid\nstateDiagram-v2\n [*] --> deploying\n deploying --> pending\n pending --> paused\n paused --> running\n running --> paused\n running --> scaled_to_zero\n scaled_to_zero --> running\n running --> [*]\n```\n\n**使用示例：**\n\n```python\nfrom huggingface_hub import get_inference_endpoint\n\nendpoint = get_inference_endpoint(\"my-text-to-image\")\nprint(endpoint.status) # 'running'\nprint(endpoint.url) # 'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'\n\n# 执行推理\nresult = endpoint.client.text_to_image(\"prompt\")\n\n# 暂停端点以节省成本\nendpoint.pause()\n\n# 恢复并等待部署\nendpoint.resume()\nendpoint.wait()\n```\n\n资料来源：[src/huggingface_hub/_inference_endpoints.py:1-80]()\n\n### 评估结果管理\n\n库提供了 `EvalResultEntry` 类用于管理和上传模型评估结果：\n\n```python\nfrom huggingface_hub import EvalResultEntry, eval_result_entries_to_yaml, upload_file\nimport yaml\n\nentries = [\n EvalResultEntry(dataset_id=\"cais/hle\", task_id=\"default\", value=20.90),\n]\n\n# 转换为 YAML 格式\nyaml_content = yaml.dump(eval_result_entries_to_yaml(entries))\n\n# 上传到 Hub\nupload_file(\n path_or_fileobj=yaml_content.encode(),\n path_in_repo=\".eval_results/hle.yaml\",\n repo_id=\"your-username/your-model\",\n)\n```\n\n**EvalResultEntry 字段说明：**\n\n| 字段名 | 类型 | 说明 |\n|-------|------|------|\n| dataset_id | str | 数据集标识符 |\n| task_id | str | 任务标识符 |\n| value | Any | 评估指标值 |\n| dataset_revision | str | 数据集版本 |\n| verify_token | str | 验证令牌 |\n| date | str | 评估日期 |\n| source_url | str | 来源 URL |\n| source_name | str | 来源名称 |\n\n资料来源：[src/huggingface_hub/_eval_results.py:1-100]()\n\n## 文件操作\n\n### 下载文件\n\n**单个文件下载：**\n\n```python\nfrom huggingface_hub import hf_hub_download\n\nhf_hub_download(\n repo_id=\"tiiuae/falcon-7b-instruct\",\n filename=\"config.json\"\n)\n```\n\n**完整仓库下载：**\n\n```python\nfrom huggingface_hub import snapshot_download\n\nsnapshot_download(\"stabilityai/stable-diffusion-2-1\")\n```\n\n资料来源：[i18n/README_ko.md:1-30]()\n\n### 上传文件\n\n**单个文件上传：**\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/path/to/local/README.md\",\n path_in_repo=\"README.md\",\n repo_id=\"lysandre/test-model\",\n)\n```\n\n**文件夹上传：**\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资料来源：[i18n/README_fr.md:1-50]()\n\n## 仓库卡片系统\n\nhuggingface_hub 提供了统一的卡片系统来管理模型、数据集和 Space 的元数据文档：\n\n| 卡片类型 | 说明 | 对应类 |\n|---------|------|-------|\n| ModelCard | 模型卡片 | 模型描述和元数据 |\n| DatasetCard | 数据集卡片 | 数据集描述和元数据 |\n| SpaceCard | Space 卡片 | 应用描述和元数据 |\n\n```python\nfrom huggingface_hub import ModelCard, ModelCardData\n\ncard_data = ModelCardData(\n language=\"en\",\n license=\"mit\",\n library_name=\"timm\",\n tags=['image-classification', 'resnet'],\n)\n\ncard = ModelCard.from_template(card_data, model_description=\"This model does x + y...\")\n```\n\n资料来源：[src/huggingface_hub/repocard.py:1-100]()\n\n## 认证机制\n\nHugging Face Hub 使用令牌（Token）进行身份验证：\n\n```bash\n# CLI 登录\nhf auth login\n```\n\n登录后，令牌会存储在本地，供后续 API 调用使用。\n\n资料来源：[i18n/README_hi.md:1-30]()\n\n## 项目配置\n\n### 入口点配置\n\nsetup.py 中定义的命令行入口点：\n\n| 命令 | 模块 | 说明 |\n|-----|------|------|\n| hf | huggingface_hub.cli.hf | 主要 CLI 工具 |\n| huggingface-cli | huggingface_hub.cli.deprecated_cli | 已废弃的 CLI |\n| tiny-agents | huggingface_hub.inference._mcp.cli | Tiny Agents 工具 |\n\n资料来源：[setup.py:30-40]()\n\n### 文件系统集成\n\n库通过 fsspec 提供了统一的文件系统接口：\n\n```python\n# fsspec.specs 入口点\nfsspec.specs: hf=huggingface_hub.HfFileSystem\n```\n\n## 依赖项\n\n### 核心依赖\n\n| 依赖包 | 说明 |\n|-------|------|\n| filelock | 文件锁支持 |\n| fsspec | 文件系统抽象 |\n| huggingface_hub | 核心包 |\n| packaging | 版本解析 |\n| pyyaml | YAML 处理 |\n| requests | HTTP 请求 |\n| tqdm | 进度条 |\n\n### 可选依赖\n\n| 额外依赖组 | 包含内容 |\n|----------|---------|\n| inference | 推理功能完整支持 |\n\n资料来源：[setup.py:1-30]()\n\n## 第三方集成\n\nHugging Face 与多个开源 ML 库合作，提供免费的模型托管和版本控制服务。这些集成库包括 PyTorch、TensorFlow、Transformers 等主流深度学习框架。\n\n资料来源：[i18n/README_fr.md:50-80]()\n\n## 技术规格\n\n| 规格 | 要求 |\n|-----|------|\n| Python 版本 | >= 3.10.0 |\n| 许可证 | Apache-2.0 |\n| 包管理 | setuptools |\n\n资料来源：[setup.py:40-50]()\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [src/huggingface_hub/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n- [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n- [src/huggingface_hub/_inference_endpoints.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_inference_endpoints.py)\n \n\n# 安装指南\n\n## 概述\n\n`huggingface_hub` 是 Hugging Face 官方提供的客户端库，用于下载和发布模型、数据集以及其他仓库到 huggingface.co Hub。该库为开发者提供了与 Hugging Face Hub 进行交互的统一接口，支持文件下载上传、模型推理、仓库管理等功能。资料来源：[setup.py:44]()\n\n## 系统要求\n\n### Python 版本要求\n\n| 要求项 | 最低版本 |\n|--------|----------|\n| Python | 3.10.0 |\n\n`huggingface_hub` 仅支持 Python 3.10 及以上版本。在安装前，请确保您的 Python 环境满足版本要求。\n\n```bash\npython --version # 确认 Python 版本 >= 3.10.0\n```\n\n资料来源：[setup.py:49]()\n\n## 安装方式\n\n### 基本安装\n\n使用 pip 安装 `huggingface_hub` 的稳定版本：\n\n```bash\npip install huggingface_hub\n```\n\n### 包含可选依赖的安装\n\n根据使用场景，可以选择安装不同的可选依赖组：\n\n| 安装命令 | 包含内容 | 使用场景 |\n|----------|----------|----------|\n| `pip install huggingface_hub[inference]` | 推理相关功能 | 使用模型推理功能 |\n| `pip install huggingface_hub[all]` | 所有可选依赖 | 完整功能体验 |\n| `pip install huggingface_hub[testing]` | 测试相关依赖 | 运行单元测试 |\n| `pip install huggingface_hub[quality]` | 代码质量工具 | 代码检查和格式化 |\n| `pip install huggingface_hub[typing]` | 类型检查工具 | 类型注解验证 |\n| `pip install huggingface_hub[dev]` | 所有开发依赖 | 本地开发环境 |\n\n资料来源：[i18n/README_ko.md:1]()\n\n### 从源码安装\n\n如需安装最新开发版本，可直接从 GitHub 仓库安装：\n\n```bash\npip install git+https://github.com/huggingface/huggingface_hub.git\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|基本安装| C[pip install huggingface_hub]\n B -->|推理功能| D[pip install huggingface_hub inference]\n B -->|完整开发| E[pip install huggingface_hub[dev]]\n B -->|源码安装| F[git+https://github.com/huggingface/huggingface_hub.git]\n C --> G{验证安装}\n D --> G\n E --> G\n F --> G\n G -->|成功| H[安装完成]\n G -->|失败| I[检查 Python 版本和依赖]\n```\n\n## 核心依赖项\n\n`huggingface_hub` 的核心功能依赖以下主要包：\n\n| 依赖包 | 用途说明 |\n|--------|----------|\n| `filelock` | 文件锁机制，用于缓存管理 |\n| `fsspec` | 文件系统规范实现 |\n| `httpx` | HTTP 客户端库 |\n| `huggingface_hub` 自身 | 核心功能模块 |\n| `pyyaml` | YAML 配置文件解析 |\n| `tqdm` | 进度条显示 |\n\n这些依赖会在安装 `huggingface_hub` 时自动安装。\n\n资料来源：[setup.py:1-20]()\n\n## CLI 命令行工具\n\n安装完成后，系统会自动注册以下命令行工具：\n\n| 命令 | 来源 | 功能说明 |\n|------|------|----------|\n| `hf` | huggingface_hub.cli.hf | 主 CLI 入口 |\n| `huggingface-cli` | huggingface_hub.cli.deprecated_cli | 传统 CLI 工具（已弃用） |\n| `tiny-agents` | huggingface_hub.inference._mcp.cli | MCP 推理代理工具 |\n\n```bash\n# 登录 Hugging Face\nhf auth login\n\n# 使用 huggingface-cli（已弃用）\nhuggingface-cli login\n```\n\n资料来源：[setup.py:50-53]()\n\n## 验证安装\n\n安装完成后，可以通过以下方式验证：\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 测试基本功能\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n```\n\n如果安装正确，会返回缓存的文件路径或开始下载文件。\n\n## 推理功能安装\n\n如果需要使用模型推理功能（如文本生成、图像生成等），必须安装 `inference` 可选依赖：\n\n```bash\npip install huggingface_hub[inference]\n```\n\n推理功能支持的特性包括：\n\n- 文本补全 (Text Completion)\n- 聊天完成 (Chat Completion)\n- 文本转图像 (Text to Image)\n- 文本转视频 (Text to Video)\n- 图像特征提取\n- 零样本分类\n\n资料来源：[src/huggingface_hub/inference/_client.py:1]()\n\n## 与 Hub 集成\n\n`huggingface_hub` 与多个开源机器学习库有官方集成，包括 Transformers、Diffusers、AllenNLP 等。这种集成提供了以下优势：\n\n- **无缝下载**：无需手动管理模型文件\n- **版本控制**：自动追踪模型和数据版本\n- **缓存管理**：统一的本地缓存机制\n\n可以通过官方文档查看完整的库集成列表：https://huggingface.co/docs/hub/libraries\n\n## 常见问题\n\n### Python 版本不满足\n\n确保使用 Python 3.10.0 或更高版本：\n\n```bash\n# 使用 python3.10 或更高版本创建虚拟环境\npython3.10 -m venv hf_env\nsource hf_env/bin/activate # Linux/Mac\n# 或\nhf_env\\Scripts\\activate # Windows\n```\n\n### 可选依赖安装失败\n\n如果某些可选依赖（如 tensorflow、torch 等）安装失败，可以单独安装核心库后再按需安装：\n\n```bash\npip install huggingface_hub\n# 按需安装特定依赖\npip install torch # 如需 PyTorch 支持\n```\n\n### 缓存目录权限问题\n\n首次使用时，`huggingface_hub` 会在本地缓存模型文件。确保缓存目录有写入权限。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[模块结构详解](#module-structure), [项目介绍](#introduction)\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- [src/huggingface_hub/constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.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- [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.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/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.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- [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.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 \n\n# 系统架构\n\n## 概述\n\nhuggingface_hub 是一个用于与 Hugging Face Hub 交互的 Python 客户端库，提供模型、数据集和 Space 的下载、上传、管理功能。库采用模块化设计，核心逻辑分散在多个专用模块中，通过 `__init__.py` 统一导出公共 API。\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 整体架构图\n\n```mermaid\ngraph TD\n subgraph 公共API层\n INIT[__init__.py - 公共接口]\n end\n \n subgraph 核心业务模块\n HF_API[hf_api.py - HfApi主类]\n REPO_CARD[repocard.py - 卡片管理]\n FILE_DOWNLOAD[file_download.py - 文件下载]\n COMMIT[_commit_api.py - 提交操作]\n HF_FS[hf_file_system.py - 文件系统]\n end\n \n subgraph 高级功能模块\n HUB_MIXIN[hub_mixin.py - 模型混入]\n INFERENCE[inference - 推理客户端]\n SPACE[_space_api.py - Space运行时]\n INFERENCE_EP[_inference_endpoints.py - 推理端点]\n end\n \n subgraph 工具模块\n URI[_hf_uris.py - URI解析]\n LFS[lfs.py - LFS上传]\n LOGIN[_login.py - 认证管理]\n COMMUNITY[community.py - 社区功能]\n end\n \n INIT --> HF_API\n INIT --> REPO_CARD\n INIT --> FILE_DOWNLOAD\n HF_API --> COMMIT\n HF_API --> HF_FS\n```\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 模块结构\n\n### 核心模块清单\n\n| 模块文件 | 主要类/函数 | 功能描述 |\n|---------|-----------|---------|\n| `__init__.py` | 公共API导出 | 静态导入自动生成，统一对外接口 |\n| `hf_api.py` | `HfApi` | 主API类，实现Repo CRUD、上传下载、讨论、PR、集合等 |\n| `file_download.py` | `hf_hub_download` | 单文件下载、缓存逻辑、ETag解析、xet下载支持 |\n| `_snapshot_download.py` | `snapshot_download` | 整仓库下载 |\n| `_commit_api.py` | `CommitOperationAdd/Delete/Copy` | 低级提交操作、LFS上传处理 |\n| `_commit_scheduler.py` | 后台提交调度 | 定时提交功能 |\n| `_upload_large_folder.py` | 大文件夹分块上传 | 超大文件夹上传 |\n| `hf_file_system.py` | `HfFileSystem` | 基于fsspec的POSIX兼容文件系统 |\n| `hub_mixin.py` | `ModelHubMixin` | ML框架集成基类 |\n| `repocard.py` | `RepoCard`, `ModelCard`, `DatasetCard`, `SpaceCard` | 仓库卡片管理 |\n| `repocard_data.py` | `CardData`, `ModelCardData` | 卡片元数据 |\n| `community.py` | `Discussion`, `DiscussionComment` | 讨论与评论 |\n| `lfs.py` | Git LFS工具 | LFS批量上传 |\n| `_login.py` | `login()`, `logout()` | 认证和令牌管理 |\n| `_inference_endpoints.py` | 推理端点管理 | 端点CRUD和扩缩容 |\n| `_jobs_api.py` | 训练任务API | 训练任务管理 |\n| `_space_api.py` | Space运行时 | Space运行管理 |\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 主要组件详解\n\n### HfApi 主类\n\n`HfApi` 是库的核心类，约11000行代码，承载了大多数 Hub 操作。\n\n**主要功能分类：**\n\n- 仓库CRUD操作（创建、删除、列表、详情）\n- 文件上传下载\n- Discussions 和 Pull Requests\n- Collections 管理\n- 模型卡片操作\n- 用户和组织管理\n\n```python\n# 使用示例\nfrom huggingface_hub import HfApi\napi = HfApi()\napi.upload_file(...)\napi.list_models(...)\n```\n\n资料来源：[hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### RepoCard 体系\n\n仓库卡片（RepoCard）用于管理 Hugging Face 仓库的元数据和文档。\n\n```mermaid\nclassDiagram\n class RepoCard {\n +content: str\n +data: CardData\n +text: str\n +ignore_metadata_errors: bool\n }\n \n class CardData {\n +to_dict()\n +to_yaml()\n }\n \n class ModelCard {\n +card_data_class = ModelCardData\n }\n \n class DatasetCard {\n +card_data_class = DatasetCardData\n }\n \n class SpaceCard {\n +card_data_class = SpaceCardData\n +repo_type = \"space\"\n }\n \n RepoCard <|-- ModelCard\n RepoCard <|-- DatasetCard\n RepoCard <|-- SpaceCard\n RepoCard --> CardData\n```\n\n**卡片类型与默认模板：**\n\n| 卡片类型 | repo_type | 用途 |\n|--------|-----------|-----|\n| `ModelCard` | model | 模型元数据 |\n| `DatasetCard` | dataset | 数据集元数据 |\n| `SpaceCard` | space | Space应用元数据 |\n\n资料来源：[repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n资料来源：[repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n\n### EvalResultEntry 评估结果\n\n评估结果数据结构用于存储和上传模型评估指标。\n\n```python\n@dataclass\nclass EvalResultEntry:\n dataset_id: str # 数据集ID\n task_id: str # 任务ID\n value: Any # 评估值\n dataset_revision: str | None # 数据集版本\n verify_token: str | None # 验证令牌\n date: str | None # 评估日期\n source_url: str | None # 来源URL\n source_name: str | None # 来源名称\n source_user: str | None # 来源用户\n source_org: str | None # 来源组织\n notes: str | None # 备注\n```\n\n**验证规则：** 如果提供了 `source_name`、`source_user` 或 `source_org`，则必须同时提供 `source_url`。\n\n资料来源：[_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n\n### HfUri URI解析\n\n`HfUri` 是一个不可变数据类，用于解析 Hugging Face 特有的 URI 格式。\n\n**URI格式：**\n```\nhf://[/][@][/]\n```\n\n**支持的类型前缀：**\n\n| 类型 | URI前缀 | 示例 |\n|-----|--------|------|\n| model | 无/空 | `hf://my-org/my-model` |\n| dataset | datasets | `hf://datasets/my-org/my-dataset` |\n| space | spaces | `hf://spaces/my-org/my-space` |\n\n**特殊版本处理：** 支持 `refs/pr/N`（PR引用）和 `refs/convert/`（转换引用）格式。\n\n```python\n@dataclass(frozen=True)\nclass HfUri:\n type: str # URI类型\n id: str # 仓库ID\n revision: str | None # 版本号\n path_in_repo: str # 仓库内路径\n```\n\n资料来源：[utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n\n### HfFileSystem 文件系统\n\n`HfFileSystem` 基于 fsspec 实现，提供 POSIX 兼容的文件系统接口访问 Hub 仓库。\n\n```python\n# entry_points配置\nentry_points={\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\n**核心功能：**\n- 像本地文件系统一样操作远程仓库\n- 支持目录遍历、文件读写\n- 自动处理 LFS 文件\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n### Commit 操作体系\n\n`_commit_api.py` 实现了底层的 Git 提交操作。\n\n```mermaid\nclassDiagram\n class CommitOperation {\n <>\n }\n \n class CommitOperationAdd {\n +path_in_repo: str\n +path_or_fileobj: str | Path | bytes\n +rfc: str\n +uploaded: bool\n +as_file()\n }\n \n class CommitOperationDelete {\n +path_in_repo: str\n +is_file: bool\n }\n \n class CommitOperationCopy {\n +src_repo_id: str\n +src_path_in_repo: str\n +dest_path_in_repo: str\n }\n \n CommitOperation <|-- CommitOperationAdd\n CommitOperation <|-- CommitOperationDelete\n CommitOperation <|-- CommitOperationCopy\n```\n\n**上传方式支持：**\n\n| 类型 | 方式 | 说明 |\n|-----|------|-----|\n| 普通文件 | 直接上传 | 小文件直接提交 |\n| LFS文件 | Git LFS | 大文件通过LFS处理 |\n| 文件夹 | 分块上传 | `_upload_large_folder.py` |\n\n资料来源：[_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n\n### ModelHubMixin 框架集成\n\n`ModelHubMixin` 是机器学习框架集成的基类，允许模型直接保存和加载到 Hub。\n\n**支持的参数：**\n\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| `base_model` | str | 基础模型ID |\n| `model_name` | str | 模型名称 |\n| `library_name` | str | 库名称 |\n| `pipeline_tag` | str | 流水线标签 |\n| `language` | str \\| list | 支持语言 |\n| `license` | str | 许可证 |\n| `tags` | list | 标签列表 |\n\n资料来源：[hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n\n### 推理客户端\n\n推理客户端提供对部署模型的远程推理功能。\n\n**主要输出类型：**\n\n- `TextGenerationOutput` - 文本生成输出\n- `TextGenerationDetails` - 详细生成信息\n- `TextGenerationStreamOutput` - 流式输出\n- `TokenElement` - Token元素\n\n**功能特性：**\n- 同步和异步客户端\n- 流式输出支持\n- 详细日志概率信息\n\n资料来源：[inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py)\n\n## 常量定义\n\n`constants.py` 定义了全局常量，包括：\n\n- `HF_PROTOCOL` - URI协议前缀 (`hf://`)\n- `HF_URI_TYPE_PREFIXES` - 类型到前缀的映射\n- 默认配置值\n\n资料来源：[constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py)\n\n## 包依赖结构\n\n### 可选依赖分组\n\n| 分组 | 依赖 | 用途 |\n|-----|------|-----|\n| inference | inference 相关包 | 推理功能 |\n| testing | pytest 等 | 测试 |\n| quality | mypy, ruff | 代码质量 |\n| typing | libcst, ty | 类型检查 |\n| all | testing + quality + typing | 全量开发依赖 |\n\n```python\nextras[\"all\"] = extras[\"testing\"] + extras[\"quality\"] + extras[\"typing\"]\nextras[\"dev\"] = extras[\"all\"]\n```\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## 入口点配置\n\nCLI 入口点和文件系统规范注册：\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\", # 主CLI\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\", # 废弃CLI\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\", # Agent应用\n ],\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\", # 文件系统\n}\n```\n\n**最低Python版本：** `>=3.10.0`\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## 公共API导出机制\n\n`__init__.py` 中的静态导入由 `utils/check_static_imports.py` 自动生成。运行 `make style` 可更新导出列表。\n\n```mermaid\nflowchart LR\n A[源码文件] --> B[check_static_imports.py]\n B --> C[自动生成]\n C --> D[__init__.py]\n D --> E[公共API]\n```\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 认证与令牌管理\n\n`_login.py` 模块处理身份认证：\n\n- `login()` - 登录并保存令牌\n- `logout()` - 登出并清除令牌\n- `notebook_login()` - Jupyter notebook 登录\n\n资料来源：[_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n\n\n## 模块结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [文件操作](#file-operations)\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/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_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/community.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/community.py)\n \n\n# 模块结构详解\n\n## 概述\n\n`huggingface_hub` 是 Hugging Face 官方提供的 Python 客户端库，用于与 Hugging Face Hub 进行交互。该库采用模块化架构设计，核心功能围绕模型仓库（Model Repository）的操作展开，包括文件下载、上传、仓库管理、社区互动等关键能力。资料来源：[README.md]()\n\n## 核心模块架构\n\n`huggingface_hub` 的源代码位于 `src/huggingface_hub/` 目录下，采用以下主要模块划分：\n\n```mermaid\ngraph TD\n A[huggingface_hub] --> B[hf_api.py]\n A --> C[file_download.py]\n A --> D[_commit_api.py]\n A --> E[community.py]\n A --> F[repocard.py]\n A --> G[inference]\n A --> H[utils]\n \n B -->|HTTP API| I[Hub交互层]\n C --> J[文件系统层]\n D --> I\n E --> K[社区功能]\n```\n\n### 主要模块职责\n\n| 模块文件 | 主要职责 |\n|---------|---------|\n| `hf_api.py` | 封装所有 Hugging Face Hub HTTP API 调用 |\n| `file_download.py` | 处理文件下载、缓存管理、快照下载 |\n| `_commit_api.py` | 实现 Git 风格的提交操作、文件上传 |\n| `community.py` | 处理社区评论、讨论、投票等互动功能 |\n| `repocard.py` | 解析和生成 Model Card / Dataset Card |\n| `inference/` | 推理 API 客户端集成 |\n| `utils/` | URI 解析、验证器等工具函数 |\n\n资料来源：[setup.py]()、[src/huggingface_hub/repocard.py]()\n\n---\n\n## hf_api.py - Hub API 封装层\n\n### 功能概述\n\n`hf_api.py` 是整个库的核心模块，负责封装所有与 Hugging Face Hub 的 HTTP API 通信。该模块提供了创建仓库、删除仓库、列表查询、上传文件、下载文件等原子操作。资料来源：[src/huggingface_hub/hf_api.py]()\n\n### 核心功能分类\n\n#### 仓库管理 API\n\n- `create_repo()` - 创建新仓库\n- `delete_repo()` - 删除仓库\n- `update_repo_visibility()` - 更新仓库可见性\n- `move_repo()` - 移动仓库\n\n#### 文件操作 API\n\n- `upload_file()` - 单文件上传\n- `upload_folder()` - 文件夹上传\n- `get_hub_wизм()` - 获取仓库信息\n- `list_repo_files()` - 列出仓库文件\n\n#### 模型/数据集/空间管理\n\n- `list_models()` - 搜索模型列表\n- `list_datasets()` - 搜索数据集列表\n- `list_spaces()` - 搜索 Spaces 列表\n- `get_model_tags()` - 获取模型标签\n\n资料来源：[src/huggingface_hub/hf_api.py]()\n\n---\n\n## file_download.py - 文件下载与缓存系统\n\n### 功能概述\n\n`file_download.py` 实现了高效的文件下载和缓存管理机制，支持单个文件下载和整个仓库的快照下载。所有下载的文件都会缓存在本地文件系统中，避免重复下载。资料来源：[README.md]()\n\n### 下载流程\n\n```mermaid\ngraph TD\n A[开始下载请求] --> B{检查本地缓存}\n B -->|缓存命中| C[返回缓存文件路径]\n B -->|缓存未命中| D[发起HTTP请求]\n D --> E{检查增量更新}\n E -->|有更新| F[下载增量内容]\n E -->|无更新| G[下载完整文件]\n F --> H[更新缓存]\n G --> H\n H --> I[返回文件路径]\n```\n\n### 核心函数\n\n| 函数名 | 功能描述 |\n|--------|---------|\n| `hf_hub_download()` | 下载单个文件到指定路径 |\n| `snapshot_download()` | 下载整个仓库的快照 |\n| `get_hub_blobs()` | 获取文件 blob 列表 |\n| `get_hub_fs()` | 获取 HfFileSystem 实例 |\n\n### 缓存机制\n\n库使用 `~/.cache/huggingface/hub/` 作为默认缓存目录，每个仓库的文件根据 repo_id 和 revision 进行组织。资料来源：[src/huggingface_hub/file_download.py]()\n\n---\n\n## _commit_api.py - Git 风格提交系统\n\n### 功能概述\n\n`_commit_api.py` 实现了基于 Git 的仓库提交操作，这是 Hugging Face Hub 的核心特性之一。该模块支持原子性的多文件提交操作，并提供了进度跟踪和文件预览功能。资料来源：[src/huggingface_hub/_commit_api.py]()\n\n### 提交操作架构\n\n```mermaid\ngraph LR\n A[CommitOperation] --> B[CommitOperationAdd]\n A --> C[CommitOperationDelete]\n \n D[preupload] --> E[验证文件]\n E --> F[计算 LFS 差异]\n F --> G[创建提交]\n \n H[CommitWorker] --> I[分块上传]\n I --> J[更新仓库树]\n J --> K[完成提交]\n```\n\n### 核心类\n\n#### CommitOperation\n\n文件操作的基类，支持以下操作类型：\n\n| 类型 | 说明 |\n|-----|------|\n| `CommitOperationAdd` | 添加或更新文件 |\n| `CommitOperationDelete` | 删除文件 |\n\n#### CommitOperationAdd 关键方法\n\n```python\ndef as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]:\n \"\"\"将本地文件对象转换为可迭代的字节流，支持进度条\"\"\"\n```\n\n该方法支持三种输入类型：\n\n- 字符串或 Path 对象（本地文件路径）\n- bytes（字节数据）\n- BufferedIOBase（已打开的文件对象）\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-50]()\n\n### 提交流程\n\n1. **预上传阶段** (`preupload_hub_metadata`)：验证文件大小、计算 LFS 指针\n2. **文件上传阶段**：分块上传普通文件，LFS 跟踪大文件\n3. **提交创建阶段**：构建提交树，创建 Git 提交\n4. **元数据更新**：更新仓库标签、卡片等元信息\n\n资料来源：[src/huggingface_hub/_commit_api.py]()\n\n---\n\n## community.py - 社区互动模块\n\n### 功能概述\n\n`community.py` 模块处理 Hugging Face Hub 的社区功能，包括评论、讨论帖、投票和 PR 评论等交互功能。这些功能使用统一的 `Discussion` 和 `Comment` 数据模型进行抽象。资料来源：[src/huggingface_hub/community.py]()\n\n### 社区功能类型\n\n| 功能 | API 方法前缀 | 说明 |\n|-----|-------------|------|\n| Discussion | `create_discussion()` | 创建讨论帖 |\n| Comment | `comment_discussion()` | 评论讨论 |\n| PR Review | `create_pull_request_review()` | PR 评审 |\n| Vote | `vote_discussion()` | 对讨论投票 |\n\n### 数据模型\n\n社区模块使用 Pydantic 或 dataclass 风格的数据类定义：\n\n- `DiscussionTitle`：讨论标题\n- `DiscussionComment`：单条评论\n- `DiscussionStatus`：讨论状态（open/closed/merged）\n\n资料来源：[src/huggingface_hub/community.py]()\n\n---\n\n## 协作流程示例\n\n### 文件上传到下载的完整流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant hf_api\n participant file_download\n participant _commit_api\n participant Hub\n \n Client->>hf_api: create_repo()\n Hub-->>hf_api: repo_id\n hf_api-->>Client: 仓库创建成功\n \n Client->>_commit_api: CommitOperationAdd()\n Client->_commit_api: commit_add_files()\n _commit_api->>Hub: Git Push\n Hub-->>_commit_api: Commit SHA\n _commit_api-->>Client: 上传完成\n \n Client->>file_download: snapshot_download()\n file_download->>Hub: HEAD 请求\n Hub-->>file_download: 文件列表\n file_download->>Hub: 分块下载\n Hub-->>file_download: 文件内容\n file_download-->>Client: 本地缓存路径\n```\n\n资料来源：[README.md]()、[src/huggingface_hub/_commit_api.py]()\n\n---\n\n## 包结构与入口点\n\n### setup.py 配置\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\",\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\",\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\",\n ],\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\n### CLI 命令\n\n| 命令 | 功能 |\n|-----|------|\n| `hf auth login` | 登录认证 |\n| `hf download` | 下载文件 |\n| `hf upload` | 上传文件 |\n| `hf spaces` | Space 管理 |\n\n### 可选依赖\n\n| Extra | 包含功能 |\n|-------|---------|\n| `inference` | 推理 API 支持 |\n| `mcp` | MCP 服务器功能 |\n| `testing` | 测试工具 |\n\n资料来源：[setup.py]()\n\n---\n\n## 关键设计模式\n\n### 1. 仓库类型统一抽象\n\n库通过 `repo_type` 参数统一抽象模型、数据集和 Space：\n\n```python\nrepo_type: Literal[\"model\", \"dataset\", \"space\"]\n```\n\n### 2. 异步与同步双支持\n\n核心 API 同时提供同步和异步版本：\n\n- 同步：`hf_hub_download()`\n- 异步：`AsyncInferenceClient`\n\n### 3. 文件系统抽象\n\n通过 `HfFileSystem` 提供类似本地文件系统的操作体验：\n\n```python\nfs = HfFileSystem()\nfs.ls(\"my-org/my-model\")\n```\n\n资料来源：[src/huggingface_hub/file_download.py]()\n\n---\n\n## 总结\n\n`huggingface_hub` 采用清晰的模块化架构，通过 `hf_api.py` 封装底层 HTTP 通信，`file_download.py` 实现高效的文件缓存，`_commit_api.py` 提供 Git 风格的版本控制能力，`community.py` 处理社区互动。这种设计使得库既保持了功能的完整性，又便于维护和扩展。\n\n---\n\n\n\n## 文件操作\n\n### 相关页面\n\n相关主题：[缓存系统](#cache-system), [Git LFS 集成](#lfs-integration)\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/_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 \n\n# 文件操作\n\n## 概述\n\nhuggingface_hub 库提供了完整的文件操作功能，涵盖从 Hugging Face Hub 下载文件、上传文件、以及通过类文件系统接口操作仓库内容。这些功能是该库的核心能力之一，使得用户能够方便地与 Hub 上的模型、数据集和 Space 进行交互。\n\n文件操作主要通过以下模块实现：\n\n| 模块 | 核心功能 |\n|------|----------|\n| `file_download.py` | 单文件下载、ETag 缓存、xet 支持 |\n| `_snapshot_download.py` | 完整仓库快照下载 |\n| `_commit_api.py` | 文件上传、删除、复制操作 |\n| `hf_file_system.py` | 基于 fsspec 的 POSIX 风格文件系统 |\n\n## 文件下载\n\n### hf_hub_download - 单文件下载\n\n`hf_hub_download` 是下载单个文件的核心函数，支持完整的缓存机制和元数据解析。\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 基础下载\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n\n# 指定版本和本地路径\nhf_hub_download(\n repo_id=\"username/my-model\",\n filename=\"pytorch_model.bin\",\n subfolder=\"weights\",\n revision=\"main\",\n local_dir=\"./models\"\n)\n```\n\n#### 核心参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `repo_id` | str | 仓库标识符 (格式: `username/model-name`) |\n| `filename` | str | 要下载的文件名 |\n| `subfolder` | str, optional | 文件所在的子文件夹 |\n| `revision` | str, optional | Git 分支名或提交哈希，默认 `main` |\n| `repo_type` | str, optional | 仓库类型：`model`、`dataset`、`space` |\n| `cache_dir` | str, optional | 缓存目录路径 |\n| `local_dir` | str, optional | 本地目录，下载后文件将复制到此 |\n| `local_dir_use_symlinks` | str/bool | 符号链接策略：`\"auto\"`、`True`、`False` |\n| `force_download` | bool | 是否强制重新下载 |\n| `etag` | str, optional | 用于缓存验证的 ETag |\n\n### 缓存机制\n\n文件下载后会自动缓存到本地，缓存路径默认为 `~/.cache/huggingface/hub`。库使用 ETag 和 Last-Modified 头进行条件请求，避免重复下载。\n\n```mermaid\ngraph TD\n A[请求下载] --> B{检查本地缓存}\n B -->|存在且有效| C[返回缓存文件]\n B -->|不存在或过期| D[发送 HTTP 请求]\n D --> E{Hub 返回 304}\n E -->|是| C\n E -->|否| F[下载新文件]\n F --> G[更新缓存]\n G --> H[返回文件路径]\n```\n\n### xet 下载支持\n\n对于支持 xet 协议的文件，系统会使用 xet 协议进行流式下载，提高大文件的下载效率。资料来源：[file_download.py:1-100]()\n\n### snapshot_download - 仓库快照下载\n\n`snapshot_download` 用于下载整个仓库的所有文件，确保所有文件来自同一修订版本。\n\n```python\nfrom huggingface_hub import snapshot_download\n\n# 下载整个模型仓库\nsnapshot_download(\"stabilityai/stable-diffusion-2-1\")\n\n# 带有过滤条件\nsnapshot_download(\n repo_id=\"my-dataset\",\n repo_type=\"dataset\",\n allow_patterns=[\"*.json\", \"*.csv\"],\n ignore_patterns=[\"*.parquet\"]\n)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `repo_id` | str | 必填 | 仓库标识符 |\n| `repo_type` | str | `\"model\"` | 仓库类型 |\n| `revision` | str | `None` | Git 修订版本 |\n| `cache_dir` | str | `None` | 缓存目录 |\n| `local_dir` | str | `None` | 本地目录 |\n| `allow_patterns` | list[str] | `None` | 包含文件模式 |\n| `ignore_patterns` | list[str] | `None` | 排除文件模式 |\n| `max_workers` | int | `8` | 最大并发下载数 |\n| `tqdm` | callable | `tqdm.auto` | 进度条工厂函数 |\n\n资料来源：[_snapshot_download.py:1-150]()\n\n## 文件上传\n\n### 核心上传函数\n\nhuggingface_hub 支持多种文件上传方式：\n\n#### upload_file - 单文件上传\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/path/to/local/model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"username/my-model\",\n)\n```\n\n#### upload_folder - 文件夹上传\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=\"Add new files\"\n)\n```\n\n### CommitOperation 机制\n\n底层文件操作通过 `CommitOperation` 类实现，支持原子性操作：\n\n```python\nfrom huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete\n\napi = HfApi()\n\n# 添加文件操作\noperations = [\n CommitOperationAdd(\n path_in_repo=\"README.md\",\n path_or_fileobj=\"/local/README.md\"\n ),\n CommitOperationDelete(\n path_in_repo=\"old_file.txt\"\n )\n]\n\n# 批量提交\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Update model files\"\n)\n```\n\n#### CommitOperationAdd\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `path_in_repo` | str | 仓库中的目标路径 |\n| `path_or_fileobj` | str/bytes/IOBase | 本地文件或字节数据 |\n\n资料来源：[_commit_api.py:1-100]()\n\n#### CommitOperationDelete\n\n```python\nCommitOperationDelete(path_in_repo=\"obsolete/model.bin\")\n```\n\n#### CommitOperationCopy\n\n```python\nCommitOperationCopy(\n src_path_in_repo=\"path/to/source/file\",\n dest_path_in_repo=\"path/to/destination/file\"\n)\n```\n\n### LFS 大文件处理\n\n大于 10MB 的文件会自动使用 Git LFS (Large File Storage) 处理：\n\n```mermaid\ngraph TD\n A[上传文件] --> B{文件大小 > 10MB?}\n B -->|否| C[普通 Git 对象]\n B -->|是| D[Git LFS 处理]\n D --> E[上传 LFS 对象]\n E --> F[创建 LFS 指针文件]\n C --> G[创建 commit]\n F --> G\n```\n\n## HfFileSystem - 文件系统接口\n\n`HfFileSystem` 提供了 POSIX 风格的文件系统接口，基于 fsspec 规范实现，使开发者能够像操作本地文件一样操作 Hub 仓库。\n\n### 基本用法\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出仓库文件\nfiles = fs.ls(\"username/my-model\")\n\n# 读取文件\nwith fs.open(\"username/my-model/config.json\", \"r\") as f:\n content = f.read()\n\n# 检查文件存在\nif fs.exists(\"username/my-model/pytorch_model.bin\"):\n print(\"Model file exists\")\n```\n\n### 支持的操作\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 读取 | `cat()`, `read_block()` | 获取文件内容 |\n| 写入 | `pipe()`, `write_block()` | 写入文件内容 |\n| 列表 | `ls()`, `glob()` | 列出文件/目录 |\n| 属性 | `info()`, `ls()` | 获取文件元数据 |\n| 创建 | `makedirs()` | 创建目录 |\n| 删除 | `rm()` | 删除文件/目录 |\n| 移动 | `mv()` | 移动/重命名 |\n| 复制 | `cp()` | 复制文件 |\n| 链接 | `symlink()` | 创建符号链接 |\n\n### URI 格式\n\nHfFileSystem 支持 `hf://` URI 协议：\n\n```\nhf://{repo_id}@{revision}/{path_in_repo}[:mount_path[:ro|:rw]]\n```\n\n示例：\n\n```python\n# 标准格式\nfs = HfFileSystem()\nfs.ls(\"hf://username/my-model@main/weights\")\n\n# 带挂载点\nfs = HfFileSystem()\nfs.get(\"hf://username/model@refs/pr/1/weights\", \"/local/weights\")\n```\n\n资料来源：[hf_file_system.py:1-200]()\n\n## HubMixin 集成\n\n`ModelHubMixin` 类为 ML 框架提供了与 Hub 集成的基类支持自动化的模型保存和加载。\n\n```python\nfrom huggingface_hub import ModelHubMixin\n\nclass MyModel(ModelHubMixin, nn.Module):\n def __init__(self):\n super().__init__()\n self.layer = nn.Linear(10, 2)\n \n @classmethod\n def _from_pretrained(cls, **kwargs):\n # 自定义加载逻辑\n return cls()\n \n def _save_pretrained(self, save_directory):\n # 自定义保存逻辑\n torch.save(self.state_dict(), f\"{save_directory}/model.bin\")\n```\n\n支持的参数包括：\n\n| 参数 | 说明 |\n|------|------|\n| `model_id` | 模型标识符或本地路径 |\n| `cache_dir` | 缓存目录 |\n| `force_download` | 强制重新下载 |\n| `resume_download` | 断点续传 |\n| `proxies` | 代理设置 |\n| `token` | 认证令牌 |\n\n资料来源：[hub_mixin.py:1-100]()\n\n## 错误处理\n\n文件操作过程中可能遇到的常见错误：\n\n| 错误类型 | 说明 |\n|----------|------|\n| `RepositoryNotFoundError` | 指定的仓库不存在 |\n| `RevisionNotFoundError` | 指定的修订版本不存在 |\n| `EntryNotFoundError` | 文件或目录不存在 |\n| `LocalEntryNotFoundError` | 缓存中找不到文件 |\n| `HfHubHTTPError` | HTTP 请求失败 |\n| `HuggingFaceHubValidationError` | 参数验证失败 |\n\n## 最佳实践\n\n1. **缓存利用**：优先使用默认缓存机制，避免重复下载\n2. **版本锁定**：生产环境中建议指定具体的 `revision` 以确保可复现性\n3. **并发控制**：使用 `max_workers` 参数控制下载并发数\n4. **符号链接**：在开发环境中使用 `local_dir_use_symlinks=\"auto\"` 节省磁盘空间\n5. **大文件处理**：对于超过 5GB 的文件，考虑分块下载或使用 `as_file()` 上下文管理器\n\n```python\nfrom huggingface_hub import hf_hub_download, CommitOperationAdd\n\n# 使用上下文管理器处理大文件\noperation = CommitOperationAdd(\n path_in_repo=\"large_model.bin\",\n path_or_fileobj=\"./large_model.bin\"\n)\n\nwith operation.as_file(with_tqdm=True) as file:\n # 逐步处理文件内容\n while chunk := file.read(8192):\n process(chunk)\n\n---\n\n\n\n## 推理系统\n\n### 相关页面\n\n相关主题：[命令行工具](#cli-commands)\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_endpoints.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_inference_endpoints.py)\n- [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py)\n- [src/huggingface_hub/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n \n\n# 推理系统\n\n## 概述\n\nhuggingface_hub 的推理系统（Inference System）是一个用于在 Hugging Face Hub 上部署的模型上执行推理任务的客户端库。该系统提供了同步和异步两种客户端实现，支持多种推理任务类型，包括文本生成、文本摘要、文本到图像、文本到视频、翻译、图像问答等。\n\n推理系统的核心设计理念是通过统一的 API 接口，屏蔽不同推理提供商的实现差异，为用户提供简洁一致的推理调用体验。系统支持多种推理提供者（Provider），包括 Hugging Face 官方推理端点、Replicate 等第三方服务。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[InferenceClient / AsyncInferenceClient]\n B --> C[Provider Helper]\n C --> D{Hub Inference / 第三方 Provider}\n D --> E[远程推理端点]\n E --> F[模型推理结果]\n F --> B\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| InferenceClient | inference/_client.py | 同步推理客户端主类 |\n| AsyncInferenceClient | inference/_generated/_async_client.py | 异步推理客户端 |\n| Provider Helper | inference/_providers/__init__.py | 提供者适配层 |\n| InferenceEndpoints | _inference_endpoints.py | 推理端点管理 |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n## 客户端实现\n\n### InferenceClient（同步客户端）\n\nInferenceClient 是推理系统的主要入口点，提供同步推理能力。客户端初始化时可以指定模型、提供者和 API 密钥等配置。\n\n**初始化参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| model | str | 默认使用的模型 ID | None |\n| provider | str | 推理提供者名称 | None |\n| api_key | str | Hugging Face API 密钥 | None |\n| timeout | float | 请求超时时间（秒） | None |\n| headers | dict | 自定义 HTTP 头 | None |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### AsyncInferenceClient（异步客户端）\n\nAsyncInferenceClient 提供异步推理能力，适用于需要高并发的应用场景，如 Web 服务或批量处理系统。\n\n```python\n# 异步客户端使用示例\n>>> client = AsyncInferenceClient(\"meta-llama/Meta-Llama-3-70B-Instruct\")\n>>> messages = [\n... {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n... {\"role\": \"user\", \"content\": \"What is 2+2?\"}\n... ]\n>>> response = await client.chat_completion(messages)\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-100]()\n\n## 支持的推理任务\n\n### 文本生成（Text Generation）\n\n文本生成是推理系统最核心的功能之一，支持流式输出和详细令牌信息返回。\n\n**主要方法：** `text_generation(prompt, *, model=None, ...)`\n**返回类型：** TextGenerationOutput\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 输入提示文本 |\n| model | str | 模型 ID（可选） |\n| stream | bool | 是否启用流式输出 |\n| details | bool | 是否返回详细生成信息 |\n| max_new_tokens | int | 最大生成令牌数 |\n| temperature | float | 采样温度 |\n| top_p | float | 核采样概率 |\n\n**流式输出示例：**\n\n```python\n>>> for details in client.text_generation(\"The huggingface_hub library is \", max_new_tokens=12, stream=True):\n... print(details)\nTextGenerationStreamOutput(token=TokenElement(id=1425, text='100', ...))\nTextGenerationStreamOutput(token=TokenElement(id=16, text='%', ...))\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本摘要（Summarization）\n\n将长文本压缩为简短摘要的功能。\n\n**主要方法：** `summarization(text, *, model=None, ...)`\n**返回类型：** SummarizationOutput\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| text | str | 待摘要的输入文本 |\n| model | str | 摘要模型 ID |\n| clean_up_tokenization_spaces | bool | 清理分词空格 |\n| truncation | str | 截断策略 |\n| generate_parameters | dict | 生成参数配置 |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import InferenceClient\n>>> client = InferenceClient()\n>>> client.summarization(\"The Eiffel tower...\")\nSummarizationOutput(generated_text=\"The Eiffel tower is one of the most famous landmarks...\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本到图像（Text-to-Image）\n\n根据文本描述生成对应图像的功能。\n\n**主要方法：** `text_to_image(prompt, *, model=None, ...)`\n**返回类型：** PIL.Image\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 图像描述文本 |\n| model | str | 生成模型 ID |\n| negative_prompt | str | 负面提示词 |\n| height | int | 输出图像高度 |\n| width | int | 输出图像宽度 |\n| num_inference_steps | int | 推理步数 |\n| guidance_scale | float | 引导比例 |\n| seed | int | 随机种子 |\n\n**使用示例：**\n\n```python\n>>> client = InferenceClient(\n... provider=\"replicate\",\n... api_key=\"hf_...\",\n... )\n>>> image = client.text_to_image(\n... \"An astronaut riding a horse on the moon.\",\n... model=\"black-forest-labs/FLUX.1-schnell\",\n... )\n>>> image.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本到视频（Text-to-Video）\n\n根据文本描述生成对应视频的功能。\n\n**主要方法：** `text_to_video(prompt, *, model=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 视频描述文本 |\n| model | str | 生成模型 ID |\n| num_frames | float | 生成帧数 |\n| num_inference_steps | int | 推理步数 |\n| guidance_scale | float | 引导比例 |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 翻译（Translation）\n\n支持多语言之间的文本翻译任务。\n\n**主要方法：** `translation(text, *, model=None, src_lang=None, tgt_lang=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| text | str | 待翻译文本 |\n| model | str | 翻译模型 ID |\n| src_lang | str | 源语言代码 |\n| tgt_lang | str | 目标语言代码 |\n| clean_up_tokenization_spaces | bool | 清理分词空格 |\n\n**使用约束：**\n\n- 如果模型支持多语言翻译，必须同时提供 `src_lang` 和 `tgt_lang` 参数\n- 只提供其中一个参数将抛出 `ValueError` 异常\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文档问答（Document Question Answering）\n\n从文档图像中提取问题答案的功能。\n\n**主要方法：** `document_question_answering(image, question, *, model=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| image | str | 图像路径或 URL |\n| question | str | 问题文本 |\n| model | str | 模型 ID |\n| doc_stride | int | 文档分块跨度 |\n| max_answer_len | int | 最大答案长度 |\n| top_k | int | 返回 Top-K 答案 |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import AsyncInferenceClient\n>>> client = AsyncInferenceClient()\n>>> await client.document_question_answering(\n... image=\"https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png\",\n... question=\"What is the invoice number?\"\n... )\n[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-100]()\n\n## 提供者系统\n\n### Provider Helper 架构\n\nProvider Helper 是推理系统实现多提供者支持的核心组件，负责将统一的推理请求转换为特定提供者的请求格式。\n\n```mermaid\ngraph LR\n A[InferenceClient] --> B[get_provider_helper]\n B --> C{Provider 类型}\n C -->|HuggingFace| D[HF Provider Helper]\n C -->|Replicate| E[Replicate Provider Helper]\n C -->|其他| F[第三方 Helper]\n D --> G[Prepare Request]\n E --> G\n F --> G\n```\n\n### 请求参数准备\n\n每个 Provider Helper 实现 `prepare_request` 方法，将通用参数转换为特定提供者的请求格式：\n\n```python\nrequest_parameters = provider_helper.prepare_request(\n inputs=text,\n parameters={\n \"temperature\": temperature,\n \"max_new_tokens\": max_new_tokens,\n ...\n },\n headers=self.headers,\n model=model_id,\n api_key=self.token,\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_providers/__init__.py:1-50]()\n\n## 推理端点管理\n\n### InferenceEndpoints 类\n\nInferenceEndpoints 类用于管理 Hugging Face 推理端点的生命周期。\n\n**主要功能：**\n\n| 功能 | 说明 |\n|------|------|\n| 创建端点 | 在指定区域创建推理端点 |\n| 删除端点 | 销毁不再需要的推理端点 |\n| 状态查询 | 获取端点运行状态 |\n| 日志查看 | 访问端点运行日志 |\n\n资料来源：[src/huggingface_hub/_inference_endpoints.py:1-100]()\n\n## 输出数据结构\n\n### 文本生成输出\n\n| 类名 | 说明 |\n|------|------|\n| TextGenerationOutput | 标准文本生成输出 |\n| TextGenerationDetails | 包含详细生成信息 |\n| TextGenerationPrefillOutputToken | 前置填充令牌 |\n| TokenElement | 单个生成令牌 |\n| TextGenerationStreamOutput | 流式输出令牌 |\n\n**TokenElement 结构：**\n\n```python\nTokenElement(\n id=1425, # 令牌 ID\n text='100', # 令牌文本\n logprob=-1.01, # 对数概率\n special=False # 是否为特殊令牌\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 评估结果\n\nEvalResultEntry 用于存储和上传模型评估结果：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| dataset_id | str | 数据集标识符 |\n| task_id | str | 任务标识符 |\n| value | Any | 评估指标值 |\n| dataset_revision | str | 数据集版本 |\n| verify_token | str | 验证令牌 |\n| date | str | 评估日期 |\n| source_url | str | 来源 URL |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import EvalResultEntry, eval_result_entries_to_yaml\n>>> entries = [\n... EvalResultEntry(dataset_id=\"cais/hle\", task_id=\"default\", value=20.90),\n... ]\n>>> yaml_data = eval_result_entries_to_yaml(entries)\n>>> yaml_data[0]\n{'dataset': {'id': 'cais/hle', 'task_id': 'default'}, 'value': 20.9}\n```\n\n资料来源：[src/huggingface_hub/_eval_results.py:1-100]()\n\n## 错误处理\n\n### 常见异常类型\n\n| 异常类型 | 触发条件 |\n|----------|----------|\n| InferenceTimeoutError | 推理请求超时 |\n| HfHubHTTPError | HTTP 请求失败（非 503） |\n| ValueError | 参数验证失败 |\n\n### 错误处理示例\n\n```python\ntry:\n result = client.text_generation(\"Hello world\")\nexcept InferenceTimeoutError:\n print(\"请求超时，请检查网络连接\")\nexcept ValueError as e:\n print(f\"参数错误: {e}\")\n```\n\n## 使用工作流\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[初始化 InferenceClient] --> B[选择任务类型]\n B --> C{文本 / 图像 / 视频}\n C -->|文本| D[文本生成 / 翻译 / 摘要]\n C -->|图像| E[文本到图像 / 文档问答]\n C -->|视频| F[文本到视频]\n D --> G[调用推理方法]\n E --> G\n F --> G\n G --> H[获取推理结果]\n H --> I[处理结果]\n```\n\n### 完整使用示例\n\n```python\nfrom huggingface_hub import InferenceClient\n\n# 初始化客户端\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_xxxxx\"\n)\n\n# 图像生成\nimage = client.text_to_image(\n \"A beautiful sunset over the ocean\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n extra_body={\"output_quality\": 100}\n)\n\n# 保存结果\nimage.save(\"sunset.png\")\n```\n\n## 性能优化建议\n\n1. **选择合适的提供者**：不同提供者的性能和成本特性不同，应根据实际需求选择\n2. **使用流式输出**：对于长文本生成，启用流式输出可改善用户体验\n3. **合理设置超时**：对于复杂任务，适当增加超时时间\n4. **使用缓存**：频繁请求相同内容时，利用推理端点的缓存机制\n\n## 扩展阅读\n\n- [Hugging Face 推理文档](https://huggingface.co/docs/huggingface_hub/main/ko/guides/inference)\n- [Hub 安全令牌](https://huggingface.co/docs/hub/security-tokens)\n- [推理端点部署指南](https://huggingface.co/docs/inference-endpoints)\n\n---\n\n\n\n## 仓库管理\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations)\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/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n- [src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n- [src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.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/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n \n\n# 仓库管理\n\n## 概述\n\n`huggingface_hub` 库提供了完整的 Hugging Face Hub 仓库管理功能，涵盖仓库的创建、删除、复制、权限管理以及元数据维护等核心操作。这些功能主要通过 `HfApi` 类实现，为 Python 用户和 CLI 工具提供了统一的接口层。仓库（Repository）是 Hugging Face 生态系统的核心概念，支持三种主要类型：模型（Model）、数据集（Dataset）和 Space。\n\n仓库管理的架构设计遵循分层原则，底层通过 HTTP API 与 Hugging Face Hub 服务器通信，中层提供文件系统的抽象（`HfFileSystem`），上层则封装了面向用户的便捷函数。这种分层设计使得用户可以根据需求选择不同层级的 API 进行操作，既可以使用高级函数快速完成任务，也可以使用底层 API 进行精细控制。\n\n---\n\n## 仓库类型\n\nHugging Face Hub 支持三种核心仓库类型，每种类型针对不同的使用场景进行了优化。\n\n| 仓库类型 | 类型标识 | 典型用途 | 支持的文件大小 |\n|---------|---------|---------|---------------|\n| 模型 | `model` | 机器学习模型存储与分享 | 支持大文件（LFS） |\n| 数据集 | `dataset` | 训练数据、评测数据存储 | 支持大文件（LFS） |\n| Space | `space` | 交互式应用与演示 | 通常较小文件 |\n\n仓库类型在创建时指定，并通过 `repo_type` 参数区分。不同类型的仓库在 Hub 上具有不同的展示页面和交互组件，例如模型仓库会显示模型卡片和推理 Widget，数据集仓库会展示数据集预览功能。\n\n```python\nfrom huggingface_hub import create_repo\n\n# 创建模型仓库\nmodel_repo = create_repo(repo_id=\"username/my-model\", repo_type=\"model\")\n\n# 创建数据集仓库\ndataset_repo = create_repo(repo_id=\"username/my-dataset\", repo_type=\"dataset\")\n\n# 创建 Space 仓库\nspace_repo = create_repo(repo_id=\"username/my-space\", repo_type=\"space\")\n```\n\n---\n\n## 仓库生命周期管理\n\n### 创建仓库\n\n`create_repo` 函数用于在 Hugging Face Hub 上创建新仓库。该函数支持丰富的配置选项，包括仓库可见性、仓库描述、许可证设置等。创建仓库时需要提供唯一的 `repo_id`，格式为 `用户名/仓库名`。\n\n```python\nfrom huggingface_hub import create_repo\n\n# 创建私有模型仓库\nrepo = create_repo(\n repo_id=\"username/my-private-model\",\n repo_type=\"model\",\n private=True,\n exist_ok=False # 仓库已存在时抛出异常\n)\n```\n\n创建仓库时的关键参数包括：`repo_id`（必填，仓库唯一标识）、`repo_type`（可选，默认为 model）、`private`（控制可见性）、`exist_ok`（已存在时是否返回成功）。仓库创建成功后返回 `Repository` 对象，包含仓库的基本信息。\n\n### 删除仓库\n\n仓库删除操作通过 `delete_repo` 函数完成，该操作是不可逆的。删除仓库需要用户具有相应的权限，且只能删除自己拥有的仓库。系统会对删除操作进行确认提示，以防止误删。\n\n```python\nfrom huggingface_hub import delete_repo\n\n# 删除仓库\ndelete_repo(repo_id=\"username/my-old-model\", repo_type=\"model\")\n```\n\n### 复制仓库\n\n`duplicate_repo` 函数允许用户复制现有仓库，创建一个新的仓库副本。这对于创建模板仓库或备份非常重要。复制操作会保留原仓库的所有文件和元数据，新仓库的所有权归当前认证用户。\n\n```python\nfrom huggingface_hub import duplicate_repo\n\n# 复制仓库\nnew_repo = duplicate_repo(from_repo_id=\"template-org/template-model\")\n```\n\n---\n\n## 仓库权限与可见性\n\n### 可见性控制\n\n仓库的可见性决定了其他用户是否可以访问仓库内容。`huggingface_hub` 通过 `private` 参数控制可见性设置：\n\n| 可见性 | private 值 | 访问权限 | 适用场景 |\n|-------|-----------|---------|---------|\n| 公开 | `False` | 所有互联网用户可读 | 开源模型、数据集 |\n| 私有 | `True` | 仅所有者可见 | 未发布工作、内部项目 |\n\n公开仓库的内容对所有互联网用户可见，但只有授权用户可以推送更新。私有仓库完全由所有者控制，适合处理敏感数据或未完成的工作。\n\n### 访问令牌管理\n\n访问令牌（Token）是 Hugging Face Hub 认证的核心机制。用户需要通过 `login` 函数进行身份验证，之后的操作将使用已认证的令牌进行授权。\n\n```python\nfrom huggingface_hub import login\n\n# 交互式登录\nlogin()\n\n# 或使用环境变量中的令牌\n# HUGGINGFACE_TOKEN=hf_xxx python script.py\n```\n\nCLI 方式登录：\n\n```bash\nhf auth login\n# 或指定令牌\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n资料来源：[src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n## 仓库元数据管理\n\n### 仓库卡片（RepoCard）\n\n每个仓库都关联一个仓库卡片（RepoCard），用于展示仓库的描述信息和元数据。`huggingface_hub` 通过 `RepoCard` 类及其子类（`ModelCard`、`DatasetCard`、`SpaceCard`）管理这些元数据。\n\n```python\nfrom huggingface_hub import ModelCard, ModelCardData\n\n# 创建模型卡片数据\ncard_data = ModelCardData(\n language=\"en\",\n license=\"apache-2.0\",\n library_name=\"pytorch\",\n tags=[\"image-classification\", \"resnet\"]\n)\n\n# 从模板创建卡片\ncard = ModelCard.from_template(card_data)\n```\n\n仓库卡片的结构包含两部分：YAML 格式的元数据块和 Markdown 格式的说明文本。`CardData` 类及其子类定义了标准化的元数据字段，包括语言、许可证、标签、训练数据集等信息。\n\n资料来源：[src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n\n### 元数据解析\n\n`RepoCard` 类提供了内容解析功能，能够从 Markdown 文本中提取 YAML 元数据和说明文本：\n\n```python\nfrom huggingface_hub import RepoCard\n\ntext = '''\n---\nlanguage: en\nlicense: mit\n---\n\n# 我的仓库\n这是模型的描述...\n'''\n\ncard = RepoCard(text)\nprint(card.data.to_dict()) # {'language': 'en', 'license': 'mit'}\nprint(card.text) # '# 我的仓库\\n这是模型的描述...\\n'\n```\n\n资料来源：[src/huggingface_hub/repocard.py:38-55](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n\n---\n\n## 本地文件夹同步\n\n### LocalFolder 类\n\n`LocalFolder` 类提供本地文件夹与远程仓库的同步功能，支持双向文件操作。该类是 `HfFileSystem` 的组成部分，为本地开发工作流提供了文件系统接口。\n\n```mermaid\ngraph TD\n A[本地文件夹] -->|文件变更| B[LocalFolder]\n B -->|差异检测| C[变更列表]\n C -->|上传| D[远程仓库]\n D -->|下载| B\n B -->|同步| A[本地文件夹]\n```\n\nLocalFolder 维护本地文件系统与远程仓库之间的状态一致性，支持以下操作：\n\n- **增量同步**：仅上传/下载变更的文件\n- **冲突处理**：检测并提示文件冲突\n- **原子操作**：确保操作的完整性\n\n资料来源：[src/huggingface_hub/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n\n---\n\n## 文件系统抽象\n\n### HfFileSystem\n\n`HfFileSystem` 是基于 fsspec 的 POSIX 风格文件系统实现，允许用户像操作本地文件一样操作 Hugging Face Hub 上的仓库文件。这种设计使得现有工具和库可以无缝集成对 Hub 的访问。\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出仓库文件\nfiles = fs.ls(\"username/my-model\")\n\n# 读取文件内容\nwith fs.open(\"username/my-model/config.json\", \"r\") as f:\n content = f.read()\n\n# 写入文件\nwith fs.open(\"username/my-model/new_file.txt\", \"w\") as f:\n f.write(\"Hello, Hub!\")\n```\n\nHfFileSystem 支持标准的文件系统操作：\n\n| 操作 | 方法 | 说明 |\n|-----|------|-----|\n| 列表 | `ls()` | 列出目录内容 |\n| 读取 | `open()` | 打开文件进行读取 |\n| 写入 | `open(mode='w')` | 打开文件进行写入 |\n| 删除 | `rm()` | 删除文件 |\n| 移动 | `mv()` | 移动或重命名文件 |\n| 存在检查 | `exists()` | 检查文件是否存在 |\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\n---\n\n## 仓库操作 API\n\n### HfApi 核心方法\n\n`HfApi` 类是仓库管理的核心接口，提供了丰富的方法来操作仓库。以下是常用的仓库管理方法：\n\n| 方法 | 功能 | 主要参数 |\n|-----|------|---------|\n| `whoami()` | 获取当前用户信息 | - |\n| `list_models()` | 列出模型仓库 | `search`, `filters`, `sort` |\n| `list_datasets()` | 列出数据集仓库 | `search`, `filters`, `sort` |\n| `listSpaces()` | 列出 Space 仓库 | `search`, `filters`, `sort` |\n| `model_info()` | 获取模型仓库信息 | `repo_id`, `revision` |\n| `dataset_info()` | 获取数据集仓库信息 | `repo_id`, `revision` |\n| `space_info()` | 获取 Space 仓库信息 | `repo_id`, `revision` |\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n\n# 获取当前用户\nuser = api.whoami()\nprint(f\"用户名: {user['name']}\")\n\n# 搜索模型\nmodels = api.list_models(search=\"bert\", sort=\"downloads\", direction=-1, limit=5)\nfor model in models:\n print(f\"{model.id} - {model.downloads} downloads\")\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---\n\n## 存储桶管理\n\n### Bucket 机制\n\nHugging Face Hub 引入了 Bucket 的概念，用于优化大文件的存储和访问。Bucket 是仓库的一种特殊形式，专门用于存储大型二进制文件，如机器学习模型权重。\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n\n# 获取 bucket 信息\nbucket_info = api.hf_hub_download(\n repo_id=\"my-org/my-bucket\",\n filename=\"large-model.bin\",\n repo_type=\"bucket\"\n)\n```\n\nBucket 机制通过以下方式优化存储：\n\n1. **智能分片**：大文件自动分片存储\n2. **并行下载**：支持多连接并发下载\n3. **增量更新**：仅传输变更的部分\n\n资料来源：[src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n\n---\n\n## CLI 命令行工具\n\n### 认证命令\n\n```bash\n# 登录 Hugging Face\nhf auth login\n\n# 检查当前认证状态\nhf whoami\n\n# 登出\nhf auth logout\n```\n\n### 仓库管理命令\n\n```bash\n# 创建新仓库\nhf repo create username/my-model\n\n# 克隆仓库到本地\nhf clone username/my-model\n\n# 查看仓库信息\nhf repo info username/my-model\n\n# 删除仓库\nhf repo delete username/my-model -y\n```\n\n### 下载与上传\n\n```bash\n# 下载单个文件\nhf download username/my-model config.json\n\n# 下载整个仓库\nhf download username/my-model\n\n# 上传文件\nhf upload username/my-model local_file.txt path/in/repo.txt\n\n# 上传文件夹\nhf upload username/my-model /path/to/local/folder/\n```\n\n---\n\n## 架构流程图\n\n### 仓库操作完整流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B{认证检查}\n B -->|已登录| C{HfApi}\n B -->|未登录| D[提示登录]\n D --> E[login 函数]\n E --> C\n \n C --> F{操作类型}\n F -->|创建| G[create_repo]\n F -->|删除| H[delete_repo]\n F -->|上传| I[upload_file]\n F -->|下载| J[hf_hub_download]\n F -->|列表| K[list_*]\n \n G --> L[HTTP API]\n H --> L\n I --> L\n J --> L\n K --> L\n \n L --> M{Hub 服务器}\n M -->|成功| N[返回结果]\n M -->|失败| O[抛出异常]\n```\n\n---\n\n## 最佳实践\n\n### 仓库命名规范\n\n- 使用有意义的名称：`username/model-purpose-variant`\n- 避免特殊字符：仅使用字母、数字和连字符\n- 版本控制：使用标签而非版本号\n\n### 安全性建议\n\n1. **保护访问令牌**：不要将令牌提交到版本控制系统\n2. **使用环境变量**：通过 `HUGGINGFACE_TOKEN` 环境变量传递令牌\n3. **最小权限**：在 Hugging Face 网站生成具有最小必要权限的令牌\n\n### 性能优化\n\n- **大文件处理**：使用 Git LFS 处理大于 10MB 的文件\n- **增量操作**：优先使用增量上传/下载而非全量操作\n- **缓存利用**：合理配置本地缓存以减少重复下载\n\n---\n\n## 相关文档\n\n- [安装指南](https://huggingface.co/docs/huggingface_hub/ko/installation)\n- [下载文件指南](https://huggingface.co/docs/huggingface_hub/ko/guides/download)\n- [上传文件指南](https://huggingface.co/docs/huggingface_hub/en/guides/upload)\n- [缓存管理](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[推理系统](#inference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/cli/hf.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/hf.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/cli/upload.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/upload.py)\n- [src/huggingface_hub/cli/models.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/models.py)\n- [src/huggingface_hub/cli/datasets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/datasets.py)\n- [src/huggingface_hub/cli/spaces.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/spaces.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n \n\n# 命令行工具\n\n## 概述\n\n`huggingface_hub` 库提供了一套完整的命令行工具（CLI），允许用户通过终端与 Hugging Face Hub 进行交互，无需编写 Python 代码即可完成文件下载、上传、模型管理、数据集浏览和 Space 操作等常见任务。\n\n命令行工具作为库的核心入口点之一，通过 `setup.py` 中定义的入口点（entry points）注册为系统可执行命令：\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\",\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\",\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\",\n ],\n ...\n}\n```\n\n资料来源：[setup.py:1-60]()\n\n安装 `huggingface_hub` 后，用户可以直接在终端使用以下命令：\n\n| 命令 | 功能描述 |\n|------|----------|\n| `hf` | 主命令行工具，提供所有核心功能 |\n| `huggingface-cli` | 已废弃的 CLI 工具（保留向后兼容） |\n| `tiny-agents` | 轻量级代理工具 |\n\n## CLI 模块架构\n\n### 模块结构\n\nCLI 模块位于 `src/huggingface_hub/cli/` 目录下，采用模块化设计，每个子模块负责特定的功能领域：\n\n```mermaid\ngraph TD\n A[hf 命令] --> B[download.py
下载模块]\n A --> C[upload.py
上传模块]\n A --> D[models.py
模型模块]\n A --> E[datasets.py
数据集模块]\n A --> F[spaces.py
Space模块]\n \n B --> G[hf_hub_download
snapshot_download]\n C --> H[upload_file
upload_folder]\n D --> I[模型列表
模型搜索]\n E --> J[数据集列表
数据集搜索]\n F --> K[Space管理
应用启动]\n```\n\n### 命令入口点\n\n主入口文件 `hf.py` 定义了 CLI 的根命令和子命令结构，采用层级式命令设计：\n\n```mermaid\ngraph LR\n A[hf 命令] --> B[auth
身份验证]\n A --> C[download
下载]\n A --> D[upload
上传]\n A --> E[list
列表查询]\n A --> F[whoami
当前用户]\n```\n\n## 身份验证模块\n\n### 登录命令\n\n`hf auth login` 命令用于在本地计算机上登录 Hugging Face 账户：\n\n```bash\nhf auth login\n```\n\n此命令会提示用户输入 HF token（可从 [Hugging Face 设置页面](https://huggingface.co/settings/tokens) 获取），并将凭证安全存储在本地配置文件中。\n\n### 身份验证流程\n\n```mermaid\nsequenceDiagram\n 用户->>CLI: hf auth login\n CLI->>HuggingFace: 请求认证\n HuggingFace-->>CLI: 返回token\n CLI->>本地配置: 存储token\n 本地配置-->>CLI: 确认存储成功\n CLI-->>用户: 登录成功\n```\n\n## 下载模块\n\n`download.py` 模块提供了从 Hugging Face Hub 下载文件和仓库的完整功能。\n\n### 主要下载命令\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `hf download` | 下载单个文件 | `hf download --repo-id model --filename config.json` |\n| `hf snapshot-download` | 下载整个仓库 | `hf snapshot-download --repo-id stabilityai/stable-diffusion-2-1` |\n\n### 下载命令参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--repo-id` | 字符串 | 是 | 仓库标识符，格式为 `namespace/repo-name` |\n| `--repo-type` | 字符串 | 否 | 仓库类型：`model`、`dataset` 或 `space`，默认为 `model` |\n| `--filename` | 字符串 | 否 | 要下载的文件名（用于单文件下载） |\n| `--local-dir` | 路径 | 否 | 本地下载目录 |\n| `--revision` | 字符串 | 否 | Git 分支名或 commit hash |\n| `--token` | 字符串 | 否 | Hugging Face 访问令牌 |\n\n### 下载流程\n\n```mermaid\ngraph TD\n A[开始下载] --> B{指定filename?}\n B -->|是| C[hf_hub_download
单文件下载]\n B -->|否| D[snapshot_download
完整仓库下载]\n \n C --> E{本地缓存存在?}\n D --> F{本地缓存存在?}\n \n E -->|是| G[使用缓存]\n E -->|否| H[从Hub下载]\n F -->|是| I[使用缓存]\n F -->|否| J[从Hub下载]\n \n G --> K[返回本地路径]\n H --> K\n I --> K\n J --> K\n```\n\n文件下载后会缓存到本地，详细信息可参考 [缓存管理指南](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)。\n\n资料来源：[src/huggingface_hub/cli/download.py]()\n\n## 上传模块\n\n`upload.py` 模块提供了向 Hugging Face Hub 上传文件和文件夹的功能。\n\n### 主要上传命令\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `hf upload` | 上传文件 | `hf upload --path config.json --repo-id username/my-model` |\n| `hf upload-folder` | 上传文件夹 | `hf upload-folder --folder-path ./my-space --repo-id username/my-space --repo-type space` |\n\n### 上传命令参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--path` | 路径 | 是* | 要上传的文件路径（用于单文件上传） |\n| `--folder-path` | 路径 | 是* | 要上传的文件夹路径（用于文件夹上传） |\n| `--repo-id` | 字符串 | 是 | 目标仓库标识符 |\n| `--repo-type` | 字符串 | 否 | 仓库类型：`model`、`dataset` 或 `space` |\n| `--path-in-repo` | 字符串 | 否 | 仓库中的目标路径 |\n| `--message` | 字符串 | 否 | Git commit 提交信息 |\n| `--token` | 字符串 | 否 | Hugging Face 访问令牌 |\n\n### 上传流程\n\n```mermaid\ngraph TD\n A[开始上传] --> B{上传类型?}\n B -->|文件| C[上传单个文件]\n B -->|文件夹| D[遍历文件夹]\n \n C --> E[验证文件存在]\n E --> F[计算文件大小]\n F --> G[分块上传]\n G --> H[创建Git commit]\n \n D --> I[递归处理文件]\n I --> J{更多文件?}\n J -->|是| I\n J -->|否| H\n \n H --> K[完成上传]\n```\n\n资料来源：[src/huggingface_hub/cli/upload.py]()\n\n## 模型管理模块\n\n`models.py` 模块提供了浏览和管理 Hugging Face Hub 上的模型功能。\n\n### 主要命令\n\n| 命令 | 功能 |\n|------|------|\n| `hf models list` | 列出所有可用的模型 |\n| `hf models search` | 搜索特定模型 |\n\n### 模型列表参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--filter` | 字符串 | 按任务类型、库名等筛选 |\n| `--search` | 字符串 | 搜索关键词 |\n| `--sort` | 字符串 | 排序字段（如 `downloads`、`likes`） |\n| `--direction` | 字符串 | 排序方向（`asc` 或 `desc`） |\n| `--limit` | 整数 | 返回结果数量限制 |\n\n### 模型卡片操作\n\n通过 `hf` 命令可以创建和编辑模型卡片（Model Card），模型卡片是描述模型元数据的重要文件，包含语言、许可证、训练数据集等信息。\n\n资料来源：[src/huggingface_hub/cli/models.py](), [src/huggingface_hub/repocard_data.py:1-100]()\n\n## 数据集管理模块\n\n`datasets.py` 模块提供了浏览和管理 Hugging Face Hub 上的数据集功能。\n\n### 主要命令\n\n| 命令 | 功能 |\n|------|------|\n| `hf datasets list` | 列出所有可用的数据集 |\n| `hf datasets search` | 搜索特定数据集 |\n\n### 数据集卡片操作\n\n数据集卡片（Dataset Card）使用 `DatasetCardData` 类进行管理，包含以下元数据字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `language` | 字符串/列表 | 数据集语言 |\n| `license` | 字符串 | 许可证类型 |\n| `annotations_creators` | 字符串 | 注释创建方式 |\n| `task_categories` | 列表 | 任务类别 |\n| `task_ids` | 列表 | 任务标识符 |\n\n资料来源：[src/huggingface_hub/cli/datasets.py](), [src/huggingface_hub/repocard.py:1-100]()\n\n## Space 管理模块\n\n`spaces.py` 模块提供了管理 Hugging Face Spaces 的功能。\n\n### 主要功能\n\n| 功能 | 说明 |\n|------|------|\n| Space 列表 | 浏览可用的 Spaces |\n| Space 搜索 | 搜索特定 Spaces |\n| Space 配置 | 管理 Space 的硬件配置 |\n| Space 启动 | 启动本地 Space 进行测试 |\n\n### 创建 Space\n\n使用 `hf spaces create` 命令可以创建新的 Space：\n\n```bash\nhf spaces create --repo-id username/my-cool-space --sdk streamlit\n```\n\n支持的 SDK 类型包括：`streamlit`、`gradio`、`docker`、`static`、`nextjs`、`svelte`。\n\n资料来源：[src/huggingface_hub/cli/spaces.py]()\n\n## 使用示例\n\n### 完整工作流程\n\n```mermaid\ngraph LR\n A[身份验证] --> B[下载模型]\n B --> C[微调模型]\n C --> D[上传模型]\n D --> E[创建模型卡片]\n E --> F[分享到社区]\n```\n\n### 常用命令示例\n\n**1. 身份验证**\n```bash\nhf auth login\n```\n\n**2. 下载模型文件**\n```bash\nhf download --repo-id meta-llama/Llama-2-7b --filename config.json\n```\n\n**3. 下载完整模型仓库**\n```bash\nhf snapshot-download --repo-id stabilityai/stable-diffusion-2-1\n```\n\n**4. 上传文件**\n```bash\nhf upload --path config.json --repo-id username/my-model\n```\n\n**5. 上传文件夹**\n```bash\nhf upload-folder --folder-path ./my-space --repo-id username/my-space --repo-type space\n```\n\n**6. 搜索模型**\n```bash\nhf models search --filter text-classification --limit 10\n```\n\n## 配置与缓存\n\n### 本地配置\n\nCLI 工具会将以下配置存储在本地：\n\n| 配置项 | 位置 | 说明 |\n|--------|------|------|\n| 访问令牌 | `~/.cache/huggingface/token` | 身份验证令牌 |\n| 缓存目录 | `~/.cache/huggingface/` | 下载文件缓存 |\n\n### 缓存管理\n\n文件下载时会自动缓存到本地，重复下载时会直接使用缓存。可以通过以下方式管理缓存：\n\n```bash\n# 查看缓存大小\nhf cache size\n\n# 清理缓存\nhf cache clear\n```\n\n## 错误处理\n\nCLI 工具在遇到错误时会返回相应的退出码：\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 命令执行成功 |\n| 1 | 通用错误 |\n| 2 | 参数错误 |\n| 128 | 身份验证失败 |\n\n常见错误及解决方案：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `RepositoryNotFoundError` | 仓库不存在或无权访问 | 检查 repo-id 是否正确，或确认已登录 |\n| `LocalTokenNotFoundError` | 未找到本地 token | 运行 `hf auth login` |\n| `FileExistsError` | 文件已存在 | 使用 `--overwrite` 参数或删除本地文件 |\n| `HuggingFaceHubValidationError` | 参数验证失败 | 检查参数格式是否正确 |\n\n## 与 Python API 的关系\n\nCLI 工具底层调用的是 `huggingface_hub` 的 Python API：\n\n| CLI 命令 | 对应 Python 函数 |\n|----------|------------------|\n| `hf download` | `hf_hub_download()` |\n| `hf snapshot-download` | `snapshot_download()` |\n| `hf upload` | `upload_file()` |\n| `hf upload-folder` | `upload_folder()` |\n\n这种设计确保了 CLI 和 Python API 的一致性，用户可以根据需求选择使用方式。\n\n---\n\n\n\n## 缓存系统\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations), [Git LFS 集成](#lfs-integration)\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/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/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n \n\n# 缓存系统\n\n## 概述\n\nHugging Face Hub 的缓存系统是 `huggingface_hub` 库的核心组件之一，负责管理从 Hugging Face Hub 下载的模型、数据集和其他文件的本地存储。该系统通过智能缓存机制避免了重复下载，提升了资源加载效率，并提供了灵活的缓存管理功能。\n\n缓存系统的主要职责包括：\n\n1. **文件缓存**：将下载的文件存储在本地缓存目录中\n2. **版本管理**：支持同一仓库的多个版本（revision）共存\n3. **元数据管理**：维护文件的 ETag、最后修改时间等元信息\n4. **缓存扫描**：提供 API 让用户查看当前缓存状态\n5. **缓存清理**：支持选择性删除缓存条目\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-50]()\n\n## 缓存架构\n\n### 缓存目录结构\n\nHugging Face Hub 采用层级化的缓存目录结构：\n\n```\n~/.cache/huggingface/hub/\n├── models--tiiuae--falcon-7b-instruct/\n│ ├── .cache/\n│ │ └── huggingface-metadata/\n│ ├── blobs/\n│ │ ├── 3a1d9c3d8e...\n│ │ └── f2b8e9a1c7...\n│ ├── refs/\n│ │ └── main\n│ └── snapshots/\n│ ├── 81fd1d6e7847c99f5862c9fb81387956d99ec7aa/\n│ │ ├── config.json -> ../../blobs/3a1d9c3d8e\n│ │ └── model.safetensors -> ../../blobs/f2b8e9a1c7\n│ └── e2983b237dccf3ab4937c97fa717319a9ca1a96d/\n```\n\n| 目录 | 用途 |\n|------|------|\n| `blobs/` | 存储实际文件内容（由 SHA256 哈希命名） |\n| `refs/` | 存储版本引用（revision）对应的 commit hash |\n| `snapshots/` | 存储文件链接到 blobs 的符号链接，按 revision 组织 |\n| `.cache/huggingface-metadata/` | 存储文件的元数据（ETag、lastModified 等） |\n\n资料来源：[src/huggingface_hub/file_download.py:100-150]()\n\n### 核心数据结构\n\n缓存系统使用两个核心数据结构来表示缓存信息：\n\n```python\n@dataclass\nclass CachedRepoInfo:\n \"\"\"缓存仓库的基本信息\"\"\"\n repo_id: str # 仓库ID，如 \"tiiuae/falcon-7b-instruct\"\n repo_type: str # 仓库类型：model、dataset 或 space\n size_on_disk: int # 仓库占用的磁盘空间\n nb_files: int # 文件数量\n revisions: list[CachedRevisionInfo] # 所有版本列表\n\n@dataclass\nclass CachedRevisionInfo:\n \"\"\"缓存版本的具体信息\"\"\"\n commit_hash: str # Git commit hash\n size_on_disk: int # 该版本占用的磁盘空间\n files: list[CachedFileInfo] # 该版本包含的文件列表\n security: SecurityDetails | None # 安全验证信息\n```\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:50-100]()\n\n## 缓存工作流程\n\n### 文件下载与缓存流程\n\n当用户调用 `hf_hub_download` 或 `snapshot_download` 时，缓存系统按以下流程工作：\n\n```mermaid\ngraph TD\n A[请求下载文件] --> B{检查缓存目录}\n B -->|文件已存在| C{检查元数据}\n C -->|ETag 未变化| D[返回缓存文件路径]\n C -->|ETag 变化| E[下载新版本]\n E --> F[更新 blob 文件]\n F --> G[更新元数据]\n G --> D\n B -->|文件不存在| H[下载文件]\n H --> I[存储到 blobs 目录]\n I --> J[创建 snapshot 链接]\n J --> K[存储元数据]\n K --> L[返回文件路径]\n D --> M[完成]\n L --> M\n```\n\n### 缓存命中判断逻辑\n\n1. **检查 blob 是否存在**：根据文件内容的 SHA256 哈希值查找 `blobs/` 目录\n2. **验证 ETag**：如果存在元数据，比较 ETag 判断是否需要重新下载\n3. **强制刷新**：通过 `force_download=True` 参数可强制重新下载\n\n```python\n# 伪代码：缓存命中逻辑\ndef get_cached_file_path(repo_id, filename, revision, etag):\n cache_dir = get_cache_dir(repo_id)\n blob_path = os.path.join(cache_dir, \"blobs\", file_hash)\n \n if os.path.exists(blob_path):\n cached_etag = get_cached_etag(repo_id, filename)\n if cached_etag == etag:\n return blob_path # 缓存命中\n else:\n # ETag 不匹配，需要重新下载\n pass\n return None # 缓存未命中\n```\n\n资料来源：[src/huggingface_hub/file_download.py:200-300]()\n\n## 缓存管理 API\n\n### 扫描缓存目录\n\n`scan_cache_dir()` 函数用于扫描并返回当前缓存目录的完整信息：\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\nprint(f\"缓存仓库数量: {len(cache_info.repos)}\")\nprint(f\"总占用空间: {cache_info.size_on_disk / 1024**3:.2f} GB\")\n\nfor repo in cache_info.repos:\n print(f\" - {repo.repo_id}: {repo.nb_files} 个文件\")\n```\n\n**返回值结构**：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `repos` | `list[CachedRepoInfo]` | 所有缓存仓库列表 |\n| `size_on_disk` | `int` | 总磁盘占用（字节） |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:150-200]()\n\n### 删除缓存策略\n\n`scan_cache_dir()` 返回的对象提供链式 API 来构建删除策略：\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# 方式1：删除指定版本\ncache_info = scan_cache_dir().delete_revisions(\n \"81fd1d6e7847c99f5862c9fb81387956d99ec7aa\",\n \"e2983b237dccf3ab4937c97fa717319a9ca1a96d\",\n)\n\n# 查看将要删除的内容（dry run）\nprint(f\"将删除 {cache_info.size_on_disk / 1024**2:.2f} MB\")\n\n# 执行删除\ncache_info.execute()\n```\n\n```python\n# 方式2：删除整个仓库的缓存\ncache_info = scan_cache_dir().delete_repos(\"tiiuae/falcon-7b-instruct\")\ncache_info.execute()\n```\n\n**DeleteCacheStrategy 常用方法**：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `delete_revisions(*revision_hashes)` | `DeleteCacheStrategy` | 标记要删除的版本 |\n| `delete_repos(*repo_ids)` | `DeleteCacheStrategy` | 标记要删除的仓库 |\n| `execute()` | `None` | 执行删除操作 |\n| `size()` | `int` | 待删除内容的总大小 |\n| `repos()` | `list[CachedRepoInfo]` | 受影响的仓库列表 |\n\n> [!WARNING]\n> `delete_revisions` 返回的 `DeleteCacheStrategy` 对象需要调用 `execute()` 方法才会真正执行删除操作。\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:200-300]()\n\n## HfFileSystem 缓存集成\n\n`HfFileSystem` 是基于 fsspec 的 POSIX 兼容文件系统实现，它深度集成了缓存系统：\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出目录时会使用缓存\nfiles = fs.ls(\"datasets/squad\")\n```\n\n### 缓存配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `cache_dir` | `str` | `~/.cache/huggingface/hub` | 缓存根目录 |\n| `storage_kwargs` | `dict` | `None` | 传递给底层存储的额外参数 |\n| `read_only` | `bool` | `False` | 是否以只读模式挂载 |\n\n```python\n# 使用自定义缓存目录\nfs = HfFileSystem(cache_dir=\"/path/to/custom/cache\")\n```\n\n资料来源：[src/huggingface_hub/hf_file_system.py:100-200]()\n\n## 快照下载与缓存\n\n`snapshot_download()` 函数用于下载整个仓库到本地，同时最大化利用缓存：\n\n```python\nfrom huggingface_hub import snapshot_download\n\nlocal_dir = snapshot_download(\n repo_id=\"stabilityai/stable-diffusion-2-1\",\n revision=\"main\",\n cache_dir=None, # 使用默认缓存目录\n force_download=False,\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `repo_id` | `str` | 必需 | 仓库标识符 |\n| `repo_type` | `str` | `\"model\"` | 仓库类型：model、dataset、space |\n| `revision` | `str` | `None` (latest) | Git 分支名或 commit hash |\n| `cache_dir` | `str` | `None` | 自定义缓存目录 |\n| `force_download` | `bool` | `False` | 是否强制重新下载 |\n| `local_dir` | `str` | `None` | 本地目标目录（非缓存目录） |\n| `allow_patterns` | `list[str]` | `None` | 仅下载匹配的文件 |\n| `ignore_patterns` | `list[str]` | `None` | 排除匹配的文件 |\n| `max_workers` | `int` | `8` | 并行下载的最大线程数 |\n\n### 缓存复用机制\n\n`snapshot_download` 内部使用增量下载策略：\n\n1. 首先检查本地缓存中是否存在目标 revision\n2. 如果存在且 `force_download=False`，直接使用缓存\n3. 如果不存在，下载缺失的 blobs 并复用已存在的 blobs\n\n资料来源：[src/huggingface_hub/_snapshot_download.py:1-100]()\n\n## LFS 大文件缓存\n\n对于 Git LFS 存储的大文件（如模型权重），缓存系统有特殊处理：\n\n```mermaid\ngraph LR\n A[下载请求] --> B{文件大小 > 阈值?}\n B -->|是| C[LFS 文件处理]\n B -->|否| D[普通文件处理]\n C --> E[下载 LFS blob]\n D --> F[下载普通 blob]\n E --> G[存储到 blobs/]\n F --> G\n```\n\n`CommitOperationAdd` 类提供 `as_file()` 方法用于流式处理上传和下载：\n\n```python\noperation = CommitOperationAdd(\n path_or_fileobj='./local/weights.h5',\n path_in_repo='remote/dir/weights.h5'\n)\n\n# 使用 as_file() 获取文件对象进行操作\nwith operation.as_file(with_tqdm=True) as file:\n content = file.read()\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py:100-200]()\n\n## 最佳实践\n\n### 1. 合理设置缓存目录\n\n```python\nimport os\nfrom huggingface_hub import snapshot_download\n\n# 为不同项目设置不同缓存目录\ncache_dir = os.path.join(os.getcwd(), \".cache\", \"my-project\")\nsnapshot_download(\"my-org/my-model\", cache_dir=cache_dir)\n```\n\n### 2. 定期清理缓存\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# 删除所有旧版本，保留最近的两个\ncache_info = scan_cache_dir()\n\nfor repo in cache_info.repos:\n # 假设 revisions 已按时间排序，保留最近2个\n revisions_to_delete = repo.revisions[2:]\n if revisions_to_delete:\n hashes = [r.commit_hash for r in revisions_to_delete]\n repo.cache_dir.delete_revisions(*hashes).execute()\n```\n\n### 3. 处理缓存失效\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 强制重新下载（忽略缓存）\nmodel_file = hf_hub_download(\n repo_id=\"meta-llama/Llama-2-7b\",\n filename=\"config.json\",\n force_download=True,\n token=True # 确保使用认证令牌\n)\n```\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 缓存管理 | `utils/_cache_manager.py` | 缓存扫描、删除策略 |\n| 文件下载 | `file_download.py` | 单文件下载与缓存 |\n| 快照下载 | `_snapshot_download.py` | 整仓库下载与缓存 |\n| 文件系统 | `hf_file_system.py` | fsspec 集成 |\n| 提交操作 | `_commit_api.py` | LFS 大文件处理 |\n\n## 总结\n\nHugging Face Hub 的缓存系统通过层级化的目录结构、智能的元数据管理和灵活的 API 设计，为用户提供了高效、可靠的本地缓存体验。开发者可以通过 `scan_cache_dir()` 查看缓存状态，使用 `delete_revisions()` 清理不需要的版本，并通过各种下载函数灵活控制缓存行为。\n\n---\n\n\n\n## Git LFS 集成\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations), [缓存系统](#cache-system)\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- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/cli/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/lfs.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 集成\n\n## 概述\n\nGit LFS（Large File Storage，大文件存储）是 Hugging Face Hub 用于处理大型二进制文件的核心机制。在机器学习场景中，模型权重、数据集文件等通常体积庞大（数百MB甚至数GB），传统 Git 无法高效处理此类文件，LFS 应运而生。\n\n`huggingface_hub` 库通过 `lfs.py` 模块和相关工具函数，提供了完整的 LFS 文件管理能力，包括大文件上传、下载、缓存管理以及批量操作支持。\n\n资料来源：[src/huggingface_hub/lfs.py:1-50]()\n\n## 核心概念\n\n### LFS 存储架构\n\nHugging Face Hub 采用 Git LFS 协议管理大文件，缓存目录结构如下：\n\n```\ncache/\n└── models--{repo_id}/\n ├── blobs/ # 实际文件blob（由git-sha或sha256标识）\n ├── refs/ # 最新已知revision => commit_hash映射\n └── snapshots/ # 每个commit的子文件夹，包含文件符号链接\n```\n\n- **blobs 目录**：存储实际的文件内容，LFS 文件由 SHA256 哈希标识\n- **refs 目录**：维护 revision 名称到 commit hash 的映射关系\n- **snapshots 目录**：每个 commit 对应一个子文件夹，文件通过符号链接指向 blobs\n\n资料来源：[src/huggingface_hub/file_download.py:96-120]()\n\n### LFS 文件识别\n\nLFS 文件通过以下特征识别：\n- 文件大小超过配置的阈值（默认 5MB）\n- 文件类型匹配预定义的模式（如 `.bin`、`.pt`、`.safetensors` 等）\n\n非 LFS 文件（如纯 Git 管理的文件）使用 git-sha 标识。\n\n资料来源：[src/huggingface_hub/utils/_lfs.py:1-30]()\n\n## 模块架构\n\n### 主要组件\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `lfs.py` | `src/huggingface_hub/lfs.py` | LFS 核心操作：上传、下载、切片、进度追踪 |\n| `utils/_lfs.py` | `src/huggingface_hub/utils/_lfs.py` | LFS 工具函数：路径处理、URL 构建 |\n| `_commit_api.py` | `src/huggingface_hub/_commit_api.py` | Commit 操作中的 LFS 处理逻辑 |\n| `cli/lfs.py` | `src/huggingface_hub/cli/lfs.py` | 命令行 LFS 工具 |\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[上传请求] --> B{文件大小检查}\n B -->|小于阈值| C[普通 Git 上传]\n B -->|大于阈值| D[LFS 上传流程]\n \n D --> E[计算 SHA256 哈希]\n E --> F{文件已存在?}\n F -->|是| G[跳过上传]\n F -->|否| H[切片上传]\n H --> I[分块传输]\n I --> J[验证完整性]\n J --> K[完成上传]\n \n C --> L[更新索引]\n G --> L\n K --> L\n```\n\n## LFS 上传机制\n\n### 分片上传流程\n\n大文件采用分片上传策略，以支持断点续传和进度追踪：\n\n```mermaid\ngraph LR\n A[文件] --> B[分片器]\n B --> C[Chunk 1]\n B --> D[Chunk 2]\n B --> E[Chunk N]\n C --> F[并行上传]\n D --> F\n E --> F\n F --> G[服务器合并]\n```\n\n### Commit 操作中的 LFS 处理\n\n`_commit_api.py` 中的 `CommitOperationAdd` 类处理 LFS 文件上传：\n\n- 自动检测文件是否需要 LFS 存储\n- 触发 LFS 批量上传协议\n- 管理 Git LFS pointer 文件的创建\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n```python\n# CommitOperationAdd 核心逻辑\nclass CommitOperationAdd:\n def __init__(self, path_or_fileobj, path_in_repo, ...):\n # 自动识别是否为 LFS 文件\n self.is_lfs_file = self._check_lfs_requirement(file_size)\n```\n\n### LFS Pointer 文件格式\n\nLFS 存储的文件以 Git pointer 形式存在于仓库中：\n\n```\nversion https://git-lfs.github.com/spec/v1\noid sha256:3f2c70a56d67f1c9c7e5e8d4b3a1f2e9c8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3\nsize 1048576\n```\n\n客户端通过此 pointer 文件识别 LFS 内容，并从 LFS 服务器获取实际数据。\n\n资料来源：[src/huggingface_hub/utils/_lfs.py:50-80]()\n\n## CLI 工具\n\n### lfs 命令\n\n`huggingface_hub` 提供命令行工具管理 LFS 操作：\n\n```bash\n# 列出 LFS 跟踪的文件\nhf lfs ls-files\n\n# 检查 LFS 状态\nhf lfs status\n\n# 手动触发 LFS 预取\nhf lfs fetch origin main\n```\n\n资料来源：[src/huggingface_hub/cli/lfs.py:1-50]()\n\n### CLI 模块结构\n\n```mermaid\nclassDiagram\n class LfsCLI {\n +ls_files()\n +status()\n +fetch()\n +push()\n }\n```\n\n## 缓存管理\n\n### 缓存目录结构\n\n```\n~/.cache/huggingface/hub/\n├── models--bert-base-uncased/\n│ ├── blobs/\n│ │ ├── 3f2c70a56d67f1c9c7e5e8d4b3a1f2e9c8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3 # LFS 文件\n│ │ └── 7cb18dc9bafbfcf74629a4b760af1b160957a83e # 普通 Git 文件\n│ ├── refs/\n│ │ └── main # revision 映射\n│ └── snapshots/\n│ └── 2439f60ef33a0d46d85da5001d52aeda5b00ce1 # commit snapshot\n```\n\n### 缓存策略\n\n- **首次下载**：从 Hub 下载 LFS 文件并存入缓存\n- **后续访问**：直接读取本地缓存，避免重复下载\n- **空间管理**：支持手动清理缓存或配置自动清理策略\n\n资料来源：[src/huggingface_hub/file_download.py:80-150]()\n\n## 配置选项\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `lfs_upload_chunk_size` | 分片上传块大小 | 100MB |\n| `lfs_multipart_threshold` | 触发 LFS 的文件大小阈值 | 5MB |\n| `lfs_allow_unsigned` | 允许上传未签名内容 | False |\n| `endpoints.lfs` | LFS 服务器地址 | Hub 默认端点 |\n\n## 使用示例\n\n### Python API 上传 LFS 文件\n\n```python\nfrom huggingface_hub import HfApi, CommitOperationAdd\n\n# 创建包含 LFS 文件的 commit\noperations = [\n CommitOperationAdd(\n path_or_fileobj=\"model.safetensors\", # 大文件自动使用 LFS\n path_in_repo=\"models/model.safetensors\",\n )\n)\n\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Add model weights\",\n)\n```\n\n### 手动触发 LFS 上传\n\n```python\nfrom huggingface_hub.utils import upload_lfs_file\n\n# 直接上传 LFS 文件\nupload_lfs_file(\n file_path=\"large_dataset.bin\",\n repo_id=\"username/my-dataset\",\n repo_type=\"dataset\",\n)\n```\n\n## 最佳实践\n\n1. **批量操作**：多个 LFS 文件应批量处理，减少 HTTP 请求次数\n2. **断点续传：大文件分片上传确保网络中断后可以继续\n3. **缓存复用**：同一文件仅下载一次，后续直接使用缓存\n4. **进度追踪**：上传/下载过程提供实时进度回调\n5. **并发控制**：避免同时发起过多并发请求，合理控制并发数\n\n## 错误处理\n\n| 错误类型 | 原因 | 处理方式 |\n|----------|------|----------|\n| `LfsUploadError` | LFS 服务器返回错误 | 重试或检查网络 |\n| `LfsSizeMismatchError` | 文件大小不匹配 | 重新上传 |\n| `LfsFileNotFoundError` | Pointer 文件指向的文件不存在 | 检查仓库状态 |\n\n资料来源：[src/huggingface_hub/lfs.py:100-200]()\n\n## 相关模块\n\n- **HfApi**：高级 API，封装 LFS 操作\n- **HfFileSystem**：文件系统接口，支持透明访问 LFS 文件\n- **snapshot_download**：下载整个仓库时自动处理 LFS\n\n资料来源：[src/huggingface_hub/hf_file_system.py:1-50]()\n\n## 扩展阅读\n\n- [Git LFS 协议规范](https://git-lfs.github.com/spec/v1)\n- [Hugging Face Hub 上传指南](https://huggingface.co/docs/huggingface_hub/guides/upload)\n- [缓存管理文档](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)\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 项目说明书",
"目录",
"项目介绍",
"概述",
"核心功能",
"安装方式",
"核心模块架构",
"主要 API 组件",
"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[文件操作]\n A --> C[仓库管理]\n A --> D[推理服务]\n A --> E[卡片系统]\n \n B --> B1[hf_hub_download]\n B --> B2[snapshot_download]\n B --> B3[upload_file]\n B --> B4[upload_folder]\n \n C --> C1[create_repo]\n C --> C2[delete_repo]\n C --> C3[list_models]\n C --> C4[list_datasets]\n \n D --> D1[InferenceClient]\n D --> D2[AsyncInferenceClient]\n D --> D3[InferenceEndpoint]\n \n E --> E1[RepoCard]\n E --> E2[ModelCard]\n E --> E3[DatasetCard]\n E --> E4[SpaceCard]\n```\n\n## 主要 API 组件\n\n### 推理客户端 (InferenceClient)\n\n`InferenceClient` 是用于与托管模型进行交互的核心类，支持多种推理任务。\n\n**支持的推理任务：**\n\n- 文本生成 (text_generation)\n- 对话完成 (chat_completion)\n- 图像生成 (text_to_image)\n- 视频生成 (text_to_video)\n- 图像描述 (image_to_text)\n- 自动语音识别 (automatic_speech_recognition)\n- 文本转语音 (text_to_speech)\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n**基础使用示例：**\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(\"meta-llama/Meta-Llama-3-70B-Instruct\")\n\n# 文本生成\noutput = client.text_generation(\"The huggingface_hub library is \", max_new_tokens=12)\n\n# 对话完成\noutput = client.chat_completion(\n messages=[\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n ]\n)\n```\n\n**图像生成示例：**\n\n```python\nfrom huggingface_hub import InferenceClient\n\nclient = InferenceClient(provider=\"replicate\", api_key=\"hf_...\")\nimage = client.text_to_image(\n \"An astronaut riding a horse on the moon.\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n)\nimage.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:100-200]()\n\n### 推理端点 (InferenceEndpoint)\n\n`InferenceEndpoint` 提供了专用推理端点的管理功能，支持部署自定义推理服务。\n\n**端点状态：**\n\n```mermaid\nstateDiagram-v2\n [*] --> deploying\n deploying --> pending\n pending --> paused\n paused --> running\n running --> paused\n running --> scaled_to_zero\n scaled_to_zero --> running\n running --> [*]\n```\n\n**使用示例：**\n\n```python\nfrom huggingface_hub import get_inference_endpoint\n\nendpoint = get_inference_endpoint(\"my-text-to-image\")\nprint(endpoint.status) # 'running'\nprint(endpoint.url) # 'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'\n\n# 执行推理\nresult = endpoint.client.text_to_image(\"prompt\")\n\n# 暂停端点以节省成本\nendpoint.pause()\n\n# 恢复并等待部署\nendpoint.resume()\nendpoint.wait()\n```\n\n资料来源：[src/huggingface_hub/_inference_endpoints.py:1-80]()\n\n### 评估结果管理\n\n库提供了 `EvalResultEntry` 类用于管理和上传模型评估结果：\n\n```python\nfrom huggingface_hub import EvalResultEntry, eval_result_entries_to_yaml, upload_file\nimport yaml\n\nentries = [\n EvalResultEntry(dataset_id=\"cais/hle\", task_id=\"default\", value=20.90),\n]\n\n# 转换为 YAML 格式\nyaml_content = yaml.dump(eval_result_entries_to_yaml(entries))\n\n# 上传到 Hub\nupload_file(\n path_or_fileobj=yaml_content.encode(),\n path_in_repo=\".eval_results/hle.yaml\",\n repo_id=\"your-username/your-model\",\n)\n```\n\n**EvalResultEntry 字段说明：**\n\n| 字段名 | 类型 | 说明 |\n|-------|------|------|\n| dataset_id | str | 数据集标识符 |\n| task_id | str | 任务标识符 |\n| value | Any | 评估指标值 |\n| dataset_revision | str | 数据集版本 |\n| verify_token | str | 验证令牌 |\n| date | str | 评估日期 |\n| source_url | str | 来源 URL |\n| source_name | str | 来源名称 |\n\n资料来源：[src/huggingface_hub/_eval_results.py:1-100]()\n\n## 文件操作\n\n### 下载文件\n\n**单个文件下载：**\n\n```python\nfrom huggingface_hub import hf_hub_download\n\nhf_hub_download(\n repo_id=\"tiiuae/falcon-7b-instruct\",\n filename=\"config.json\"\n)\n```\n\n**完整仓库下载：**\n\n```python\nfrom huggingface_hub import snapshot_download\n\nsnapshot_download(\"stabilityai/stable-diffusion-2-1\")\n```\n\n资料来源：[i18n/README_ko.md:1-30]()\n\n### 上传文件\n\n**单个文件上传：**\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/path/to/local/README.md\",\n path_in_repo=\"README.md\",\n repo_id=\"lysandre/test-model\",\n)\n```\n\n**文件夹上传：**\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资料来源：[i18n/README_fr.md:1-50]()\n\n## 仓库卡片系统\n\nhuggingface_hub 提供了统一的卡片系统来管理模型、数据集和 Space 的元数据文档：\n\n| 卡片类型 | 说明 | 对应类 |\n|---------|------|-------|\n| ModelCard | 模型卡片 | 模型描述和元数据 |\n| DatasetCard | 数据集卡片 | 数据集描述和元数据 |\n| SpaceCard | Space 卡片 | 应用描述和元数据 |\n\n```python\nfrom huggingface_hub import ModelCard, ModelCardData\n\ncard_data = ModelCardData(\n language=\"en\",\n license=\"mit\",\n library_name=\"timm\",\n tags=['image-classification', 'resnet'],\n)\n\ncard = ModelCard.from_template(card_data, model_description=\"This model does x + y...\")\n```\n\n资料来源：[src/huggingface_hub/repocard.py:1-100]()\n\n## 认证机制\n\nHugging Face Hub 使用令牌（Token）进行身份验证：\n\n```bash\n# CLI 登录\nhf auth login\n```\n\n登录后，令牌会存储在本地，供后续 API 调用使用。\n\n资料来源：[i18n/README_hi.md:1-30]()\n\n## 项目配置\n\n### 入口点配置\n\nsetup.py 中定义的命令行入口点：\n\n| 命令 | 模块 | 说明 |\n|-----|------|------|\n| hf | huggingface_hub.cli.hf | 主要 CLI 工具 |\n| huggingface-cli | huggingface_hub.cli.deprecated_cli | 已废弃的 CLI |\n| tiny-agents | huggingface_hub.inference._mcp.cli | Tiny Agents 工具 |\n\n资料来源：[setup.py:30-40]()\n\n### 文件系统集成\n\n库通过 fsspec 提供了统一的文件系统接口：\n\n```python\n# fsspec.specs 入口点\nfsspec.specs: hf=huggingface_hub.HfFileSystem\n```\n\n## 依赖项\n\n### 核心依赖\n\n| 依赖包 | 说明 |\n|-------|------|\n| filelock | 文件锁支持 |\n| fsspec | 文件系统抽象 |\n| huggingface_hub | 核心包 |\n| packaging | 版本解析 |\n| pyyaml | YAML 处理 |\n| requests | HTTP 请求 |\n| tqdm | 进度条 |\n\n### 可选依赖\n\n| 额外依赖组 | 包含内容 |\n|----------|---------|\n| inference | 推理功能完整支持 |\n\n资料来源：[setup.py:1-30]()\n\n## 第三方集成\n\nHugging Face 与多个开源 ML 库合作，提供免费的模型托管和版本控制服务。这些集成库包括 PyTorch、TensorFlow、Transformers 等主流深度学习框架。\n\n资料来源：[i18n/README_fr.md:50-80]()\n\n## 技术规格\n\n| 规格 | 要求 |\n|-----|------|\n| Python 版本 | >= 3.10.0 |\n| 许可证 | Apache-2.0 |\n| 包管理 | setuptools |\n\n资料来源：[setup.py:40-50]()\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n- [src/huggingface_hub/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n- [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n- [src/huggingface_hub/_inference_endpoints.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_inference_endpoints.py)\n \n\n# 安装指南\n\n## 概述\n\n`huggingface_hub` 是 Hugging Face 官方提供的客户端库，用于下载和发布模型、数据集以及其他仓库到 huggingface.co Hub。该库为开发者提供了与 Hugging Face Hub 进行交互的统一接口，支持文件下载上传、模型推理、仓库管理等功能。资料来源：[setup.py:44]()\n\n## 系统要求\n\n### Python 版本要求\n\n| 要求项 | 最低版本 |\n|--------|----------|\n| Python | 3.10.0 |\n\n`huggingface_hub` 仅支持 Python 3.10 及以上版本。在安装前，请确保您的 Python 环境满足版本要求。\n\n```bash\npython --version # 确认 Python 版本 >= 3.10.0\n```\n\n资料来源：[setup.py:49]()\n\n## 安装方式\n\n### 基本安装\n\n使用 pip 安装 `huggingface_hub` 的稳定版本：\n\n```bash\npip install huggingface_hub\n```\n\n### 包含可选依赖的安装\n\n根据使用场景，可以选择安装不同的可选依赖组：\n\n| 安装命令 | 包含内容 | 使用场景 |\n|----------|----------|----------|\n| `pip install huggingface_hub[inference]` | 推理相关功能 | 使用模型推理功能 |\n| `pip install huggingface_hub[all]` | 所有可选依赖 | 完整功能体验 |\n| `pip install huggingface_hub[testing]` | 测试相关依赖 | 运行单元测试 |\n| `pip install huggingface_hub[quality]` | 代码质量工具 | 代码检查和格式化 |\n| `pip install huggingface_hub[typing]` | 类型检查工具 | 类型注解验证 |\n| `pip install huggingface_hub[dev]` | 所有开发依赖 | 本地开发环境 |\n\n资料来源：[i18n/README_ko.md:1]()\n\n### 从源码安装\n\n如需安装最新开发版本，可直接从 GitHub 仓库安装：\n\n```bash\npip install git+https://github.com/huggingface/huggingface_hub.git\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|基本安装| C[pip install huggingface_hub]\n B -->|推理功能| D[pip install huggingface_hub inference]\n B -->|完整开发| E[pip install huggingface_hub[dev]]\n B -->|源码安装| F[git+https://github.com/huggingface/huggingface_hub.git]\n C --> G{验证安装}\n D --> G\n E --> G\n F --> G\n G -->|成功| H[安装完成]\n G -->|失败| I[检查 Python 版本和依赖]\n```\n\n## 核心依赖项\n\n`huggingface_hub` 的核心功能依赖以下主要包：\n\n| 依赖包 | 用途说明 |\n|--------|----------|\n| `filelock` | 文件锁机制，用于缓存管理 |\n| `fsspec` | 文件系统规范实现 |\n| `httpx` | HTTP 客户端库 |\n| `huggingface_hub` 自身 | 核心功能模块 |\n| `pyyaml` | YAML 配置文件解析 |\n| `tqdm` | 进度条显示 |\n\n这些依赖会在安装 `huggingface_hub` 时自动安装。\n\n资料来源：[setup.py:1-20]()\n\n## CLI 命令行工具\n\n安装完成后，系统会自动注册以下命令行工具：\n\n| 命令 | 来源 | 功能说明 |\n|------|------|----------|\n| `hf` | huggingface_hub.cli.hf | 主 CLI 入口 |\n| `huggingface-cli` | huggingface_hub.cli.deprecated_cli | 传统 CLI 工具（已弃用） |\n| `tiny-agents` | huggingface_hub.inference._mcp.cli | MCP 推理代理工具 |\n\n```bash\n# 登录 Hugging Face\nhf auth login\n\n# 使用 huggingface-cli（已弃用）\nhuggingface-cli login\n```\n\n资料来源：[setup.py:50-53]()\n\n## 验证安装\n\n安装完成后，可以通过以下方式验证：\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 测试基本功能\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n```\n\n如果安装正确，会返回缓存的文件路径或开始下载文件。\n\n## 推理功能安装\n\n如果需要使用模型推理功能（如文本生成、图像生成等），必须安装 `inference` 可选依赖：\n\n```bash\npip install huggingface_hub[inference]\n```\n\n推理功能支持的特性包括：\n\n- 文本补全 (Text Completion)\n- 聊天完成 (Chat Completion)\n- 文本转图像 (Text to Image)\n- 文本转视频 (Text to Video)\n- 图像特征提取\n- 零样本分类\n\n资料来源：[src/huggingface_hub/inference/_client.py:1]()\n\n## 与 Hub 集成\n\n`huggingface_hub` 与多个开源机器学习库有官方集成，包括 Transformers、Diffusers、AllenNLP 等。这种集成提供了以下优势：\n\n- **无缝下载**：无需手动管理模型文件\n- **版本控制**：自动追踪模型和数据版本\n- **缓存管理**：统一的本地缓存机制\n\n可以通过官方文档查看完整的库集成列表：https://huggingface.co/docs/hub/libraries\n\n## 常见问题\n\n### Python 版本不满足\n\n确保使用 Python 3.10.0 或更高版本：\n\n```bash\n# 使用 python3.10 或更高版本创建虚拟环境\npython3.10 -m venv hf_env\nsource hf_env/bin/activate # Linux/Mac\n# 或\nhf_env\\Scripts\\activate # Windows\n```\n\n### 可选依赖安装失败\n\n如果某些可选依赖（如 tensorflow、torch 等）安装失败，可以单独安装核心库后再按需安装：\n\n```bash\npip install huggingface_hub\n# 按需安装特定依赖\npip install torch # 如需 PyTorch 支持\n```\n\n### 缓存目录权限问题\n\n首次使用时，`huggingface_hub` 会在本地缓存模型文件。确保缓存目录有写入权限。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[模块结构详解](#module-structure), [项目介绍](#introduction)\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- [src/huggingface_hub/constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.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- [src/huggingface_hub/repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.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/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.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- [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.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 \n\n# 系统架构\n\n## 概述\n\nhuggingface_hub 是一个用于与 Hugging Face Hub 交互的 Python 客户端库，提供模型、数据集和 Space 的下载、上传、管理功能。库采用模块化设计，核心逻辑分散在多个专用模块中，通过 `__init__.py` 统一导出公共 API。\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 整体架构图\n\n```mermaid\ngraph TD\n subgraph 公共API层\n INIT[__init__.py - 公共接口]\n end\n \n subgraph 核心业务模块\n HF_API[hf_api.py - HfApi主类]\n REPO_CARD[repocard.py - 卡片管理]\n FILE_DOWNLOAD[file_download.py - 文件下载]\n COMMIT[_commit_api.py - 提交操作]\n HF_FS[hf_file_system.py - 文件系统]\n end\n \n subgraph 高级功能模块\n HUB_MIXIN[hub_mixin.py - 模型混入]\n INFERENCE[inference - 推理客户端]\n SPACE[_space_api.py - Space运行时]\n INFERENCE_EP[_inference_endpoints.py - 推理端点]\n end\n \n subgraph 工具模块\n URI[_hf_uris.py - URI解析]\n LFS[lfs.py - LFS上传]\n LOGIN[_login.py - 认证管理]\n COMMUNITY[community.py - 社区功能]\n end\n \n INIT --> HF_API\n INIT --> REPO_CARD\n INIT --> FILE_DOWNLOAD\n HF_API --> COMMIT\n HF_API --> HF_FS\n```\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 模块结构\n\n### 核心模块清单\n\n| 模块文件 | 主要类/函数 | 功能描述 |\n|---------|-----------|---------|\n| `__init__.py` | 公共API导出 | 静态导入自动生成，统一对外接口 |\n| `hf_api.py` | `HfApi` | 主API类，实现Repo CRUD、上传下载、讨论、PR、集合等 |\n| `file_download.py` | `hf_hub_download` | 单文件下载、缓存逻辑、ETag解析、xet下载支持 |\n| `_snapshot_download.py` | `snapshot_download` | 整仓库下载 |\n| `_commit_api.py` | `CommitOperationAdd/Delete/Copy` | 低级提交操作、LFS上传处理 |\n| `_commit_scheduler.py` | 后台提交调度 | 定时提交功能 |\n| `_upload_large_folder.py` | 大文件夹分块上传 | 超大文件夹上传 |\n| `hf_file_system.py` | `HfFileSystem` | 基于fsspec的POSIX兼容文件系统 |\n| `hub_mixin.py` | `ModelHubMixin` | ML框架集成基类 |\n| `repocard.py` | `RepoCard`, `ModelCard`, `DatasetCard`, `SpaceCard` | 仓库卡片管理 |\n| `repocard_data.py` | `CardData`, `ModelCardData` | 卡片元数据 |\n| `community.py` | `Discussion`, `DiscussionComment` | 讨论与评论 |\n| `lfs.py` | Git LFS工具 | LFS批量上传 |\n| `_login.py` | `login()`, `logout()` | 认证和令牌管理 |\n| `_inference_endpoints.py` | 推理端点管理 | 端点CRUD和扩缩容 |\n| `_jobs_api.py` | 训练任务API | 训练任务管理 |\n| `_space_api.py` | Space运行时 | Space运行管理 |\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 主要组件详解\n\n### HfApi 主类\n\n`HfApi` 是库的核心类，约11000行代码，承载了大多数 Hub 操作。\n\n**主要功能分类：**\n\n- 仓库CRUD操作（创建、删除、列表、详情）\n- 文件上传下载\n- Discussions 和 Pull Requests\n- Collections 管理\n- 模型卡片操作\n- 用户和组织管理\n\n```python\n# 使用示例\nfrom huggingface_hub import HfApi\napi = HfApi()\napi.upload_file(...)\napi.list_models(...)\n```\n\n资料来源：[hf_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_api.py)\n\n### RepoCard 体系\n\n仓库卡片（RepoCard）用于管理 Hugging Face 仓库的元数据和文档。\n\n```mermaid\nclassDiagram\n class RepoCard {\n +content: str\n +data: CardData\n +text: str\n +ignore_metadata_errors: bool\n }\n \n class CardData {\n +to_dict()\n +to_yaml()\n }\n \n class ModelCard {\n +card_data_class = ModelCardData\n }\n \n class DatasetCard {\n +card_data_class = DatasetCardData\n }\n \n class SpaceCard {\n +card_data_class = SpaceCardData\n +repo_type = \"space\"\n }\n \n RepoCard <|-- ModelCard\n RepoCard <|-- DatasetCard\n RepoCard <|-- SpaceCard\n RepoCard --> CardData\n```\n\n**卡片类型与默认模板：**\n\n| 卡片类型 | repo_type | 用途 |\n|--------|-----------|-----|\n| `ModelCard` | model | 模型元数据 |\n| `DatasetCard` | dataset | 数据集元数据 |\n| `SpaceCard` | space | Space应用元数据 |\n\n资料来源：[repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n资料来源：[repocard_data.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard_data.py)\n\n### EvalResultEntry 评估结果\n\n评估结果数据结构用于存储和上传模型评估指标。\n\n```python\n@dataclass\nclass EvalResultEntry:\n dataset_id: str # 数据集ID\n task_id: str # 任务ID\n value: Any # 评估值\n dataset_revision: str | None # 数据集版本\n verify_token: str | None # 验证令牌\n date: str | None # 评估日期\n source_url: str | None # 来源URL\n source_name: str | None # 来源名称\n source_user: str | None # 来源用户\n source_org: str | None # 来源组织\n notes: str | None # 备注\n```\n\n**验证规则：** 如果提供了 `source_name`、`source_user` 或 `source_org`，则必须同时提供 `source_url`。\n\n资料来源：[_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n\n### HfUri URI解析\n\n`HfUri` 是一个不可变数据类，用于解析 Hugging Face 特有的 URI 格式。\n\n**URI格式：**\n```\nhf://[/][@][/]\n```\n\n**支持的类型前缀：**\n\n| 类型 | URI前缀 | 示例 |\n|-----|--------|------|\n| model | 无/空 | `hf://my-org/my-model` |\n| dataset | datasets | `hf://datasets/my-org/my-dataset` |\n| space | spaces | `hf://spaces/my-org/my-space` |\n\n**特殊版本处理：** 支持 `refs/pr/N`（PR引用）和 `refs/convert/`（转换引用）格式。\n\n```python\n@dataclass(frozen=True)\nclass HfUri:\n type: str # URI类型\n id: str # 仓库ID\n revision: str | None # 版本号\n path_in_repo: str # 仓库内路径\n```\n\n资料来源：[utils/_hf_uris.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py)\n\n### HfFileSystem 文件系统\n\n`HfFileSystem` 基于 fsspec 实现，提供 POSIX 兼容的文件系统接口访问 Hub 仓库。\n\n```python\n# entry_points配置\nentry_points={\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\n**核心功能：**\n- 像本地文件系统一样操作远程仓库\n- 支持目录遍历、文件读写\n- 自动处理 LFS 文件\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n### Commit 操作体系\n\n`_commit_api.py` 实现了底层的 Git 提交操作。\n\n```mermaid\nclassDiagram\n class CommitOperation {\n <>\n }\n \n class CommitOperationAdd {\n +path_in_repo: str\n +path_or_fileobj: str | Path | bytes\n +rfc: str\n +uploaded: bool\n +as_file()\n }\n \n class CommitOperationDelete {\n +path_in_repo: str\n +is_file: bool\n }\n \n class CommitOperationCopy {\n +src_repo_id: str\n +src_path_in_repo: str\n +dest_path_in_repo: str\n }\n \n CommitOperation <|-- CommitOperationAdd\n CommitOperation <|-- CommitOperationDelete\n CommitOperation <|-- CommitOperationCopy\n```\n\n**上传方式支持：**\n\n| 类型 | 方式 | 说明 |\n|-----|------|-----|\n| 普通文件 | 直接上传 | 小文件直接提交 |\n| LFS文件 | Git LFS | 大文件通过LFS处理 |\n| 文件夹 | 分块上传 | `_upload_large_folder.py` |\n\n资料来源：[_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n\n### ModelHubMixin 框架集成\n\n`ModelHubMixin` 是机器学习框架集成的基类，允许模型直接保存和加载到 Hub。\n\n**支持的参数：**\n\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| `base_model` | str | 基础模型ID |\n| `model_name` | str | 模型名称 |\n| `library_name` | str | 库名称 |\n| `pipeline_tag` | str | 流水线标签 |\n| `language` | str \\| list | 支持语言 |\n| `license` | str | 许可证 |\n| `tags` | list | 标签列表 |\n\n资料来源：[hub_mixin.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)\n\n### 推理客户端\n\n推理客户端提供对部署模型的远程推理功能。\n\n**主要输出类型：**\n\n- `TextGenerationOutput` - 文本生成输出\n- `TextGenerationDetails` - 详细生成信息\n- `TextGenerationStreamOutput` - 流式输出\n- `TokenElement` - Token元素\n\n**功能特性：**\n- 同步和异步客户端\n- 流式输出支持\n- 详细日志概率信息\n\n资料来源：[inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py)\n\n## 常量定义\n\n`constants.py` 定义了全局常量，包括：\n\n- `HF_PROTOCOL` - URI协议前缀 (`hf://`)\n- `HF_URI_TYPE_PREFIXES` - 类型到前缀的映射\n- 默认配置值\n\n资料来源：[constants.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py)\n\n## 包依赖结构\n\n### 可选依赖分组\n\n| 分组 | 依赖 | 用途 |\n|-----|------|-----|\n| inference | inference 相关包 | 推理功能 |\n| testing | pytest 等 | 测试 |\n| quality | mypy, ruff | 代码质量 |\n| typing | libcst, ty | 类型检查 |\n| all | testing + quality + typing | 全量开发依赖 |\n\n```python\nextras[\"all\"] = extras[\"testing\"] + extras[\"quality\"] + extras[\"typing\"]\nextras[\"dev\"] = extras[\"all\"]\n```\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## 入口点配置\n\nCLI 入口点和文件系统规范注册：\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\", # 主CLI\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\", # 废弃CLI\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\", # Agent应用\n ],\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\", # 文件系统\n}\n```\n\n**最低Python版本：** `>=3.10.0`\n\n资料来源：[setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n\n## 公共API导出机制\n\n`__init__.py` 中的静态导入由 `utils/check_static_imports.py` 自动生成。运行 `make style` 可更新导出列表。\n\n```mermaid\nflowchart LR\n A[源码文件] --> B[check_static_imports.py]\n B --> C[自动生成]\n C --> D[__init__.py]\n D --> E[公共API]\n```\n\n资料来源：[CLAUDE.md](https://github.com/huggingface/huggingface_hub/blob/main/CLAUDE.md)\n\n## 认证与令牌管理\n\n`_login.py` 模块处理身份认证：\n\n- `login()` - 登录并保存令牌\n- `logout()` - 登出并清除令牌\n- `notebook_login()` - Jupyter notebook 登录\n\n资料来源：[_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n\n\n## 模块结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [文件操作](#file-operations)\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/file_download.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/file_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/community.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/community.py)\n \n\n# 模块结构详解\n\n## 概述\n\n`huggingface_hub` 是 Hugging Face 官方提供的 Python 客户端库，用于与 Hugging Face Hub 进行交互。该库采用模块化架构设计，核心功能围绕模型仓库（Model Repository）的操作展开，包括文件下载、上传、仓库管理、社区互动等关键能力。资料来源：[README.md]()\n\n## 核心模块架构\n\n`huggingface_hub` 的源代码位于 `src/huggingface_hub/` 目录下，采用以下主要模块划分：\n\n```mermaid\ngraph TD\n A[huggingface_hub] --> B[hf_api.py]\n A --> C[file_download.py]\n A --> D[_commit_api.py]\n A --> E[community.py]\n A --> F[repocard.py]\n A --> G[inference]\n A --> H[utils]\n \n B -->|HTTP API| I[Hub交互层]\n C --> J[文件系统层]\n D --> I\n E --> K[社区功能]\n```\n\n### 主要模块职责\n\n| 模块文件 | 主要职责 |\n|---------|---------|\n| `hf_api.py` | 封装所有 Hugging Face Hub HTTP API 调用 |\n| `file_download.py` | 处理文件下载、缓存管理、快照下载 |\n| `_commit_api.py` | 实现 Git 风格的提交操作、文件上传 |\n| `community.py` | 处理社区评论、讨论、投票等互动功能 |\n| `repocard.py` | 解析和生成 Model Card / Dataset Card |\n| `inference/` | 推理 API 客户端集成 |\n| `utils/` | URI 解析、验证器等工具函数 |\n\n资料来源：[setup.py]()、[src/huggingface_hub/repocard.py]()\n\n---\n\n## hf_api.py - Hub API 封装层\n\n### 功能概述\n\n`hf_api.py` 是整个库的核心模块，负责封装所有与 Hugging Face Hub 的 HTTP API 通信。该模块提供了创建仓库、删除仓库、列表查询、上传文件、下载文件等原子操作。资料来源：[src/huggingface_hub/hf_api.py]()\n\n### 核心功能分类\n\n#### 仓库管理 API\n\n- `create_repo()` - 创建新仓库\n- `delete_repo()` - 删除仓库\n- `update_repo_visibility()` - 更新仓库可见性\n- `move_repo()` - 移动仓库\n\n#### 文件操作 API\n\n- `upload_file()` - 单文件上传\n- `upload_folder()` - 文件夹上传\n- `get_hub_wизм()` - 获取仓库信息\n- `list_repo_files()` - 列出仓库文件\n\n#### 模型/数据集/空间管理\n\n- `list_models()` - 搜索模型列表\n- `list_datasets()` - 搜索数据集列表\n- `list_spaces()` - 搜索 Spaces 列表\n- `get_model_tags()` - 获取模型标签\n\n资料来源：[src/huggingface_hub/hf_api.py]()\n\n---\n\n## file_download.py - 文件下载与缓存系统\n\n### 功能概述\n\n`file_download.py` 实现了高效的文件下载和缓存管理机制，支持单个文件下载和整个仓库的快照下载。所有下载的文件都会缓存在本地文件系统中，避免重复下载。资料来源：[README.md]()\n\n### 下载流程\n\n```mermaid\ngraph TD\n A[开始下载请求] --> B{检查本地缓存}\n B -->|缓存命中| C[返回缓存文件路径]\n B -->|缓存未命中| D[发起HTTP请求]\n D --> E{检查增量更新}\n E -->|有更新| F[下载增量内容]\n E -->|无更新| G[下载完整文件]\n F --> H[更新缓存]\n G --> H\n H --> I[返回文件路径]\n```\n\n### 核心函数\n\n| 函数名 | 功能描述 |\n|--------|---------|\n| `hf_hub_download()` | 下载单个文件到指定路径 |\n| `snapshot_download()` | 下载整个仓库的快照 |\n| `get_hub_blobs()` | 获取文件 blob 列表 |\n| `get_hub_fs()` | 获取 HfFileSystem 实例 |\n\n### 缓存机制\n\n库使用 `~/.cache/huggingface/hub/` 作为默认缓存目录，每个仓库的文件根据 repo_id 和 revision 进行组织。资料来源：[src/huggingface_hub/file_download.py]()\n\n---\n\n## _commit_api.py - Git 风格提交系统\n\n### 功能概述\n\n`_commit_api.py` 实现了基于 Git 的仓库提交操作，这是 Hugging Face Hub 的核心特性之一。该模块支持原子性的多文件提交操作，并提供了进度跟踪和文件预览功能。资料来源：[src/huggingface_hub/_commit_api.py]()\n\n### 提交操作架构\n\n```mermaid\ngraph LR\n A[CommitOperation] --> B[CommitOperationAdd]\n A --> C[CommitOperationDelete]\n \n D[preupload] --> E[验证文件]\n E --> F[计算 LFS 差异]\n F --> G[创建提交]\n \n H[CommitWorker] --> I[分块上传]\n I --> J[更新仓库树]\n J --> K[完成提交]\n```\n\n### 核心类\n\n#### CommitOperation\n\n文件操作的基类，支持以下操作类型：\n\n| 类型 | 说明 |\n|-----|------|\n| `CommitOperationAdd` | 添加或更新文件 |\n| `CommitOperationDelete` | 删除文件 |\n\n#### CommitOperationAdd 关键方法\n\n```python\ndef as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]:\n \"\"\"将本地文件对象转换为可迭代的字节流，支持进度条\"\"\"\n```\n\n该方法支持三种输入类型：\n\n- 字符串或 Path 对象（本地文件路径）\n- bytes（字节数据）\n- BufferedIOBase（已打开的文件对象）\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-50]()\n\n### 提交流程\n\n1. **预上传阶段** (`preupload_hub_metadata`)：验证文件大小、计算 LFS 指针\n2. **文件上传阶段**：分块上传普通文件，LFS 跟踪大文件\n3. **提交创建阶段**：构建提交树，创建 Git 提交\n4. **元数据更新**：更新仓库标签、卡片等元信息\n\n资料来源：[src/huggingface_hub/_commit_api.py]()\n\n---\n\n## community.py - 社区互动模块\n\n### 功能概述\n\n`community.py` 模块处理 Hugging Face Hub 的社区功能，包括评论、讨论帖、投票和 PR 评论等交互功能。这些功能使用统一的 `Discussion` 和 `Comment` 数据模型进行抽象。资料来源：[src/huggingface_hub/community.py]()\n\n### 社区功能类型\n\n| 功能 | API 方法前缀 | 说明 |\n|-----|-------------|------|\n| Discussion | `create_discussion()` | 创建讨论帖 |\n| Comment | `comment_discussion()` | 评论讨论 |\n| PR Review | `create_pull_request_review()` | PR 评审 |\n| Vote | `vote_discussion()` | 对讨论投票 |\n\n### 数据模型\n\n社区模块使用 Pydantic 或 dataclass 风格的数据类定义：\n\n- `DiscussionTitle`：讨论标题\n- `DiscussionComment`：单条评论\n- `DiscussionStatus`：讨论状态（open/closed/merged）\n\n资料来源：[src/huggingface_hub/community.py]()\n\n---\n\n## 协作流程示例\n\n### 文件上传到下载的完整流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant hf_api\n participant file_download\n participant _commit_api\n participant Hub\n \n Client->>hf_api: create_repo()\n Hub-->>hf_api: repo_id\n hf_api-->>Client: 仓库创建成功\n \n Client->>_commit_api: CommitOperationAdd()\n Client->_commit_api: commit_add_files()\n _commit_api->>Hub: Git Push\n Hub-->>_commit_api: Commit SHA\n _commit_api-->>Client: 上传完成\n \n Client->>file_download: snapshot_download()\n file_download->>Hub: HEAD 请求\n Hub-->>file_download: 文件列表\n file_download->>Hub: 分块下载\n Hub-->>file_download: 文件内容\n file_download-->>Client: 本地缓存路径\n```\n\n资料来源：[README.md]()、[src/huggingface_hub/_commit_api.py]()\n\n---\n\n## 包结构与入口点\n\n### setup.py 配置\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\",\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\",\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\",\n ],\n \"fsspec.specs\": \"hf=huggingface_hub.HfFileSystem\",\n}\n```\n\n### CLI 命令\n\n| 命令 | 功能 |\n|-----|------|\n| `hf auth login` | 登录认证 |\n| `hf download` | 下载文件 |\n| `hf upload` | 上传文件 |\n| `hf spaces` | Space 管理 |\n\n### 可选依赖\n\n| Extra | 包含功能 |\n|-------|---------|\n| `inference` | 推理 API 支持 |\n| `mcp` | MCP 服务器功能 |\n| `testing` | 测试工具 |\n\n资料来源：[setup.py]()\n\n---\n\n## 关键设计模式\n\n### 1. 仓库类型统一抽象\n\n库通过 `repo_type` 参数统一抽象模型、数据集和 Space：\n\n```python\nrepo_type: Literal[\"model\", \"dataset\", \"space\"]\n```\n\n### 2. 异步与同步双支持\n\n核心 API 同时提供同步和异步版本：\n\n- 同步：`hf_hub_download()`\n- 异步：`AsyncInferenceClient`\n\n### 3. 文件系统抽象\n\n通过 `HfFileSystem` 提供类似本地文件系统的操作体验：\n\n```python\nfs = HfFileSystem()\nfs.ls(\"my-org/my-model\")\n```\n\n资料来源：[src/huggingface_hub/file_download.py]()\n\n---\n\n## 总结\n\n`huggingface_hub` 采用清晰的模块化架构，通过 `hf_api.py` 封装底层 HTTP 通信，`file_download.py` 实现高效的文件缓存，`_commit_api.py` 提供 Git 风格的版本控制能力，`community.py` 处理社区互动。这种设计使得库既保持了功能的完整性，又便于维护和扩展。\n\n---\n\n\n\n## 文件操作\n\n### 相关页面\n\n相关主题：[缓存系统](#cache-system), [Git LFS 集成](#lfs-integration)\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/_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 \n\n# 文件操作\n\n## 概述\n\nhuggingface_hub 库提供了完整的文件操作功能，涵盖从 Hugging Face Hub 下载文件、上传文件、以及通过类文件系统接口操作仓库内容。这些功能是该库的核心能力之一，使得用户能够方便地与 Hub 上的模型、数据集和 Space 进行交互。\n\n文件操作主要通过以下模块实现：\n\n| 模块 | 核心功能 |\n|------|----------|\n| `file_download.py` | 单文件下载、ETag 缓存、xet 支持 |\n| `_snapshot_download.py` | 完整仓库快照下载 |\n| `_commit_api.py` | 文件上传、删除、复制操作 |\n| `hf_file_system.py` | 基于 fsspec 的 POSIX 风格文件系统 |\n\n## 文件下载\n\n### hf_hub_download - 单文件下载\n\n`hf_hub_download` 是下载单个文件的核心函数，支持完整的缓存机制和元数据解析。\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 基础下载\nhf_hub_download(repo_id=\"tiiuae/falcon-7b-instruct\", filename=\"config.json\")\n\n# 指定版本和本地路径\nhf_hub_download(\n repo_id=\"username/my-model\",\n filename=\"pytorch_model.bin\",\n subfolder=\"weights\",\n revision=\"main\",\n local_dir=\"./models\"\n)\n```\n\n#### 核心参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `repo_id` | str | 仓库标识符 (格式: `username/model-name`) |\n| `filename` | str | 要下载的文件名 |\n| `subfolder` | str, optional | 文件所在的子文件夹 |\n| `revision` | str, optional | Git 分支名或提交哈希，默认 `main` |\n| `repo_type` | str, optional | 仓库类型：`model`、`dataset`、`space` |\n| `cache_dir` | str, optional | 缓存目录路径 |\n| `local_dir` | str, optional | 本地目录，下载后文件将复制到此 |\n| `local_dir_use_symlinks` | str/bool | 符号链接策略：`\"auto\"`、`True`、`False` |\n| `force_download` | bool | 是否强制重新下载 |\n| `etag` | str, optional | 用于缓存验证的 ETag |\n\n### 缓存机制\n\n文件下载后会自动缓存到本地，缓存路径默认为 `~/.cache/huggingface/hub`。库使用 ETag 和 Last-Modified 头进行条件请求，避免重复下载。\n\n```mermaid\ngraph TD\n A[请求下载] --> B{检查本地缓存}\n B -->|存在且有效| C[返回缓存文件]\n B -->|不存在或过期| D[发送 HTTP 请求]\n D --> E{Hub 返回 304}\n E -->|是| C\n E -->|否| F[下载新文件]\n F --> G[更新缓存]\n G --> H[返回文件路径]\n```\n\n### xet 下载支持\n\n对于支持 xet 协议的文件，系统会使用 xet 协议进行流式下载，提高大文件的下载效率。资料来源：[file_download.py:1-100]()\n\n### snapshot_download - 仓库快照下载\n\n`snapshot_download` 用于下载整个仓库的所有文件，确保所有文件来自同一修订版本。\n\n```python\nfrom huggingface_hub import snapshot_download\n\n# 下载整个模型仓库\nsnapshot_download(\"stabilityai/stable-diffusion-2-1\")\n\n# 带有过滤条件\nsnapshot_download(\n repo_id=\"my-dataset\",\n repo_type=\"dataset\",\n allow_patterns=[\"*.json\", \"*.csv\"],\n ignore_patterns=[\"*.parquet\"]\n)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `repo_id` | str | 必填 | 仓库标识符 |\n| `repo_type` | str | `\"model\"` | 仓库类型 |\n| `revision` | str | `None` | Git 修订版本 |\n| `cache_dir` | str | `None` | 缓存目录 |\n| `local_dir` | str | `None` | 本地目录 |\n| `allow_patterns` | list[str] | `None` | 包含文件模式 |\n| `ignore_patterns` | list[str] | `None` | 排除文件模式 |\n| `max_workers` | int | `8` | 最大并发下载数 |\n| `tqdm` | callable | `tqdm.auto` | 进度条工厂函数 |\n\n资料来源：[_snapshot_download.py:1-150]()\n\n## 文件上传\n\n### 核心上传函数\n\nhuggingface_hub 支持多种文件上传方式：\n\n#### upload_file - 单文件上传\n\n```python\nfrom huggingface_hub import upload_file\n\nupload_file(\n path_or_fileobj=\"/path/to/local/model.bin\",\n path_in_repo=\"pytorch_model.bin\",\n repo_id=\"username/my-model\",\n)\n```\n\n#### upload_folder - 文件夹上传\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=\"Add new files\"\n)\n```\n\n### CommitOperation 机制\n\n底层文件操作通过 `CommitOperation` 类实现，支持原子性操作：\n\n```python\nfrom huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete\n\napi = HfApi()\n\n# 添加文件操作\noperations = [\n CommitOperationAdd(\n path_in_repo=\"README.md\",\n path_or_fileobj=\"/local/README.md\"\n ),\n CommitOperationDelete(\n path_in_repo=\"old_file.txt\"\n )\n]\n\n# 批量提交\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Update model files\"\n)\n```\n\n#### CommitOperationAdd\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `path_in_repo` | str | 仓库中的目标路径 |\n| `path_or_fileobj` | str/bytes/IOBase | 本地文件或字节数据 |\n\n资料来源：[_commit_api.py:1-100]()\n\n#### CommitOperationDelete\n\n```python\nCommitOperationDelete(path_in_repo=\"obsolete/model.bin\")\n```\n\n#### CommitOperationCopy\n\n```python\nCommitOperationCopy(\n src_path_in_repo=\"path/to/source/file\",\n dest_path_in_repo=\"path/to/destination/file\"\n)\n```\n\n### LFS 大文件处理\n\n大于 10MB 的文件会自动使用 Git LFS (Large File Storage) 处理：\n\n```mermaid\ngraph TD\n A[上传文件] --> B{文件大小 > 10MB?}\n B -->|否| C[普通 Git 对象]\n B -->|是| D[Git LFS 处理]\n D --> E[上传 LFS 对象]\n E --> F[创建 LFS 指针文件]\n C --> G[创建 commit]\n F --> G\n```\n\n## HfFileSystem - 文件系统接口\n\n`HfFileSystem` 提供了 POSIX 风格的文件系统接口，基于 fsspec 规范实现，使开发者能够像操作本地文件一样操作 Hub 仓库。\n\n### 基本用法\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出仓库文件\nfiles = fs.ls(\"username/my-model\")\n\n# 读取文件\nwith fs.open(\"username/my-model/config.json\", \"r\") as f:\n content = f.read()\n\n# 检查文件存在\nif fs.exists(\"username/my-model/pytorch_model.bin\"):\n print(\"Model file exists\")\n```\n\n### 支持的操作\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 读取 | `cat()`, `read_block()` | 获取文件内容 |\n| 写入 | `pipe()`, `write_block()` | 写入文件内容 |\n| 列表 | `ls()`, `glob()` | 列出文件/目录 |\n| 属性 | `info()`, `ls()` | 获取文件元数据 |\n| 创建 | `makedirs()` | 创建目录 |\n| 删除 | `rm()` | 删除文件/目录 |\n| 移动 | `mv()` | 移动/重命名 |\n| 复制 | `cp()` | 复制文件 |\n| 链接 | `symlink()` | 创建符号链接 |\n\n### URI 格式\n\nHfFileSystem 支持 `hf://` URI 协议：\n\n```\nhf://{repo_id}@{revision}/{path_in_repo}[:mount_path[:ro|:rw]]\n```\n\n示例：\n\n```python\n# 标准格式\nfs = HfFileSystem()\nfs.ls(\"hf://username/my-model@main/weights\")\n\n# 带挂载点\nfs = HfFileSystem()\nfs.get(\"hf://username/model@refs/pr/1/weights\", \"/local/weights\")\n```\n\n资料来源：[hf_file_system.py:1-200]()\n\n## HubMixin 集成\n\n`ModelHubMixin` 类为 ML 框架提供了与 Hub 集成的基类支持自动化的模型保存和加载。\n\n```python\nfrom huggingface_hub import ModelHubMixin\n\nclass MyModel(ModelHubMixin, nn.Module):\n def __init__(self):\n super().__init__()\n self.layer = nn.Linear(10, 2)\n \n @classmethod\n def _from_pretrained(cls, **kwargs):\n # 自定义加载逻辑\n return cls()\n \n def _save_pretrained(self, save_directory):\n # 自定义保存逻辑\n torch.save(self.state_dict(), f\"{save_directory}/model.bin\")\n```\n\n支持的参数包括：\n\n| 参数 | 说明 |\n|------|------|\n| `model_id` | 模型标识符或本地路径 |\n| `cache_dir` | 缓存目录 |\n| `force_download` | 强制重新下载 |\n| `resume_download` | 断点续传 |\n| `proxies` | 代理设置 |\n| `token` | 认证令牌 |\n\n资料来源：[hub_mixin.py:1-100]()\n\n## 错误处理\n\n文件操作过程中可能遇到的常见错误：\n\n| 错误类型 | 说明 |\n|----------|------|\n| `RepositoryNotFoundError` | 指定的仓库不存在 |\n| `RevisionNotFoundError` | 指定的修订版本不存在 |\n| `EntryNotFoundError` | 文件或目录不存在 |\n| `LocalEntryNotFoundError` | 缓存中找不到文件 |\n| `HfHubHTTPError` | HTTP 请求失败 |\n| `HuggingFaceHubValidationError` | 参数验证失败 |\n\n## 最佳实践\n\n1. **缓存利用**：优先使用默认缓存机制，避免重复下载\n2. **版本锁定**：生产环境中建议指定具体的 `revision` 以确保可复现性\n3. **并发控制**：使用 `max_workers` 参数控制下载并发数\n4. **符号链接**：在开发环境中使用 `local_dir_use_symlinks=\"auto\"` 节省磁盘空间\n5. **大文件处理**：对于超过 5GB 的文件，考虑分块下载或使用 `as_file()` 上下文管理器\n\n```python\nfrom huggingface_hub import hf_hub_download, CommitOperationAdd\n\n# 使用上下文管理器处理大文件\noperation = CommitOperationAdd(\n path_in_repo=\"large_model.bin\",\n path_or_fileobj=\"./large_model.bin\"\n)\n\nwith operation.as_file(with_tqdm=True) as file:\n # 逐步处理文件内容\n while chunk := file.read(8192):\n process(chunk)\n\n---\n\n\n\n## 推理系统\n\n### 相关页面\n\n相关主题：[命令行工具](#cli-commands)\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_endpoints.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_inference_endpoints.py)\n- [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py)\n- [src/huggingface_hub/_eval_results.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_eval_results.py)\n \n\n# 推理系统\n\n## 概述\n\nhuggingface_hub 的推理系统（Inference System）是一个用于在 Hugging Face Hub 上部署的模型上执行推理任务的客户端库。该系统提供了同步和异步两种客户端实现，支持多种推理任务类型，包括文本生成、文本摘要、文本到图像、文本到视频、翻译、图像问答等。\n\n推理系统的核心设计理念是通过统一的 API 接口，屏蔽不同推理提供商的实现差异，为用户提供简洁一致的推理调用体验。系统支持多种推理提供者（Provider），包括 Hugging Face 官方推理端点、Replicate 等第三方服务。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[InferenceClient / AsyncInferenceClient]\n B --> C[Provider Helper]\n C --> D{Hub Inference / 第三方 Provider}\n D --> E[远程推理端点]\n E --> F[模型推理结果]\n F --> B\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| InferenceClient | inference/_client.py | 同步推理客户端主类 |\n| AsyncInferenceClient | inference/_generated/_async_client.py | 异步推理客户端 |\n| Provider Helper | inference/_providers/__init__.py | 提供者适配层 |\n| InferenceEndpoints | _inference_endpoints.py | 推理端点管理 |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n## 客户端实现\n\n### InferenceClient（同步客户端）\n\nInferenceClient 是推理系统的主要入口点，提供同步推理能力。客户端初始化时可以指定模型、提供者和 API 密钥等配置。\n\n**初始化参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| model | str | 默认使用的模型 ID | None |\n| provider | str | 推理提供者名称 | None |\n| api_key | str | Hugging Face API 密钥 | None |\n| timeout | float | 请求超时时间（秒） | None |\n| headers | dict | 自定义 HTTP 头 | None |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### AsyncInferenceClient（异步客户端）\n\nAsyncInferenceClient 提供异步推理能力，适用于需要高并发的应用场景，如 Web 服务或批量处理系统。\n\n```python\n# 异步客户端使用示例\n>>> client = AsyncInferenceClient(\"meta-llama/Meta-Llama-3-70B-Instruct\")\n>>> messages = [\n... {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n... {\"role\": \"user\", \"content\": \"What is 2+2?\"}\n... ]\n>>> response = await client.chat_completion(messages)\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-100]()\n\n## 支持的推理任务\n\n### 文本生成（Text Generation）\n\n文本生成是推理系统最核心的功能之一，支持流式输出和详细令牌信息返回。\n\n**主要方法：** `text_generation(prompt, *, model=None, ...)`\n**返回类型：** TextGenerationOutput\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 输入提示文本 |\n| model | str | 模型 ID（可选） |\n| stream | bool | 是否启用流式输出 |\n| details | bool | 是否返回详细生成信息 |\n| max_new_tokens | int | 最大生成令牌数 |\n| temperature | float | 采样温度 |\n| top_p | float | 核采样概率 |\n\n**流式输出示例：**\n\n```python\n>>> for details in client.text_generation(\"The huggingface_hub library is \", max_new_tokens=12, stream=True):\n... print(details)\nTextGenerationStreamOutput(token=TokenElement(id=1425, text='100', ...))\nTextGenerationStreamOutput(token=TokenElement(id=16, text='%', ...))\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本摘要（Summarization）\n\n将长文本压缩为简短摘要的功能。\n\n**主要方法：** `summarization(text, *, model=None, ...)`\n**返回类型：** SummarizationOutput\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| text | str | 待摘要的输入文本 |\n| model | str | 摘要模型 ID |\n| clean_up_tokenization_spaces | bool | 清理分词空格 |\n| truncation | str | 截断策略 |\n| generate_parameters | dict | 生成参数配置 |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import InferenceClient\n>>> client = InferenceClient()\n>>> client.summarization(\"The Eiffel tower...\")\nSummarizationOutput(generated_text=\"The Eiffel tower is one of the most famous landmarks...\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本到图像（Text-to-Image）\n\n根据文本描述生成对应图像的功能。\n\n**主要方法：** `text_to_image(prompt, *, model=None, ...)`\n**返回类型：** PIL.Image\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 图像描述文本 |\n| model | str | 生成模型 ID |\n| negative_prompt | str | 负面提示词 |\n| height | int | 输出图像高度 |\n| width | int | 输出图像宽度 |\n| num_inference_steps | int | 推理步数 |\n| guidance_scale | float | 引导比例 |\n| seed | int | 随机种子 |\n\n**使用示例：**\n\n```python\n>>> client = InferenceClient(\n... provider=\"replicate\",\n... api_key=\"hf_...\",\n... )\n>>> image = client.text_to_image(\n... \"An astronaut riding a horse on the moon.\",\n... model=\"black-forest-labs/FLUX.1-schnell\",\n... )\n>>> image.save(\"astronaut.png\")\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文本到视频（Text-to-Video）\n\n根据文本描述生成对应视频的功能。\n\n**主要方法：** `text_to_video(prompt, *, model=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| prompt | str | 视频描述文本 |\n| model | str | 生成模型 ID |\n| num_frames | float | 生成帧数 |\n| num_inference_steps | int | 推理步数 |\n| guidance_scale | float | 引导比例 |\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 翻译（Translation）\n\n支持多语言之间的文本翻译任务。\n\n**主要方法：** `translation(text, *, model=None, src_lang=None, tgt_lang=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| text | str | 待翻译文本 |\n| model | str | 翻译模型 ID |\n| src_lang | str | 源语言代码 |\n| tgt_lang | str | 目标语言代码 |\n| clean_up_tokenization_spaces | bool | 清理分词空格 |\n\n**使用约束：**\n\n- 如果模型支持多语言翻译，必须同时提供 `src_lang` 和 `tgt_lang` 参数\n- 只提供其中一个参数将抛出 `ValueError` 异常\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 文档问答（Document Question Answering）\n\n从文档图像中提取问题答案的功能。\n\n**主要方法：** `document_question_answering(image, question, *, model=None, ...)`\n\n**关键参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| image | str | 图像路径或 URL |\n| question | str | 问题文本 |\n| model | str | 模型 ID |\n| doc_stride | int | 文档分块跨度 |\n| max_answer_len | int | 最大答案长度 |\n| top_k | int | 返回 Top-K 答案 |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import AsyncInferenceClient\n>>> client = AsyncInferenceClient()\n>>> await client.document_question_answering(\n... image=\"https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png\",\n... question=\"What is the invoice number?\"\n... )\n[DocumentQuestionAnsweringOutputElement(answer='us-001', end=16, score=0.9999666213989258, start=16)]\n```\n\n资料来源：[src/huggingface_hub/inference/_generated/_async_client.py:1-100]()\n\n## 提供者系统\n\n### Provider Helper 架构\n\nProvider Helper 是推理系统实现多提供者支持的核心组件，负责将统一的推理请求转换为特定提供者的请求格式。\n\n```mermaid\ngraph LR\n A[InferenceClient] --> B[get_provider_helper]\n B --> C{Provider 类型}\n C -->|HuggingFace| D[HF Provider Helper]\n C -->|Replicate| E[Replicate Provider Helper]\n C -->|其他| F[第三方 Helper]\n D --> G[Prepare Request]\n E --> G\n F --> G\n```\n\n### 请求参数准备\n\n每个 Provider Helper 实现 `prepare_request` 方法，将通用参数转换为特定提供者的请求格式：\n\n```python\nrequest_parameters = provider_helper.prepare_request(\n inputs=text,\n parameters={\n \"temperature\": temperature,\n \"max_new_tokens\": max_new_tokens,\n ...\n },\n headers=self.headers,\n model=model_id,\n api_key=self.token,\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_providers/__init__.py:1-50]()\n\n## 推理端点管理\n\n### InferenceEndpoints 类\n\nInferenceEndpoints 类用于管理 Hugging Face 推理端点的生命周期。\n\n**主要功能：**\n\n| 功能 | 说明 |\n|------|------|\n| 创建端点 | 在指定区域创建推理端点 |\n| 删除端点 | 销毁不再需要的推理端点 |\n| 状态查询 | 获取端点运行状态 |\n| 日志查看 | 访问端点运行日志 |\n\n资料来源：[src/huggingface_hub/_inference_endpoints.py:1-100]()\n\n## 输出数据结构\n\n### 文本生成输出\n\n| 类名 | 说明 |\n|------|------|\n| TextGenerationOutput | 标准文本生成输出 |\n| TextGenerationDetails | 包含详细生成信息 |\n| TextGenerationPrefillOutputToken | 前置填充令牌 |\n| TokenElement | 单个生成令牌 |\n| TextGenerationStreamOutput | 流式输出令牌 |\n\n**TokenElement 结构：**\n\n```python\nTokenElement(\n id=1425, # 令牌 ID\n text='100', # 令牌文本\n logprob=-1.01, # 对数概率\n special=False # 是否为特殊令牌\n)\n```\n\n资料来源：[src/huggingface_hub/inference/_client.py:1-100]()\n\n### 评估结果\n\nEvalResultEntry 用于存储和上传模型评估结果：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| dataset_id | str | 数据集标识符 |\n| task_id | str | 任务标识符 |\n| value | Any | 评估指标值 |\n| dataset_revision | str | 数据集版本 |\n| verify_token | str | 验证令牌 |\n| date | str | 评估日期 |\n| source_url | str | 来源 URL |\n\n**使用示例：**\n\n```python\n>>> from huggingface_hub import EvalResultEntry, eval_result_entries_to_yaml\n>>> entries = [\n... EvalResultEntry(dataset_id=\"cais/hle\", task_id=\"default\", value=20.90),\n... ]\n>>> yaml_data = eval_result_entries_to_yaml(entries)\n>>> yaml_data[0]\n{'dataset': {'id': 'cais/hle', 'task_id': 'default'}, 'value': 20.9}\n```\n\n资料来源：[src/huggingface_hub/_eval_results.py:1-100]()\n\n## 错误处理\n\n### 常见异常类型\n\n| 异常类型 | 触发条件 |\n|----------|----------|\n| InferenceTimeoutError | 推理请求超时 |\n| HfHubHTTPError | HTTP 请求失败（非 503） |\n| ValueError | 参数验证失败 |\n\n### 错误处理示例\n\n```python\ntry:\n result = client.text_generation(\"Hello world\")\nexcept InferenceTimeoutError:\n print(\"请求超时，请检查网络连接\")\nexcept ValueError as e:\n print(f\"参数错误: {e}\")\n```\n\n## 使用工作流\n\n### 基本使用流程\n\n```mermaid\ngraph TD\n A[初始化 InferenceClient] --> B[选择任务类型]\n B --> C{文本 / 图像 / 视频}\n C -->|文本| D[文本生成 / 翻译 / 摘要]\n C -->|图像| E[文本到图像 / 文档问答]\n C -->|视频| F[文本到视频]\n D --> G[调用推理方法]\n E --> G\n F --> G\n G --> H[获取推理结果]\n H --> I[处理结果]\n```\n\n### 完整使用示例\n\n```python\nfrom huggingface_hub import InferenceClient\n\n# 初始化客户端\nclient = InferenceClient(\n provider=\"replicate\",\n api_key=\"hf_xxxxx\"\n)\n\n# 图像生成\nimage = client.text_to_image(\n \"A beautiful sunset over the ocean\",\n model=\"black-forest-labs/FLUX.1-schnell\",\n extra_body={\"output_quality\": 100}\n)\n\n# 保存结果\nimage.save(\"sunset.png\")\n```\n\n## 性能优化建议\n\n1. **选择合适的提供者**：不同提供者的性能和成本特性不同，应根据实际需求选择\n2. **使用流式输出**：对于长文本生成，启用流式输出可改善用户体验\n3. **合理设置超时**：对于复杂任务，适当增加超时时间\n4. **使用缓存**：频繁请求相同内容时，利用推理端点的缓存机制\n\n## 扩展阅读\n\n- [Hugging Face 推理文档](https://huggingface.co/docs/huggingface_hub/main/ko/guides/inference)\n- [Hub 安全令牌](https://huggingface.co/docs/hub/security-tokens)\n- [推理端点部署指南](https://huggingface.co/docs/inference-endpoints)\n\n---\n\n\n\n## 仓库管理\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations)\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/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n- [src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n- [src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.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/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n \n\n# 仓库管理\n\n## 概述\n\n`huggingface_hub` 库提供了完整的 Hugging Face Hub 仓库管理功能，涵盖仓库的创建、删除、复制、权限管理以及元数据维护等核心操作。这些功能主要通过 `HfApi` 类实现，为 Python 用户和 CLI 工具提供了统一的接口层。仓库（Repository）是 Hugging Face 生态系统的核心概念，支持三种主要类型：模型（Model）、数据集（Dataset）和 Space。\n\n仓库管理的架构设计遵循分层原则，底层通过 HTTP API 与 Hugging Face Hub 服务器通信，中层提供文件系统的抽象（`HfFileSystem`），上层则封装了面向用户的便捷函数。这种分层设计使得用户可以根据需求选择不同层级的 API 进行操作，既可以使用高级函数快速完成任务，也可以使用底层 API 进行精细控制。\n\n---\n\n## 仓库类型\n\nHugging Face Hub 支持三种核心仓库类型，每种类型针对不同的使用场景进行了优化。\n\n| 仓库类型 | 类型标识 | 典型用途 | 支持的文件大小 |\n|---------|---------|---------|---------------|\n| 模型 | `model` | 机器学习模型存储与分享 | 支持大文件（LFS） |\n| 数据集 | `dataset` | 训练数据、评测数据存储 | 支持大文件（LFS） |\n| Space | `space` | 交互式应用与演示 | 通常较小文件 |\n\n仓库类型在创建时指定，并通过 `repo_type` 参数区分。不同类型的仓库在 Hub 上具有不同的展示页面和交互组件，例如模型仓库会显示模型卡片和推理 Widget，数据集仓库会展示数据集预览功能。\n\n```python\nfrom huggingface_hub import create_repo\n\n# 创建模型仓库\nmodel_repo = create_repo(repo_id=\"username/my-model\", repo_type=\"model\")\n\n# 创建数据集仓库\ndataset_repo = create_repo(repo_id=\"username/my-dataset\", repo_type=\"dataset\")\n\n# 创建 Space 仓库\nspace_repo = create_repo(repo_id=\"username/my-space\", repo_type=\"space\")\n```\n\n---\n\n## 仓库生命周期管理\n\n### 创建仓库\n\n`create_repo` 函数用于在 Hugging Face Hub 上创建新仓库。该函数支持丰富的配置选项，包括仓库可见性、仓库描述、许可证设置等。创建仓库时需要提供唯一的 `repo_id`，格式为 `用户名/仓库名`。\n\n```python\nfrom huggingface_hub import create_repo\n\n# 创建私有模型仓库\nrepo = create_repo(\n repo_id=\"username/my-private-model\",\n repo_type=\"model\",\n private=True,\n exist_ok=False # 仓库已存在时抛出异常\n)\n```\n\n创建仓库时的关键参数包括：`repo_id`（必填，仓库唯一标识）、`repo_type`（可选，默认为 model）、`private`（控制可见性）、`exist_ok`（已存在时是否返回成功）。仓库创建成功后返回 `Repository` 对象，包含仓库的基本信息。\n\n### 删除仓库\n\n仓库删除操作通过 `delete_repo` 函数完成，该操作是不可逆的。删除仓库需要用户具有相应的权限，且只能删除自己拥有的仓库。系统会对删除操作进行确认提示，以防止误删。\n\n```python\nfrom huggingface_hub import delete_repo\n\n# 删除仓库\ndelete_repo(repo_id=\"username/my-old-model\", repo_type=\"model\")\n```\n\n### 复制仓库\n\n`duplicate_repo` 函数允许用户复制现有仓库，创建一个新的仓库副本。这对于创建模板仓库或备份非常重要。复制操作会保留原仓库的所有文件和元数据，新仓库的所有权归当前认证用户。\n\n```python\nfrom huggingface_hub import duplicate_repo\n\n# 复制仓库\nnew_repo = duplicate_repo(from_repo_id=\"template-org/template-model\")\n```\n\n---\n\n## 仓库权限与可见性\n\n### 可见性控制\n\n仓库的可见性决定了其他用户是否可以访问仓库内容。`huggingface_hub` 通过 `private` 参数控制可见性设置：\n\n| 可见性 | private 值 | 访问权限 | 适用场景 |\n|-------|-----------|---------|---------|\n| 公开 | `False` | 所有互联网用户可读 | 开源模型、数据集 |\n| 私有 | `True` | 仅所有者可见 | 未发布工作、内部项目 |\n\n公开仓库的内容对所有互联网用户可见，但只有授权用户可以推送更新。私有仓库完全由所有者控制，适合处理敏感数据或未完成的工作。\n\n### 访问令牌管理\n\n访问令牌（Token）是 Hugging Face Hub 认证的核心机制。用户需要通过 `login` 函数进行身份验证，之后的操作将使用已认证的令牌进行授权。\n\n```python\nfrom huggingface_hub import login\n\n# 交互式登录\nlogin()\n\n# 或使用环境变量中的令牌\n# HUGGINGFACE_TOKEN=hf_xxx python script.py\n```\n\nCLI 方式登录：\n\n```bash\nhf auth login\n# 或指定令牌\nhf auth login --token $HUGGINGFACE_TOKEN\n```\n\n资料来源：[src/huggingface_hub/_login.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_login.py)\n\n---\n\n## 仓库元数据管理\n\n### 仓库卡片（RepoCard）\n\n每个仓库都关联一个仓库卡片（RepoCard），用于展示仓库的描述信息和元数据。`huggingface_hub` 通过 `RepoCard` 类及其子类（`ModelCard`、`DatasetCard`、`SpaceCard`）管理这些元数据。\n\n```python\nfrom huggingface_hub import ModelCard, ModelCardData\n\n# 创建模型卡片数据\ncard_data = ModelCardData(\n language=\"en\",\n license=\"apache-2.0\",\n library_name=\"pytorch\",\n tags=[\"image-classification\", \"resnet\"]\n)\n\n# 从模板创建卡片\ncard = ModelCard.from_template(card_data)\n```\n\n仓库卡片的结构包含两部分：YAML 格式的元数据块和 Markdown 格式的说明文本。`CardData` 类及其子类定义了标准化的元数据字段，包括语言、许可证、标签、训练数据集等信息。\n\n资料来源：[src/huggingface_hub/repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n\n### 元数据解析\n\n`RepoCard` 类提供了内容解析功能，能够从 Markdown 文本中提取 YAML 元数据和说明文本：\n\n```python\nfrom huggingface_hub import RepoCard\n\ntext = '''\n---\nlanguage: en\nlicense: mit\n---\n\n# 我的仓库\n这是模型的描述...\n'''\n\ncard = RepoCard(text)\nprint(card.data.to_dict()) # {'language': 'en', 'license': 'mit'}\nprint(card.text) # '# 我的仓库\\n这是模型的描述...\\n'\n```\n\n资料来源：[src/huggingface_hub/repocard.py:38-55](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py)\n\n---\n\n## 本地文件夹同步\n\n### LocalFolder 类\n\n`LocalFolder` 类提供本地文件夹与远程仓库的同步功能，支持双向文件操作。该类是 `HfFileSystem` 的组成部分，为本地开发工作流提供了文件系统接口。\n\n```mermaid\ngraph TD\n A[本地文件夹] -->|文件变更| B[LocalFolder]\n B -->|差异检测| C[变更列表]\n C -->|上传| D[远程仓库]\n D -->|下载| B\n B -->|同步| A[本地文件夹]\n```\n\nLocalFolder 维护本地文件系统与远程仓库之间的状态一致性，支持以下操作：\n\n- **增量同步**：仅上传/下载变更的文件\n- **冲突处理**：检测并提示文件冲突\n- **原子操作**：确保操作的完整性\n\n资料来源：[src/huggingface_hub/_local_folder.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_local_folder.py)\n\n---\n\n## 文件系统抽象\n\n### HfFileSystem\n\n`HfFileSystem` 是基于 fsspec 的 POSIX 风格文件系统实现，允许用户像操作本地文件一样操作 Hugging Face Hub 上的仓库文件。这种设计使得现有工具和库可以无缝集成对 Hub 的访问。\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出仓库文件\nfiles = fs.ls(\"username/my-model\")\n\n# 读取文件内容\nwith fs.open(\"username/my-model/config.json\", \"r\") as f:\n content = f.read()\n\n# 写入文件\nwith fs.open(\"username/my-model/new_file.txt\", \"w\") as f:\n f.write(\"Hello, Hub!\")\n```\n\nHfFileSystem 支持标准的文件系统操作：\n\n| 操作 | 方法 | 说明 |\n|-----|------|-----|\n| 列表 | `ls()` | 列出目录内容 |\n| 读取 | `open()` | 打开文件进行读取 |\n| 写入 | `open(mode='w')` | 打开文件进行写入 |\n| 删除 | `rm()` | 删除文件 |\n| 移动 | `mv()` | 移动或重命名文件 |\n| 存在检查 | `exists()` | 检查文件是否存在 |\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\n---\n\n## 仓库操作 API\n\n### HfApi 核心方法\n\n`HfApi` 类是仓库管理的核心接口，提供了丰富的方法来操作仓库。以下是常用的仓库管理方法：\n\n| 方法 | 功能 | 主要参数 |\n|-----|------|---------|\n| `whoami()` | 获取当前用户信息 | - |\n| `list_models()` | 列出模型仓库 | `search`, `filters`, `sort` |\n| `list_datasets()` | 列出数据集仓库 | `search`, `filters`, `sort` |\n| `listSpaces()` | 列出 Space 仓库 | `search`, `filters`, `sort` |\n| `model_info()` | 获取模型仓库信息 | `repo_id`, `revision` |\n| `dataset_info()` | 获取数据集仓库信息 | `repo_id`, `revision` |\n| `space_info()` | 获取 Space 仓库信息 | `repo_id`, `revision` |\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n\n# 获取当前用户\nuser = api.whoami()\nprint(f\"用户名: {user['name']}\")\n\n# 搜索模型\nmodels = api.list_models(search=\"bert\", sort=\"downloads\", direction=-1, limit=5)\nfor model in models:\n print(f\"{model.id} - {model.downloads} downloads\")\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---\n\n## 存储桶管理\n\n### Bucket 机制\n\nHugging Face Hub 引入了 Bucket 的概念，用于优化大文件的存储和访问。Bucket 是仓库的一种特殊形式，专门用于存储大型二进制文件，如机器学习模型权重。\n\n```python\nfrom huggingface_hub import HfApi\n\napi = HfApi()\n\n# 获取 bucket 信息\nbucket_info = api.hf_hub_download(\n repo_id=\"my-org/my-bucket\",\n filename=\"large-model.bin\",\n repo_type=\"bucket\"\n)\n```\n\nBucket 机制通过以下方式优化存储：\n\n1. **智能分片**：大文件自动分片存储\n2. **并行下载**：支持多连接并发下载\n3. **增量更新**：仅传输变更的部分\n\n资料来源：[src/huggingface_hub/_buckets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_buckets.py)\n\n---\n\n## CLI 命令行工具\n\n### 认证命令\n\n```bash\n# 登录 Hugging Face\nhf auth login\n\n# 检查当前认证状态\nhf whoami\n\n# 登出\nhf auth logout\n```\n\n### 仓库管理命令\n\n```bash\n# 创建新仓库\nhf repo create username/my-model\n\n# 克隆仓库到本地\nhf clone username/my-model\n\n# 查看仓库信息\nhf repo info username/my-model\n\n# 删除仓库\nhf repo delete username/my-model -y\n```\n\n### 下载与上传\n\n```bash\n# 下载单个文件\nhf download username/my-model config.json\n\n# 下载整个仓库\nhf download username/my-model\n\n# 上传文件\nhf upload username/my-model local_file.txt path/in/repo.txt\n\n# 上传文件夹\nhf upload username/my-model /path/to/local/folder/\n```\n\n---\n\n## 架构流程图\n\n### 仓库操作完整流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B{认证检查}\n B -->|已登录| C{HfApi}\n B -->|未登录| D[提示登录]\n D --> E[login 函数]\n E --> C\n \n C --> F{操作类型}\n F -->|创建| G[create_repo]\n F -->|删除| H[delete_repo]\n F -->|上传| I[upload_file]\n F -->|下载| J[hf_hub_download]\n F -->|列表| K[list_*]\n \n G --> L[HTTP API]\n H --> L\n I --> L\n J --> L\n K --> L\n \n L --> M{Hub 服务器}\n M -->|成功| N[返回结果]\n M -->|失败| O[抛出异常]\n```\n\n---\n\n## 最佳实践\n\n### 仓库命名规范\n\n- 使用有意义的名称：`username/model-purpose-variant`\n- 避免特殊字符：仅使用字母、数字和连字符\n- 版本控制：使用标签而非版本号\n\n### 安全性建议\n\n1. **保护访问令牌**：不要将令牌提交到版本控制系统\n2. **使用环境变量**：通过 `HUGGINGFACE_TOKEN` 环境变量传递令牌\n3. **最小权限**：在 Hugging Face 网站生成具有最小必要权限的令牌\n\n### 性能优化\n\n- **大文件处理**：使用 Git LFS 处理大于 10MB 的文件\n- **增量操作**：优先使用增量上传/下载而非全量操作\n- **缓存利用**：合理配置本地缓存以减少重复下载\n\n---\n\n## 相关文档\n\n- [安装指南](https://huggingface.co/docs/huggingface_hub/ko/installation)\n- [下载文件指南](https://huggingface.co/docs/huggingface_hub/ko/guides/download)\n- [上传文件指南](https://huggingface.co/docs/huggingface_hub/en/guides/upload)\n- [缓存管理](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[推理系统](#inference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/huggingface_hub/cli/hf.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/hf.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/cli/upload.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/upload.py)\n- [src/huggingface_hub/cli/models.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/models.py)\n- [src/huggingface_hub/cli/datasets.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/datasets.py)\n- [src/huggingface_hub/cli/spaces.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/spaces.py)\n- [setup.py](https://github.com/huggingface/huggingface_hub/blob/main/setup.py)\n \n\n# 命令行工具\n\n## 概述\n\n`huggingface_hub` 库提供了一套完整的命令行工具（CLI），允许用户通过终端与 Hugging Face Hub 进行交互，无需编写 Python 代码即可完成文件下载、上传、模型管理、数据集浏览和 Space 操作等常见任务。\n\n命令行工具作为库的核心入口点之一，通过 `setup.py` 中定义的入口点（entry points）注册为系统可执行命令：\n\n```python\nentry_points={\n \"console_scripts\": [\n \"hf=huggingface_hub.cli.hf:main\",\n \"huggingface-cli=huggingface_hub.cli.deprecated_cli:main\",\n \"tiny-agents=huggingface_hub.inference._mcp.cli:app\",\n ],\n ...\n}\n```\n\n资料来源：[setup.py:1-60]()\n\n安装 `huggingface_hub` 后，用户可以直接在终端使用以下命令：\n\n| 命令 | 功能描述 |\n|------|----------|\n| `hf` | 主命令行工具，提供所有核心功能 |\n| `huggingface-cli` | 已废弃的 CLI 工具（保留向后兼容） |\n| `tiny-agents` | 轻量级代理工具 |\n\n## CLI 模块架构\n\n### 模块结构\n\nCLI 模块位于 `src/huggingface_hub/cli/` 目录下，采用模块化设计，每个子模块负责特定的功能领域：\n\n```mermaid\ngraph TD\n A[hf 命令] --> B[download.py
下载模块]\n A --> C[upload.py
上传模块]\n A --> D[models.py
模型模块]\n A --> E[datasets.py
数据集模块]\n A --> F[spaces.py
Space模块]\n \n B --> G[hf_hub_download
snapshot_download]\n C --> H[upload_file
upload_folder]\n D --> I[模型列表
模型搜索]\n E --> J[数据集列表
数据集搜索]\n F --> K[Space管理
应用启动]\n```\n\n### 命令入口点\n\n主入口文件 `hf.py` 定义了 CLI 的根命令和子命令结构，采用层级式命令设计：\n\n```mermaid\ngraph LR\n A[hf 命令] --> B[auth
身份验证]\n A --> C[download
下载]\n A --> D[upload
上传]\n A --> E[list
列表查询]\n A --> F[whoami
当前用户]\n```\n\n## 身份验证模块\n\n### 登录命令\n\n`hf auth login` 命令用于在本地计算机上登录 Hugging Face 账户：\n\n```bash\nhf auth login\n```\n\n此命令会提示用户输入 HF token（可从 [Hugging Face 设置页面](https://huggingface.co/settings/tokens) 获取），并将凭证安全存储在本地配置文件中。\n\n### 身份验证流程\n\n```mermaid\nsequenceDiagram\n 用户->>CLI: hf auth login\n CLI->>HuggingFace: 请求认证\n HuggingFace-->>CLI: 返回token\n CLI->>本地配置: 存储token\n 本地配置-->>CLI: 确认存储成功\n CLI-->>用户: 登录成功\n```\n\n## 下载模块\n\n`download.py` 模块提供了从 Hugging Face Hub 下载文件和仓库的完整功能。\n\n### 主要下载命令\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `hf download` | 下载单个文件 | `hf download --repo-id model --filename config.json` |\n| `hf snapshot-download` | 下载整个仓库 | `hf snapshot-download --repo-id stabilityai/stable-diffusion-2-1` |\n\n### 下载命令参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--repo-id` | 字符串 | 是 | 仓库标识符，格式为 `namespace/repo-name` |\n| `--repo-type` | 字符串 | 否 | 仓库类型：`model`、`dataset` 或 `space`，默认为 `model` |\n| `--filename` | 字符串 | 否 | 要下载的文件名（用于单文件下载） |\n| `--local-dir` | 路径 | 否 | 本地下载目录 |\n| `--revision` | 字符串 | 否 | Git 分支名或 commit hash |\n| `--token` | 字符串 | 否 | Hugging Face 访问令牌 |\n\n### 下载流程\n\n```mermaid\ngraph TD\n A[开始下载] --> B{指定filename?}\n B -->|是| C[hf_hub_download
单文件下载]\n B -->|否| D[snapshot_download
完整仓库下载]\n \n C --> E{本地缓存存在?}\n D --> F{本地缓存存在?}\n \n E -->|是| G[使用缓存]\n E -->|否| H[从Hub下载]\n F -->|是| I[使用缓存]\n F -->|否| J[从Hub下载]\n \n G --> K[返回本地路径]\n H --> K\n I --> K\n J --> K\n```\n\n文件下载后会缓存到本地，详细信息可参考 [缓存管理指南](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)。\n\n资料来源：[src/huggingface_hub/cli/download.py]()\n\n## 上传模块\n\n`upload.py` 模块提供了向 Hugging Face Hub 上传文件和文件夹的功能。\n\n### 主要上传命令\n\n| 命令 | 功能 | 典型用法 |\n|------|------|----------|\n| `hf upload` | 上传文件 | `hf upload --path config.json --repo-id username/my-model` |\n| `hf upload-folder` | 上传文件夹 | `hf upload-folder --folder-path ./my-space --repo-id username/my-space --repo-type space` |\n\n### 上传命令参数\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `--path` | 路径 | 是* | 要上传的文件路径（用于单文件上传） |\n| `--folder-path` | 路径 | 是* | 要上传的文件夹路径（用于文件夹上传） |\n| `--repo-id` | 字符串 | 是 | 目标仓库标识符 |\n| `--repo-type` | 字符串 | 否 | 仓库类型：`model`、`dataset` 或 `space` |\n| `--path-in-repo` | 字符串 | 否 | 仓库中的目标路径 |\n| `--message` | 字符串 | 否 | Git commit 提交信息 |\n| `--token` | 字符串 | 否 | Hugging Face 访问令牌 |\n\n### 上传流程\n\n```mermaid\ngraph TD\n A[开始上传] --> B{上传类型?}\n B -->|文件| C[上传单个文件]\n B -->|文件夹| D[遍历文件夹]\n \n C --> E[验证文件存在]\n E --> F[计算文件大小]\n F --> G[分块上传]\n G --> H[创建Git commit]\n \n D --> I[递归处理文件]\n I --> J{更多文件?}\n J -->|是| I\n J -->|否| H\n \n H --> K[完成上传]\n```\n\n资料来源：[src/huggingface_hub/cli/upload.py]()\n\n## 模型管理模块\n\n`models.py` 模块提供了浏览和管理 Hugging Face Hub 上的模型功能。\n\n### 主要命令\n\n| 命令 | 功能 |\n|------|------|\n| `hf models list` | 列出所有可用的模型 |\n| `hf models search` | 搜索特定模型 |\n\n### 模型列表参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--filter` | 字符串 | 按任务类型、库名等筛选 |\n| `--search` | 字符串 | 搜索关键词 |\n| `--sort` | 字符串 | 排序字段（如 `downloads`、`likes`） |\n| `--direction` | 字符串 | 排序方向（`asc` 或 `desc`） |\n| `--limit` | 整数 | 返回结果数量限制 |\n\n### 模型卡片操作\n\n通过 `hf` 命令可以创建和编辑模型卡片（Model Card），模型卡片是描述模型元数据的重要文件，包含语言、许可证、训练数据集等信息。\n\n资料来源：[src/huggingface_hub/cli/models.py](), [src/huggingface_hub/repocard_data.py:1-100]()\n\n## 数据集管理模块\n\n`datasets.py` 模块提供了浏览和管理 Hugging Face Hub 上的数据集功能。\n\n### 主要命令\n\n| 命令 | 功能 |\n|------|------|\n| `hf datasets list` | 列出所有可用的数据集 |\n| `hf datasets search` | 搜索特定数据集 |\n\n### 数据集卡片操作\n\n数据集卡片（Dataset Card）使用 `DatasetCardData` 类进行管理，包含以下元数据字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `language` | 字符串/列表 | 数据集语言 |\n| `license` | 字符串 | 许可证类型 |\n| `annotations_creators` | 字符串 | 注释创建方式 |\n| `task_categories` | 列表 | 任务类别 |\n| `task_ids` | 列表 | 任务标识符 |\n\n资料来源：[src/huggingface_hub/cli/datasets.py](), [src/huggingface_hub/repocard.py:1-100]()\n\n## Space 管理模块\n\n`spaces.py` 模块提供了管理 Hugging Face Spaces 的功能。\n\n### 主要功能\n\n| 功能 | 说明 |\n|------|------|\n| Space 列表 | 浏览可用的 Spaces |\n| Space 搜索 | 搜索特定 Spaces |\n| Space 配置 | 管理 Space 的硬件配置 |\n| Space 启动 | 启动本地 Space 进行测试 |\n\n### 创建 Space\n\n使用 `hf spaces create` 命令可以创建新的 Space：\n\n```bash\nhf spaces create --repo-id username/my-cool-space --sdk streamlit\n```\n\n支持的 SDK 类型包括：`streamlit`、`gradio`、`docker`、`static`、`nextjs`、`svelte`。\n\n资料来源：[src/huggingface_hub/cli/spaces.py]()\n\n## 使用示例\n\n### 完整工作流程\n\n```mermaid\ngraph LR\n A[身份验证] --> B[下载模型]\n B --> C[微调模型]\n C --> D[上传模型]\n D --> E[创建模型卡片]\n E --> F[分享到社区]\n```\n\n### 常用命令示例\n\n**1. 身份验证**\n```bash\nhf auth login\n```\n\n**2. 下载模型文件**\n```bash\nhf download --repo-id meta-llama/Llama-2-7b --filename config.json\n```\n\n**3. 下载完整模型仓库**\n```bash\nhf snapshot-download --repo-id stabilityai/stable-diffusion-2-1\n```\n\n**4. 上传文件**\n```bash\nhf upload --path config.json --repo-id username/my-model\n```\n\n**5. 上传文件夹**\n```bash\nhf upload-folder --folder-path ./my-space --repo-id username/my-space --repo-type space\n```\n\n**6. 搜索模型**\n```bash\nhf models search --filter text-classification --limit 10\n```\n\n## 配置与缓存\n\n### 本地配置\n\nCLI 工具会将以下配置存储在本地：\n\n| 配置项 | 位置 | 说明 |\n|--------|------|------|\n| 访问令牌 | `~/.cache/huggingface/token` | 身份验证令牌 |\n| 缓存目录 | `~/.cache/huggingface/` | 下载文件缓存 |\n\n### 缓存管理\n\n文件下载时会自动缓存到本地，重复下载时会直接使用缓存。可以通过以下方式管理缓存：\n\n```bash\n# 查看缓存大小\nhf cache size\n\n# 清理缓存\nhf cache clear\n```\n\n## 错误处理\n\nCLI 工具在遇到错误时会返回相应的退出码：\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 命令执行成功 |\n| 1 | 通用错误 |\n| 2 | 参数错误 |\n| 128 | 身份验证失败 |\n\n常见错误及解决方案：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `RepositoryNotFoundError` | 仓库不存在或无权访问 | 检查 repo-id 是否正确，或确认已登录 |\n| `LocalTokenNotFoundError` | 未找到本地 token | 运行 `hf auth login` |\n| `FileExistsError` | 文件已存在 | 使用 `--overwrite` 参数或删除本地文件 |\n| `HuggingFaceHubValidationError` | 参数验证失败 | 检查参数格式是否正确 |\n\n## 与 Python API 的关系\n\nCLI 工具底层调用的是 `huggingface_hub` 的 Python API：\n\n| CLI 命令 | 对应 Python 函数 |\n|----------|------------------|\n| `hf download` | `hf_hub_download()` |\n| `hf snapshot-download` | `snapshot_download()` |\n| `hf upload` | `upload_file()` |\n| `hf upload-folder` | `upload_folder()` |\n\n这种设计确保了 CLI 和 Python API 的一致性，用户可以根据需求选择使用方式。\n\n---\n\n\n\n## 缓存系统\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations), [Git LFS 集成](#lfs-integration)\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/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/hf_file_system.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hf_file_system.py)\n- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n \n\n# 缓存系统\n\n## 概述\n\nHugging Face Hub 的缓存系统是 `huggingface_hub` 库的核心组件之一，负责管理从 Hugging Face Hub 下载的模型、数据集和其他文件的本地存储。该系统通过智能缓存机制避免了重复下载，提升了资源加载效率，并提供了灵活的缓存管理功能。\n\n缓存系统的主要职责包括：\n\n1. **文件缓存**：将下载的文件存储在本地缓存目录中\n2. **版本管理**：支持同一仓库的多个版本（revision）共存\n3. **元数据管理**：维护文件的 ETag、最后修改时间等元信息\n4. **缓存扫描**：提供 API 让用户查看当前缓存状态\n5. **缓存清理**：支持选择性删除缓存条目\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:1-50]()\n\n## 缓存架构\n\n### 缓存目录结构\n\nHugging Face Hub 采用层级化的缓存目录结构：\n\n```\n~/.cache/huggingface/hub/\n├── models--tiiuae--falcon-7b-instruct/\n│ ├── .cache/\n│ │ └── huggingface-metadata/\n│ ├── blobs/\n│ │ ├── 3a1d9c3d8e...\n│ │ └── f2b8e9a1c7...\n│ ├── refs/\n│ │ └── main\n│ └── snapshots/\n│ ├── 81fd1d6e7847c99f5862c9fb81387956d99ec7aa/\n│ │ ├── config.json -> ../../blobs/3a1d9c3d8e\n│ │ └── model.safetensors -> ../../blobs/f2b8e9a1c7\n│ └── e2983b237dccf3ab4937c97fa717319a9ca1a96d/\n```\n\n| 目录 | 用途 |\n|------|------|\n| `blobs/` | 存储实际文件内容（由 SHA256 哈希命名） |\n| `refs/` | 存储版本引用（revision）对应的 commit hash |\n| `snapshots/` | 存储文件链接到 blobs 的符号链接，按 revision 组织 |\n| `.cache/huggingface-metadata/` | 存储文件的元数据（ETag、lastModified 等） |\n\n资料来源：[src/huggingface_hub/file_download.py:100-150]()\n\n### 核心数据结构\n\n缓存系统使用两个核心数据结构来表示缓存信息：\n\n```python\n@dataclass\nclass CachedRepoInfo:\n \"\"\"缓存仓库的基本信息\"\"\"\n repo_id: str # 仓库ID，如 \"tiiuae/falcon-7b-instruct\"\n repo_type: str # 仓库类型：model、dataset 或 space\n size_on_disk: int # 仓库占用的磁盘空间\n nb_files: int # 文件数量\n revisions: list[CachedRevisionInfo] # 所有版本列表\n\n@dataclass\nclass CachedRevisionInfo:\n \"\"\"缓存版本的具体信息\"\"\"\n commit_hash: str # Git commit hash\n size_on_disk: int # 该版本占用的磁盘空间\n files: list[CachedFileInfo] # 该版本包含的文件列表\n security: SecurityDetails | None # 安全验证信息\n```\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:50-100]()\n\n## 缓存工作流程\n\n### 文件下载与缓存流程\n\n当用户调用 `hf_hub_download` 或 `snapshot_download` 时，缓存系统按以下流程工作：\n\n```mermaid\ngraph TD\n A[请求下载文件] --> B{检查缓存目录}\n B -->|文件已存在| C{检查元数据}\n C -->|ETag 未变化| D[返回缓存文件路径]\n C -->|ETag 变化| E[下载新版本]\n E --> F[更新 blob 文件]\n F --> G[更新元数据]\n G --> D\n B -->|文件不存在| H[下载文件]\n H --> I[存储到 blobs 目录]\n I --> J[创建 snapshot 链接]\n J --> K[存储元数据]\n K --> L[返回文件路径]\n D --> M[完成]\n L --> M\n```\n\n### 缓存命中判断逻辑\n\n1. **检查 blob 是否存在**：根据文件内容的 SHA256 哈希值查找 `blobs/` 目录\n2. **验证 ETag**：如果存在元数据，比较 ETag 判断是否需要重新下载\n3. **强制刷新**：通过 `force_download=True` 参数可强制重新下载\n\n```python\n# 伪代码：缓存命中逻辑\ndef get_cached_file_path(repo_id, filename, revision, etag):\n cache_dir = get_cache_dir(repo_id)\n blob_path = os.path.join(cache_dir, \"blobs\", file_hash)\n \n if os.path.exists(blob_path):\n cached_etag = get_cached_etag(repo_id, filename)\n if cached_etag == etag:\n return blob_path # 缓存命中\n else:\n # ETag 不匹配，需要重新下载\n pass\n return None # 缓存未命中\n```\n\n资料来源：[src/huggingface_hub/file_download.py:200-300]()\n\n## 缓存管理 API\n\n### 扫描缓存目录\n\n`scan_cache_dir()` 函数用于扫描并返回当前缓存目录的完整信息：\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\ncache_info = scan_cache_dir()\nprint(f\"缓存仓库数量: {len(cache_info.repos)}\")\nprint(f\"总占用空间: {cache_info.size_on_disk / 1024**3:.2f} GB\")\n\nfor repo in cache_info.repos:\n print(f\" - {repo.repo_id}: {repo.nb_files} 个文件\")\n```\n\n**返回值结构**：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `repos` | `list[CachedRepoInfo]` | 所有缓存仓库列表 |\n| `size_on_disk` | `int` | 总磁盘占用（字节） |\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:150-200]()\n\n### 删除缓存策略\n\n`scan_cache_dir()` 返回的对象提供链式 API 来构建删除策略：\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# 方式1：删除指定版本\ncache_info = scan_cache_dir().delete_revisions(\n \"81fd1d6e7847c99f5862c9fb81387956d99ec7aa\",\n \"e2983b237dccf3ab4937c97fa717319a9ca1a96d\",\n)\n\n# 查看将要删除的内容（dry run）\nprint(f\"将删除 {cache_info.size_on_disk / 1024**2:.2f} MB\")\n\n# 执行删除\ncache_info.execute()\n```\n\n```python\n# 方式2：删除整个仓库的缓存\ncache_info = scan_cache_dir().delete_repos(\"tiiuae/falcon-7b-instruct\")\ncache_info.execute()\n```\n\n**DeleteCacheStrategy 常用方法**：\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| `delete_revisions(*revision_hashes)` | `DeleteCacheStrategy` | 标记要删除的版本 |\n| `delete_repos(*repo_ids)` | `DeleteCacheStrategy` | 标记要删除的仓库 |\n| `execute()` | `None` | 执行删除操作 |\n| `size()` | `int` | 待删除内容的总大小 |\n| `repos()` | `list[CachedRepoInfo]` | 受影响的仓库列表 |\n\n> [!WARNING]\n> `delete_revisions` 返回的 `DeleteCacheStrategy` 对象需要调用 `execute()` 方法才会真正执行删除操作。\n\n资料来源：[src/huggingface_hub/utils/_cache_manager.py:200-300]()\n\n## HfFileSystem 缓存集成\n\n`HfFileSystem` 是基于 fsspec 的 POSIX 兼容文件系统实现，它深度集成了缓存系统：\n\n```python\nfrom huggingface_hub import HfFileSystem\n\nfs = HfFileSystem()\n\n# 列出目录时会使用缓存\nfiles = fs.ls(\"datasets/squad\")\n```\n\n### 缓存配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `cache_dir` | `str` | `~/.cache/huggingface/hub` | 缓存根目录 |\n| `storage_kwargs` | `dict` | `None` | 传递给底层存储的额外参数 |\n| `read_only` | `bool` | `False` | 是否以只读模式挂载 |\n\n```python\n# 使用自定义缓存目录\nfs = HfFileSystem(cache_dir=\"/path/to/custom/cache\")\n```\n\n资料来源：[src/huggingface_hub/hf_file_system.py:100-200]()\n\n## 快照下载与缓存\n\n`snapshot_download()` 函数用于下载整个仓库到本地，同时最大化利用缓存：\n\n```python\nfrom huggingface_hub import snapshot_download\n\nlocal_dir = snapshot_download(\n repo_id=\"stabilityai/stable-diffusion-2-1\",\n revision=\"main\",\n cache_dir=None, # 使用默认缓存目录\n force_download=False,\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `repo_id` | `str` | 必需 | 仓库标识符 |\n| `repo_type` | `str` | `\"model\"` | 仓库类型：model、dataset、space |\n| `revision` | `str` | `None` (latest) | Git 分支名或 commit hash |\n| `cache_dir` | `str` | `None` | 自定义缓存目录 |\n| `force_download` | `bool` | `False` | 是否强制重新下载 |\n| `local_dir` | `str` | `None` | 本地目标目录（非缓存目录） |\n| `allow_patterns` | `list[str]` | `None` | 仅下载匹配的文件 |\n| `ignore_patterns` | `list[str]` | `None` | 排除匹配的文件 |\n| `max_workers` | `int` | `8` | 并行下载的最大线程数 |\n\n### 缓存复用机制\n\n`snapshot_download` 内部使用增量下载策略：\n\n1. 首先检查本地缓存中是否存在目标 revision\n2. 如果存在且 `force_download=False`，直接使用缓存\n3. 如果不存在，下载缺失的 blobs 并复用已存在的 blobs\n\n资料来源：[src/huggingface_hub/_snapshot_download.py:1-100]()\n\n## LFS 大文件缓存\n\n对于 Git LFS 存储的大文件（如模型权重），缓存系统有特殊处理：\n\n```mermaid\ngraph LR\n A[下载请求] --> B{文件大小 > 阈值?}\n B -->|是| C[LFS 文件处理]\n B -->|否| D[普通文件处理]\n C --> E[下载 LFS blob]\n D --> F[下载普通 blob]\n E --> G[存储到 blobs/]\n F --> G\n```\n\n`CommitOperationAdd` 类提供 `as_file()` 方法用于流式处理上传和下载：\n\n```python\noperation = CommitOperationAdd(\n path_or_fileobj='./local/weights.h5',\n path_in_repo='remote/dir/weights.h5'\n)\n\n# 使用 as_file() 获取文件对象进行操作\nwith operation.as_file(with_tqdm=True) as file:\n content = file.read()\n```\n\n资料来源：[src/huggingface_hub/_commit_api.py:100-200]()\n\n## 最佳实践\n\n### 1. 合理设置缓存目录\n\n```python\nimport os\nfrom huggingface_hub import snapshot_download\n\n# 为不同项目设置不同缓存目录\ncache_dir = os.path.join(os.getcwd(), \".cache\", \"my-project\")\nsnapshot_download(\"my-org/my-model\", cache_dir=cache_dir)\n```\n\n### 2. 定期清理缓存\n\n```python\nfrom huggingface_hub import scan_cache_dir\n\n# 删除所有旧版本，保留最近的两个\ncache_info = scan_cache_dir()\n\nfor repo in cache_info.repos:\n # 假设 revisions 已按时间排序，保留最近2个\n revisions_to_delete = repo.revisions[2:]\n if revisions_to_delete:\n hashes = [r.commit_hash for r in revisions_to_delete]\n repo.cache_dir.delete_revisions(*hashes).execute()\n```\n\n### 3. 处理缓存失效\n\n```python\nfrom huggingface_hub import hf_hub_download\n\n# 强制重新下载（忽略缓存）\nmodel_file = hf_hub_download(\n repo_id=\"meta-llama/Llama-2-7b\",\n filename=\"config.json\",\n force_download=True,\n token=True # 确保使用认证令牌\n)\n```\n\n## 相关模块\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 缓存管理 | `utils/_cache_manager.py` | 缓存扫描、删除策略 |\n| 文件下载 | `file_download.py` | 单文件下载与缓存 |\n| 快照下载 | `_snapshot_download.py` | 整仓库下载与缓存 |\n| 文件系统 | `hf_file_system.py` | fsspec 集成 |\n| 提交操作 | `_commit_api.py` | LFS 大文件处理 |\n\n## 总结\n\nHugging Face Hub 的缓存系统通过层级化的目录结构、智能的元数据管理和灵活的 API 设计，为用户提供了高效、可靠的本地缓存体验。开发者可以通过 `scan_cache_dir()` 查看缓存状态，使用 `delete_revisions()` 清理不需要的版本，并通过各种下载函数灵活控制缓存行为。\n\n---\n\n\n\n## Git LFS 集成\n\n### 相关页面\n\n相关主题：[文件操作](#file-operations), [缓存系统](#cache-system)\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- [src/huggingface_hub/_commit_api.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_commit_api.py)\n- [src/huggingface_hub/cli/lfs.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/cli/lfs.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 集成\n\n## 概述\n\nGit LFS（Large File Storage，大文件存储）是 Hugging Face Hub 用于处理大型二进制文件的核心机制。在机器学习场景中，模型权重、数据集文件等通常体积庞大（数百MB甚至数GB），传统 Git 无法高效处理此类文件，LFS 应运而生。\n\n`huggingface_hub` 库通过 `lfs.py` 模块和相关工具函数，提供了完整的 LFS 文件管理能力，包括大文件上传、下载、缓存管理以及批量操作支持。\n\n资料来源：[src/huggingface_hub/lfs.py:1-50]()\n\n## 核心概念\n\n### LFS 存储架构\n\nHugging Face Hub 采用 Git LFS 协议管理大文件，缓存目录结构如下：\n\n```\ncache/\n└── models--{repo_id}/\n ├── blobs/ # 实际文件blob（由git-sha或sha256标识）\n ├── refs/ # 最新已知revision => commit_hash映射\n └── snapshots/ # 每个commit的子文件夹，包含文件符号链接\n```\n\n- **blobs 目录**：存储实际的文件内容，LFS 文件由 SHA256 哈希标识\n- **refs 目录**：维护 revision 名称到 commit hash 的映射关系\n- **snapshots 目录**：每个 commit 对应一个子文件夹，文件通过符号链接指向 blobs\n\n资料来源：[src/huggingface_hub/file_download.py:96-120]()\n\n### LFS 文件识别\n\nLFS 文件通过以下特征识别：\n- 文件大小超过配置的阈值（默认 5MB）\n- 文件类型匹配预定义的模式（如 `.bin`、`.pt`、`.safetensors` 等）\n\n非 LFS 文件（如纯 Git 管理的文件）使用 git-sha 标识。\n\n资料来源：[src/huggingface_hub/utils/_lfs.py:1-30]()\n\n## 模块架构\n\n### 主要组件\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `lfs.py` | `src/huggingface_hub/lfs.py` | LFS 核心操作：上传、下载、切片、进度追踪 |\n| `utils/_lfs.py` | `src/huggingface_hub/utils/_lfs.py` | LFS 工具函数：路径处理、URL 构建 |\n| `_commit_api.py` | `src/huggingface_hub/_commit_api.py` | Commit 操作中的 LFS 处理逻辑 |\n| `cli/lfs.py` | `src/huggingface_hub/cli/lfs.py` | 命令行 LFS 工具 |\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[上传请求] --> B{文件大小检查}\n B -->|小于阈值| C[普通 Git 上传]\n B -->|大于阈值| D[LFS 上传流程]\n \n D --> E[计算 SHA256 哈希]\n E --> F{文件已存在?}\n F -->|是| G[跳过上传]\n F -->|否| H[切片上传]\n H --> I[分块传输]\n I --> J[验证完整性]\n J --> K[完成上传]\n \n C --> L[更新索引]\n G --> L\n K --> L\n```\n\n## LFS 上传机制\n\n### 分片上传流程\n\n大文件采用分片上传策略，以支持断点续传和进度追踪：\n\n```mermaid\ngraph LR\n A[文件] --> B[分片器]\n B --> C[Chunk 1]\n B --> D[Chunk 2]\n B --> E[Chunk N]\n C --> F[并行上传]\n D --> F\n E --> F\n F --> G[服务器合并]\n```\n\n### Commit 操作中的 LFS 处理\n\n`_commit_api.py` 中的 `CommitOperationAdd` 类处理 LFS 文件上传：\n\n- 自动检测文件是否需要 LFS 存储\n- 触发 LFS 批量上传协议\n- 管理 Git LFS pointer 文件的创建\n\n资料来源：[src/huggingface_hub/_commit_api.py:1-100]()\n\n```python\n# CommitOperationAdd 核心逻辑\nclass CommitOperationAdd:\n def __init__(self, path_or_fileobj, path_in_repo, ...):\n # 自动识别是否为 LFS 文件\n self.is_lfs_file = self._check_lfs_requirement(file_size)\n```\n\n### LFS Pointer 文件格式\n\nLFS 存储的文件以 Git pointer 形式存在于仓库中：\n\n```\nversion https://git-lfs.github.com/spec/v1\noid sha256:3f2c70a56d67f1c9c7e5e8d4b3a1f2e9c8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3\nsize 1048576\n```\n\n客户端通过此 pointer 文件识别 LFS 内容，并从 LFS 服务器获取实际数据。\n\n资料来源：[src/huggingface_hub/utils/_lfs.py:50-80]()\n\n## CLI 工具\n\n### lfs 命令\n\n`huggingface_hub` 提供命令行工具管理 LFS 操作：\n\n```bash\n# 列出 LFS 跟踪的文件\nhf lfs ls-files\n\n# 检查 LFS 状态\nhf lfs status\n\n# 手动触发 LFS 预取\nhf lfs fetch origin main\n```\n\n资料来源：[src/huggingface_hub/cli/lfs.py:1-50]()\n\n### CLI 模块结构\n\n```mermaid\nclassDiagram\n class LfsCLI {\n +ls_files()\n +status()\n +fetch()\n +push()\n }\n```\n\n## 缓存管理\n\n### 缓存目录结构\n\n```\n~/.cache/huggingface/hub/\n├── models--bert-base-uncased/\n│ ├── blobs/\n│ │ ├── 3f2c70a56d67f1c9c7e5e8d4b3a1f2e9c8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3 # LFS 文件\n│ │ └── 7cb18dc9bafbfcf74629a4b760af1b160957a83e # 普通 Git 文件\n│ ├── refs/\n│ │ └── main # revision 映射\n│ └── snapshots/\n│ └── 2439f60ef33a0d46d85da5001d52aeda5b00ce1 # commit snapshot\n```\n\n### 缓存策略\n\n- **首次下载**：从 Hub 下载 LFS 文件并存入缓存\n- **后续访问**：直接读取本地缓存，避免重复下载\n- **空间管理**：支持手动清理缓存或配置自动清理策略\n\n资料来源：[src/huggingface_hub/file_download.py:80-150]()\n\n## 配置选项\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `lfs_upload_chunk_size` | 分片上传块大小 | 100MB |\n| `lfs_multipart_threshold` | 触发 LFS 的文件大小阈值 | 5MB |\n| `lfs_allow_unsigned` | 允许上传未签名内容 | False |\n| `endpoints.lfs` | LFS 服务器地址 | Hub 默认端点 |\n\n## 使用示例\n\n### Python API 上传 LFS 文件\n\n```python\nfrom huggingface_hub import HfApi, CommitOperationAdd\n\n# 创建包含 LFS 文件的 commit\noperations = [\n CommitOperationAdd(\n path_or_fileobj=\"model.safetensors\", # 大文件自动使用 LFS\n path_in_repo=\"models/model.safetensors\",\n )\n)\n\napi.create_commit(\n repo_id=\"username/my-model\",\n operations=operations,\n commit_message=\"Add model weights\",\n)\n```\n\n### 手动触发 LFS 上传\n\n```python\nfrom huggingface_hub.utils import upload_lfs_file\n\n# 直接上传 LFS 文件\nupload_lfs_file(\n file_path=\"large_dataset.bin\",\n repo_id=\"username/my-dataset\",\n repo_type=\"dataset\",\n)\n```\n\n## 最佳实践\n\n1. **批量操作**：多个 LFS 文件应批量处理，减少 HTTP 请求次数\n2. **断点续传：大文件分片上传确保网络中断后可以继续\n3. **缓存复用**：同一文件仅下载一次，后续直接使用缓存\n4. **进度追踪**：上传/下载过程提供实时进度回调\n5. **并发控制**：避免同时发起过多并发请求，合理控制并发数\n\n## 错误处理\n\n| 错误类型 | 原因 | 处理方式 |\n|----------|------|----------|\n| `LfsUploadError` | LFS 服务器返回错误 | 重试或检查网络 |\n| `LfsSizeMismatchError` | 文件大小不匹配 | 重新上传 |\n| `LfsFileNotFoundError` | Pointer 文件指向的文件不存在 | 检查仓库状态 |\n\n资料来源：[src/huggingface_hub/lfs.py:100-200]()\n\n## 相关模块\n\n- **HfApi**：高级 API，封装 LFS 操作\n- **HfFileSystem**：文件系统接口，支持透明访问 LFS 文件\n- **snapshot_download**：下载整个仓库时自动处理 LFS\n\n资料来源：[src/huggingface_hub/hf_file_system.py:1-50]()\n\n## 扩展阅读\n\n- [Git LFS 协议规范](https://git-lfs.github.com/spec/v1)\n- [Hugging Face Hub 上传指南](https://huggingface.co/docs/huggingface_hub/guides/upload)\n- [缓存管理文档](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)\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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 huggingface_hub 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. file-operations：文件操作。围绕“文件操作”模拟一次用户任务，不展示安装或运行结果。\n4. inference：推理系统。围绕“推理系统”模拟一次用户任务，不展示安装或运行结果。\n5. repository-management：仓库管理。围绕“仓库管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. file-operations\n输入：用户提供的“文件操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. inference\n输入：用户提供的“推理系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. repository-management\n输入：用户提供的“仓库管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / file-operations：Step 3 必须围绕“文件操作”形成一个小中间产物，并等待用户确认。\n- Step 4 / inference：Step 4 必须围绕“推理系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / repository-management：Step 5 必须围绕“仓库管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/huggingface/huggingface_hub\n- https://github.com/huggingface/huggingface_hub#readme\n- .opencode/skills/hf-release-notes/SKILL.md\n- README.md\n- src/huggingface_hub/__init__.py\n- src/huggingface_hub/hf_api.py\n- src/huggingface_hub/constants.py\n- src/huggingface_hub/file_download.py\n- src/huggingface_hub/_snapshot_download.py\n- src/huggingface_hub/_commit_api.py\n- src/huggingface_hub/hf_file_system.py\n- src/huggingface_hub/inference/_client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 huggingface_hub 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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"
}