1 介绍

HuggingFace
一句话概括：AI 领域的 GitHub，全球最大开源 AI 模型共享社区 + 开发平台
官网：https://huggingface.co
⚠️重要提示：国内直连访问不稳定，需要合规网络环境；部分大厂模型（Llama 系列）需要申请权限才能使用
两种在线试用方式：
①模型主页内置推理组件（最简单）；
②Spaces 现成可视化聊天界面（体验更好）

1.1 基础背景

Hugging Face 既是美国 AI 公司名称，也是网站平台名称。
2016 年创立，最早做聊天机器人，后来凭借 Transformers 开源 Python 库爆火，成为开源大模型生态核心阵地。

1.2 网站四大核心板块（网页上主要功能）

1. Models【模型仓库｜最重要】
   • 相当于 AI 模型 “应用商店”
   • 存放上百万开源预训练 AI 模型
   • 包含：大语言模型（Llama、通义千问 Qwen、Mistral）、AI 绘画 Stable Diffusion、语音识别、翻译、图片分类等
   • 任何人可以下载、在线试用、二次微调、上传自己训练的模型
   • 所有主流开源大模型，基本都会第一时间发布在这里。
2. Datasets【数据集仓库】
   • 海量公开训练数据，文本、图片、音频数据集，AI 训练专用。
3. Spaces【在线演示平台｜普通人最容易上手】
   • 无需本地配置电脑！
   • 开发者上传代码，在线生成可直接体验的 AI 网页 Demo：
   • AI 聊天、绘画、语音克隆、视频生成工具都在这里。点开就能网页试用。
4. 文档、社区、企业服务
   • 提供全套 AI 开发工具教程；同时有付费企业版用于商用部署模型。

1.3 配套王牌工具（代码层面）

Transformers（Python 库）
行业标准工具包，几行代码就能加载网站上任意模型，兼容 PyTorch、TensorFlow，开发大模型必备。

1.4 普通人 / 开发者分别能用它做什么

✅ 普通爱好者
打开 Spaces，免费体验各类开源 AI 绘画、开源聊天大模型、语音工具。
✅ AI 开发者 / 算法工程师
下载现成模型，不用从零训练 AI；
在本地电脑 / 显卡运行大模型；
微调模型、上传自己训练成果、快速搭建网页 Demo。

1.5 重要补充知识点

1. 区分开源 / 闭源
   平台只是托管场所：有些模型免费商用，有些只能个人学习（如部分 Llama 系列），下载前看清许可证。
2. 网络访问
   官网境外站点，国内直连访问不稳定；国内替代平台：魔搭 ModelScope（阿里）、智谱开放平台、HuggingFace 镜像站。
3. 和 ChatGPT 区别
   ChatGPT 是闭源成品 AI 服务； GitHub = 存放程序代码。
   Hugging Face 是模型开源社区，提供原材料（模型），你可以自己部署、改造；Hugging Face = 存放 AI 模型、AI 训练数据。

2 注册 & 登录账号

1. 打开官网，右上角点击 Sign Up 注册
2. 填写邮箱、密码，设置用户名，勾选协议创建账号
3. 去邮箱接收验证邮件，点击链接激活账号
4. 返回网页右上角 Log in 登录

3 使用

3.1 进入模型市场，搜索开源大模型

顶部导航栏点击 Models，进入模型仓库（模型超市）
搜索方式：

方式 A：精准搜索（推荐）
顶部搜索框直接输入模型名称，举例常用中文开源模型：Qwen（通义千问开源）、Llama 3、Mistral、Yi（零一万物）、ChatGLM

方式 B：筛选查找
左侧筛选栏：

• Tasks（任务） → 选择 Text Generation（文本生成 / 聊天大模型） 可以勾选语言：
• Chinese，筛选中文模型
• 排序选 Most Downloaded（下载最多）/Trending（热门），优先选热度高、稳定的模型

小提示：名字带 Instruct 的版本是对话微调版，适合直接聊天；不带的是基础预训练模型。

3.2 进入模型主页，在线试用

3.2.1 方法 1：模型内置推理窗口

3.2.1.1 以任意开源对话模型举例：

