HuggingFace镜像站-AI 快站使用说明文档

欢迎使用 AI 快站！我们致力于为 AI 开发者提供稳定、高速、免费的 Hugging Face 模型和数据集下载加速服务。本文档将引导您快速掌握 AI 快站的各项功能，解决模型下载难题，提升开发效率。

🚀 为什么选择 AI 快站？

⚡️ 超快下载速度: 依托独特的加速技术，模型下载速度最高可达 10M/s+
🔄 断点续传支持: 内建或推荐的工具均支持断点续传，有效解决大模型下载过程中因网络波动导致中断的烦恼，确保下载 100% 完成。
🆓 完全免费使用: AI 快站作为一个公益项目，所有下载加速服务完全免费，旨在降低 AI 开发门槛，让每一位开发者都能便捷地访问全球 AI 资源。
🛠️ 6种下载使用方式: 支持网页直接访问、专用命令行工具、官方 Hugging Face CLI、Python 环境变量、Git Clone 以及 Ollama 等多种方式，灵活满足不同场景下的使用需求。

📖 AI 快站使用方法详解

我们提供了多种灵活的方式来使用 AI 快站的加速服务，您可以根据自己的习惯和场景选择最合适的方法。

方法 1：网页在线访问 🌐

最简单直观的方式，无需任何配置。

1. 直接访问 AI 快站官网 aifasthub.com。
1. 在网站内搜索您需要的模型或数据集。
1. 访问模型或数据集的详情页面，页面内的所有资源链接（包括文件下载链接）均已自动通过 AI 快站的加速节点。
1. 在 "Files and versions" 选项卡下，点击文件旁的下载按钮即可开始高速下载。

适用场景: 临时下载少量文件、浏览模型/数据集内容、无需编程或命令行操作的用户。

方法 2：专用命令行工具 hf-fast.sh 💻

hf-fast.sh 是 AI 快站开发的高效下载脚本，基于成熟的 aria2 工具，特别适合在 Linux 和 Mac OS 环境下进行稳定、高速、多线程的批量下载。

安装与授权 (首次使用)

bash 复制代码

# 下载脚本
wget https://fast360.xyz/images/hf-fast.sh

# 赋予执行权限
chmod a+x hf-fast.sh

基础使用

bash 复制代码

# 下载模型 (例如：gpt2)
./hf-fast.sh gpt2

# 下载数据集 (例如：squad) - 使用 -d 参数
./hf-fast.sh -d squad

完整使用说明与选项

bash 复制代码

Usage: hf-fast.sh [OPTIONS] REPO_ID

通过 AI 快站加速节点下载 Hugging Face Hub 上的文件。

Options:
  -i, --include PATTERN   指定下载文件的匹配模式 (可多次使用, 例如: -i "*.bin" -i "*.json")
  -e, --exclude PATTERN   指定排除下载文件的匹配模式 (可多次使用, 例如: -e "*.md" -e "*.txt")
  -t, --token TOKEN       用于访问私有或需要授权的仓库的 Hugging Face Token
  -r, --revision REV      指定要下载的仓库版本/分支/标签 (默认为: main)
  -d, --dataset           标记下载的是数据集而非模型
  -j, --jobs N            设置并发下载的文件数量 (默认为: 4)
  -o, --output DIR        指定文件下载到的本地目录 (默认为: 当前目录下以 REPO_ID 命名的文件夹)
  --endpoint URL          指定 AI 快站的 API 端点 (默认为: https://aifasthub.com)
  --debug                 启用 Debug 模式，输出更详细的日志信息
  -h, --help              显示此帮助信息

Examples:
  # 下载 gpt2 模型，仅下载 .bin 文件，排除 .md 文件
  ./hf-fast.sh -i "*.bin" -e "*.md" gpt2

  # 使用 Hugging Face Token 下载 Llama-3 模型，并发数为 8
  ./hf-fast.sh -t YOUR_HF_TOKEN -j 8 meta-llama/Meta-Llama-3-8B

  # 下载 gpt2 模型到指定目录 ./models/gpt2
  ./hf-fast.sh -o ./models/gpt2 gpt2

  # 下载 gpt2 模型并开启 Debug 模式
  ./hf-fast.sh --debug gpt2

适用场景: Linux/Mac 用户、需要批量下载、追求最高下载效率和稳定性、自动化脚本集成。

方法 3：官方 Hugging Face CLI 工具集成 🤗

您可以继续使用 Hugging Face 官方的 huggingface-cli 工具，只需简单配置一个环境变量，即可将所有下载请求指向 AI 快站的加速节点。

1. 安装/更新 huggingface_hub

确保您安装了较新版本的 huggingface_hub (建议 0.17.0 或更高版本，需要 Python >= 3.8)。

复制代码

pip install -U huggingface_hub

1. 设置环境变量 HF_ENDPOINT

将环境变量 HF_ENDPOINT 设置为 AI 快站的加速地址。

Linux / Mac OS:

bash 复制代码

export HF_ENDPOINT="https://aifasthub.com"
# (可选) 将上面这行添加到 ~/.bashrc 或 ~/.zshrc 文件中，使其永久生效
echo 'export HF_ENDPOINT="https://aifasthub.com"' >> ~/.bashrc  # 或 ~/.zshrc
source ~/.bashrc # 或 source ~/.zshrc 使其立即生效

Windows PowerShell:

shell 复制代码

$env:HF_ENDPOINT = "https://aifasthub.com"
# (可选) 将上面这行添加到 PowerShell 配置文件中使其永久生效
# Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://aifasthub.com"'

1. 使用 huggingface-cli 下载

设置环境变量后，正常使用 huggingface-cli download 命令即可享受加速。推荐加上 --resume-download 以支持断点续传。

scss 复制代码

# 下载模型 (例如：gpt2) 到当前目录下的 gpt2 文件夹
huggingface-cli download gpt2 --local-dir gpt2 --resume-download

# 下载数据集 (例如：wikitext) 到当前目录下的 wikitext 文件夹
huggingface-cli download wikitext --repo-type dataset --local-dir wikitext --resume-download

适用场景: 习惯使用官方 huggingface-cli 工具的用户、跨平台需求 (Windows/Linux/Mac)、希望利用官方工具链其他功能（如缓存管理、符号链接等）的用户。

方法 4：Python 脚本集成 (环境变量) 🐍

对于 Python 开发者，这是一种非侵入式的加速方式。只需在运行 Python 脚本前设置 HF_ENDPOINT 环境变量，transformers、datasets、huggingface_hub 等库在下载模型或数据集时会自动使用 AI 快站的加速节点，无需修改任何 Python 代码。

设置方式一：运行脚本时指定

在命令行中运行 Python 脚本时临时设置环境变量：

arduino 复制代码

export HF_ENDPOINT=https://aifasthub.com your_script.py

设置方式二：在 Python 脚本内部设置 (需在 import 相关库之前)

python 复制代码

import os
os.environ['HF_ENDPOINT'] = 'https://aifasthub.com'

# --- 在设置环境变量之后再 import 和使用 Hugging Face 相关库 ---
from transformers import AutoModel, AutoTokenizer

# 示例：使用 transformers 加载模型，会自动通过 AI 快站下载
model_name = 'BAAI/bge-large-zh-v1.5'
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)

