在企业知识库、个人笔记检索与离线问答场景中，把文档直接交给大模型并不是理想方案：上下文长度有限，知识更新需要重新整理，敏感资料上传云端还可能带来合规压力。一个更实用的思路，是用 Haystack 编排文档处理、检索、提示词构建和答案生成组件，再由 Ollama 在本机提供嵌入与大模型推理能力，从而搭建可替换、可调试、可扩展的本地 RAG 管道。🦙
一、先理解整体架构
完整方案通常拆成两条管道。索引管道负责读取文件、清洗文本、切分片段、生成向量并写入文档库；查询管道负责把问题向量化、召回相关片段、组装提示词，最后调用本地模型生成答案。Haystack 的 Pipeline 本质上是由组件构成的有向多重图，支持分支、循环、并行与异步执行，因此比把所有逻辑塞进一个函数更容易维护。相关概念可参考 Haystack Pipeline 官方文档。
在 Ollama 集成中，常用组件包括 OllamaDocumentEmbedder、OllamaTextEmbedder、OllamaGenerator 和 OllamaChatGenerator：前两个分别处理文档与查询的向量化，后两个分别面向普通文本生成和对话生成。安装集成包可使用 pip install ollama-haystack，具体组件及参数以 Haystack 的 Ollama 集成说明 为准。
二、准备本地运行环境
首先安装 Ollama 并启动服务，然后拉取一个生成模型和一个嵌入模型。例如执行 ollama pull qwen3:8b 与 ollama pull nomic-embed-text。模型名称只是示例，实际选择应结合机器内存、显存、中文能力和响应速度；应用配置中的名称必须与本地已经拉取的模型一致。Ollama 服务通常监听本机 11434 端口，但容器化部署时还要检查端口映射和网络地址。
Python 环境建议独立创建虚拟环境，再安装 Haystack 与 Ollama 集成包。启动开发前可以先访问 Ollama 的模型列表接口，或直接运行一次命令行对话，以排除“模型尚未下载”“服务没有启动”和“容器无法访问宿主机”等基础问题。✅
三、编排索引管道
索引阶段可以按照以下顺序连接组件：
- 文件转换器读取 PDF、TXT、Markdown 或 Office 文档，将内容转换为 Haystack Document。
- DocumentCleaner 清理空白字符、重复页眉页脚及不必要内容。
- DocumentSplitter 按词、句子或段落切分，并设置适当的重叠窗口。
- OllamaDocumentEmbedder 为每个片段生成向量。
- DocumentWriter 将文本、向量和元数据写入 Document Store。
切分策略会直接影响召回质量。片段过大容易混入无关信息，片段过小又可能破坏语义。实践中应根据文档类型分别设置：制度文件适合按标题和段落切分，FAQ 适合保留完整问答，技术手册则应保留章节路径、产品版本和页码等元数据。OllamaDocumentEmbedder 会把生成的向量写入 Document 的 embedding 字段，其参数说明可查看 Ollama 集成 API 参考。
四、编排查询与生成管道
查询管道的典型连接关系是：问题 → OllamaTextEmbedder → 向量检索器 → PromptBuilder → OllamaGenerator。查询嵌入模型必须与索引阶段保持一致，否则向量空间不兼容，检索结果会明显失真。检索器输出的 documents 与用户问题一起传入 PromptBuilder，再由生成组件调用 Ollama。
提示词应明确约束模型“仅依据给定资料回答”，并要求资料不足时直接说明无法确定。可以让模型输出简洁答案，同时附带文档标题、页码或来源编号。这样做不能彻底消除幻觉，却能提高答案的可核查性。若应用需要多轮消息、流式响应、工具调用或结构化输出，可优先评估 OllamaChatGenerator；普通知识库问答使用 OllamaGenerator 往往更直接。
建议的提示结构：
角色与回答规则
检索到的上下文
用户问题
引用格式与资料不足时的处理方式
五、组件连接中的常见问题
- 输入输出名称不匹配：连接 Pipeline 组件时，应检查上游输出字段与下游输入字段，必要时显式指定端口。
- 嵌入模型混用：更换嵌入模型后必须重新生成文档向量，不能继续沿用旧索引。
- 召回内容重复：检查滑动窗口重叠范围，并在写入前按内容哈希或业务主键去重。
- 首轮响应较慢：模型首次加载通常需要时间，可结合 keep_alive 控制模型在内存中的保留周期，但应同步关注资源占用。
- 容器地址错误：Haystack 与 Ollama 分处不同容器时，不能把 localhost 理解为另一容器，需要使用同一容器网络中的服务名。
六、从可运行走向可用
调优时不要只观察最终回答，应分别记录切分结果、召回片段、相似度、提示词长度、模型耗时和完整输出。准备一组来自真实业务的测试问题，并加入“知识库中没有答案”的反例，持续评估召回准确性、引用正确性和拒答表现。🔍
数据量较小时，可以先用内存文档库快速验证流程；数据增多或需要持久化、过滤和并发访问时，再切换到适合生产环境的向量数据库。元数据过滤同样值得重视，例如先限制部门、文档版本或生效日期，再执行向量检索，通常比单纯增加 top_k 更有效。
总结
Ollama 与 Haystack 的组合价值不只是“本地运行模型”，而是把模型推理、向量化、文档存储、检索和提示词构建拆成边界清晰的组件。先建立索引与查询两条最小管道，再围绕切分策略、嵌入一致性、元数据过滤、引用约束和运行观测逐步优化，就能形成一个更可控、更易迭代的本地检索增强生成系统。🚀
