LlamaIndex 本地密集向量嵌入实战FastEmbedEmbedding 集成指南与源码解析【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文围绕 LlamaIndex 官方 API 参考中 embeddings/fastembed.md 所记录的llama_index.embeddings.fastembed.FastEmbedEmbedding展开讲解如何在 LlamaIndex 索引与检索流程中接入 Qdrant FastEmbed以本地 ONNX 推理方式生成文本嵌入向量。读完本文你将掌握该集成包的安装方式、全部构造参数与默认值、文档/查询双路编码与异步调用能力并能基于源码理解其底层实现、测试保障及常见问题排查方法。1. FastEmbedEmbedding 在 LlamaIndex 中的定位FastEmbed 是 Qdrant 开源的一个轻量、快速的 Python 嵌入生成库基于 ONNX Runtime 做本地推理。FastEmbedEmbedding是 LlamaIndex 官方对它的适配器其完整实现位于 base.py以独立的llama-index-embeddings-fastembed包分发当前仓库中版本为0.6.0见 pyproject.toml。它在 LlamaIndex 中承担的是**密集向量dense embedding**生成职责与同样基于 FastEmbed 的稀疏向量集成对应 sparse_embeddings/fastembed.md互相独立一个面向语义稠密表示一个面向BM25式稀疏加权表示。从类继承关系看见下方源码与测试FastEmbedEmbedding直接继承自核心库的BaseEmbedding定义于 llama-index-core 的 base.py因此能无缝接入 LlamaIndex 的索引构建、检索器与查询引擎体系。由于推理完全在本地发生模型下载完成后不再依赖任何远程 API非常适合追求低延迟、低成本或数据不出内网的 RAG 场景。2. 安装与引入集成包本身只声明对llama-index-core的依赖真正的推理库fastembed需要在运行时按需安装源码在导入时才做检查详见第 4 节。安装方式# 1. 安装 LlamaIndex 的 FastEmbed 集成包 pip install llama-index-embeddings-fastembed # 2. 安装推理后端CPU 版 pip install fastembed # 3. 若需 GPU 加速安装 GPU 版源码中的导入提示即推荐此方式 pip install fastembed-gpu安装后通过如下方式导入并实例化代码与仓库中的示例笔记本 fastembed.ipynb 保持一致from llama_index.embeddings.fastembed import FastEmbedEmbedding embed_model FastEmbedEmbedding(model_nameBAAI/bge-small-en-v1.5)包的导出结构非常精简init.py 仅公开FastEmbedEmbedding一个符号from llama_index.embeddings.fastembed.base import FastEmbedEmbedding __all__ [FastEmbedEmbedding]环境约束提示从 pyproject.toml 看该包声明requires-python 3.10,3.13并要求llama-index-core0.13.0,0.15开发依赖中锁定fastembed0.2.2可作为选型版本下限的参考。3. 构造参数全解析字段与默认值FastEmbedEmbedding的所有核心字段在 base.py 中通过 pydanticField声明下面对照源码逐项说明参数类型默认值说明model_namestrBAAI/bge-small-en-v1.5使用的 FastEmbed 模型名称。可在构造时显式更换具体可选模型清单以 FastEmbed 项目维护的“Supported Models”列表为准cache_dirOptional[str]None模型缓存目录为None时使用系统临时目录下的fastembed_cachethreadsOptional[int]None单个 onnxruntime session 可使用的线程数默认交由运行时决定doc_embed_typeLiteral[default, passage]default文档编码方式default调用普通embedpassage调用passage_embed详见第 5 节providersOptional[List[str]]None指定 ONNX 执行提供者如[CUDAExecutionProvider]默认使用 ONNX Runtime 可用提供者此外__init__接收**kwargs并透传给父类super().__init__(...)与底层TextEmbedding(...)见 base.py这意味着所有BaseEmbedding标准字段都可以直接在构造时传入其中最有实操价值的是embed_batch_size批处理大小核心库默认值为10见 constants.py 的DEFAULT_EMBED_BATCH_SIZE取值范围为1 size 2048定义于 BaseEmbeddingnum_workers异步批量编码时的并发 worker 数None表示自动embeddings_cache可选的结果缓存可传入带put/get接口的缓存实现。一个配置了批大小与 passage 编码模式的典型实例embed_model FastEmbedEmbedding( model_nameBAAI/bge-small-en-v1.5, embed_batch_size24, # 覆盖核心库默认的 10 doc_embed_typepassage, # 对文档使用 passage_embed cache_dir/opt/models/fastembed_cache, )class_name()方法固定返回FastEmbedEmbeddingbase.py这在 LlamaIndex 的序列化、调试与可观测性场景中用于标识模型类型。4. 懒加载机制初始化时做了什么FastEmbedEmbedding.__init__的一个关键设计是推迟导入并立即构建底层模型。源码base.py先尝试from fastembed import TextEmbeddingtry: from fastembed import TextEmbedding except ImportError as e: raise ImportError( Could not import FastEmbed. Please install it with pip install fastembed or pip install fastembed-gpu for GPU support ) from e self._model TextEmbedding( model_namemodel_name, cache_dircache_dir, threadsthreads, providersproviders, **kwargs, )这段代码带来的两个可观察行为缺失依赖时快速失败若只装了集成包而没装fastembed构造对象就会抛出带明确修复提示的ImportError而不是拖到真正编码时才报错。模型下载/缓存发生在构造阶段首次指定一个未缓存的模型名时TextEmbedding构造会触发模型文件下载之后复用cache_dir缓存默认落在系统临时目录的fastembed_cache所以首次实例化通常比后续慢。另外注意_model被声明为 pydanticPrivateAttrbase.py不会参与字段序列化model_config中开启了arbitrary_types_allowedTrue以允许持有非 pydantic 类型的运行时对象。5. 文本编码 API文档编码与查询编码的分工FastEmbed 对「文档」与「查询」采用不同的编码入口FastEmbedEmbedding将这层差异封装为四个受保护方法base.py方法底层调用语义_get_text_embedding(text)_get_text_embeddings([text])[0]单条文本向量_get_text_embeddings(texts)doc_embed_typepassage时走passage_embed否则走embed批量文档向量_get_query_embedding(query)_model.query_embed(query)查询向量始终用 query 专用入口从源码可见对文档/文本走的是embed/passage_embed由doc_embed_type决定对查询则固定使用query_embed。FastEmbed 中passage与query分开编码本质上服务的是非对称检索场景长文档 vs 短查询如果你用较短、与查询风格相近的文本作为被检索内容保持默认doc_embed_typedefault即可。上述方法最终都会把底层numpy.ndarray转换为float列表embedding.tolist()对齐 LlamaIndex 的Embedding List[float]类型约定见 BaseEmbedding。对外使用者一般直接调用BaseEmbedding提供的公开方法。例如仓库示例笔记本中的用法embeddings embed_model.get_text_embedding(Some text to embed.) print(len(embeddings)) # 向量维度 print(embeddings[:5]) # 前几维数值批量场景推荐get_text_embedding_batch([文本 A, 文本 B, ...])会自动按embed_batch_size分片并复用底层 session。6. 异步调用与并发FastEmbedEmbedding同时提供异步 API。四个_get_*/_aget_*方法中异步版本统一借助asyncio.to_thread把 CPU 密集的同步推理抛到线程池执行base.py从而避免阻塞事件循环import asyncio async def main(): vecs await embed_model.aget_text_embedding_batch([hello, world]) return vecs asyncio.run(main())由于推理本身是本地 CPU/GPU 计算异步收益主要在于「等待期间不阻塞其他协程」若需要更高并发吞吐可结合num_workers参数使用核心库内部的并发调度。7. 接入 Settings 与索引构建的完整用例在 LlamaIndex 新版 API 中推荐通过全局Settings注入 embedding 模型让索引、检索器与查询引擎自动复用from llama_index.core import Settings, VectorStoreIndex from llama_index.core.node_parser import SentenceSplitter from llama_index.embeddings.fastembed import FastEmbedEmbedding # 1) 配置全局嵌入模型 Settings.embed_model FastEmbedEmbedding( model_nameBAAI/bge-small-en-v1.5, embed_batch_size32, doc_embed_typepassage, ) Settings.node_parser SentenceSplitter(chunk_size512, chunk_overlap20) # 2) 构建向量索引内部会自动调用嵌入模型 documents [ LlamaIndex 是一个面向 LLM 应用的数据框架。, FastEmbed 基于 ONNX Runtime 在本地生成嵌入向量。, ] index VectorStoreIndex.from_documents(documents) # 3) 查询自动使用 query_embed 对查询编码 query_engine index.as_query_engine() response query_engine.query(FastEmbed 的推理基于什么运行时) print(response)若配合外部向量库如 Qdrant、Pinecone只需将index替换为对应VectorStoreIndex构造即可嵌入模型保持同一配置。8. 测试用例如何验证契约集成包的测试位于 tests/test_embeddings_fastembed.py共两个用例揭示了实现的两个契约patch(fastembed.TextEmbedding) def test_create_fastembed_embedding(mock_text_embedding): cache Path(./test_cache_2) fastembed_embedding FastEmbedEmbedding( cache_dirstr(cache), embed_batch_size24, doc_embed_typepassage, ) assert fastembed_embedding.cache_dir str(cache) assert fastembed_embedding.embed_batch_size 24 assert fastembed_embedding.doc_embed_type passage assert mock_text_embedding.call_args.kwargs[cache_dir] str(cache) assert mock_text_embedding.call_args.kwargs[threads] is None assert mock_text_embedding.call_args.kwargs[providers] is Nonetest_class断言FastEmbedEmbedding.__mro__中包含BaseEmbedding保证它遵循 LlamaIndex 统一嵌入接口test_create_fastembed_embedding通过 mockTextEmbedding验证自定义字段cache_dir、embed_batch_size、doc_embed_type会被正确保存同时cache_dir会原样透传给底层TextEmbedding而threads、providers在未显式指定时为None。这说明「集成包负责适配接口、fastembed 负责真实推理」的边界也便于你验证自己传参是否正确。9. 常见问题与排查建议ImportError: Could not import FastEmbed未安装推理后端。按第 2 节执行pip install fastembedCPU或pip install fastembed-gpuGPU后重试。首次实例化很慢 / 卡在下载构造阶段会下载并缓存模型权重属正常现象。将cache_dir指向持久化目录如/opt/models/fastembed_cache可避免每次重复下载也方便离线复用。查询结果不理想检查文档与查询是否使用了匹配的编码通道。默认配置下文档走embed、查询走query_embed二者在 FastEmbed 的“查询/文档”联合训练语义下协同如果你手动把所有内容都当成查询风格处理可考虑调整doc_embed_type并复测。CPU 推理慢可通过threads增大单个 ONNX session 线程数或安装 GPU 后端并在providers中显式声明[CUDAExecutionProvider]。嵌入结果与向量库维度不匹配更换model_name会改变输出维度需确保向量库的 collection/索引 schema 与模型维度一致不要在已有索引中途切换不同维度的模型。结语FastEmbedEmbedding是 LlamaIndex 体系中「去 API 依赖、纯本地嵌入」的代表性集成构造参数透明、文档与查询编码分工清晰、同步与异步 API 齐备并通过继承BaseEmbedding无缝融入索引与检索全链路。其完整源码与配套 API 参考位于 llama-index-embeddings-fastembed 集成目录类定义见 base.py官方 API 文档入口为 embeddings/fastembed.md配合 fastembed.ipynb 示例可以快速上手并落地到实际 RAG 项目中。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LlamaIndex 本地密集向量嵌入实战：FastEmbedEmbedding 集成指南与源码解析
LlamaIndex 本地密集向量嵌入实战FastEmbedEmbedding 集成指南与源码解析【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本文围绕 LlamaIndex 官方 API 参考中 embeddings/fastembed.md 所记录的llama_index.embeddings.fastembed.FastEmbedEmbedding展开讲解如何在 LlamaIndex 索引与检索流程中接入 Qdrant FastEmbed以本地 ONNX 推理方式生成文本嵌入向量。读完本文你将掌握该集成包的安装方式、全部构造参数与默认值、文档/查询双路编码与异步调用能力并能基于源码理解其底层实现、测试保障及常见问题排查方法。1. FastEmbedEmbedding 在 LlamaIndex 中的定位FastEmbed 是 Qdrant 开源的一个轻量、快速的 Python 嵌入生成库基于 ONNX Runtime 做本地推理。FastEmbedEmbedding是 LlamaIndex 官方对它的适配器其完整实现位于 base.py以独立的llama-index-embeddings-fastembed包分发当前仓库中版本为0.6.0见 pyproject.toml。它在 LlamaIndex 中承担的是**密集向量dense embedding**生成职责与同样基于 FastEmbed 的稀疏向量集成对应 sparse_embeddings/fastembed.md互相独立一个面向语义稠密表示一个面向BM25式稀疏加权表示。从类继承关系看见下方源码与测试FastEmbedEmbedding直接继承自核心库的BaseEmbedding定义于 llama-index-core 的 base.py因此能无缝接入 LlamaIndex 的索引构建、检索器与查询引擎体系。由于推理完全在本地发生模型下载完成后不再依赖任何远程 API非常适合追求低延迟、低成本或数据不出内网的 RAG 场景。2. 安装与引入集成包本身只声明对llama-index-core的依赖真正的推理库fastembed需要在运行时按需安装源码在导入时才做检查详见第 4 节。安装方式# 1. 安装 LlamaIndex 的 FastEmbed 集成包 pip install llama-index-embeddings-fastembed # 2. 安装推理后端CPU 版 pip install fastembed # 3. 若需 GPU 加速安装 GPU 版源码中的导入提示即推荐此方式 pip install fastembed-gpu安装后通过如下方式导入并实例化代码与仓库中的示例笔记本 fastembed.ipynb 保持一致from llama_index.embeddings.fastembed import FastEmbedEmbedding embed_model FastEmbedEmbedding(model_nameBAAI/bge-small-en-v1.5)包的导出结构非常精简init.py 仅公开FastEmbedEmbedding一个符号from llama_index.embeddings.fastembed.base import FastEmbedEmbedding __all__ [FastEmbedEmbedding]环境约束提示从 pyproject.toml 看该包声明requires-python 3.10,3.13并要求llama-index-core0.13.0,0.15开发依赖中锁定fastembed0.2.2可作为选型版本下限的参考。3. 构造参数全解析字段与默认值FastEmbedEmbedding的所有核心字段在 base.py 中通过 pydanticField声明下面对照源码逐项说明参数类型默认值说明model_namestrBAAI/bge-small-en-v1.5使用的 FastEmbed 模型名称。可在构造时显式更换具体可选模型清单以 FastEmbed 项目维护的“Supported Models”列表为准cache_dirOptional[str]None模型缓存目录为None时使用系统临时目录下的fastembed_cachethreadsOptional[int]None单个 onnxruntime session 可使用的线程数默认交由运行时决定doc_embed_typeLiteral[default, passage]default文档编码方式default调用普通embedpassage调用passage_embed详见第 5 节providersOptional[List[str]]None指定 ONNX 执行提供者如[CUDAExecutionProvider]默认使用 ONNX Runtime 可用提供者此外__init__接收**kwargs并透传给父类super().__init__(...)与底层TextEmbedding(...)见 base.py这意味着所有BaseEmbedding标准字段都可以直接在构造时传入其中最有实操价值的是embed_batch_size批处理大小核心库默认值为10见 constants.py 的DEFAULT_EMBED_BATCH_SIZE取值范围为1 size 2048定义于 BaseEmbeddingnum_workers异步批量编码时的并发 worker 数None表示自动embeddings_cache可选的结果缓存可传入带put/get接口的缓存实现。一个配置了批大小与 passage 编码模式的典型实例embed_model FastEmbedEmbedding( model_nameBAAI/bge-small-en-v1.5, embed_batch_size24, # 覆盖核心库默认的 10 doc_embed_typepassage, # 对文档使用 passage_embed cache_dir/opt/models/fastembed_cache, )class_name()方法固定返回FastEmbedEmbeddingbase.py这在 LlamaIndex 的序列化、调试与可观测性场景中用于标识模型类型。4. 懒加载机制初始化时做了什么FastEmbedEmbedding.__init__的一个关键设计是推迟导入并立即构建底层模型。源码base.py先尝试from fastembed import TextEmbeddingtry: from fastembed import TextEmbedding except ImportError as e: raise ImportError( Could not import FastEmbed. Please install it with pip install fastembed or pip install fastembed-gpu for GPU support ) from e self._model TextEmbedding( model_namemodel_name, cache_dircache_dir, threadsthreads, providersproviders, **kwargs, )这段代码带来的两个可观察行为缺失依赖时快速失败若只装了集成包而没装fastembed构造对象就会抛出带明确修复提示的ImportError而不是拖到真正编码时才报错。模型下载/缓存发生在构造阶段首次指定一个未缓存的模型名时TextEmbedding构造会触发模型文件下载之后复用cache_dir缓存默认落在系统临时目录的fastembed_cache所以首次实例化通常比后续慢。另外注意_model被声明为 pydanticPrivateAttrbase.py不会参与字段序列化model_config中开启了arbitrary_types_allowedTrue以允许持有非 pydantic 类型的运行时对象。5. 文本编码 API文档编码与查询编码的分工FastEmbed 对「文档」与「查询」采用不同的编码入口FastEmbedEmbedding将这层差异封装为四个受保护方法base.py方法底层调用语义_get_text_embedding(text)_get_text_embeddings([text])[0]单条文本向量_get_text_embeddings(texts)doc_embed_typepassage时走passage_embed否则走embed批量文档向量_get_query_embedding(query)_model.query_embed(query)查询向量始终用 query 专用入口从源码可见对文档/文本走的是embed/passage_embed由doc_embed_type决定对查询则固定使用query_embed。FastEmbed 中passage与query分开编码本质上服务的是非对称检索场景长文档 vs 短查询如果你用较短、与查询风格相近的文本作为被检索内容保持默认doc_embed_typedefault即可。上述方法最终都会把底层numpy.ndarray转换为float列表embedding.tolist()对齐 LlamaIndex 的Embedding List[float]类型约定见 BaseEmbedding。对外使用者一般直接调用BaseEmbedding提供的公开方法。例如仓库示例笔记本中的用法embeddings embed_model.get_text_embedding(Some text to embed.) print(len(embeddings)) # 向量维度 print(embeddings[:5]) # 前几维数值批量场景推荐get_text_embedding_batch([文本 A, 文本 B, ...])会自动按embed_batch_size分片并复用底层 session。6. 异步调用与并发FastEmbedEmbedding同时提供异步 API。四个_get_*/_aget_*方法中异步版本统一借助asyncio.to_thread把 CPU 密集的同步推理抛到线程池执行base.py从而避免阻塞事件循环import asyncio async def main(): vecs await embed_model.aget_text_embedding_batch([hello, world]) return vecs asyncio.run(main())由于推理本身是本地 CPU/GPU 计算异步收益主要在于「等待期间不阻塞其他协程」若需要更高并发吞吐可结合num_workers参数使用核心库内部的并发调度。7. 接入 Settings 与索引构建的完整用例在 LlamaIndex 新版 API 中推荐通过全局Settings注入 embedding 模型让索引、检索器与查询引擎自动复用from llama_index.core import Settings, VectorStoreIndex from llama_index.core.node_parser import SentenceSplitter from llama_index.embeddings.fastembed import FastEmbedEmbedding # 1) 配置全局嵌入模型 Settings.embed_model FastEmbedEmbedding( model_nameBAAI/bge-small-en-v1.5, embed_batch_size32, doc_embed_typepassage, ) Settings.node_parser SentenceSplitter(chunk_size512, chunk_overlap20) # 2) 构建向量索引内部会自动调用嵌入模型 documents [ LlamaIndex 是一个面向 LLM 应用的数据框架。, FastEmbed 基于 ONNX Runtime 在本地生成嵌入向量。, ] index VectorStoreIndex.from_documents(documents) # 3) 查询自动使用 query_embed 对查询编码 query_engine index.as_query_engine() response query_engine.query(FastEmbed 的推理基于什么运行时) print(response)若配合外部向量库如 Qdrant、Pinecone只需将index替换为对应VectorStoreIndex构造即可嵌入模型保持同一配置。8. 测试用例如何验证契约集成包的测试位于 tests/test_embeddings_fastembed.py共两个用例揭示了实现的两个契约patch(fastembed.TextEmbedding) def test_create_fastembed_embedding(mock_text_embedding): cache Path(./test_cache_2) fastembed_embedding FastEmbedEmbedding( cache_dirstr(cache), embed_batch_size24, doc_embed_typepassage, ) assert fastembed_embedding.cache_dir str(cache) assert fastembed_embedding.embed_batch_size 24 assert fastembed_embedding.doc_embed_type passage assert mock_text_embedding.call_args.kwargs[cache_dir] str(cache) assert mock_text_embedding.call_args.kwargs[threads] is None assert mock_text_embedding.call_args.kwargs[providers] is Nonetest_class断言FastEmbedEmbedding.__mro__中包含BaseEmbedding保证它遵循 LlamaIndex 统一嵌入接口test_create_fastembed_embedding通过 mockTextEmbedding验证自定义字段cache_dir、embed_batch_size、doc_embed_type会被正确保存同时cache_dir会原样透传给底层TextEmbedding而threads、providers在未显式指定时为None。这说明「集成包负责适配接口、fastembed 负责真实推理」的边界也便于你验证自己传参是否正确。9. 常见问题与排查建议ImportError: Could not import FastEmbed未安装推理后端。按第 2 节执行pip install fastembedCPU或pip install fastembed-gpuGPU后重试。首次实例化很慢 / 卡在下载构造阶段会下载并缓存模型权重属正常现象。将cache_dir指向持久化目录如/opt/models/fastembed_cache可避免每次重复下载也方便离线复用。查询结果不理想检查文档与查询是否使用了匹配的编码通道。默认配置下文档走embed、查询走query_embed二者在 FastEmbed 的“查询/文档”联合训练语义下协同如果你手动把所有内容都当成查询风格处理可考虑调整doc_embed_type并复测。CPU 推理慢可通过threads增大单个 ONNX session 线程数或安装 GPU 后端并在providers中显式声明[CUDAExecutionProvider]。嵌入结果与向量库维度不匹配更换model_name会改变输出维度需确保向量库的 collection/索引 schema 与模型维度一致不要在已有索引中途切换不同维度的模型。结语FastEmbedEmbedding是 LlamaIndex 体系中「去 API 依赖、纯本地嵌入」的代表性集成构造参数透明、文档与查询编码分工清晰、同步与异步 API 齐备并通过继承BaseEmbedding无缝融入索引与检索全链路。其完整源码与配套 API 参考位于 llama-index-embeddings-fastembed 集成目录类定义见 base.py官方 API 文档入口为 embeddings/fastembed.md配合 fastembed.ipynb 示例可以快速上手并落地到实际 RAG 项目中。【免费下载链接】llama_indexLlamaIndex is the leading document agent and OCR platform项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考