Hugging Face 简介

Hugging Face 最值得看的，不只是“模型很多”，而是它把模型、数据集、演示应用和推理入口都放进了同一个开源生态里。你做本地实验、下载权重、找 embedding 模型、搭一个 demo，很多时候都会经过它。

#为什么它会成为默认站点

#1. Hub 本身就是基础设施

Hugging Face 官方文档现在把 Hub 直接定义成托管三类 Git-based repositories 的平台：

Models
Datasets
Spaces

这点很关键。因为它不是单纯的“模型下载站”，而是版本化仓库系统。分支、提交历史、diff、协作流程都能沿用 Git 心智。

#2. 工具链完整

常见组合通常就是这些：

transformers：加载和运行模型
datasets：管理和流式读取数据集
huggingface_hub：下载、上传、推理和 Hub 操作
accelerate / peft：训练和微调相关

#3. 开发节奏很顺

很多团队最后会形成一条非常自然的链路：

先在 Hub 上找模型，再本地跑一版，再决定是否接推理服务，最后需要演示时再丢到 Spaces。

#别把它只当“模型商店”

很多新手第一次接触 Hugging Face，只会做两件事：搜索模型，复制代码。这个当然没错，但真正用久以后，你更会依赖它做下面这些事：

找到合适的 embedding 模型
看 model card 判断能不能商用、适不适合中文
直接复用别人的 Space 验证效果
用同一个 InferenceClient 接不同 provider 或 endpoint

#快速理解四块核心能力

#Transformers 库

使用预训练模型的标准方式：

python
from transformers import pipeline

# 文本生成
generator = pipeline("text-generation", model="gpt2")
result = generator("AI 技术正在", max_length=50)
print(result[0]["generated_text"])

# 文本分类
classifier = pipeline("sentiment-analysis")
result = classifier("这个产品太棒了！")
print(result)  # [{'label': 'POSITIVE', 'score': 0.99}]

# 问答
qa = pipeline("question-answering")
result = qa(question="什么是 Python?", context="Python 是一种编程语言...")

#Embedding 模型

生成文本向量：

python
from sentence_transformers import SentenceTransformer

# 加载模型
model = SentenceTransformer("BAAI/bge-small-zh-v1.5")

# 生成向量
sentences = ["这是第一个句子", "这是第二个句子"]
embeddings = model.encode(sentences)

print(embeddings.shape)  # (2, 512)

#模型 Hub

下载和上传模型：

python
from huggingface_hub import HfApi, snapshot_download

# 下载模型
model_path = snapshot_download(repo_id="BAAI/bge-small-zh-v1.5")

# 上传模型
api = HfApi()
api.upload_folder(
    folder_path="./my_model",
    repo_id="username/my-model",
    repo_type="model"
)

#快速开始

#安装

bash
pip install transformers
pip install sentence-transformers  # Embedding 模型
pip install huggingface_hub  # Hub 操作
pip install accelerate  # GPU 加速

#基础使用

python
from transformers import AutoTokenizer, AutoModel
import torch

# 1. 加载模型和分词器
model_name = "BAAI/bge-small-zh-v1.5"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)

# 2. 编码文本
text = "Hugging Face 是一个 AI 开源社区"
inputs = tokenizer(text, return_tensors="pt", padding=True)

# 3. 获取向量
with torch.no_grad():
    outputs = model(**inputs)
    embeddings = outputs.last_hidden_state.mean(dim=1)

print(embeddings.shape)  # torch.Size([1, 512])

#常用 Embedding 模型

#中文模型

模型	维度	特点
BAAI/bge-small-zh-v1.5	512	轻量快速
BAAI/bge-base-zh-v1.5	768	平衡选择
BAAI/bge-large-zh-v1.5	1024	高精度

#多语言模型

模型	维度	特点
sentence-transformers/all-MiniLM-L6-v2	384	轻量英文
intfloat/multilingual-e5-small	384	多语言
BAAI/bge-m3	1024	多语言最强

#使用示例

python
from sentence_transformers import SentenceTransformer

# 中文场景推荐
model = SentenceTransformer("BAAI/bge-small-zh-v1.5")

# 多语言场景
model = SentenceTransformer("BAAI/bge-m3")

# 快速英文场景
model = SentenceTransformer("all-MiniLM-L6-v2")

#Inference API

