纲要嵌入模型的核心作用将非结构化文本转化为高维向量坐标支撑语义相似度检索是 RAG 系统的基石LangChain 嵌入模型接口统一封装embed_documents与embed_query主流模型接入OpenAI、Ollama、BGE、智谱等嵌入缓存机制原理避免重复向量化降低 API 调用成本实现CacheBackedEmbeddings 本地文件存储国产嵌入模型集成以硅基流动平台的 BGE‑M3 为例配置代理地址与 API Key无缝切换完整可运行代码使用FakeEmbeddings演示嵌入、缓存与检索无需外部 API Key引言在 RAG 流水线中文档经过加载和切片之后必须被转换成一种机器可以理解的数学形式——向量。嵌入模型就是将文本映射为高维空间中的坐标使得语义相近的文本在空间中彼此靠近。LangChain 为这些模型提供了统一的调用方式并内置缓存来优化重复嵌入的性能与成本。本文将通过可运行的代码展示如何在 LangChain 中使用嵌入模型并接入国产模型。适用版本说明本文示例基于langchain-core0.1.x及langchain-community0.1.x。CacheBackedEmbeddings在langchain0.1.0中已稳定支持。嵌入模型的工作原理嵌入模型本质上是一个“翻译器”输入一句话如“今天天气怎么样”输出一个固定长度的数字数组向量。语义相近的句子生成的向量距离更近反之则更远。在 RAG 系统中嵌入模型承担两项任务入库将知识库中的文档片段逐一向量化存入向量数据库。检索将用户查询向量化在数据库中搜索距离最近的 Top‑K 个片段。文档 / 用户查询嵌入模型高维向量向量数据库存储 / 相似性搜索LangChain 中的嵌入模型实现所有嵌入模型都实现两个核心方法embed_documents(texts: List[str])批量嵌入文档。embed_query(text: str)嵌入单个查询。常用嵌入模型一览模型维度语言支持运行方式OpenAItext-embedding-ada-0021536多语言API 调用BGE‑M3BAAI1024多语言本地 / API智谱嵌入模型1024中文API 调用Ollama 托管的开源模型可配置取决于模型本地运行选型注意事项入库和检索必须使用同一个嵌入模型且向量数据库的维度需与模型一致。中文应用优先选择专门优化中文的模型混合语言场景则用多语言模型。非本地运行的嵌入模型按 token 计费合理使用缓存可大幅降低成本。缓存机制同一段文本通过同一嵌入模型得到的向量始终不变。LangChain 提供了CacheBackedEmbeddings可将向量缓存到本地文件或 Redis再次嵌入时直接读取避免重复计算。完整可运行代码以下代码使用FakeEmbeddings模拟嵌入过程并演示缓存的效果。无需任何 API Key可直接在本地运行。安装依赖pipinstalllangchain langchain-core langchain-community chromadb核心代码fromlangchain_community.embeddings.fakeimportFakeEmbeddingsfromlangchain_community.vectorstoresimportChromafromlangchain_core.documentsimportDocumentfromlangchain.embeddingsimportCacheBackedEmbeddingsfromlangchain.storageimportLocalFileStoreimporttime# 1. 准备文档docs[Document(page_content智能温控水杯支持手机 App 远程控温。),Document(page_content产品续航 48 小时采用 316 不锈钢内胆。),Document(page_content充电时请使用 5V/2A 适配器。),]base_embeddingsFakeEmbeddings(size128)# 2. 无缓存嵌入starttime.time()vectorstore_no_cacheChroma.from_documents(docs,base_embeddings,collection_nameno_cache)print(f无缓存嵌入耗时{time.time()-start:.4f}秒)# 3. 带缓存嵌入storeLocalFileStore(./embedding_cache/)cached_embeddingsCacheBackedEmbeddings.from_bytes_store(base_embeddings,store,namespacetest)starttime.time()vectorstore_cachedChroma.from_documents(docs,cached_embeddings,collection_namecached)print(f首次嵌入填充缓存耗时{time.time()-start:.4f}秒)# 4. 再次嵌入相同文档命中缓存starttime.time()vectorstore_cached2Chroma.from_documents(docs,cached_embeddings,collection_namecached2)print(f再次嵌入命中缓存耗时{time.time()-start:.4f}秒)# 5. 检索测试query如何给水杯充电vectorstoreChroma.from_documents(docs,cached_embeddings)resultvectorstore.similarity_search(query,k1)print(f检索结果{result[0].page_content})运行后可以观察到第二次嵌入的耗时显著减少验证了缓存机制的效果。注意CacheBackedEmbeddings.from_bytes_store在langchain0.1.0中可用。若使用更早版本请参考官方文档的迁移指南。国产嵌入模型集成示例以硅基流动平台的 BGE‑M3 为例它完全兼容 OpenAI 的 API 格式只需修改模型名、API Key 和 Base URL 即可接入。fromlangchain_openaiimportOpenAIEmbeddings embeddingsOpenAIEmbeddings(modelBAAI/bge-m3,openai_api_keyyour_api_key,# 替换为实际 Keyopenai_api_basehttps://api.siliconflow.cn/v1# 平台代理地址)vectorsembeddings.embed_documents([智能温控水杯,明天天气])print(f向量维度{len(vectors[0])})# 输出 1024版本兼容提示langchain-openai包在v0.1.0之后支持openai_api_base参数。若使用langchain0.3.0推荐使用base_url替代openai_api_base两者在过渡期均有效。API 速览本节汇总博客中涉及的核心 APIAPI所属库方法签名说明FakeEmbeddingslangchain_community.embeddings.fake__init__(size: int)生成指定维度的随机向量用于测试CacheBackedEmbeddingslangchain.embeddingsfrom_bytes_store(underlying_embeddings, document_embedding_store, namespace)包装嵌入模型提供缓存能力LocalFileStorelangchain.storage__init__(root_path: str)本地文件系统存储用于缓存持久化Chromalangchain_community.vectorstoresfrom_documents(documents, embedding, collection_name)从文档列表创建向量数据库OpenAIEmbeddingslangchain_openai__init__(model, openai_api_key, openai_api_base)调用 OpenAI 兼容接口的嵌入模型Demo 示例以下是一个完整的、可直接运行的 HTML 文件使用 Python 后端演示了嵌入、缓存与检索的完整流程。运行说明将上述核心代码保存为embedding_demo.py。在终端执行python embedding_demo.py。观察控制台输出的耗时对比和检索结果。代码说明使用FakeEmbeddings模拟嵌入无需真实 API Key。通过CacheBackedEmbeddings实现缓存第二次嵌入耗时明显降低。使用Chroma向量数据库进行相似性检索验证嵌入质量。技术点总结LangChain 统一的嵌入接口设计。缓存机制的原理与实现方式。向量数据库的创建与检索流程。参考文档官方文档LangChain Embeddings 概念文档LangChain CacheBackedEmbeddings API 参考LangChain Chroma 向量存储文档OpenAI Embeddings API 参考参考链接硅基流动平台 API 文档BGE‑M3 模型页面 (HuggingFace)Ollama 嵌入模型支持总结嵌入模型是连接文本与向量计算的桥梁也是 RAG 检索质量的决定性因素之一。LangChain 通过embed_documents和embed_query两个方法统一了调用接口配合缓存机制可有效控制成本。无论是使用 OpenAI 还是国产 BGE 系列掌握好嵌入模型的选型和接入方式就能为 RAG 应用打下坚实基础。