如何强制LangChain使用HF_HOME环境变量加载本地模型而非联网下载

问题背景 #

已将Snowflake/snowflake-arctic-embed-l模型下载到$HF_HOME/Snowflake/snowflake-arctic-embed-l目录，Python运行时能识别HF_HOME环境变量，但使用LangChain的SentenceTransformersTokenTextSplitter指定模型名时，程序仍尝试从网络下载模型，仅指定绝对路径可正常加载。

解决方案 #

1. 升级sentence-transformers版本 #

当前环境中sentence-transformers版本（3.0.0）与模型创建版本（3.4.1）不兼容，旧版本可能存在HF_HOME路径解析问题，先升级依赖：

pip install --upgrade sentence-transformers

2. 方式一：通过model_kwargs传递缓存路径 #

利用SentenceTransformersTokenTextSplitter的model_kwargs参数，将HF_HOME作为缓存目录传递给底层模型初始化逻辑：

import os
from langchain.text_splitter import SentenceTransformersTokenTextSplitter

splitter = SentenceTransformersTokenTextSplitter(
    model_name="Snowflake/snowflake-arctic-embed-l",
    tokens_per_chunk=500,
    chunk_overlap=50,
    model_kwargs={"cache_folder": os.getenv("HF_HOME")}
)

3. 方式二：设置SENTENCE_TRANSFORMERS_HOME环境变量 #

sentence-transformers库默认使用SENTENCE_TRANSFORMERS_HOME作为缓存目录，将其指向HF_HOME即可让库自动读取本地模型：

终端中设置（运行脚本前）

export SENTENCE_TRANSFORMERS_HOME=$HF_HOME

Python代码中设置（脚本开头）

import os
os.environ["SENTENCE_TRANSFORMERS_HOME"] = os.getenv("HF_HOME")

from langchain.text_splitter import SentenceTransformersTokenTextSplitter
splitter = SentenceTransformersTokenTextSplitter(
    model_name="Snowflake/snowflake-arctic-embed-l",
    tokens_per_chunk=500,
    chunk_overlap=50
)

4. 方式三：拼接HF_HOME与模型路径（最直接） #

直接通过HF_HOME构造模型的本地绝对路径，无需依赖库的缓存解析：

import os
from langchain.text_splitter import SentenceTransformersTokenTextSplitter

model_path = os.path.join(os.getenv("HF_HOME"), "Snowflake", "snowflake-arctic-embed-l")
splitter = SentenceTransformersTokenTextSplitter(
    model_name=model_path,
    tokens_per_chunk=500,
    chunk_overlap=50
)

内容的提问来源于stack exchange，提问作者mon