AI大模型应用开发中使用HuggingFace进行Embedding的方案

原创已于 2025-10-09 21:31:26 修改 · 605 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #python #自然语言处理

于 2025-10-09 21:29:46 首次发布

方案一、使用HuggingFace镜像网站进行Embedding

HuggingFace由于官方网站huggingface.co访问受限，国内开发人员只能使用其在国内的镜像网站”https://hf-mirror.com“进行访问。Python程序中可以直接通过sentence-transformers或者Langchian对sentence-transformers进行二次封装的包使用HuggingFace的Embedding。但在实际应用中，Langchain的在线Embedding可以使用镜像网站；而sentence-transformers的在线Embedding，由于其内置模块会自动搜寻huggingface.co，无法直接使用镜像网站。所以如果要通过镜像网站使用HuggingFace的Embedding功能，只能通过Langchain方式调用API。

在线使用Langchain包中的Embedding功能时，Langchain的langchain-huggingface包需单独安装，不能仅靠安装 langchain 或 transformers 就自动包含它。安装方法：

pip install langchain-huggingface

在安装之前，可以先在pip配置文件中设置安装包的清华大学的镜像网站。

# 设置全局镜像源（推荐）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 之后直接安装即可（会自动走清华镜像），例如：

pip install langchain

安装之后检查安装包：

pip show langchain     # 输出应包含版本信息和安装路径

方案二、下载后，本地加载Huggingface模型进行Embedding

对国内开发者来说，最稳妥的方案，就是从镜像网站将Huggingface下载到本地，然后在本地加载Huggingface模型，在没有网络的环境下仍然可以使用，可作为企业私有化布署的首选方案。

下面重点介绍使用下载到本地的Huggingface进行Embedding的方法。

第一步：安装必要库（使用清华大学镜像网站安装）

pip install sentence-transformers huggingface_hub torch -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步：编写python程序，使用snapshot_download()从镜像网站下载模型

import os
from huggingface_hub import snapshot_download
from sentence_transformers import SentenceTransformer

# ✅ 必须提前设置环境变量（在 import 之前最好）
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 设置缓存目录
os.makedirs("./models", exist_ok=True)

# 要下载的模型名称
model_name = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
local_model_path = f"./models/{model_name.replace('/', '_')}"

print(f"正在从镜像站下载模型到: {local_model_path}")
print(f"镜像地址: https://hf-mirror.com/{model_name}")

# 使用 snapshot_download 主动从镜像下载
try:
    snapshot_download(
        repo_id=model_name,
        local_dir=local_model_path,
        local_dir_use_symlinks=False,  # 直接复制文件，避免软链接问题
        endpoint="https://hf-mirror.com",  # 显式指定镜像站点
        max_workers=3
    )
    print("✅ 模型下载完成！")
except Exception as e:
    print("❌ 下载失败:", str(e))
    raise

第三步：加载本地模型进行 embedding

from sentence_transformers import SentenceTransformer
import os

# 指定本地模型路径
model_path = "./models/st_paraphrase-multilingual-MiniLM-L12-v2"
model = SentenceTransformer(model_path)

# 测试 embedding
sentences = ["你好，世界！", "Hello, world!"]
embeddings = model.encode(sentences)

print("Embedding 向量示例：")
print(embeddings[0][:10])  # 打印前10维