LlamaIndex 本地嵌入实战:使用 OllamaEmbedding 在 Ollama 上生成文本向量
LlamaIndex 本地嵌入实战:使用 OllamaEmbedding 在 Ollama 上生成文本向量
导读
本篇文章聚焦 LlamaIndex 官方集成包 llama-index-embeddings-ollama 中的核心类 OllamaEmbedding,完整讲解如何在本地或远程 Ollama 服务上生成文本/查询向量,并将其无缝接入 LlamaIndex 的向量索引、检索与查询引擎。读完本文,你将掌握该集成包的安装与模型准备、全部构造参数的含义与默认值、单条与批量嵌入、指令(instruction)前缀优化、异步调用,以及底层调用链与测试验证方式,可直接把本地私有的向量化能力落地到自己的 RAG 应用中。
一、集成包与源码位置
OllamaEmbedding 位于仓库的 llama-index-integrations/embeddings/llama-index-embeddings-ollama 目录,其实现文件为 llama_index/embeddings/ollama/base.py,对外导出入口在 llama_index/embeddings/ollama/init.py,官方说明文档为 README.md。集成包依赖 ollama>=0.3.1 与 llama-index-core>=0.13.0,<0.15(见 pyproject.toml),要求 Python >=3.10,<4.0。
在类继承关系上,OllamaEmbedding 继承自 llama_index.core.base.embeddings.base.BaseEmbedding,这意味着它天然获得 LlamaIndex 嵌入模型体系中的缓存、限流、回调与进度条等通用能力,本文后续会结合源码展开说明。
二、环境准备:安装与模型拉取
1. 安装 Python 集成包
pip install llama-index-embeddings-ollama
2. 安装并启动 Ollama
使用本集成前,需要在机器上安装并运行 Ollama 服务,默认监听地址为 http://localhost:11434。可执行 ollama serve 或通过系统服务方式启动。
3. 拉取嵌入模型
Ollama 上常用的嵌入模型包括:
nomic-embed-text:通用型嵌入模型,体积小、速度快;embeddinggemma:基于 Google Gemma 的嵌入模型,官方示例笔记本默认使用该模型;mxbai-embed-large:更大规模的嵌入模型,适合对质量要求更高的场景。
ollama pull nomic-embed-text
# 或
ollama pull embeddinggemma
拉取完成后可用 ollama list 确认模型已就绪。
三、基本用法:单条与批量向量生成
1. 初始化嵌入模型
from llama_index.embeddings.ollama import OllamaEmbedding
embed_model = OllamaEmbedding(
model_name="nomic-embed-text", # 或 "embeddinggemma"
base_url="http://localhost:11434", # 默认 Ollama 地址,可省略
)
2. 生成单个文本向量与查询向量
# 文本向量(用于文档内容)
text_embedding = embed_model.get_text_embedding("Hello, world!")
print(f"Embedding dimension: {len(text_embedding)}")
# 查询向量(用于检索时的问题)
query_embedding = embed_model.get_query_embedding("What is AI?")
3. 批量生成文本向量
texts = [
"The capital of France is Paris.",
"Python is a programming language.",
"Machine learning is a subset of AI.",
]
embeddings = embed_model.get_text_embeddings(texts)
print(f"Generated {len(embeddings)} embeddings")
此外,BaseEmbedding 还提供了带批处理逻辑的 get_text_embedding_batch(texts, show_progress=False) 方法,内部按 embed_batch_size 分块调用,并支持 show_progress=True 显示进度条。仓库中的示例笔记本 docs/examples/embeddings/ollama_embedding.ipynb 演示了 get_text_embedding_batch、get_text_embedding、get_query_embedding 三种方法,输出向量维度为 768(对应 embeddinggemma 模型)。
四、构造参数详解(含默认值与底层实现)
OllamaEmbedding 的构造签名与字段定义可在 base.py 中查看,完整参数如下:
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
model_name |
必填 | 无 | Ollama 嵌入模型名称,如 "nomic-embed-text"、"embeddinggemma" |
base_url |
可选 | "http://localhost:11434" |
Ollama 服务地址,远程部署时需修改 |
embed_batch_size |
可选 | 10 |
每次嵌入调用的批大小,字段校验 gt=0、le=2048 |
ollama_additional_kwargs |
可选 | {} |
透传给 Ollama API 的额外参数(如 mirostat 等推理选项) |
query_instruction |
可选 | None |
嵌入查询前自动拼接的指令前缀 |
text_instruction |
可选 | None |
嵌入文本前自动拼接的指令前缀 |
keep_alive |
可选 | "5m" |
请求后模型在内存中驻留的时长,支持时长字符串或秒数 |
client_kwargs |
可选 | {} |
传给 ollama.Client/AsyncClient 的额外关键字参数(如认证头) |
callback_manager |
可选 | None |
LlamaIndex 回调管理器,用于埋点与观测 |
其中 embed_batch_size 的默认值来自核心常量 DEFAULT_EMBED_BATCH_SIZE = 10(见 llama-index-core/llama_index/core/constants.py),字段声明通过 Field(gt=0, le=2048) 限定了取值范围。
底层实现要点(对应 base.py):
- 构造时会分别创建同步客户端与异步客户端:
Client(host=self.base_url, **client_kwargs)与AsyncClient(host=self.base_url, **client_kwargs); - 每次嵌入请求实际调用的是 Ollama 官方 Python 库的
client.embed(model=..., input=..., options=self.ollama_additional_kwargs, keep_alive=self.keep_alive),ollama_additional_kwargs会作为options透传到服务端,keep_alive则用于控制模型在内存中的驻留时间,避免频繁换出导致推理延迟; get_general_text_embedding/get_general_text_embeddings直接封装底层embed调用并返回向量列表,同步与异步(aget_general_text_embedding/aget_general_text_embeddings)实现一一对应。
五、与 LlamaIndex 向量索引集成
最典型的使用场景是把 Ollama 嵌入模型设为全局 Settings.embed_model,随后构建 VectorStoreIndex:
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.embeddings.ollama import OllamaEmbedding
# 全局设置嵌入模型
Settings.embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://localhost:11434",
)
# 加载文档
documents = SimpleDirectoryReader("data").load_data()
# 使用 Ollama 嵌入构建索引
index = VectorStoreIndex.from_documents(documents)
# 查询索引
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic?")
print(response)
也可以搭配 Ollama 本地 LLM 一起使用,实现完全本地化的「向量化 + 生成」链路:
from llama_index.core import VectorStoreIndex, Settings
from llama_index.embeddings.ollama import OllamaEmbedding
from llama_index.llms.ollama import Ollama
Settings.llm = Ollama(model="llama3.1", base_url="http://localhost:11434")
Settings.embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://localhost:11434",
)
这样做的好处是:文档与问题都在本机完成向量化,无需把文本发送到外部 API,兼顾隐私、成本与离线可用性。
六、用指令前缀(Instruction)提升检索质量
部分嵌入模型(如 nomic-embed-text)建议在查询与文档前拼接语义指令,以区分「检索问题」与「待检索文档」,从而显著改善检索相关性。OllamaEmbedding 通过 query_instruction 与 text_instruction 两个参数原生支持:
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
query_instruction="Represent the question for retrieving supporting documents:",
text_instruction="Represent the document for retrieval:",
)
# 内部实际处理为:"Represent the question for retrieving supporting documents: What is machine learning?"
query_embedding = embed_model.get_query_embedding("What is machine learning?")
# 内部实际处理为:"Represent the document for retrieval: Machine learning is a method of data analysis."
text_embedding = embed_model.get_text_embedding("Machine learning is a method of data analysis.")
从源码看,前缀拼接发生在 _format_query 与 _format_text 两个私有方法中(base.py):拼接时会对指令与正文做 strip() 去除首尾空白,从而避免产生多余空格或空字符串异常。对应单元测试位于 tests/test_embeddings_ollama.py,覆盖了带/不带指令、空白清理、空字符串、批量文本以及同步/异步路径下指令前缀均被正确应用的行为。
七、异步用法
集成同时提供了完整的异步 API,适合在高并发或 I/O 密集场景下使用:
import asyncio
from llama_index.embeddings.ollama import OllamaEmbedding
embed_model = OllamaEmbedding(model_name="nomic-embed-text")
async def main():
# 异步单条文本向量
embedding = await embed_model.aget_text_embedding("Hello, world!")
# 异步批量向量
embeddings = await embed_model.aget_text_embeddings(
["Text 1", "Text 2", "Text 3"]
)
# 异步查询向量
query_embedding = await embed_model.aget_query_embedding("What is AI?")
asyncio.run(main())
异步路径同样经过 _aget_query_embedding、_aget_text_embedding、_aget_text_embeddings 的指令格式化后,调用 AsyncClient.embed(base.py)。
八、远程 Ollama 服务与自定义客户端
1. 连接远程服务器
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://your-remote-server:11434",
)
2. 通过 client_kwargs 透传认证等配置
client_kwargs 会原样传入 ollama.Client 与 AsyncClient,例如为私有化部署配置鉴权头:
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
client_kwargs={"headers": {"Authorization": "Bearer token"}},
)
该用法在 tests/test_embeddings_ollama.py 中有对应的实例化验证。
九、源码级原理:调用链与基础能力
1. 同步/异步调用链
以 get_text_embedding 为例,完整的调用路径为:
get_text_embedding(text)
└─ _get_text_embedding(text) # OllamaEmbedding 实现,先 _format_text 格式化
└─ get_general_text_embedding(text)
└─ self._client.embed(model, input, options, keep_alive)
查询向量路径则对应 _get_query_embedding → _format_query → get_general_text_embedding。批量路径 get_general_text_embeddings 一次将整个批次文本作为 input 列表传给 Ollama 服务端,由服务端批量返回向量。
2. 继承自 BaseEmbedding 的通用能力
get_text_embedding、aget_text_embedding、get_text_embedding_batch 等公开方法定义在 llama-index-core/llama_index/core/base/embeddings/base.py,它们为 OllamaEmbedding 注入了以下通用机制:
- 回调与观测:每次嵌入会通过
callback_manager触发CBEventType.EMBEDDING事件,并向 Dispatcher 广播EmbeddingStartEvent/EmbeddingEndEvent,可接入日志、追踪等观测体系; - 嵌入缓存:当设置了
embeddings_cache时,相同文本的向量会命中缓存,避免重复调用本地服务; - 限流:配置
rate_limiter后可对请求频率进行控制; - 批处理与进度条:
get_text_embedding_batch按embed_batch_size切块,show_progress=True时展示「Generating embeddings」进度条。
这些能力意味着 OllamaEmbedding 虽然只实现了 _get_* 系列私有方法,却自动获得了与 LlamaIndex 生态完全一致的工程化行为。
十、测试验证:本地服务集成测试
集成包的测试文件 tests/test_embeddings_ollama.py 展示了两种验证思路:
- 真实集成测试:测试启动时通过
ollama.Client探测本地 Ollama 服务及模型(模型名可用环境变量OLLAMA_TEST_MODEL覆盖,默认llama3.1:latest)。服务可用时执行真实嵌入,断言返回值为非空浮点列表、查询向量与文本向量维度一致且互不相等;服务不可用则通过pytest.mark.skipif自动跳过。 - 指令功能单元测试:使用
unittest.mock.patch模拟底层嵌入调用,验证query_instruction/text_instruction在同步、异步、单条、批量各路径下均被正确拼接到文本之前。
这套测试结构对自行扩展 Ollama 集成或排查问题具有参考价值。
十一、常见问题排查
连接错误(Connection Errors)
- 确认 Ollama 服务已启动:执行
ollama serve或检查服务状态; - 确认
base_url与 Ollama 服务实际监听地址一致; - 确认目标模型已拉取:
ollama pull <model-name>。
模型不存在(Model Not Found)
- 用
ollama list查看当前已有模型; - 用
ollama pull <model-name>拉取所需模型; - 核对代码中的
model_name与ollama list输出的模型名完全一致(包括标签,如:latest)。
结语
OllamaEmbedding 为 LlamaIndex 提供了开箱即用的本地向量化能力:一条 pip install llama-index-embeddings-ollama 即可将 Ollama 上的嵌入模型接入 LlamaIndex 的索引、检索与查询链路。结合本文介绍的参数语义、指令前缀优化与异步 API,你可以在完全本地、隐私可控的前提下,构建出高质量且可观测的 RAG 应用。