Haystack Ollama 集成指南：本地 LLM 嵌入与 Chat 生成全解析

Haystack Ollama 集成指南本地 LLM 嵌入与 Chat 生成全解析【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack导读Ollama 是目前在本地机器上运行开源 LLM 最流行的方案之一它默认使用量化后的 GGUF 格式让开发者即使没有 GPU 也能在普通机器上跑起 LLM。Haystack 通过ollama-haystack集成包将 Ollama 的嵌入模型与 Chat 模型无缝接入 PipelineOllamaDocumentEmbedder/OllamaTextEmbedder负责把文档和查询转为向量以支撑向量检索RAGOllamaChatGenerator则负责完成本地化的对话生成并支持流式输出、工具调用、思考模式与结构化输出。读完本文你将掌握这三个组件的完整参数体系、独立运行与 Pipeline 集成方式以及背后的实现原理。本文基于 docs-website/reference_versioned_docs/version-2.19/integrations-api/ollama.md 展开并辅以同仓库内对应的组件文档如 ollamadocumentembedder.mdx、ollamachatgenerator.mdx与 Haystack 核心源码进行印证。一、集成概览安装与前置条件Ollama 集成由独立的 Python 包ollama-haystack提供不属于 Haystack 核心库。安装方式pip install ollama-haystack在使用任何组件之前需要确保本机有一个正在运行的 Ollama 实例。安装 Ollama 有两种常见方式直接安装到本机系统macOS、Linux、Windows 均支持使用 Docker 快速启动docker run -d -p 11434:11434 --name ollama ollama/ollama:latest之后拉取所需的模型。以 Zephyr 为例# 使用 Docker 时 docker exec ollama ollama pull zephyr # 本机已安装 Ollama 时 ollama pull zephyr提示选择模型的特定量化版本。Ollama 模型库的模型卡片会列出可用 tag可以用model:tag语法拉取指定的量化版本例如ollama pull zephyr:7b-alpha-q3_K_S。更小的量化如 q3_K_S占用内存更少、推理更快但精度会略有下降。由于 Ollama 本身就内置了 embedding API 与 chat API安装ollama-haystack之后无需额外配置即可使用。绝大多数环境Mac、Linux、Docker下 Ollama 服务默认监听http://localhost:11434这也是三个组件的默认url。二、OllamaDocumentEmbedder为文档批量计算向量OllamaDocumentEmbedder计算一组Document的嵌入向量并把结果写入每个文档的embedding字段。这些向量是执行向量检索的前提——检索时查询向量会与文档向量做相似度比较找出最相关的文档。它通常出现在索引 Pipeline 中、DocumentWriter之前。2.1 独立使用from haystack import Document from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder doc Document(contentWhat do llamas say once you have thanked them? No probllama!) document_embedder OllamaDocumentEmbedder() result document_embedder.run([doc]) print(result[documents][0].embedding) # Calculating embeddings: 100%|██████████| 1/1 [00:0200:00, 2.82s/it] # [-0.16412407159805298, -3.8359334468841553, ... ]2.2 构造参数全解析OllamaDocumentEmbedder.__init__的完整签名来自参考文档__init__( model: str nomic-embed-text, url: str http://localhost:11434, generation_kwargs: dict[str, Any] | None None, timeout: int 120, keep_alive: float | str | None None, prefix: str , suffix: str , progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, batch_size: int 32, dimensions: int | None None, ) - None参数类型默认值说明modelstrnomic-embed-text使用的嵌入模型名称必须是当前 Ollama 实例中已存在的模型urlstrhttp://localhost:11434运行中的 Ollama 实例地址generation_kwargsdict[str, Any] \| NoneNone透传给 Ollama 生成端点的可选参数如temperature、top_p等可参考 Ollama Modelfile 文档中的合法参数表timeoutint120从 Ollama API 抛出超时错误前的等待秒数keep_alivefloat \| str \| NoneNone控制请求结束后模型在内存中驻留的时长未设置时使用 Ollama 默认值5 分钟prefixstr追加到每段文本开头的字符串suffixstr追加到每段文本结尾的字符串progress_barboolTrue运行时是否显示进度条meta_fields_to_embedlist[str] \| NoneNone需要连同文档正文一起参与嵌入的元数据字段列表embedding_separatorstr\n将元数据字段与文档正文拼接时使用的分隔符batch_sizeint32每批处理的文档数量dimensionsint \| NoneNone期望输出的嵌入向量维度仅支持实现了 Matryoshka Representation LearningMRL的模型keep_alive的取值规则需要特别说明时长字符串如10m、24h秒数如3600任意负数使模型在响应生成后持续驻留内存如-1或-1m0生成响应后立即将模型从内存卸载。dimensions参数只在实现 MRLMatryoshka Representation Learning嵌套向量表示学习的模型中生效参考文档点名的模型包括nomic-embed-text-v1.5、mxbai-embed-large、qwen3-embedding。MRL 允许在不重新训练的情况下按需截取向量维度例如把 1024 维截断为 256 维从而显著降低存储与检索成本当dimensionsNone默认时返回完整向量。文档还注明该参数要求ollama-python 0.6.2。2.3 元数据嵌入与输出结构通过meta_fields_to_embed可以让文档的部分元数据参与嵌入使相似度检索能够感知元数据语义。拼接规则是元数据字段值与文档正文之间用embedding_separator默认换行\n连接prefix与suffix则分别加在每段文本的最前与最后。run(documents, generation_kwargsNone)的返回值为字典包含两个键documents已附加嵌入向量的文档列表meta嵌入过程中收集的元数据。其中meta会自动带上使用的模型名例如使用nomic-embed-text时输出{meta: {model: nomic-embed-text}}。run也支持在调用时通过generation_kwargs传入覆盖实例级参数的推理选项。2.4 索引 Pipeline 实战下面是一个完整的 PDF 索引 Pipeline转换 → 清洗 → 切分 → 嵌入 → 写入向量存储。from haystack import Pipeline from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder from haystack.components.preprocessors import DocumentCleaner, DocumentSplitter from haystack.components.converters import PyPDFToDocument from haystack.components.writers import DocumentWriter from haystack.document_stores.types import DuplicatePolicy from haystack.document_stores.in_memory import InMemoryDocumentStore document_store InMemoryDocumentStore(embedding_similarity_functioncosine) embedder OllamaDocumentEmbedder( modelnomic-embed-text, urlhttp://localhost:11434, ) # 这是默认模型与默认 URL cleaner DocumentCleaner() splitter DocumentSplitter() file_converter PyPDFToDocument() writer DocumentWriter(document_storedocument_store, policyDuplicatePolicy.OVERWRITE) indexing_pipeline Pipeline() # 向 Pipeline 添加组件 indexing_pipeline.add_component(embedder, embedder) indexing_pipeline.add_component(converter, file_converter) indexing_pipeline.add_component(cleaner, cleaner) indexing_pipeline.add_component(splitter, splitter) indexing_pipeline.add_component(writer, writer) # 连接组件 indexing_pipeline.connect(converter, cleaner) indexing_pipeline.connect(cleaner, splitter) indexing_pipeline.connect(splitter, embedder) indexing_pipeline.connect(embedder, writer) # 运行 Pipeline indexing_pipeline.run({converter: {sources: [files/test_pdf_data.pdf]}}) # Calculating embeddings: 100%|██████████| 115/115 # {embedder: {meta: {model: nomic-embed-text}}, writer: {documents_written: 115}}注意InMemoryDocumentStore显式指定了embedding_similarity_functioncosine这样后续检索时使用余弦相似度比较向量。关于 Pipeline 的完整组件能力可参考 haystack/core/pipeline 目录下的实现。2.5 生命周期方法warm_up()创建同步 Ollama 客户端在 Pipeline 首次运行前预加载避免运行时才初始化造成延迟warm_up_async()创建异步 Ollama 客户端close()关闭同步客户端释放连接资源close_async()关闭异步客户端。run_async()则是对应run()的异步版本用于在异步 Pipeline 中调用。这与 Haystack 核心库中AsyncPipeline并入Pipeline的设计一致可参考 releasenotes 中 Merge-AsyncPipeline-into-Pipeline-73c83002fd647297.yaml。三、OllamaTextEmbedder为查询字符串计算向量OllamaTextEmbedder计算单个字符串的嵌入向量。在 RAG 查询 Pipeline 中它通常位于嵌入检索器如InMemoryEmbeddingRetriever之前先用它将用户查询转成向量再交给检索器与文档向量比对。需要嵌入一批文档时则改用OllamaDocumentEmbedder。3.1 独立使用from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder embedder OllamaTextEmbedder() result embedder.run( textWhat do llamas say once you have thanked them? No probllama!, ) print(result[embedding])3.2 构造参数全解析__init__( model: str nomic-embed-text, url: str http://localhost:11434, generation_kwargs: dict[str, Any] | None None, timeout: int 120, keep_alive: float | str | None None, dimensions: int | None None, ) - None与OllamaDocumentEmbedder相比Text 版本参数更精简去掉了与批量文档相关的prefix、suffix、progress_bar、meta_fields_to_embed、embedding_separator、batch_size保留并共享相同的核心参数语义model默认nomic-embed-texturl默认http://localhost:11434generation_kwargs透传的推理选项temperature、top_p等timeout默认 120 秒keep_alive模型内存驻留时长规则与 Document 版本完全一致时长字符串 / 秒数 / 负数常驻 /0立即卸载dimensionsMRL 模型的期望向量维度None时返回完整向量。3.3 输出结构run(text, generation_kwargsNone)返回字典embedding计算得到的嵌入向量list[float]meta嵌入过程的元数据同样自动包含模型名如{model: nomic-embed-text}。run_async提供异步等价实现。3.4 RAG 查询 Pipeline 实战下面的示例同时演示两个 Embedder 的配合先用OllamaDocumentEmbedder为文档建索引再用OllamaTextEmbedder编码查询并检索。from haystack import Document from haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.embedders.ollama import ( OllamaDocumentEmbedder, OllamaTextEmbedder, ) from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] document_embedder OllamaDocumentEmbedder() documents_with_embeddings document_embedder.run(documents)[documents] document_store.write_documents(documents_with_embeddings) query_pipeline Pipeline() query_pipeline.add_component(text_embedder, OllamaTextEmbedder()) query_pipeline.add_component( retriever, InMemoryEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query Who lives in Berlin? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])这里query_pipeline.connect(text_embedder.embedding, retriever.query_embedding)将查询向量直接接到检索器的query_embedding输入是 Haystack 管道式连接的标准写法。四、OllamaChatGenerator本地 LLM 对话生成OllamaChatGenerator是面向运行在 Ollama 上的 LLM如llama2、mixtral、qwen3的 Chat 生成组件。它基于ChatMessage对象工作——ChatMessage是 Haystack 的数据类包含消息内容、角色user、assistant、system、tool与可选元数据定义见 haystack/dataclasses/chat_message.py其中from_user、from_system等工厂方法用于快速构造消息。它默认使用qwen3:0.6b模型和http://localhost:11434地址。除基本的对话生成外参考文档明确指出它支持**流式输出streaming、工具调用tool calls、推理思考reasoning与结构化输出structured outputs**四大进阶能力。4.1 独立使用from haystack_integrations.components.generators.ollama.chat import OllamaChatGenerator from haystack.dataclasses import ChatMessage llm OllamaChatGenerator(modelqwen3:0.6b) result llm.run(messages[ChatMessage.from_user(What is the capital of France?)]) print(result)4.2 构造参数全解析__init__( model: str qwen3:0.6b, url: str http://localhost:11434, generation_kwargs: dict[str, Any] | None None, timeout: int 120, max_retries: int 0, keep_alive: float | str | None None, streaming_callback: Callable[[StreamingChunk], None] | None None, tools: ToolsType | None None, response_format: None | Literal[json] | JsonSchemaValue | None None, think: bool | Literal[low, medium, high] False, ) - None参数类型默认值说明modelstrqwen3:0.6b模型名称必须是当前 Ollama 实例中已 pull 的模型urlstrhttp://localhost:11434Ollama 服务的基础地址generation_kwargsdict[str, Any] \| NoneNone透传推理选项temperature、top_p等timeoutint120API 超时秒数max_retriesint0失败请求HTTP 429、5xx、连接/超时错误的最大重试次数采用指数退避0表示禁用重试keep_alivefloat \| str \| NoneNone模型内存驻留时长规则同 Embedderstreaming_callbackCallable[[StreamingChunk], None] \| NoneNone每收到一个新 token 时被调用的回调函数参数为StreamingChunktoolsToolsType \| NoneNone可供模型发起调用的Tool/Toolset对象可混合传入列表每个工具需有唯一名称并非所有模型支持工具调用response_formatNone \| json \| JsonSchemaValueNone结构化输出格式thinkbool \| low \| medium \| highFalse是否开启思考模式仅思考型模型支持关键参数详解max_retries参考文档明确其作用于 HTTP 429、5xx 以及连接/超时错误采用指数退避策略默认0关闭重试。在本地网络不稳定或模型首次加载较慢时适当调大该值可提升健壮性。think思考模式设为True时模型会在产出回答前先进行思考仅 [thinking models] 支持。部分模型如 gpt-oss支持low/medium/high三档思考强度。思考过程的中间输出可通过返回的ChatMessage的reasoning属性查看——这与 Haystack 的StreamingChunk/ChatMessage中对reasoning内容的建模一脉相承见 haystack/dataclasses/streaming_chunk.py 中的reasoning字段。response_format结构化输出None不对响应施加结构原样返回json强制模型输出 JSON 对象JSON Schema按指定 JSON Schema 约束输出要求 Ollama ≥ 0.1.34。tools工具调用ToolsType在 Haystack 核心中的定义是Sequence[Tool | Toolset] | Toolset见 haystack/tools/tool_types.py即可以传入单个Toolset、Tool列表或 Tool 与 Toolset 混合的列表。Toolset的定义位于 haystack/tools/toolset.py而create_tool_from_function可以将普通 Python 函数一键包装为 Tool见 haystack/tools/from_function.py。4.3 工具调用Function Calling支持三种灵活的传参方式Tool 对象列表把单个工具作为列表元素传入单个 Toolset直接传入整个工具集混合 Tools 与 Toolsets在同一列表中组合多个 Toolset 与独立 Tool。from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.ollama import OllamaChatGenerator # 创建独立工具 weather_tool Tool( nameweather, descriptionGet weather info, parameters..., function... ) news_tool Tool( namenews, descriptionGet latest news, parameters..., function... ) # 将相关工具归组为 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传入工具与工具集 generator OllamaChatGenerator( modelllama2, tools[math_toolset, weather_tool, news_tool], # Toolset 与 Tool 混用 )在run()中还可以通过tools参数按调用覆盖初始化时的工具配置。关于 Tool / Toolset 的完整用法可参考 haystack/tools 目录以及组件文档 tool.mdx、toolset.mdx。4.4 流式输出Streaming向streaming_callback传入回调即可开启流式输出。内置的print_streaming_chunk位于haystack.components.generators.utils可直接打印文本 token 与工具事件工具调用与工具结果from haystack.components.generators.utils import print_streaming_chunk # 为任意 Generator 或 ChatGenerator 配置流式回调 component SomeGeneratorOrChatGenerator(streaming_callbackprint_streaming_chunk) # ChatGenerator 传消息列表Generator 传 prompt 字符串注意事项流式模式只支持单条响应若供应商支持多个候选需设置n1默认优先使用print_streaming_chunk仅当需要特定传输方式如 SSE/WebSocket或自定义 UI 格式化时才编写自定义回调。StreamingChunk是流式回调收到的数据单元其定义在 haystack/dataclasses/streaming_chunk.py包含content、tool_calls、tool_call_result、reasoning等字段且同一 chunk 中这四个字段最多只能设置一个。4.5 流式 工具调用组合将tools与streaming_callback同时传入时当模型决定调用工具流式 chunk 携带的是工具调用增量tool-call deltas而非文本 token流结束后重建出的ChatMessage会通过replies[0]暴露完整的tool_calls列表from haystack.dataclasses import ChatMessage from haystack.dataclasses.streaming_chunk import StreamingChunk from haystack.tools import create_tool_from_function from haystack_integrations.components.generators.ollama import OllamaChatGenerator def get_weather(city: str) - str: Get current weather for a city. return fSunny, 22°C in {city} def callback(chunk: StreamingChunk) - None: if chunk.tool_calls: print(f[tool delta] {chunk.tool_calls}) elif chunk.content: print(chunk.content, end, flushTrue) generator OllamaChatGenerator( modelllama3.1:8b, generation_kwargs{temperature: 0.0}, tools[create_tool_from_function(get_weather)], streaming_callbackcallback, ) response generator.run( messages[ ChatMessage.from_user( Whats the weather in Berlin? Use the get_weather tool., ), ], ) # 重建后的最终消息tool_calls 已填充text 为 None assistant_message response[replies][0] print(assistant_message.tool_calls) # - [ToolCall(tool_nameget_weather, arguments{city: Berlin}, ...)]如果不想手写回调直接用内置的print_streaming_chunk即可同时处理文本 token 与工具事件。4.6 多模态输入OllamaChatGenerator还支持多模态模型如llava通过ImageContent传入图片from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.ollama import OllamaChatGenerator llm OllamaChatGenerator(modelllava, urlhttp://localhost:11434) image ImageContent.from_file_path(apple.jpg) user_message ChatMessage.from_user( content_parts[What does the image show? Max 5 words., image], ) response llm.run([user_message])[replies][0].text print(response) # Red apple on straw.4.7 run 方法签名与返回值run( messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None, *, streaming_callback: StreamingCallbackT | None None ) - dict[str, list[ChatMessage]]messages输入消息列表如果传入字符串会被自动转换为一个角色为user的ChatMessagegeneration_kwargs单次调用级别的推理选项覆盖会与实例级generation_kwargs合并按调用覆盖实例tools若设置则覆盖初始化时的tools配置streaming_callback提供回调此处或构造函数中即切换为流式模式。返回值字典仅包含一个键replies模型响应的ChatMessage列表。run_async为对应的异步版本。4.8 序列化支持OllamaChatGenerator实现了to_dict()/from_dict()用于与 Haystack 的 Pipeline YAML 序列化机制集成to_dict()将组件序列化为字典from_dict(data)从字典反序列化出组件实例。这使整个 Pipeline 可以被保存为 YAML/JSON 配置并在其他环境中重建Haystack 的 marshal 能力见 haystack/marshal。4.9 Chat Pipeline 实战结合ChatPromptBuilder将用户模板消息渲染后送入 LLMfrom haystack.components.builders import ChatPromptBuilder from haystack_integrations.components.generators.ollama import OllamaChatGenerator from haystack.dataclasses import ChatMessage from haystack import Pipeline # 不使用运行时模板变量因此无需参数初始化 prompt_builder ChatPromptBuilder() generator OllamaChatGenerator( modelzephyr, urlhttp://localhost:11434, generation_kwargs{ temperature: 0.9, }, ) pipe Pipeline() pipe.add_component(prompt_builder, prompt_builder) pipe.add_component(llm, generator) pipe.connect(prompt_builder.prompt, llm.messages) location Berlin messages [ ChatMessage.from_system( Always respond in Spanish even if some input data is in other languages. ), ChatMessage.from_user(Tell me about {{location}}), ] print( pipe.run( data{ prompt_builder: { template_variables: {location: location}, template: messages, } } ) )运行结果中的replies[0]是一个ChatRole.ASSISTANT角色的ChatMessage其_meta中同样携带模型名如{model: zephyr, ...}。五、配套组件OllamaGenerator已弃用Haystack 还提供过一个面向 prompt 字符串的OllamaGenerator其默认模型为orca-mini、默认 URL 同为http://localhost:11434。参考文档与组件文档均标注其为弃用状态未来版本会移除官方建议迁移到OllamaChatGenerator后者也接受纯字符串输入。本文不展开其细节仅在文中明确其迁移方向避免新项目继续选用。六、生命周期管理与异步能力小结三个组件两个 Embedder 与 ChatGenerator均实现了统一的生命周期方法与 Haystack 核心的组件协议保持一致方法作用warm_up()创建同步客户端供 Pipeline 预加载模型与客户端避免首次运行时延迟warm_up_async()创建异步客户端close()关闭同步客户端释放资源close_async()关闭异步客户端run()同步执行推理run_async()异步执行推理OllamaChatGenerator另有to_dict/from_dict这一设计呼应了 Haystack 将 AsyncPipeline 并入 Pipeline 的演进参见 Merge-AsyncPipeline-into-Pipeline-73c83002fd647297.yaml同步与异步可以在同一 Pipeline 框架内无缝混用。七、快速决策表与最佳实践需求推荐组件默认模型为文档批量计算向量索引阶段OllamaDocumentEmbeddernomic-embed-text为查询字符串计算向量检索阶段OllamaTextEmbeddernomic-embed-text本地对话 / RAG 生成OllamaChatGeneratorqwen3:0.6b实践建议均有上文依据Embedder 与 Retriever 的模型必须一致索引时文档向量与查询向量需由同一模型或同一 MRL 维度截断策略产出否则相似度比对失去意义长驻模型用keep_alive-1高频调用场景下避免反复加载/卸载模型带来的延迟抖动低频场景用keep_alive0及时释放显存/内存结构化输出优先使用response_format需要 JSON 时优先用json或 JSON Schema而不是在 prompt 里求模型输出 JSON流式优先用内置回调默认使用print_streaming_chunk自定义回调仅用于 SSE/WebSocket 等特殊传输需求按调用覆盖参数run()中的generation_kwargs/tools会覆盖实例级配置适合在同一组件上服务不同请求场景工具调用注意模型兼容性并非所有 Ollama 模型支持 tools选择模型前应先确认其工具调用能力。结语通过ollama-haystackHaystack 可以在完全不依赖云服务的情况下完成向量化 → 检索 → 生成的完整本地 RAG 链路OllamaDocumentEmbedder与OllamaTextEmbedder撑起索引与检索两端OllamaChatGenerator则提供了对话生成、工具调用、流式输出、思考模式与结构化输出等生产级能力。结合本文给出的参数说明与 Pipeline 示例你可以快速在自己的机器上搭建一套完全本地化的 LLM 应用。如需深入了解组件细节建议继续阅读同仓库中的组件文档ollamadocumentembedder.mdx、ollamatextembedder.mdx、ollamachatgenerator.mdx以及 Haystack 核心数据类 chat_message.py 与 streaming_chunk.py 的源码实现。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考