print(f"模型 '{model_name}' 加载成功！")

适用场景: Python 开发者、在代码中直接加载和使用 Hugging Face 模型/数据集、不希望修改现有 Python 代码的用户。

方法 5：Git Clone 加速 🛠️

如果您习惯使用 git 来管理模型仓库，可以通过修改 clone URL 来使用 AI 快站进行加速。

将 Hugging Face 仓库的 URL huggingface.co/{repo_id} 替换为 aifasthub.com/{repo_id}。

bash 复制代码

# 示例：克隆 gpt2 模型仓库
git clone https://aifasthub.com/gpt2

注意: git clone 对于非常大的仓库或包含很多历史记录的仓库可能会下载较慢或占用较多磁盘空间（.git 目录）。对于仅需获取最新模型文件的场景，更推荐使用 hf-fast.sh 或 huggingface-cli。

适用场景: 需要获取完整 Git 历史记录的用户、习惯使用 Git 进行版本管理和协作的团队。

方法 6：Ollama 模型下载加速 🦙

如果您使用 Ollama 加载本地大模型，可以直接通过 AI 快站加速下载 Hugging Face 上的 GGUF 格式模型。

使用格式

将 Ollama run 命令中的模型名称替换为 aifasthub.com/{username}/{reponame}:{tag} 的格式。

arduino 复制代码

ollama run aifasthub.com/{huggingface_用户名}/{仓库名}:{GGUF格式参数}

重要限制:

仅支持 GGUF 格式的模型文件。
必须提供完整的 Hugging Face 仓库 ID ({username}/{reponame})。
必须指定 GGUF 文件的量化参数标签 (例如 Q4_K_M, Q8_0, Q5_K_S 等)。

示例

ruby 复制代码

# 下载 Llama-3.2 1B Instruct Q8_0 量化模型
ollama run aifasthub.com/bartowski/Llama-3.2-1B-Instruct-GGUF:Q8_0

# 下载 Qwen2.5 3B Instruct Q3_K_M 量化模型
ollama run aifasthub.com/Qwen/Qwen2.5-3B-Instruct-GGUF:Q3_K_M

# 下载 Llama-2 7B Chat Q4_K_M 量化模型
ollama run aifasthub.com/TheBloke/Llama-2-7B-Chat-GGUF:Q4_K_M

适用场景: Ollama 用户、需要快速下载并运行 GGUF 格式模型的用户。

❓ 常见问题 (FAQ)

Q1: 如何下载需要登录授权的私有模型/数据集 (Gated Models)？

