06. 开源模型宝库：HuggingFace 与 ModelScope

课时信息

📅 时间：课后 / 选修 🎯 目标：掌握国内环境下高效下载与运行开源模型的方法

1. 痛点：网络之墙

HuggingFace (HF) 是 AI 界的 GitHub，存放着全世界最前沿的开源模型。但由于众所周知的网络原因，在国内直接下载模型（通常几十 GB）经常失败。

今天我们学习两把钥匙：HF-Mirror 和 ModelScope。

2. 钥匙一：HF-Mirror (国内镜像)

HF-Mirror 是 HuggingFace 的国内公益镜像站。

配置方法 (Linux/Mac/Windows PowerShell)

在下载模型前，设置环境变量：

export HF_ENDPOINT=https://hf-mirror.com

结合 huggingface-cli 下载

安装官方命令行工具：

pip install -U "huggingface_hub[cli]"

下载模型 (以 Qwen2.5-Coder-7B 为例)：

# 开启多线程加速
huggingface-cli download \
  --resume-download Qwen/Qwen2.5-Coder-7B-Instruct \
  --local-dir ./Qwen2.5-Coder-7B-Instruct

---

3. 钥匙二：ModelScope (魔搭社区)

ModelScope 是阿里推出的 "中国版 HuggingFace"。 优势：

• 速度极快：国内服务器，跑满带宽。
• 生态兼容：大部分主流模型 (Llama, DeepSeek, Qwen) 都会同步首发。
• API 兼容：提供了兼容 transformers 的 Python 库。

安装 SDK

pip install modelscope

Python 下载示例

from modelscope.hub.snapshot_download import snapshot_download

# 下载模型到本地 cache
model_dir = snapshot_download('Qwen/Qwen2.5-Coder-7B-Instruct')
print(f"模型已下载至: {model_dir}")

---

4. 实战：用 Python 启动 Transformer 模型

Ollama 虽然方便，但如果你想研究模型底层、微调 (Fine-tune) 或做量化，必须掌握使用 Python 的 transformers 库直接加载模型。

准备环境

pip install torch transformers accelerate

编写启动脚本 (run_model.py)

这个脚本会自动判断：如果有 GPU 用 GPU，没 GPU 用 CPU。

import os
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# 1. 强制使用 HF 镜像 (如果没设环境变量)
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 模型名称 (HuggingFace ID)
model_name = "Qwen/Qwen2.5-Coder-1.5B-Instruct"

print(f"正在加载模型: {model_name} ...")

# 2. 加载 Tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 3. 加载模型 (自动映射设备)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

# 4. 准备对话
prompt = "写一个 Python 函数，计算斐波那契数列。"
messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": prompt}
]

# 5. 格式化输入
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

# 6. 推理 (Generate)
print("正在生成代码...")
generated_ids = model.generate(
    model_inputs.input_ids,
    max_new_tokens=512
)
generated_ids = [
    output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]

response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
print("---" * 20)
print(response)

显存警告

7B 模型大约需要 14GB+ 显存 (FP16)。如果你的显存不足，请尝试 1.5B 版本，或者在 from_pretrained 中添加 load_in_8bit=True (需要安装 bitsandbytes 库)。