LlamaIndex 本地嵌入实战:使用 OllamaEmbedding 在 Ollama 上生成文本向量

原创2026-10-10 20:36:481,613 阅读
文章标签:人工智能大模型RAGAI AgentAgent 框架Agent 工作流Prompt 模板向量数据库Embedding

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 展示了两种验证思路:

  1. 真实集成测试:测试启动时通过 ollama.Client 探测本地 Ollama 服务及模型(模型名可用环境变量 OLLAMA_TEST_MODEL 覆盖,默认 llama3.1:latest)。服务可用时执行真实嵌入,断言返回值为非空浮点列表、查询向量与文本向量维度一致且互不相等;服务不可用则通过 pytest.mark.skipif 自动跳过。
  2. 指令功能单元测试:使用 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 应用。

登录后查看全文
llama_index