1. 搜索结果点击模型名称，进入 Model Card（模型卡片主页）
2. 页面右侧找到 Inference Widget（在线推理组件）
   ✅能看到这个窗口 = 支持直接网页试用！
3. 在输入框写提示词，点击 Submit 发送，直接在线运行大模型

3.2.1.2 常见踩坑说明

1. 提示 Gated model：受限模型（Meta Llama3 等）
   解决：下拉页面填写信息申请访问权限，等待审批通过才能使用；
2. 报错加载失败：免费公共算力有限、超时、负载过高；换一个模型重试；
3. 部分小模型没有内置推理窗口 → 使用下面 Spaces 方案。

3.2.2 方法 2：Spaces 可视化聊天 Demo（更好的体验，强烈推荐新手）

很多开发者把模型封装成网页聊天界面，像 ChatGPT 一样使用，不用调试参数！

1. 顶部导航点击 Spaces
2. 搜索关键词：Qwen chat、Llama3 chat、ChatGLM webui
3. 点开对应 Space 链接，直接出现聊天窗口，输入对话即可
   注意：免费 CPU 启动很慢；部分 Space 需要排队；长时间闲置页面会休眠，刷新重启即可。

3.3关键基础参数解释（调整生成效果）

在线界面经常看到这些选项，新手参考：

1. Temperature 温度：0~1，越高回答越有创意；日常聊天推荐 0.6~0.8
2. Max new tokens：限制单次最大输出字数
3. Top P：默认 0.9 即可，不用改动

📌新手友好入门模型推荐（中文可用，大多无需复杂权限）

1. Qwen/Qwen2-7B-Instruct（阿里通义千问开源，中文优秀）
2. THUDM/chatglm3-6b（智谱清言开源）
3. 01-ai/Yi-6B-Chat（零一万物）

3.4 高频问题避坑

1. 一直转圈、无法生成 免费公共推理资源有限，高峰拥堵；
   解决方案：换模型、或者本地下载模型运行。
2. 模型申请权限一直不通过 Llama
   系列属于 Meta 受限模型，填写申请理由尽量写学术 / 个人研究用途。
3. 页面打不开、加载缓慢：网络环境问题。
4. 不要商用：留意每个模型页面的 License 协议，部分开源模型禁止商业使用。

4 HuggingFace Transformers 本地部署完整教程

目标：Python + transformers 库，电脑本地跑开源大模型（Qwen/ChatGLM/Yi 等）

4.1 前置说明

1. 硬件参考（最低）
   6B 模型：推荐 ≥16G 内存；有 NVIDIA GPU ≥8G 显存最佳
   没有显卡（纯 CPU）：速度非常慢，仅适合测试
2. 只支持 NVIDIA 显卡（CUDA）；AMD 显卡需要额外方案（ROCm）
3. 环境：Python 3.9 ~ 3.11（最稳定，不推荐 3.12 踩坑）

4.2 环境安装

1. 创建虚拟环境（可选但强烈推荐）

# windows/mac通用
python -m venv hf-env

# Windows 激活
hf-env\Scripts\activate

# Mac/Linux激活
source hf-env/bin/activate

2. 安装依赖包

# 核心库
pip install transformers accelerate torch sentencepiece protobuf

# 可选：加速加载模型、量化（节省显存）
pip install bitsandbytes

# 可选
pip install transformers accelerate torch sentencepiece protobuf bitsandbytes gradio

accelerate：自动适配 GPU/CPU；bitsandbytes 用来 4/8bit 量化，显存不够必备

3. 重点：安装 PyTorch CUDA 版本
   先查看自己显卡是否支持 CUDA，去pytorch.org复制对应命令
   示例（CUDA12.1）：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

4.3 运行方案

示范模型：Qwen/Qwen2-7B-Instruct（中文效果好，新手首选）
如果你想跑 ChatGLM3、Yi，只需要更换模型名称！

4.3.1 基础标准版（自动检测 GPU，简单易懂）

新建 run_llm.py

from transformers import AutoTokenizer, AutoModelForCausalLM

# 模型名称（huggingface上的模型地址）
model_name = "Qwen/Qwen2-7B-Instruct"

# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(model_name)
# 加载模型，自动放到GPU
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",  # 自动分配显卡内存
    trust_remote_code=True
)