现在更实用的理解不是“只有一个旧的 Inference API”，而是 Hugging Face 在推进统一的 Inference Providers + InferenceClient 入口。也就是说，你可以用相似的客户端心智去接不同 provider 或不同部署方式。

在线调用模型：

python
import requests

API_URL = "https://api-inference.huggingface.co/models/gpt2"
headers = {"Authorization": f"Bearer {HF_TOKEN}"}

def query(payload):
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()

output = query({"inputs": "The future of AI is"})
print(output)

#免费 Embedding API

python
import requests

API_URL = "https://api-inference.huggingface.co/pipeline/feature-extraction/BAAI/bge-small-zh-v1.5"
headers = {"Authorization": f"Bearer {HF_TOKEN}"}

def get_embedding(text):
    response = requests.post(API_URL, headers=headers, json={"inputs": text})
    return response.json()

embedding = get_embedding("你好世界")

#与 LangChain 集成

python
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.vectorstores import FAISS

# 使用 HuggingFace Embedding
embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-small-zh-v1.5"
)

# 创建向量存储
vectorstore = FAISS.from_texts(
    texts=["文档1", "文档2"],
    embedding=embeddings
)

# 相似性搜索
docs = vectorstore.similarity_search("查询", k=3)

#与 LlamaIndex 集成

python
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings, VectorStoreIndex, SimpleDirectoryReader

# 设置 Embedding 模型
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-zh-v1.5"
)

# 加载文档并创建索引
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)

# 查询
query_engine = index.as_query_engine()
response = query_engine.query("问题")

#Spaces：托管 AI 应用

#Gradio 应用

python
import gradio as gr
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-small-zh-v1.5")

def get_embedding(text):
    embedding = model.encode(text)
    return str(embedding[:10]) + "..."

demo = gr.Interface(
    fn=get_embedding,
    inputs="text",
    outputs="text",
    title="文本向量生成器"
)

demo.launch()

#部署到 Spaces

创建 requirements.txt

#一个更务实的建议

如果你现在只是做本地原型，先别急着把 Hugging Face 想成“生产推理平台”。它最先给你带来的价值，通常是：

更快找到合适模型
更快验证任务效果
更快搭出一个能展示的 demo

等你走到稳定调用、成本控制和 SLA，再去细分是 Inference Providers、Endpoints，还是自托管。 2. 创建 app.py（Gradio 或 Streamlit） 3. 推送到 Hugging Face Space

#本地运行 LLM

#使用 Transformers

python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# 加载模型
model_name = "Qwen/Qwen2-0.5B"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto"
)

# 生成文本
inputs = tokenizer("Python 是", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0]))

#使用 Text Generation Inference (TGI)

bash
# Docker 部署
docker run --gpus all -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id mistralai/Mistral-7B-v0.1

#模型微调

#使用 PEFT (LoRA)

python
from peft import LoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

# 加载基础模型
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")

# 配置 LoRA
lora_config = LoraConfig(
    r=8,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.1
)

# 应用 LoRA
model = get_peft_model(model, lora_config)
print(f"可训练参数: {model.print_trainable_parameters()}")

#定价

服务	价格
公开模型	免费
Inference API (免费)	有限调用
Inference Endpoints	$0.06/小时起
PRO 订阅	$9/月
Enterprise Hub	联系销售

#最佳实践

#1. 选择合适的模型

python
# 场景 1：快速原型（小模型）
model = SentenceTransformer("all-MiniLM-L6-v2")  # 384 维

# 场景 2：中文生产环境
model = SentenceTransformer("BAAI/bge-base-zh-v1.5")  # 768 维

# 场景 3：多语言场景
model = SentenceTransformer("BAAI/bge-m3")  # 1024 维

#2. 缓存模型

python
import os

# 设置缓存目录
os.environ["HF_HOME"] = "/path/to/cache"
os.environ["TRANSFORMERS_CACHE"] = "/path/to/cache"

# 模型会自动缓存到该目录

#3. 离线使用

python
# 先下载模型
from huggingface_hub import snapshot_download
snapshot_download("BAAI/bge-small-zh-v1.5", local_dir="./models/bge")

# 离线加载
model = SentenceTransformer("./models/bge")

#下一步

Model Hub 指南 - 了解模型托管与协作平台
Transformers 库 - 核心库使用与代码示例
Inference API - 在线调用与部署模型

提示：Hugging Face 是 AI 开发的基础设施，掌握它可以让你快速使用各种开源模型。