AI RunnablePassThrough问题与解决方法

时间：2026-07-23 15:53

先直接给出结论：您之前使用的那个 HuggingFacePipelineEmbeddings 在官方稳定版 langchain-huggingface 中根本不存在——这正是导入失败的真正原因。这个错误责任在我，确实是我之前提供了错误的名称，深表歉意。在 langchain-huggingface

先直接给出结论：您之前使用的那个 HuggingFacePipelineEmbeddings 在官方稳定版 langchain-huggingface 中根本不存在——这正是导入失败的真正原因。这个错误责任在我，确实是我之前提供了错误的名称，深表歉意。

在 langchain-huggingface 的正式版本中，本地可用的 Embedding 类实际上只有两个：

HuggingFaceEmbeddings —— 唯一的本地嵌入类，必须依赖 sentence-transformers
HuggingFaceEndpointEmbeddings —— 调用远程推理接口，本地无法运行 BGE 这类模型

当前局面总结

如果想通过 langchain_huggingface 在本地加载 BGE 模型 → 只能使用 HuggingFaceEmbeddings
HuggingFaceEmbeddings 强制要求安装 sentence-transformers
新版 sentence-transformers 搭配 transformers>=4.51 存在官方兼容性 Bug

也就是说，如果您坚持使用 langchain_huggingface 这条路径，就绕不开版本兼容性问题。不过请放心，下面两条方案都基于纯 LangChain 生态，无需手写原生 transformers 代码，可以直接使用。

方案 A｜锁定兼容版本组合（继续使用 HuggingFaceEmbeddings，推荐用于教学演示）

激活您的 rag_env 环境，然后执行以下锁定版本命令，将 transformers 和 sentence-transformers 降级到官方确认兼容的版本：

pip install transformers==4.46.3 sentence-transformers==3.2.1 --force-reinstall

安装完成后，您原来的代码就能直接运行成功：

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
os.environ["HF_HOME"] = r"D:\huggingface_cache"

from langchain_huggingface import HuggingFaceEmbeddings

embedding_model = HuggingFaceEmbeddings(
    model_name="BAAI/bge-small-zh-v1.5",
    model_kwargs={"device": "cpu"},
    encode_kwargs={"normalize_embeddings": True},
)

text = "订单未发货时，用户可以直接申请退款。"
vector = embedding_model.embed_query(text)
print(type(vector))
print(f"向量维度：{len(vector)}")
print(vector[:10])

方案 B｜更换 LangChain 官方替代包 FastEmbedEmbeddings（彻底绕过 sentence-transformers）

如果您不想折腾版本兼容问题，还有一条更干净的路径：不使用 langchain_huggingface，转而采用社区支持的 FastEmbed。它同样是 LangChain 标准组件，不依赖 sentence-transformers，也不受 transformers 版本影响。

pip install fastembed langchain-community

完整代码示例如下：

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
os.environ["HF_HOME"] = r"D:\huggingface_cache"

from langchain_community.embeddings import FastEmbedEmbeddings

embedding_model = FastEmbedEmbeddings(model_name="BAAI/bge-small-zh-v1.5")

text = "订单未发货时，用户可以直接申请退款。"
vector = embedding_model.embed_query(text)
print(type(vector))
print(f"向量维度：{len(vector)}")
print(vector[:10])

✅ 接口完全一致，后续接入 Chroma 向量库的代码无需修改。