# 对话模板
messages = [
    {"role": "system", "content": "你是一名乐于助人的AI助手"},
    {"role": "user", "content": "简单介绍一下Hugging Face"}
]

# 编码输入
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer([text], return_tensors="pt").to("cuda")

# 生成回答
outputs = model.generate(
    **inputs,
    max_new_tokens=512,
    temperature=0.7
)

# 打印结果
result = tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)
print(result)

4.3.2 显存不足解决方案（重要）

7B 模型直接加载需要大量显存，开启4bit 量化，显存占用直接减半
修改模型加载代码：

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
    trust_remote_code=True,
    load_in_4bit=True,   # 开启4bit量化
)

⚠️ load_in_4bit 需要安装 bitsandbytes，Windows 部分版本兼容会报错

4.3.3 模型下载问题（国内最大痛点）

直接运行代码会尝试从 hf 官网下载，速度极慢 / 失败
方法 A：设置镜像源（推荐）
运行代码前，在终端设置环境变量

# Windows cmd
set HF_ENDPOINT=https://hf-mirror.com

# Mac / Linux
export HF_ENDPOINT=https://hf-mirror.com

再执行 python run_llm.py，会走国内镜像加速下载

方法 B：手动提前下载模型

1. 使用工具 huggingface-hub

pip install huggingface-hub

# 镜像下载模型
set HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2-7B-Instruct --local-dir ./Qwen2-7B-Instruct

• 代码中直接读取本地文件夹
  下载模型到本地文件夹

model_name = "./Qwen2-7B-Instruct" # 本地路径，不再联网下载

4.3.5 受限模型说明（Llama3 等）

如果你要运行 Meta Llama 3：
HuggingFace 网页申请模型访问权限
在本地登录你的 huggingface 账号

huggingface-cli login

粘贴你的 HF Token，才能正常下载、加载模型。

4.3.6 常见报错排查

• OutOfMemoryError 显存爆了
  ✅ 开启 load_in_4bit=True；或者换更小模型：Qwen2-1.5B-Instruct
• trust_remote_code 报错
  ✅ 加上参数 trust_remote_code=True
• 运行速度很慢，全程 CPU 跑
  ✅ 确认 cuda 版本正确，执行下面代码测试 torch 是否识别显卡

import torch
print(torch.cuda.is_available()) #输出True才算成功启用GPU

• 下载模型中断
  ✅ 使用 hf 镜像；或者手动 cli 下载

4.4 新手推荐起步模型（硬件门槛低）

• 轻量测试：Qwen/Qwen2-1.5B-Instruct （低配置电脑可跑）
• 均衡性能：Qwen/Qwen2-7B-Instruct（中文首选）

4.5 Gradio 网页 UI 版本（浏览器聊天界面）

from transformers import AutoTokenizer, AutoModelForCausalLM
import gradio as gr

# ========== 配置区 ==========
model_path = "Qwen/Qwen2-7B-Instruct"
load_4bit = True
max_new_tokens = 512
temperature = 0.7
# ===========================

print("正在加载模型...")
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    device_map="auto",
    trust_remote_code=True,
    load_in_4bit=load_4bit
).eval()

def predict(message, history):
    messages = [{"role": "system", "content": "你是一个乐于助人的AI助手。"}]
    # 拼接历史对话
    for user_msg, bot_msg in history:
        messages.append({"role": "user", "content": user_msg})
        messages.append({"role": "assistant", "content": bot_msg})
    messages.append({"role": "user", "content": message})

    prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer([prompt], return_tensors="pt").to("cuda")

    outputs = model.generate(
        **inputs,
        max_new_tokens=max_new_tokens,
        temperature=temperature,
        do_sample=True
    )
    answer = tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)
    return answer


# 启动网页界面
demo = gr.ChatInterface(
    fn=predict,
    title="本地大模型聊天",
    description="基于Transformers + Qwen2 本地部署",
)

if __name__ == "__main__":
    # server_name="0.0.0.0" 局域网其他设备也能访问
    demo.launch(server_name="0.0.0.0", share=False)

运行：python chat_webui.py
启动成功后会输出地址，浏览器打开：http://127.0.0.1:7860

未完待续，后续更新…