Haystack × Ollama 集成实战本地 Embedding 与 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本篇指南系统讲解 Haystack 与 Ollama 的官方集成ollama-haystack包覆盖OllamaDocumentEmbedder、OllamaTextEmbedder与OllamaChatGenerator三个核心组件如何在本地起一个 Ollama 服务、如何把文档批量向量化并写入 Document Store、如何在 RAG 查询管线中用嵌入检索召回以及如何用 Chat Generator 实现流式输出、工具调用、思考模式与结构化输出。读完你可以在完全不依赖云端 API 的前提下用 Haystack 搭建一条完整的本地化 RAG 与 Agent 链路。本文基于 Haystack 仓库中 version-2.18 的 Ollama 集成 API 参考 展开并结合仓库内对应组件的使用指南OllamaDocumentEmbedder、OllamaTextEmbedder、OllamaChatGenerator以及 Haystack 核心源码如 StreamingChunk作补充说明。一、Ollama 集成是什么为什么值得用Ollama 是一个聚焦“在本地运行 LLM”的开源项目内部默认使用量化后的 GGUF 格式因此即使是普通机器甚至没有 GPU也能跑起大模型且无需复杂的安装配置。Haystack 通过ollama-haystack这个独立集成包把 Ollama 提供的embedding API 与 chat/generate API封装成标准的 Haystack 组件可以无缝嵌入 Haystack 的 Pipeline。这套集成的典型应用场景本地语义搜索用OllamaDocumentEmbedder批量给文档生成向量并写入 Document Store再用OllamaTextEmbedder把查询向量化配合 InMemoryEmbeddingRetriever 做余弦相似度召回本地 RAG 问答检索到的上下文交给OllamaChatGenerator生成答案全程数据不出本机本地 AgentOllamaChatGenerator支持工具调用Tool/Toolset、流式输出与思考模式可承载轻量级 Agent 工作流。需要说明的是ollama-haystack属于独立发布的集成包源码维护在 haystack-core-integrations 仓库Haystack 核心仓库内保留的是其 API 参考文档与使用指南。安装方式统一为pip install ollama-haystack前提是你已有一个正在运行的 Ollama 实例本地安装或 Docker 容器均可。由于 Ollama 自带 embedding 与 chat API无需额外配置即可使用。快速启动 Ollama 服务使用 Docker 是启动 Ollama 最快的方式默认端口 11434docker run -d -p 11434:11434 --name ollama ollama/ollama:latest拉取模型例如 Zephyrdocker exec ollama ollama pull zephyr如果你是在本机直接安装的 Ollama则执行ollama pull zephyr小技巧选择具体量化版本。可以在模型卡片中查看可用 tag然后指定版本拉取例如ollama pull zephyr:7b-alpha-q3_K_S。较低的量化级别如 q3占用内存更小适合无 GPU 环境。二、OllamaDocumentEmbedder把文档批量变成向量OllamaDocumentEmbedder计算一组 Document 的 embedding并把得到的向量写回每个 Document 的embedding字段。它使用与 Ollama Library 兼容的 embedding 模型。这些向量是后续向量检索的基础检索时查询向量会与文档向量比较找出最相似的相关文档。它在管线中的典型位置是索引管线的DocumentWriter之前见 使用指南。构造函数与全部参数__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参数默认值说明modelnomic-embed-text使用的 embedding 模型名必须已存在于运行的 Ollama 实例中可用ollama pull拉取urlhttp://localhost:11434正在运行的 Ollama 实例地址Mac/Linux/Docker 默认都是 11434 端口generation_kwargsNone透传给 Ollama 生成端点的可选参数如temperature、top_p等参考 Ollama Modelfile 的合法参数与取值timeout120触发 Ollama API 超时错误前的等待秒数keep_aliveNone控制请求结束后模型在内存中驻留的时间。不设置则用 Ollama 默认值5 分钟。取值方式时长字符串如10m、24h以秒为单位的数字如3600任意负数表示常驻内存如-1或-1m0表示生成响应后立即卸载模型prefix拼接到每段文本开头的字符串suffix拼接到每段文本末尾的字符串progress_barTrue运行时是否显示进度条meta_fields_to_embedNone需要随文档正文一起嵌入的元数据字段列表embedding_separator\n拼接元数据字段与文档正文时使用的分隔符batch_size32每批处理的文档数量dimensionsNone期望的 embedding 输出维度。仅支持实现了Matryoshka Representation LearningMRL的模型如nomic-embed-text-v1.5、mxbai-embed-large、qwen3-embedding。为None默认时返回完整向量。该参数要求ollama-python 0.6.2参数要点解读meta_fields_to_embedembedding_separator是一对组合当你希望“带上下文的文档”获得更好检索效果时可以把来源、章节等元数据拼进文本一起向量化分隔符控制拼接格式prefix/suffix可用于按模型要求添加指令式前后缀部分 embedding 模型对输入格式敏感batch_size决定一次请求送入多少文档批量过小会增加请求次数过大可能超出模型输入限制dimensions对 MRL 模型非常实用可以输出降维向量显著减少向量存储与检索开销代价是精度略降。独立使用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, ... ]run 方法签名与返回值run( documents: list[Document], generation_kwargs: dict[str, Any] | None None ) - dict[str, list[Document] | dict[str, Any]]documents待向量化的 Document 列表generation_kwargs可选调用时临时覆盖/追加传给 Ollama 生成端点的参数。返回字典包含两个键documents已附加 embedding 信息的 Document 列表meta嵌入过程中收集到的元数据。元数据说明组件会自动把所用模型名写入返回的meta中。使用nomic-embed-text时的返回形如{meta: {model: nomic-embed-text}}放进索引管线文档处理 → 向量化 → 入库以下示例把 PDF 转换、清洗、切分、向量化、写入 Document Store 串成一条完整索引管线DocumentStore使用余弦相似度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() 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) 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}}三、OllamaTextEmbedder把查询变成向量OllamaTextEmbedder计算单个字符串的 embedding用于查询侧。进行向量检索时先用它把查询转成向量再由 embedding Retriever 用该向量在文档集合中检索相似文档。它在管线中的典型位置是查询/RAG 管线中 embedding Retriever 之前。选择原则embed 一段字符串用OllamaTextEmbedderembed 一组文档用OllamaDocumentEmbedder。构造函数与全部参数__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相比 DocumentEmbedderTextEmbedder 更精简其余参数语义完全一致model默认nomic-embed-text须已存在于运行的 Ollama 实例url默认http://localhost:11434generation_kwargs透传给 Ollama 生成端点的可选参数temperature、top_p等timeoutAPI 超时秒数默认120keep_alive模型驻留内存策略规则同 DocumentEmbedder时长字符串 / 秒数 / 负数常驻 /0立即卸载dimensionsMRL 模型可指定输出维度如nomic-embed-text-v1.5、mxbai-embed-large、qwen3-embeddingNone时返回完整向量。run 方法签名与返回值run( text: str, generation_kwargs: dict[str, Any] | None None ) - dict[str, list[float] | dict[str, Any]]text待向量化的字符串generation_kwargs调用时临时覆盖/追加的生成参数。返回字典包含两个键embedding计算得到的向量float 列表meta嵌入过程收集的元数据同样会自动附带模型名如{model: nomic-embed-text}。独立使用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])组装完整的本地 RAG 检索管线索引侧用OllamaDocumentEmbedder写入带向量的文档查询侧用OllamaTextEmbedderInMemoryEmbeddingRetriever召回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])这里InMemoryEmbeddingRetriever是 Haystack 核心自带的组件见 源码它接收query_embedding输入在 Document Store 中对所有文档向量计算相似度并返回 top-k 文档。至此你已拥有一套完全本地化的语义检索能力。四、OllamaChatGenerator本地 LLM 对话、流式与工具调用OllamaChatGenerator是面向 Ollama 服务的 Chat Generator支持流式输出、工具调用Tool Calls、思考模式Reasoning与结构化输出Structured Outputs。它基于 Ollama 的 chat API通过ChatMessage对象进行多轮对话。它的典型管线位置是ChatPromptBuilder之后见 使用指南。构造函数与全部参数__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参数默认值说明modelqwen3:0.6b模型名必须已经 pull 到运行的 Ollama 实例中urlhttp://localhost:11434Ollama 服务的基础 URLgeneration_kwargsNone透传给 Ollama 生成端点的可选参数temperature、top_p等timeout120API 超时秒数max_retries0失败请求HTTP 429、5xx、连接/超时错误的最大重试次数使用指数退避默认0表示不重试keep_aliveNone模型驻留内存策略规则同 Embedder时长字符串 / 秒数 / 负数常驻 /0立即卸载streaming_callbackNone每收到一个流式 token 时被调用的回调函数接收StreamingChunk参数提供后组件进入流式模式toolsNone模型可为其准备调用的 Tool 和/或 Toolset 对象列表或单个 Toolset。每个工具名需唯一。并非所有模型支持工具兼容模型见 Ollama 官网工具模型列表response_formatNone结构化输出格式None原样返回json返回 JSON 对象JSON Schema返回符合该 Schema 的 JSON 对象需要 Ollama ≥ 0.1.34thinkFalse若为True模型在产出回复前先“思考”。仅支持思考类模型部分模型如gpt-oss支持low/medium/high三档思考强度。中间“思考”输出可通过返回的ChatMessage的reasoning属性查看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输入消息。可以是ChatMessage列表如果是字符串会被自动转换成包含一条 user 角色的ChatMessagegeneration_kwargs单次调用的生成参数覆盖会与实例级generation_kwargs合并实例级为底调用级覆盖其上tools本次调用传入的工具若设置则覆盖初始化时的tools参数streaming_callback运行时传入的回调与构造函数中的回调一样会把组件切换为流式模式运行时回调优先于初始化回调。返回字典包含一个键replies模型回复的ChatMessage列表。此外run_async提供异步版本签名与语义相同便于在异步管线中调用。生命周期方法与序列化OllamaChatGenerator与其他 Haystack 组件一样实现了一组标准的生命周期/序列化方法warm_up()/warm_up_async()创建同步/异步的 Ollama 客户端通常由管线在首次运行前自动预热close()/close_async()关闭同步/异步客户端释放连接资源to_dict()把组件序列化为字典from_dict(data)从字典反序列化组件。Embedder 组件同样实现了warm_up/warm_up_async/close/close_async用于管理 Ollama 客户端连接的生命周期。独立使用基础对话from haystack_integrations.components.generators.ollama import OllamaChatGenerator from haystack.dataclasses import ChatMessage generator OllamaChatGenerator( modelzephyr, urlhttp://localhost:11434, generation_kwargs{ num_predict: 100, temperature: 0.9, }, ) messages [ ChatMessage.from_system(\nYou are a helpful, respectful and honest assistant), ChatMessage.from_user(Whats Natural Language Processing?), ] print(generator.run(messagesmessages))返回结果是一个包含replies的字典其中每个ChatMessage带有 assistant 角色、文本内容以及模型元数据_meta中含model: zephyr等信息{ replies: [ ChatMessage( _roleChatRole.ASSISTANT: assistant, _content[TextContent(textNatural Language Processing (NLP) is a subfield of ...)], _nameNone, _meta{model: zephyr, ...}, ) ] }多模态输入部分模型如llava支持图像输入。把ImageContent作为ChatMessage的内容片段传入即可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.工具调用Tool 与 Toolset 的灵活组合tools参数接受非常灵活的工具配置Tool 对象列表逐个传入独立工具单个 Toolset直接传入整个 Toolset混合模式在同一个列表中混入多个 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]) # 混合传入 Toolset 与 Tool 对象 generator OllamaChatGenerator( modelllama2, tools[math_toolset, weather_tool, news_tool], # Toolset 与 Tool 的混合 )更常见的做法是用create_tool_from_function把普通 Python 函数包装成工具参考 工具相关文档 与 Toolset 文档。流式输出把回调传给streaming_callback即可逐 token 输出。最简单的方式是使用内置的print_streaming_chunk它能统一打印文本 token 与工具事件工具调用和工具结果from haystack.components.generators.utils import print_streaming_chunk # 任意 Generator/ChatGenerator 都可以配置流式回调 component SomeGeneratorOrChatGenerator(streaming_callbackprint_streaming_chunk) # ChatGenerator 传消息列表 # component.run([ChatMessage.from_user(Your question here)])注意流式模式只支持单条回复。如果某个服务商支持多个候选回复需要设置n1。StreamingChunk的字段设计见 haystack/dataclasses/streaming_chunk.py决定了回调的写法——每个 chunk 恰好表示以下四种情况之一Tool calls模型正在构造工具调用读chunk.tool_callsTool result工具执行完毕返回结果读chunk.tool_call_resultText tokens普通助手文本读chunk.contentReasoning tokens思考模型的扩展思考输出读chunk.reasoning。一个 chunk 中只会出现上述字段之一源码中__post_init__会校验content、tool_calls、tool_call_result、reasoning只能设置一个。可用chunk.start与chunk.finish_reason判断边界用chunk.index与chunk.component_info做追踪。在异步上下文run_async中StreamingCallbackT同时接受同步与异步回调若向run_async传入同步回调会记录警告可能阻塞事件循环但运行仍会继续反向向同步run传异步回调则会直接报错。流式 工具调用把tools与streaming_callback同时传入即可边流式边调用工具当模型决定调用工具时流式 chunk 携带的是工具调用增量而非文本 token最终重建出的ChatMessage会把解析好的tool_calls列表暴露在replies[0]上。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 与工具事件。结构化输出与思考模式response_format参数让输出结果可预测None不施加任何结构原样返回json输出被格式化为一个 JSON 对象JSON Schema输出为符合指定 JSON Schema 的 JSON 对象需要 Ollama ≥ 0.1.34。think参数用于思考类模型Ollama 官网有专门的 thinking 模型筛选设为True让模型先思考再作答部分模型支持low/medium/high强度档位中间的思考过程可以通过返回的ChatMessage.reasoning属性读取。放进对话管线配合ChatPromptBuilder可以搭建模板化对话管线这里展示一个“无论输入什么语言都用西班牙语回答”的示例from 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, } } ) )ChatMessage是 Haystack 核心的数据类文档包含消息内容、角色user、assistant、system、tool以及可选元数据是贯穿整套 Agent/RAG 对话链路的基本单元。五、组件对照速查组件输入输出典型位置OllamaDocumentEmbedderdocuments: list[Document]documents带向量、meta索引管线中DocumentWriter之前OllamaTextEmbeddertext: strembedding、meta查询/RAG 管线中 embedding Retriever 之前OllamaChatGeneratormessages: list[ChatMessage] \| strreplies: list[ChatMessage]ChatPromptBuilder之后三者共用一致的连接管理约定都提供warm_up/warm_up_async创建同步/异步 Ollama 客户端与close/close_async关闭客户端OllamaChatGenerator额外提供to_dict/from_dict序列化支持。三者默认 URL 均为http://localhost:11434。六、进一步阅读Ollama 集成 API 参考当前主分支OllamaDocumentEmbedder 使用指南OllamaTextEmbedder 使用指南OllamaChatGenerator 使用指南Generator 选型指南含流式、自托管方案对比ChatMessage 数据类说明StreamingChunk 源码【免费下载链接】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），仅供参考 Haystack × Ollama 集成实战：本地 Embedding 与 Chat 生成全指南
Haystack × Ollama 集成实战本地 Embedding 与 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本篇指南系统讲解 Haystack 与 Ollama 的官方集成ollama-haystack包覆盖OllamaDocumentEmbedder、OllamaTextEmbedder与OllamaChatGenerator三个核心组件如何在本地起一个 Ollama 服务、如何把文档批量向量化并写入 Document Store、如何在 RAG 查询管线中用嵌入检索召回以及如何用 Chat Generator 实现流式输出、工具调用、思考模式与结构化输出。读完你可以在完全不依赖云端 API 的前提下用 Haystack 搭建一条完整的本地化 RAG 与 Agent 链路。本文基于 Haystack 仓库中 version-2.18 的 Ollama 集成 API 参考 展开并结合仓库内对应组件的使用指南OllamaDocumentEmbedder、OllamaTextEmbedder、OllamaChatGenerator以及 Haystack 核心源码如 StreamingChunk作补充说明。一、Ollama 集成是什么为什么值得用Ollama 是一个聚焦“在本地运行 LLM”的开源项目内部默认使用量化后的 GGUF 格式因此即使是普通机器甚至没有 GPU也能跑起大模型且无需复杂的安装配置。Haystack 通过ollama-haystack这个独立集成包把 Ollama 提供的embedding API 与 chat/generate API封装成标准的 Haystack 组件可以无缝嵌入 Haystack 的 Pipeline。这套集成的典型应用场景本地语义搜索用OllamaDocumentEmbedder批量给文档生成向量并写入 Document Store再用OllamaTextEmbedder把查询向量化配合 InMemoryEmbeddingRetriever 做余弦相似度召回本地 RAG 问答检索到的上下文交给OllamaChatGenerator生成答案全程数据不出本机本地 AgentOllamaChatGenerator支持工具调用Tool/Toolset、流式输出与思考模式可承载轻量级 Agent 工作流。需要说明的是ollama-haystack属于独立发布的集成包源码维护在 haystack-core-integrations 仓库Haystack 核心仓库内保留的是其 API 参考文档与使用指南。安装方式统一为pip install ollama-haystack前提是你已有一个正在运行的 Ollama 实例本地安装或 Docker 容器均可。由于 Ollama 自带 embedding 与 chat API无需额外配置即可使用。快速启动 Ollama 服务使用 Docker 是启动 Ollama 最快的方式默认端口 11434docker run -d -p 11434:11434 --name ollama ollama/ollama:latest拉取模型例如 Zephyrdocker exec ollama ollama pull zephyr如果你是在本机直接安装的 Ollama则执行ollama pull zephyr小技巧选择具体量化版本。可以在模型卡片中查看可用 tag然后指定版本拉取例如ollama pull zephyr:7b-alpha-q3_K_S。较低的量化级别如 q3占用内存更小适合无 GPU 环境。二、OllamaDocumentEmbedder把文档批量变成向量OllamaDocumentEmbedder计算一组 Document 的 embedding并把得到的向量写回每个 Document 的embedding字段。它使用与 Ollama Library 兼容的 embedding 模型。这些向量是后续向量检索的基础检索时查询向量会与文档向量比较找出最相似的相关文档。它在管线中的典型位置是索引管线的DocumentWriter之前见 使用指南。构造函数与全部参数__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参数默认值说明modelnomic-embed-text使用的 embedding 模型名必须已存在于运行的 Ollama 实例中可用ollama pull拉取urlhttp://localhost:11434正在运行的 Ollama 实例地址Mac/Linux/Docker 默认都是 11434 端口generation_kwargsNone透传给 Ollama 生成端点的可选参数如temperature、top_p等参考 Ollama Modelfile 的合法参数与取值timeout120触发 Ollama API 超时错误前的等待秒数keep_aliveNone控制请求结束后模型在内存中驻留的时间。不设置则用 Ollama 默认值5 分钟。取值方式时长字符串如10m、24h以秒为单位的数字如3600任意负数表示常驻内存如-1或-1m0表示生成响应后立即卸载模型prefix拼接到每段文本开头的字符串suffix拼接到每段文本末尾的字符串progress_barTrue运行时是否显示进度条meta_fields_to_embedNone需要随文档正文一起嵌入的元数据字段列表embedding_separator\n拼接元数据字段与文档正文时使用的分隔符batch_size32每批处理的文档数量dimensionsNone期望的 embedding 输出维度。仅支持实现了Matryoshka Representation LearningMRL的模型如nomic-embed-text-v1.5、mxbai-embed-large、qwen3-embedding。为None默认时返回完整向量。该参数要求ollama-python 0.6.2参数要点解读meta_fields_to_embedembedding_separator是一对组合当你希望“带上下文的文档”获得更好检索效果时可以把来源、章节等元数据拼进文本一起向量化分隔符控制拼接格式prefix/suffix可用于按模型要求添加指令式前后缀部分 embedding 模型对输入格式敏感batch_size决定一次请求送入多少文档批量过小会增加请求次数过大可能超出模型输入限制dimensions对 MRL 模型非常实用可以输出降维向量显著减少向量存储与检索开销代价是精度略降。独立使用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, ... ]run 方法签名与返回值run( documents: list[Document], generation_kwargs: dict[str, Any] | None None ) - dict[str, list[Document] | dict[str, Any]]documents待向量化的 Document 列表generation_kwargs可选调用时临时覆盖/追加传给 Ollama 生成端点的参数。返回字典包含两个键documents已附加 embedding 信息的 Document 列表meta嵌入过程中收集到的元数据。元数据说明组件会自动把所用模型名写入返回的meta中。使用nomic-embed-text时的返回形如{meta: {model: nomic-embed-text}}放进索引管线文档处理 → 向量化 → 入库以下示例把 PDF 转换、清洗、切分、向量化、写入 Document Store 串成一条完整索引管线DocumentStore使用余弦相似度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() 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) 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}}三、OllamaTextEmbedder把查询变成向量OllamaTextEmbedder计算单个字符串的 embedding用于查询侧。进行向量检索时先用它把查询转成向量再由 embedding Retriever 用该向量在文档集合中检索相似文档。它在管线中的典型位置是查询/RAG 管线中 embedding Retriever 之前。选择原则embed 一段字符串用OllamaTextEmbedderembed 一组文档用OllamaDocumentEmbedder。构造函数与全部参数__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相比 DocumentEmbedderTextEmbedder 更精简其余参数语义完全一致model默认nomic-embed-text须已存在于运行的 Ollama 实例url默认http://localhost:11434generation_kwargs透传给 Ollama 生成端点的可选参数temperature、top_p等timeoutAPI 超时秒数默认120keep_alive模型驻留内存策略规则同 DocumentEmbedder时长字符串 / 秒数 / 负数常驻 /0立即卸载dimensionsMRL 模型可指定输出维度如nomic-embed-text-v1.5、mxbai-embed-large、qwen3-embeddingNone时返回完整向量。run 方法签名与返回值run( text: str, generation_kwargs: dict[str, Any] | None None ) - dict[str, list[float] | dict[str, Any]]text待向量化的字符串generation_kwargs调用时临时覆盖/追加的生成参数。返回字典包含两个键embedding计算得到的向量float 列表meta嵌入过程收集的元数据同样会自动附带模型名如{model: nomic-embed-text}。独立使用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])组装完整的本地 RAG 检索管线索引侧用OllamaDocumentEmbedder写入带向量的文档查询侧用OllamaTextEmbedderInMemoryEmbeddingRetriever召回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])这里InMemoryEmbeddingRetriever是 Haystack 核心自带的组件见 源码它接收query_embedding输入在 Document Store 中对所有文档向量计算相似度并返回 top-k 文档。至此你已拥有一套完全本地化的语义检索能力。四、OllamaChatGenerator本地 LLM 对话、流式与工具调用OllamaChatGenerator是面向 Ollama 服务的 Chat Generator支持流式输出、工具调用Tool Calls、思考模式Reasoning与结构化输出Structured Outputs。它基于 Ollama 的 chat API通过ChatMessage对象进行多轮对话。它的典型管线位置是ChatPromptBuilder之后见 使用指南。构造函数与全部参数__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参数默认值说明modelqwen3:0.6b模型名必须已经 pull 到运行的 Ollama 实例中urlhttp://localhost:11434Ollama 服务的基础 URLgeneration_kwargsNone透传给 Ollama 生成端点的可选参数temperature、top_p等timeout120API 超时秒数max_retries0失败请求HTTP 429、5xx、连接/超时错误的最大重试次数使用指数退避默认0表示不重试keep_aliveNone模型驻留内存策略规则同 Embedder时长字符串 / 秒数 / 负数常驻 /0立即卸载streaming_callbackNone每收到一个流式 token 时被调用的回调函数接收StreamingChunk参数提供后组件进入流式模式toolsNone模型可为其准备调用的 Tool 和/或 Toolset 对象列表或单个 Toolset。每个工具名需唯一。并非所有模型支持工具兼容模型见 Ollama 官网工具模型列表response_formatNone结构化输出格式None原样返回json返回 JSON 对象JSON Schema返回符合该 Schema 的 JSON 对象需要 Ollama ≥ 0.1.34thinkFalse若为True模型在产出回复前先“思考”。仅支持思考类模型部分模型如gpt-oss支持low/medium/high三档思考强度。中间“思考”输出可通过返回的ChatMessage的reasoning属性查看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输入消息。可以是ChatMessage列表如果是字符串会被自动转换成包含一条 user 角色的ChatMessagegeneration_kwargs单次调用的生成参数覆盖会与实例级generation_kwargs合并实例级为底调用级覆盖其上tools本次调用传入的工具若设置则覆盖初始化时的tools参数streaming_callback运行时传入的回调与构造函数中的回调一样会把组件切换为流式模式运行时回调优先于初始化回调。返回字典包含一个键replies模型回复的ChatMessage列表。此外run_async提供异步版本签名与语义相同便于在异步管线中调用。生命周期方法与序列化OllamaChatGenerator与其他 Haystack 组件一样实现了一组标准的生命周期/序列化方法warm_up()/warm_up_async()创建同步/异步的 Ollama 客户端通常由管线在首次运行前自动预热close()/close_async()关闭同步/异步客户端释放连接资源to_dict()把组件序列化为字典from_dict(data)从字典反序列化组件。Embedder 组件同样实现了warm_up/warm_up_async/close/close_async用于管理 Ollama 客户端连接的生命周期。独立使用基础对话from haystack_integrations.components.generators.ollama import OllamaChatGenerator from haystack.dataclasses import ChatMessage generator OllamaChatGenerator( modelzephyr, urlhttp://localhost:11434, generation_kwargs{ num_predict: 100, temperature: 0.9, }, ) messages [ ChatMessage.from_system(\nYou are a helpful, respectful and honest assistant), ChatMessage.from_user(Whats Natural Language Processing?), ] print(generator.run(messagesmessages))返回结果是一个包含replies的字典其中每个ChatMessage带有 assistant 角色、文本内容以及模型元数据_meta中含model: zephyr等信息{ replies: [ ChatMessage( _roleChatRole.ASSISTANT: assistant, _content[TextContent(textNatural Language Processing (NLP) is a subfield of ...)], _nameNone, _meta{model: zephyr, ...}, ) ] }多模态输入部分模型如llava支持图像输入。把ImageContent作为ChatMessage的内容片段传入即可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.工具调用Tool 与 Toolset 的灵活组合tools参数接受非常灵活的工具配置Tool 对象列表逐个传入独立工具单个 Toolset直接传入整个 Toolset混合模式在同一个列表中混入多个 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]) # 混合传入 Toolset 与 Tool 对象 generator OllamaChatGenerator( modelllama2, tools[math_toolset, weather_tool, news_tool], # Toolset 与 Tool 的混合 )更常见的做法是用create_tool_from_function把普通 Python 函数包装成工具参考 工具相关文档 与 Toolset 文档。流式输出把回调传给streaming_callback即可逐 token 输出。最简单的方式是使用内置的print_streaming_chunk它能统一打印文本 token 与工具事件工具调用和工具结果from haystack.components.generators.utils import print_streaming_chunk # 任意 Generator/ChatGenerator 都可以配置流式回调 component SomeGeneratorOrChatGenerator(streaming_callbackprint_streaming_chunk) # ChatGenerator 传消息列表 # component.run([ChatMessage.from_user(Your question here)])注意流式模式只支持单条回复。如果某个服务商支持多个候选回复需要设置n1。StreamingChunk的字段设计见 haystack/dataclasses/streaming_chunk.py决定了回调的写法——每个 chunk 恰好表示以下四种情况之一Tool calls模型正在构造工具调用读chunk.tool_callsTool result工具执行完毕返回结果读chunk.tool_call_resultText tokens普通助手文本读chunk.contentReasoning tokens思考模型的扩展思考输出读chunk.reasoning。一个 chunk 中只会出现上述字段之一源码中__post_init__会校验content、tool_calls、tool_call_result、reasoning只能设置一个。可用chunk.start与chunk.finish_reason判断边界用chunk.index与chunk.component_info做追踪。在异步上下文run_async中StreamingCallbackT同时接受同步与异步回调若向run_async传入同步回调会记录警告可能阻塞事件循环但运行仍会继续反向向同步run传异步回调则会直接报错。流式 工具调用把tools与streaming_callback同时传入即可边流式边调用工具当模型决定调用工具时流式 chunk 携带的是工具调用增量而非文本 token最终重建出的ChatMessage会把解析好的tool_calls列表暴露在replies[0]上。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 与工具事件。结构化输出与思考模式response_format参数让输出结果可预测None不施加任何结构原样返回json输出被格式化为一个 JSON 对象JSON Schema输出为符合指定 JSON Schema 的 JSON 对象需要 Ollama ≥ 0.1.34。think参数用于思考类模型Ollama 官网有专门的 thinking 模型筛选设为True让模型先思考再作答部分模型支持low/medium/high强度档位中间的思考过程可以通过返回的ChatMessage.reasoning属性读取。放进对话管线配合ChatPromptBuilder可以搭建模板化对话管线这里展示一个“无论输入什么语言都用西班牙语回答”的示例from 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, } } ) )ChatMessage是 Haystack 核心的数据类文档包含消息内容、角色user、assistant、system、tool以及可选元数据是贯穿整套 Agent/RAG 对话链路的基本单元。五、组件对照速查组件输入输出典型位置OllamaDocumentEmbedderdocuments: list[Document]documents带向量、meta索引管线中DocumentWriter之前OllamaTextEmbeddertext: strembedding、meta查询/RAG 管线中 embedding Retriever 之前OllamaChatGeneratormessages: list[ChatMessage] \| strreplies: list[ChatMessage]ChatPromptBuilder之后三者共用一致的连接管理约定都提供warm_up/warm_up_async创建同步/异步 Ollama 客户端与close/close_async关闭客户端OllamaChatGenerator额外提供to_dict/from_dict序列化支持。三者默认 URL 均为http://localhost:11434。六、进一步阅读Ollama 集成 API 参考当前主分支OllamaDocumentEmbedder 使用指南OllamaTextEmbedder 使用指南OllamaChatGenerator 使用指南Generator 选型指南含流式、自托管方案对比ChatMessage 数据类说明StreamingChunk 源码【免费下载链接】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），仅供参考