使用 Hugging Face API 操作仓库指南

简介

本文介绍如何使用 Hugging Face API 通过 Python 直接操作 Hugging Face 仓库（模型或数据集），包括上传、删除、列出文件等常见操作。这种方法比使用命令行工具更灵活，特别适合批量操作和自动化脚本。

前置准备

1. 安装依赖

bash
展开代码
pip install -U "huggingface_hub[cli]" --break-system-packages

2. 获取 API Token

登录 Hugging Face 官网
点击头像 → Settings → Access Tokens
创建新 Token（需勾选 write 权限）

3. 设置环境变量

bash
展开代码
export HF_TOKEN='你的Token'

基本操作

初始化 API 客户端

python
展开代码
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')  # 如果包安装在用户目录
from huggingface_hub import HfApi
import os

# 方式1: 从环境变量读取
api = HfApi(token=os.environ.get('HF_TOKEN'))

# 方式2: 直接指定（不推荐，安全性差）
api = HfApi(token='hf_xxxxxxxxxxxxx')

常用操作示例

1. 上传整个文件夹

python
展开代码
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 上传整个文件夹
api.upload_folder(
    folder_path='.',  # 当前目录
    repo_id='hugxd/mmdu_val',  # 仓库ID: 用户名/仓库名
    repo_type='dataset',  # 'model' 或 'dataset'
    ignore_patterns=['.git/**']  # 忽略的文件模式
)
"

参数说明：

folder_path: 要上传的本地文件夹路径
repo_id: 仓库ID，格式为 用户名/仓库名
repo_type: 仓库类型，'model' 或 'dataset'
ignore_patterns: 要忽略的文件模式列表

2. 删除文件

python
展开代码
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 要删除的文件列表
files_to_delete = [
    'benchmark.json',
    'mmdu-45k.json',
    'mmdu-45k_pics.zip',
    'mmdu_pics.zip'
]

print('开始删除无关文件...')
for file in files_to_delete:
    try:
        api.delete_file(
            path_in_repo=file,
            repo_id='hugxd/mmdu_val',
            repo_type='dataset'
        )
        print(f'✓ 已删除: {file}')
    except Exception as e:
        print(f'✗ 删除失败 {file}: {e}')

print('\\n删除完成！')
"

3. 列出仓库文件

python
展开代码
cd /data/xiedong/mmdu/mmdu_val && export HF_TOKEN=xxxx && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', 'xxxx'))

# 列出所有文件
files = api.list_repo_files('hugxd/mmdu_val', repo_type='dataset')

print(f'仓库中共有 {len(files)} 个文件:')
for f in sorted(files):
    print(f)
"

4. 上传单个文件

python
展开代码
api.upload_file(
    path_or_fileobj='/path/to/local/file.json',
    path_in_repo='file.json',  # 在仓库中的路径
    repo_id='hugxd/mmdu_val',
    repo_type='dataset'
)

5. 创建仓库（如果不存在）

python
展开代码
api.create_repo(
    repo_id='hugxd/mmdu_val',
    repo_type='dataset',
    exist_ok=True  # 如果已存在则不会报错
)

完整示例：同步本地文件夹到远程仓库

bash
展开代码
cd /path/to/local/folder && export HF_TOKEN=你的Token && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN'))

# 1. 创建仓库（如果不存在）
api.create_repo(
    repo_id='用户名/仓库名',
    repo_type='dataset',  # 或 'model'
    exist_ok=True
)

# 2. 上传整个文件夹
api.upload_folder(
    folder_path='.',
    repo_id='用户名/仓库名',
    repo_type='dataset',
    ignore_patterns=['.git/**', '__pycache__/**', '*.pyc']
)

print('上传完成！')
"

提示词模板（给 AI 使用）

当需要操作 Hugging Face 仓库时，可以使用以下提示词模板：


展开代码
请使用 Hugging Face API 帮我操作仓库：

仓库信息：
- 仓库ID: hugxd/mmdu_val
- 仓库类型: dataset (或 model)
- API Token: xxxx

操作需求：
1. [具体操作，如：上传本地文件夹 /data/xiedong/mmdu/mmdu_val]
2. [或：删除文件 benchmark.json, mmdu-45k.json]
3. [或：列出所有文件]

请使用以下格式的命令：
cd [工作目录] && export HF_TOKEN=[Token] && python -c "
import sys
sys.path.insert(0, '/home/xd/.local/lib/python3.12/site-packages')
from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ.get('HF_TOKEN', '[Token]'))

# [具体操作代码]
"

注意事项

安全性: 不要在代码中硬编码 API Token，优先使用环境变量
权限: 确保 Token 有 write 权限才能上传/删除文件
路径: path_in_repo 是文件在仓库中的相对路径，不是本地路径
仓库类型: 区分 'model' 和 'dataset'，操作时需指定正确类型
批量操作: 删除多个文件时，建议使用循环并添加异常处理

常见问题

Q: 上传大文件时超时怎么办？

A: 使用 upload_large_folder 方法，或分批上传：

python
展开代码
api.upload_large_folder(
    folder_path='.',
    repo_id='hugxd/mmdu_val',
    repo_type='dataset'
)

Q: 如何只上传特定文件？

A: 使用 ignore_patterns 参数排除不需要的文件，或使用 upload_file 逐个上传。

Q: 如何检查文件是否已存在？

A: 先使用 list_repo_files 列出所有文件，然后检查目标文件是否在列表中。

目录