1. 获取授权: 首先，您需要在 Hugging Face 官网 (huggingface.co) 登录您的账户，并访问需要下载的模型/数据集页面，申请访问权限。通常需要同意相关条款。
1. 获取 Access Token: 访问您的 Hugging Face 账户设置 -> Access Tokens 页面 (huggingface.co/settings/to...%25EF%25BC%258C%25E5%2588%259B%25E5%25BB%25BA%25E4%25B8%2580%25E4%25B8%25AA%25E5%2585%25B7%25E6%259C%2589 "https://huggingface.co/settings/tokens)%EF%BC%8C%E5%88%9B%E5%BB%BA%E4%B8%80%E4%B8%AA%E5%85%B7%E6%9C%89") Read 权限的 Token 并复制它。

使用 Token 下载:

使用 hf-fast.sh: 使用 -t 参数传入您的 Token。

bash 复制代码

./hf-fast.sh -t hf_YOUR_ACCESS_TOKEN meta-llama/Meta-Llama-3-8B

使用 huggingface-cli:

方式一：使用 --token 参数。

css 复制代码

huggingface-cli download meta-llama/Meta-Llama-3-8B --token hf_YOUR_ACCESS_TOKEN --local-dir Meta-Llama-3-8B --resume-download

方式二：设置 HF_TOKEN 环境变量（推荐，避免每次输入）。

ini 复制代码

export HF_TOKEN="hf_YOUR_ACCESS_TOKEN"
huggingface-cli download meta-llama/Meta-Llama-3-8B --local-dir Meta-Llama-3-8B --resume-download
# (Windows PowerShell: $env:HF_TOKEN = "hf_YOUR_ACCESS_TOKEN")

Python 脚本: 使用 huggingface_hub.login() 或设置 HF_TOKEN 环境变量。

arduino 复制代码

import os
os.environ['HF_ENDPOINT'] = 'https://aifasthub.com'
# os.environ['HF_TOKEN'] = 'hf_YOUR_ACCESS_TOKEN' # 方式一：设置环境变量

from huggingface_hub import login
# login(token='hf_YOUR_ACCESS_TOKEN') # 方式二：代码中登录 (会缓存token)

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B")

Q2: 下载速度不稳定或下载中断怎么办？

确认使用断点续传:
- hf-fast.sh 基于 aria2，默认支持断点续传。如果中断，重新运行相同的命令即可从断点继续。
- 使用 huggingface-cli 时，请务必添加 --resume-download 参数。
调整并发数 (适用于 hf-fast.sh): 如果网络带宽较高，可以尝试增加并发下载数 -j 来提高整体速度（默认为 4）。但请注意，过高的并发数可能给服务器带来压力或被目标服务器限制。

bash 复制代码

./hf-fast.sh -j 8 your_model_name

网络环境: 下载速度受限于您的本地网络带宽和网络质量。如果速度持续不佳，请检查您的网络连接。AI 快站会持续优化节点和服务，但无法完全克服用户本地网络问题。

Q3: 如何在 Python 脚本中最方便地使用 AI 快站加速？

推荐使用设置环境变量的方式 (方法 4)，因为它完全非侵入式。

推荐: 在运行脚本前设置 HF_ENDPOINT 环境变量。这样您的 Python 代码无需任何改动。

ini 复制代码

# Linux/Mac
export HF_ENDPOINT="https://aifasthub.com"
python your_script.py

# Windows PowerShell
$env:HF_ENDPOINT = "https://aifasthub.com"
python your_script.py

备选: 在 Python 代码开头处设置 os.environ['HF_ENDPOINT'] = 'aifasthub.com'。确保这行代码在 import transformers 或其他 Hugging Face 相关库之前执行。

Q4: 使用 Ollama 通过 AI 快站下载模型需要注意什么？

请务必遵守以下规则，否则 Ollama 可能无法正确解析和下载：

1. 模型名称格式必须是 aifasthub.com/{hf_username}/{hf_reponame}:{tag}。
1. 仅支持下载 GGUF 格式的模型。
1. 必须提供完整的 Hugging Face 仓库 ID ({hf_username}/{hf_reponame})。
1. 必须指定 GGUF 文件的量化参数标签作为 tag (例如 Q4_K_M, Q8_0 等)。

正确示例: ollama run aifasthub.com/TheBloke/Llama-2-7B-Chat-GGUF:Q4_K_M 错误示例: ollama run aifasthub.com/Llama-2-7B-Chat-GGUF (缺少用户名和标签) 错误示例: ollama run aifasthub.com/TheBloke/Llama-2-7B-Chat-GGUF (缺少标签)

选择哪种方法？

快速尝试/偶尔下载: 网页在线访问 (方法 1)。
Linux/Mac 主力开发，追求高效稳定: 专用命令行工具 hf-fast.sh (方法 2)。
习惯官方工具/跨平台/需要官方工具链特性: Hugging Face CLI + 环境变量 (方法 3)。
Python 项目集成，不想改代码: Python 环境变量 (方法 4)。
需要 Git 历史/版本控制: Git Clone 加速 (方法 5)。
Ollama 用户下载 GGUF 模型: Ollama 特定格式 (方法 6)。

感谢您选择 AI 快站！如果您在使用过程中遇到任何问题或有任何建议，欢迎反馈！