1. 多轮对话客服系统的整体架构设计思路1.1 为什么选择这套技术栈组合做多轮对话客服系统最核心的诉求就三个能记住上下文、能查私有知识、能本地跑起来不烧钱。市面上方案很多但真正能同时满足这三点的组合并不多。我试过纯调云端API的做法效果确实好但成本随对话量线性上涨而且数据要出本地很多做企业内部客服的场景根本过不了合规这一关。后来转向本地化方案最终锁定Python Ollama Chroma LangChain这套组合用下来最顺手。拆开说各自的定位。Ollama负责把大模型跑在本地它把模型下载、量化、推理服务封装成一条命令不用自己去折腾CUDA版本和显存分配对个人开发者极其友好。Chroma是轻量级向量数据库专门存知识库的向量表示支持持久化到本地磁盘重启不丢数据而且它的Python客户端API设计得很直觉几行代码就能建集合、加文档、做相似度检索。LangChain是胶水层把模型调用、提示词模板、检索器、对话历史管理这些零件串成一条链尤其是它的ConversationBufferMemory和RetrievalQA这类封装省掉大量重复代码。Python就不用多说了整个生态的底座。这套组合最大的优势是全本地、可离线、零调用成本。模型权重下载一次之后断网也能跑。对于做内部知识库客服、售后问答机器人这类场景数据不出内网安全性和成本都控制得住。当然代价是本地模型的能力上限不如云端旗舰模型但对于客服这种领域相对收敛的任务7B到14B级别的模型配合好的知识库检索效果完全够用。1.2 多轮对话与单轮问答的本质区别很多人第一次做客服系统容易把它当成单轮问答来做——用户问一句系统查一次知识库返回一个答案。这样做出来的东西用户问第二句“那它多少钱”的时候就懵了因为它不知道“它”指的是上一句里的哪个产品。多轮对话的核心难点在于指代消解和上下文继承。具体来说多轮对话系统需要维护一个对话状态这个状态里至少包含历史问答对、当前话题、用户提到的实体产品名、订单号等。当用户说“它的保修期多久”时系统要能从历史里找到“它”指代的对象把这个问题改写成“XX产品的保修期多久”再去检索知识库。这个改写动作行话叫Query Rewriting查询重写是多轮客服系统里最关键的一环也是新手最容易忽略的地方。我在实际项目里踩过的坑是一开始直接把用户当前这句话丢给向量库检索结果多轮场景下检索命中率惨不忍睹。后来加了查询重写这一步命中率直接翻倍。所以这套系统的架构里查询重写模块是必须有的不能省。1.3 整体数据流与模块划分把整个系统拆开数据流大致是这样的用户输入进来先经过查询重写模块结合历史对话把当前问题补全成独立完整的问题然后这个完整问题进入检索模块Chroma 做向量相似度搜索召回最相关的若干知识片段接着提示词组装模块把检索结果、历史对话、系统指令拼成一个完整的prompt最后Ollama推理模块调用本地模型生成回答回答再写回对话历史等待下一轮。模块划分上我建议分成四层接入层处理用户输入输出可以是命令行、Web API、或者接微信/网页的接口、对话管理层维护会话状态、历史记录、查询重写、检索层Chroma向量库的增删改查、模型层Ollama的调用封装。分层的好处是每一层可以独立替换比如以后想把Chroma换成别的向量库只动检索层就行上层无感知。提示不要一上来就追求微服务架构个人项目或者小团队用单进程Python脚本完全够用模块之间用函数调用而不是网络请求调试起来简单十倍。等真的扛不住并发量了再拆。2. 环境搭建与核心组件安装实操2.1 Python环境准备与虚拟环境隔离Python版本我建议用3.10 或 3.11这两个版本对LangChain和Chroma的兼容性最好。3.12虽然新但有些依赖包的wheel还没跟上装的时候容易编译报错。装Python本身去官网下载安装包就行Windows记得勾选“Add Python to PATH”Linux用系统包管理器或者源码编译都可以。装完第一件事是建虚拟环境千万别在全局环境里装这些库依赖冲突能把你搞崩溃。用venv或者conda都行python -m venv venv # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate用conda的话conda create -n chatbot python3.11 conda activate chatbot虚拟环境激活后命令行前面会出现(venv)或(chatbot)标识看到这个就说明隔离成功了。这一步看着简单但我见过太多人跳过这步最后pip装了几百个包互相打架重装系统的心都有。2.2 Ollama安装与模型拉取避坑Ollama的安装Windows和Mac直接去官网下安装包双击一路下一步。Linux用一条curl脚本就能装。装完之后验证一下ollama --version能打印版本号就说明装好了。接下来是拉模型这是新手最容易卡住的地方——下载慢。默认从官方源拉国内网络环境下经常几KB每秒一个7B模型要下好几个小时。解决办法是配置国内镜像源设置环境变量OLLAMA_HOST指向镜像地址或者用一些社区维护的镜像加速服务。具体镜像地址会变建议去Ollama的社区文档查最新的。模型选择上客服场景我推荐qwen2.5:7b或者qwen2.5:14b中文能力强指令遵循好。如果机器显存有限用qwen2.5:3b也能跑但复杂问题的推理能力会弱一些。拉模型命令ollama pull qwen2.5:7b拉完之后测试一下能不能正常推理ollama run qwen2.5:7b 你好请介绍一下你自己如果报500 internal server error: llama-server process这类错误通常是显存不够或者模型文件损坏。先检查显存占用关掉其他吃显存的程序还不行就删掉模型重新拉ollama rm qwen2.5:7b ollama pull qwen2.5:7b注意Ollama默认把模型存在系统盘7B模型大概4-5GB14B要9GB左右。如果系统盘空间紧张提前设置OLLAMA_MODELS环境变量把模型目录挪到大盘上不然装到一半磁盘满了很尴尬。2.3 LangChain与Chroma依赖安装这两个库用pip装就行但要注意版本匹配。LangChain生态更新极快不同版本API差异很大建议锁定版本pip install langchain0.2.16 pip install langchain-community0.2.16 pip install langchain-ollama0.1.3 pip install chromadb0.5.5 pip install sentence-transformers3.0.1这里解释一下为什么装langchain-ollama这个独立包。LangChain从0.2版本开始把各家模型的集成拆成了独立包langchain-ollama就是专门对接Ollama的比老版本用Ollama类的方式更规范。sentence-transformers是用来做文本向量化的Chroma本身不带embedding能力需要外挂一个embedding模型。embedding模型我推荐BAAI/bge-small-zh-v1.5或者bge-m3中文语义表示效果好模型也不大。第一次用会自动从HuggingFace下载如果下载慢可以设置HF_ENDPOINT环境变量指向国内镜像。装完之后跑个import测试import langchain import chromadb from langchain_ollama import OllamaLLM print(all ok)没报错就说明环境齐了。2.4 目录结构与配置文件规划项目目录我习惯这样组织清晰且好扩展chatbot/ ├── config.py # 配置项集中管理 ├── llm_client.py # Ollama调用封装 ├── vector_store.py # Chroma操作封装 ├── query_rewriter.py # 查询重写模块 ├── dialog_manager.py # 对话状态管理 ├── main.py # 入口 ├── data/ # 知识库原始文档 └── chroma_db/ # Chroma持久化目录config.py里放模型名、向量库路径、检索top_k、温度等参数改配置不用翻代码。这个习惯在项目变大之后能救命尤其是要同时维护测试环境和生产环境的时候。3. 知识库构建与向量检索核心实现3.1 文档加载与文本切分策略知识库的质量直接决定客服系统的上限。原始文档可能是PDF、Word、Markdown、Excel各种格式LangChain提供了对应的LoaderPyPDFLoader、Docx2txtLoader、UnstructuredMarkdownLoader等等。加载进来是一堆Document对象每个对象有page_content和metadata。接下来是文本切分这一步极其关键。切得太碎语义不完整检索出来的片段答非所问切得太大一个片段里混了好几个主题模型容易被无关信息干扰。我的经验值是chunk_size 设 500-800 字符chunk_overlap 设 50-100 字符。overlap的作用是防止一句话正好被切在中间导致两边都读不通。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap80, separators[\n\n, \n, 。, , , , , , ] )注意separators的顺序它优先按段落切段落太长再按句子切最后才按字符硬切。中文场景一定要把中文标点加进去默认的分隔符是英文的切中文效果很差。实操心得如果你的知识库是FAQ形式一条问答就是一个完整语义单元那就别切了一条一个chunkmetadata里标记好问题类型。强行切分反而破坏语义完整性。3.2 向量化与Chroma持久化存储切分完的chunk要转成向量存进Chroma。向量化用HuggingFaceEmbeddings包装bge模型from langchain_community.embeddings import HuggingFaceEmbeddings embedding HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, model_kwargs{device: cpu}, encode_kwargs{normalize_embeddings: True} )normalize_embeddingsTrue很重要它把向量归一化到单位长度这样余弦相似度计算就等价于点积检索更快更准。存进Chromafrom langchain_community.vectorstores import Chroma vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db, collection_namecustomer_service ) vectorstore.persist()persist_directory指定持久化目录下次启动直接Chroma(persist_directory..., embedding_function...)就能加载不用重新向量化。collection_name相当于数据库里的表名不同知识库用不同collection隔离。这里有个性能细节批量向量化比逐条快得多。from_documents内部会批量处理但如果你自己写循环逐条add速度会慢好几倍。几千条文档的话用默认的批量方式几分钟就搞定。3.3 检索器配置与相似度阈值调优检索器决定了召回哪些片段给模型。基础配置retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 4} )k4表示召回最相似的4个片段。k太小可能漏掉关键信息k太大则塞给模型的上下文过长既慢又容易引入噪声。我的经验是k取3到5之间具体看知识库的粒度。search_type除了similarity还有mmr最大边际相关性。MMR会在相似度和多样性之间做平衡避免召回一堆内容重复的片段。如果你的知识库里有大量近似表述用MMR效果更好retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 4, fetch_k: 10, lambda_mult: 0.5} )fetch_k10表示先取10个候选再从中挑4个多样性最好的。lambda_mult控制多样性权重0偏向多样性1偏向相似度0.5是折中。相似度阈值是另一个关键参数。低于某个阈值的片段说明和问题根本不相关应该丢弃而不是硬塞给模型。Chroma支持score_thresholdretriever vectorstore.as_retriever( search_typesimilarity_score_threshold, search_kwargs{score_threshold: 0.5, k: 4} )阈值设多少要看embedding模型bge系列一般0.4-0.6之间比较合适。设太高会漏召回设太低会引入噪声建议拿一批测试问题跑一下看召回片段的分数分布再定。3.4 检索效果评估与迭代方法知识库建完不能就这么上线得评估检索效果。我的做法是准备一批测试问答对每个问题标注好应该召回哪个文档片段。然后跑检索看top_k里有没有命中正确片段算命中率。如果命中率低排查顺序是先看切分是否合理片段语义是否完整再看embedding模型是否适合领域通用模型对专业术语可能表示不好最后看检索参数k值、阈值。有时候问题出在原始文档本身表述和用户提问方式差异太大这时候可以考虑给文档片段加上同义问法或者用查询扩展技术。我做过一个售后客服的知识库用户问“怎么退货”文档里写的是“商品退回流程”字面差异大但语义相近bge模型能正确召回。但如果用户问“我不想要了怎么办”这种口语化表达就需要embedding模型有足够强的语义泛化能力bge-m3比bge-small在这方面表现更好代价是模型更大、推理更慢。4. 多轮对话管理与查询重写实现4.1 对话历史的存储与截断策略多轮对话要记住历史但历史不能无限增长。模型有上下文窗口限制qwen2.5:7b是32K token看着很大但历史对话加上检索片段加上系统提示很容易就撑满了。而且历史越长推理越慢成本越高。我的策略是滑动窗口 摘要压缩结合。最近N轮对话保留原文更早的对话压缩成一段摘要。N一般取5到10轮。实现上维护一个列表class DialogManager: def __init__(self, max_turns8): self.history [] self.max_turns max_turns def add_turn(self, user_input, ai_output): self.history.append({user: user_input, ai: ai_output}) if len(self.history) self.max_turns: self._compress_old_history() def _compress_old_history(self): old self.history[:-self.max_turns//2] # 调用模型把old压缩成摘要 summary self._summarize(old) self.history [{summary: summary}] self.history[-self.max_turns//2:]摘要压缩会多一次模型调用有额外延迟。如果对延迟敏感可以只做滑动窗口直接丢弃最老的对话。但丢弃有个风险用户可能在第10轮提到一个关键信息第15轮又引用它这时候历史里已经没了系统就答不上来。所以关键实体信息建议单独抽出来存成结构化状态不随历史丢弃。4.2 查询重写的原理与提示词设计查询重写是多轮客服的灵魂。用户说“它多少钱”系统要结合历史改写成“XX产品多少钱”。这个改写用LLM来做最自然给模型一个提示词REWRITE_PROMPT 你是一个查询重写助手。根据下面的对话历史把用户的最新问题改写成不依赖上下文、可以独立理解的完整问题。只输出改写后的问题不要解释。 对话历史 {history} 用户最新问题{question} 改写后的问题把历史格式化成文本填进去调用模型生成改写结果。这里有个技巧改写结果要保留原问题的意图不要添加历史里没有的信息。有时候模型会过度发挥把历史里提到的所有实体都塞进去导致改写后的问题偏离原意。可以在提示词里加一句“如果最新问题本身已经完整直接原样返回”。改写模块的延迟大概几百毫秒对客服场景可以接受。如果追求极致速度可以用小模型专门做改写比如qwen2.5:3b改写任务比生成回答简单小模型够用。4.3 指代消解与上下文继承的工程实现指代消解是查询重写要解决的核心问题。中文里的指代有几种代词指代它、他、这个、那个、省略指代“多少钱”省略了主语、零指代“还有呢”。LLM做指代消解的能力比传统规则方法强很多但也不是百分百准。工程上我加了一层实体追踪。每轮对话结束后用模型或规则从对话里抽取实体产品名、订单号、日期等存到一个实体表里。查询重写时把实体表也作为上下文提供给模型帮助它判断指代对象。这样即使历史被截断了实体信息还在。def extract_entities(text): # 简化示例实际可以用NER模型或让LLM抽取 entities {} # 匹配订单号格式 order_match re.search(r订单[号]?[:]?\s*(\w), text) if order_match: entities[order_id] order_match.group(1) return entities实体追踪还有个好处可以在回答里主动引用比如“您刚才提到的订单12345物流状态是...”用户体验会好很多。4.4 对话状态机的设计与边界处理客服系统不是所有问题都需要查知识库。用户说“你好”不需要检索用户说“转人工”应该直接走转接流程用户骂人应该走安抚话术。这些靠一个对话状态机来路由。我设计的状态有greeting问候、qa知识问答、clarify澄清追问、handoff转人工、fallback兜底。每轮输入先做意图分类判断当前该走哪个状态。意图分类可以用LLM做few-shot也可以训一个小分类模型。边界处理上几个必须考虑的情况检索结果为空怎么办走fallback回复“这个问题我暂时答不上来建议您...”、模型生成超时怎么办设超时时间超时返回兜底话术、用户连续追问同一问题怎么办检测重复主动询问是否没解决。这些细节决定了系统是“能用”还是“好用”。5. 系统集成与完整对话流程串联5.1 LangChain链的组装方式把各个模块串起来LangChain提供了Runnable接口可以用管道符|组合from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser chain ( {context: retriever, question: RunnablePassthrough()} | prompt_template | llm | StrOutputParser() )但多轮对话场景下这个简单链不够用因为要注入历史、要做查询重写。我实际用的是自定义函数串联比硬套LangChain的链更灵活def chat(user_input, session_id): history dialog_manager.get_history(session_id) rewritten query_rewriter.rewrite(user_input, history) docs retriever.invoke(rewritten) context \n\n.join([d.page_content for d in docs]) prompt build_prompt(context, history, user_input) answer llm.invoke(prompt) dialog_manager.add_turn(session_id, user_input, answer) return answer这样每一步都清晰可控出问题好定位。LangChain的价值在于它提供了retriever、embedding、llm这些标准组件而不是非要你用它的链式语法。5.2 提示词模板的工程化设计提示词模板决定了模型输出的质量。客服场景的模板我一般包含这几块角色设定、知识库上下文、对话历史、当前问题、输出要求。PROMPT_TEMPLATE 你是一个专业的客服助手请根据下面的知识库内容回答用户问题。 要求 1. 只根据知识库内容回答不要编造信息 2. 如果知识库中没有相关信息如实告知用户 3. 回答要简洁、友好、专业 4. 涉及数字、日期、金额时务必准确 知识库内容 {context} 对话历史 {history} 用户问题{question} 回答几个细节“只根据知识库回答”这句能显著降低幻觉率但也不能保证百分百模型有时候还是会自由发挥。“如实告知”给了模型一个退路避免它硬编。输出要求里明确“简洁”能防止模型啰嗦。实操心得提示词里的顺序有讲究。把知识库放在前面、问题放在后面模型对最近的内容注意力更强回答更聚焦。如果反过来模型容易被历史对话带偏。5.3 流式输出与响应速度优化客服系统用户对延迟很敏感等5秒才出字体验很差。Ollama支持流式输出LangChain也封装了stream方法for chunk in llm.stream(prompt): print(chunk, end, flushTrue)流式输出让用户看到字一个个蹦出来感知延迟大幅降低。虽然总时间没变但体验好很多。响应速度优化还有几个方向检索加速Chroma建索引数据量大时用HNSW、模型量化用q4量化版模型速度快一倍质量损失很小、缓存相同问题直接返回缓存答案。缓存对客服场景特别有效因为用户问的问题重复率很高热门问题缓存命中率能到30%以上。5.4 会话隔离与并发处理多个用户同时用会话必须隔离。每个用户分配一个session_id对话历史按session_id分开存。简单实现用字典sessions {} # {session_id: DialogManager}但字典在内存里进程重启就丢了。生产环境要持久化可以存Redis或者SQLite。并发方面Python的GIL限制了多线程CPU并行但Ollama推理是IO密集等模型返回用异步或者多线程能提升吞吐。FastAPI配async def接口是常见做法。如果并发量真的上来了单机Ollama扛不住可以考虑多实例部署加负载均衡或者用vLLM这类高吞吐推理框架替换Ollama。但那是另一个量级的工程了个人项目和小团队用Ollama单实例足够。6. 常见问题排查与实战避坑指南6.1 模型加载与推理报错速查实际跑起来会遇到各种报错我整理了一张速查表报错信息可能原因解决办法500 internal server error: llama-server process显存不足或模型损坏关其他程序释放显存或删模型重拉model not found模型名写错或没拉取ollama list确认模型名ollama pull拉取connection refusedOllama服务没启动ollama serve启动服务context length exceeded输入超过模型上下文窗口减少历史轮数或检索片段数CUDA out of memory显存不够换小模型或用量化版context length exceeded这个特别常见因为很多人不控制历史长度。qwen2.5:7b虽然标称32K但实际用的时候输入越长推理越慢建议控制在8K以内。6.2 检索不准的排查思路检索不准的表现是明明知识库里有答案但模型说不知道或者答非所问。排查步骤第一步单独测检索。把用户问题直接丢给retriever看召回的片段是什么。如果召回的就是无关内容问题在检索层如果召回正确但模型答错问题在生成层。第二步检查切分。把召回的片段打印出来看是不是被切得七零八落语义不完整。如果是调整chunk_size和overlap。第三步检查embedding。用几个语义相近但表述不同的句子测embedding相似度看模型能不能正确判断。如果相似度区分度低换更强的embedding模型。第四步检查查询重写。多轮场景下如果重写后的query偏离原意检索肯定不准。把重写结果打印出来人工检查。6.3 回答质量差的调优手段回答质量差有几种表现答非所问、编造信息、啰嗦、格式乱。对应调优手段答非所问通常是检索没召回正确内容或者提示词没约束好。先解决检索再在提示词里强调“根据以下内容回答”。编造信息降低temperature设0.1-0.3提示词里加“不知道就说不知道”检索时提高相似度阈值过滤噪声。啰嗦提示词里明确“回答控制在100字以内”或者用few-shot给几个简洁回答的示例。格式乱提示词里规定输出格式比如“用分点列表回答”或者用输出解析器后处理。temperature这个参数值得单独说。客服场景我建议设0.1到0.3要的是稳定准确不是创意。设太高模型会自由发挥设0又可能过于死板。0.2是个不错的平衡点。6.4 性能瓶颈定位与优化清单系统跑起来慢定位瓶颈的方法是在每个环节打时间戳import time t0 time.time() rewritten query_rewriter.rewrite(user_input, history) t1 time.time() docs retriever.invoke(rewritten) t2 time.time() answer llm.invoke(prompt) t3 time.time() print(f重写:{t1-t0:.2f}s 检索:{t2-t1:.2f}s 生成:{t3-t2:.2f}s)一般生成占大头7B模型生成100字大概2-5秒看硬件。检索通常几十毫秒重写几百毫秒。如果检索特别慢检查Chroma的索引和集合大小如果生成特别慢考虑换量化模型或升级硬件。优化清单按性价比排序流式输出体验提升最大改动最小、缓存热门问答命中率高时效果显著、模型量化速度翻倍质量损失小、减少检索片段数k从5降到3上下文短了生成快、升级硬件GPU比CPU快一个数量级但成本高。6.5 上线前的检查清单系统开发完准备上线过一遍这个清单知识库覆盖度测试问题集里多少能正确回答目标80%以上兜底话术检索为空、模型超时、异常输入都有兜底回复会话隔离多用户并发测试确认历史不串持久化重启后知识库和会话状态能恢复日志每轮对话的输入、检索结果、输出都记日志方便排查限流防止单用户高频请求打爆服务敏感词过滤用户输入和模型输出都过一遍过滤我个人在实际操作中的体会是知识库的质量比模型的选择重要得多。同样的模型知识库整理得好回答准确率能到90%知识库乱七八糟再强的模型也救不回来。所以前期在文档整理、切分策略、测试集构建上多花时间后期调优会轻松很多。另外多轮对话系统一定要用真实的多轮场景去测单轮测试通过不代表多轮没问题指代消解和上下文继承的坑只有多轮测试才能暴露出来。
基于Python+Ollama+Chroma+LangChain的多轮对话客服系统实战
1. 多轮对话客服系统的整体架构设计思路1.1 为什么选择这套技术栈组合做多轮对话客服系统最核心的诉求就三个能记住上下文、能查私有知识、能本地跑起来不烧钱。市面上方案很多但真正能同时满足这三点的组合并不多。我试过纯调云端API的做法效果确实好但成本随对话量线性上涨而且数据要出本地很多做企业内部客服的场景根本过不了合规这一关。后来转向本地化方案最终锁定Python Ollama Chroma LangChain这套组合用下来最顺手。拆开说各自的定位。Ollama负责把大模型跑在本地它把模型下载、量化、推理服务封装成一条命令不用自己去折腾CUDA版本和显存分配对个人开发者极其友好。Chroma是轻量级向量数据库专门存知识库的向量表示支持持久化到本地磁盘重启不丢数据而且它的Python客户端API设计得很直觉几行代码就能建集合、加文档、做相似度检索。LangChain是胶水层把模型调用、提示词模板、检索器、对话历史管理这些零件串成一条链尤其是它的ConversationBufferMemory和RetrievalQA这类封装省掉大量重复代码。Python就不用多说了整个生态的底座。这套组合最大的优势是全本地、可离线、零调用成本。模型权重下载一次之后断网也能跑。对于做内部知识库客服、售后问答机器人这类场景数据不出内网安全性和成本都控制得住。当然代价是本地模型的能力上限不如云端旗舰模型但对于客服这种领域相对收敛的任务7B到14B级别的模型配合好的知识库检索效果完全够用。1.2 多轮对话与单轮问答的本质区别很多人第一次做客服系统容易把它当成单轮问答来做——用户问一句系统查一次知识库返回一个答案。这样做出来的东西用户问第二句“那它多少钱”的时候就懵了因为它不知道“它”指的是上一句里的哪个产品。多轮对话的核心难点在于指代消解和上下文继承。具体来说多轮对话系统需要维护一个对话状态这个状态里至少包含历史问答对、当前话题、用户提到的实体产品名、订单号等。当用户说“它的保修期多久”时系统要能从历史里找到“它”指代的对象把这个问题改写成“XX产品的保修期多久”再去检索知识库。这个改写动作行话叫Query Rewriting查询重写是多轮客服系统里最关键的一环也是新手最容易忽略的地方。我在实际项目里踩过的坑是一开始直接把用户当前这句话丢给向量库检索结果多轮场景下检索命中率惨不忍睹。后来加了查询重写这一步命中率直接翻倍。所以这套系统的架构里查询重写模块是必须有的不能省。1.3 整体数据流与模块划分把整个系统拆开数据流大致是这样的用户输入进来先经过查询重写模块结合历史对话把当前问题补全成独立完整的问题然后这个完整问题进入检索模块Chroma 做向量相似度搜索召回最相关的若干知识片段接着提示词组装模块把检索结果、历史对话、系统指令拼成一个完整的prompt最后Ollama推理模块调用本地模型生成回答回答再写回对话历史等待下一轮。模块划分上我建议分成四层接入层处理用户输入输出可以是命令行、Web API、或者接微信/网页的接口、对话管理层维护会话状态、历史记录、查询重写、检索层Chroma向量库的增删改查、模型层Ollama的调用封装。分层的好处是每一层可以独立替换比如以后想把Chroma换成别的向量库只动检索层就行上层无感知。提示不要一上来就追求微服务架构个人项目或者小团队用单进程Python脚本完全够用模块之间用函数调用而不是网络请求调试起来简单十倍。等真的扛不住并发量了再拆。2. 环境搭建与核心组件安装实操2.1 Python环境准备与虚拟环境隔离Python版本我建议用3.10 或 3.11这两个版本对LangChain和Chroma的兼容性最好。3.12虽然新但有些依赖包的wheel还没跟上装的时候容易编译报错。装Python本身去官网下载安装包就行Windows记得勾选“Add Python to PATH”Linux用系统包管理器或者源码编译都可以。装完第一件事是建虚拟环境千万别在全局环境里装这些库依赖冲突能把你搞崩溃。用venv或者conda都行python -m venv venv # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate用conda的话conda create -n chatbot python3.11 conda activate chatbot虚拟环境激活后命令行前面会出现(venv)或(chatbot)标识看到这个就说明隔离成功了。这一步看着简单但我见过太多人跳过这步最后pip装了几百个包互相打架重装系统的心都有。2.2 Ollama安装与模型拉取避坑Ollama的安装Windows和Mac直接去官网下安装包双击一路下一步。Linux用一条curl脚本就能装。装完之后验证一下ollama --version能打印版本号就说明装好了。接下来是拉模型这是新手最容易卡住的地方——下载慢。默认从官方源拉国内网络环境下经常几KB每秒一个7B模型要下好几个小时。解决办法是配置国内镜像源设置环境变量OLLAMA_HOST指向镜像地址或者用一些社区维护的镜像加速服务。具体镜像地址会变建议去Ollama的社区文档查最新的。模型选择上客服场景我推荐qwen2.5:7b或者qwen2.5:14b中文能力强指令遵循好。如果机器显存有限用qwen2.5:3b也能跑但复杂问题的推理能力会弱一些。拉模型命令ollama pull qwen2.5:7b拉完之后测试一下能不能正常推理ollama run qwen2.5:7b 你好请介绍一下你自己如果报500 internal server error: llama-server process这类错误通常是显存不够或者模型文件损坏。先检查显存占用关掉其他吃显存的程序还不行就删掉模型重新拉ollama rm qwen2.5:7b ollama pull qwen2.5:7b注意Ollama默认把模型存在系统盘7B模型大概4-5GB14B要9GB左右。如果系统盘空间紧张提前设置OLLAMA_MODELS环境变量把模型目录挪到大盘上不然装到一半磁盘满了很尴尬。2.3 LangChain与Chroma依赖安装这两个库用pip装就行但要注意版本匹配。LangChain生态更新极快不同版本API差异很大建议锁定版本pip install langchain0.2.16 pip install langchain-community0.2.16 pip install langchain-ollama0.1.3 pip install chromadb0.5.5 pip install sentence-transformers3.0.1这里解释一下为什么装langchain-ollama这个独立包。LangChain从0.2版本开始把各家模型的集成拆成了独立包langchain-ollama就是专门对接Ollama的比老版本用Ollama类的方式更规范。sentence-transformers是用来做文本向量化的Chroma本身不带embedding能力需要外挂一个embedding模型。embedding模型我推荐BAAI/bge-small-zh-v1.5或者bge-m3中文语义表示效果好模型也不大。第一次用会自动从HuggingFace下载如果下载慢可以设置HF_ENDPOINT环境变量指向国内镜像。装完之后跑个import测试import langchain import chromadb from langchain_ollama import OllamaLLM print(all ok)没报错就说明环境齐了。2.4 目录结构与配置文件规划项目目录我习惯这样组织清晰且好扩展chatbot/ ├── config.py # 配置项集中管理 ├── llm_client.py # Ollama调用封装 ├── vector_store.py # Chroma操作封装 ├── query_rewriter.py # 查询重写模块 ├── dialog_manager.py # 对话状态管理 ├── main.py # 入口 ├── data/ # 知识库原始文档 └── chroma_db/ # Chroma持久化目录config.py里放模型名、向量库路径、检索top_k、温度等参数改配置不用翻代码。这个习惯在项目变大之后能救命尤其是要同时维护测试环境和生产环境的时候。3. 知识库构建与向量检索核心实现3.1 文档加载与文本切分策略知识库的质量直接决定客服系统的上限。原始文档可能是PDF、Word、Markdown、Excel各种格式LangChain提供了对应的LoaderPyPDFLoader、Docx2txtLoader、UnstructuredMarkdownLoader等等。加载进来是一堆Document对象每个对象有page_content和metadata。接下来是文本切分这一步极其关键。切得太碎语义不完整检索出来的片段答非所问切得太大一个片段里混了好几个主题模型容易被无关信息干扰。我的经验值是chunk_size 设 500-800 字符chunk_overlap 设 50-100 字符。overlap的作用是防止一句话正好被切在中间导致两边都读不通。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap80, separators[\n\n, \n, 。, , , , , , ] )注意separators的顺序它优先按段落切段落太长再按句子切最后才按字符硬切。中文场景一定要把中文标点加进去默认的分隔符是英文的切中文效果很差。实操心得如果你的知识库是FAQ形式一条问答就是一个完整语义单元那就别切了一条一个chunkmetadata里标记好问题类型。强行切分反而破坏语义完整性。3.2 向量化与Chroma持久化存储切分完的chunk要转成向量存进Chroma。向量化用HuggingFaceEmbeddings包装bge模型from langchain_community.embeddings import HuggingFaceEmbeddings embedding HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5, model_kwargs{device: cpu}, encode_kwargs{normalize_embeddings: True} )normalize_embeddingsTrue很重要它把向量归一化到单位长度这样余弦相似度计算就等价于点积检索更快更准。存进Chromafrom langchain_community.vectorstores import Chroma vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db, collection_namecustomer_service ) vectorstore.persist()persist_directory指定持久化目录下次启动直接Chroma(persist_directory..., embedding_function...)就能加载不用重新向量化。collection_name相当于数据库里的表名不同知识库用不同collection隔离。这里有个性能细节批量向量化比逐条快得多。from_documents内部会批量处理但如果你自己写循环逐条add速度会慢好几倍。几千条文档的话用默认的批量方式几分钟就搞定。3.3 检索器配置与相似度阈值调优检索器决定了召回哪些片段给模型。基础配置retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 4} )k4表示召回最相似的4个片段。k太小可能漏掉关键信息k太大则塞给模型的上下文过长既慢又容易引入噪声。我的经验是k取3到5之间具体看知识库的粒度。search_type除了similarity还有mmr最大边际相关性。MMR会在相似度和多样性之间做平衡避免召回一堆内容重复的片段。如果你的知识库里有大量近似表述用MMR效果更好retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 4, fetch_k: 10, lambda_mult: 0.5} )fetch_k10表示先取10个候选再从中挑4个多样性最好的。lambda_mult控制多样性权重0偏向多样性1偏向相似度0.5是折中。相似度阈值是另一个关键参数。低于某个阈值的片段说明和问题根本不相关应该丢弃而不是硬塞给模型。Chroma支持score_thresholdretriever vectorstore.as_retriever( search_typesimilarity_score_threshold, search_kwargs{score_threshold: 0.5, k: 4} )阈值设多少要看embedding模型bge系列一般0.4-0.6之间比较合适。设太高会漏召回设太低会引入噪声建议拿一批测试问题跑一下看召回片段的分数分布再定。3.4 检索效果评估与迭代方法知识库建完不能就这么上线得评估检索效果。我的做法是准备一批测试问答对每个问题标注好应该召回哪个文档片段。然后跑检索看top_k里有没有命中正确片段算命中率。如果命中率低排查顺序是先看切分是否合理片段语义是否完整再看embedding模型是否适合领域通用模型对专业术语可能表示不好最后看检索参数k值、阈值。有时候问题出在原始文档本身表述和用户提问方式差异太大这时候可以考虑给文档片段加上同义问法或者用查询扩展技术。我做过一个售后客服的知识库用户问“怎么退货”文档里写的是“商品退回流程”字面差异大但语义相近bge模型能正确召回。但如果用户问“我不想要了怎么办”这种口语化表达就需要embedding模型有足够强的语义泛化能力bge-m3比bge-small在这方面表现更好代价是模型更大、推理更慢。4. 多轮对话管理与查询重写实现4.1 对话历史的存储与截断策略多轮对话要记住历史但历史不能无限增长。模型有上下文窗口限制qwen2.5:7b是32K token看着很大但历史对话加上检索片段加上系统提示很容易就撑满了。而且历史越长推理越慢成本越高。我的策略是滑动窗口 摘要压缩结合。最近N轮对话保留原文更早的对话压缩成一段摘要。N一般取5到10轮。实现上维护一个列表class DialogManager: def __init__(self, max_turns8): self.history [] self.max_turns max_turns def add_turn(self, user_input, ai_output): self.history.append({user: user_input, ai: ai_output}) if len(self.history) self.max_turns: self._compress_old_history() def _compress_old_history(self): old self.history[:-self.max_turns//2] # 调用模型把old压缩成摘要 summary self._summarize(old) self.history [{summary: summary}] self.history[-self.max_turns//2:]摘要压缩会多一次模型调用有额外延迟。如果对延迟敏感可以只做滑动窗口直接丢弃最老的对话。但丢弃有个风险用户可能在第10轮提到一个关键信息第15轮又引用它这时候历史里已经没了系统就答不上来。所以关键实体信息建议单独抽出来存成结构化状态不随历史丢弃。4.2 查询重写的原理与提示词设计查询重写是多轮客服的灵魂。用户说“它多少钱”系统要结合历史改写成“XX产品多少钱”。这个改写用LLM来做最自然给模型一个提示词REWRITE_PROMPT 你是一个查询重写助手。根据下面的对话历史把用户的最新问题改写成不依赖上下文、可以独立理解的完整问题。只输出改写后的问题不要解释。 对话历史 {history} 用户最新问题{question} 改写后的问题把历史格式化成文本填进去调用模型生成改写结果。这里有个技巧改写结果要保留原问题的意图不要添加历史里没有的信息。有时候模型会过度发挥把历史里提到的所有实体都塞进去导致改写后的问题偏离原意。可以在提示词里加一句“如果最新问题本身已经完整直接原样返回”。改写模块的延迟大概几百毫秒对客服场景可以接受。如果追求极致速度可以用小模型专门做改写比如qwen2.5:3b改写任务比生成回答简单小模型够用。4.3 指代消解与上下文继承的工程实现指代消解是查询重写要解决的核心问题。中文里的指代有几种代词指代它、他、这个、那个、省略指代“多少钱”省略了主语、零指代“还有呢”。LLM做指代消解的能力比传统规则方法强很多但也不是百分百准。工程上我加了一层实体追踪。每轮对话结束后用模型或规则从对话里抽取实体产品名、订单号、日期等存到一个实体表里。查询重写时把实体表也作为上下文提供给模型帮助它判断指代对象。这样即使历史被截断了实体信息还在。def extract_entities(text): # 简化示例实际可以用NER模型或让LLM抽取 entities {} # 匹配订单号格式 order_match re.search(r订单[号]?[:]?\s*(\w), text) if order_match: entities[order_id] order_match.group(1) return entities实体追踪还有个好处可以在回答里主动引用比如“您刚才提到的订单12345物流状态是...”用户体验会好很多。4.4 对话状态机的设计与边界处理客服系统不是所有问题都需要查知识库。用户说“你好”不需要检索用户说“转人工”应该直接走转接流程用户骂人应该走安抚话术。这些靠一个对话状态机来路由。我设计的状态有greeting问候、qa知识问答、clarify澄清追问、handoff转人工、fallback兜底。每轮输入先做意图分类判断当前该走哪个状态。意图分类可以用LLM做few-shot也可以训一个小分类模型。边界处理上几个必须考虑的情况检索结果为空怎么办走fallback回复“这个问题我暂时答不上来建议您...”、模型生成超时怎么办设超时时间超时返回兜底话术、用户连续追问同一问题怎么办检测重复主动询问是否没解决。这些细节决定了系统是“能用”还是“好用”。5. 系统集成与完整对话流程串联5.1 LangChain链的组装方式把各个模块串起来LangChain提供了Runnable接口可以用管道符|组合from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser chain ( {context: retriever, question: RunnablePassthrough()} | prompt_template | llm | StrOutputParser() )但多轮对话场景下这个简单链不够用因为要注入历史、要做查询重写。我实际用的是自定义函数串联比硬套LangChain的链更灵活def chat(user_input, session_id): history dialog_manager.get_history(session_id) rewritten query_rewriter.rewrite(user_input, history) docs retriever.invoke(rewritten) context \n\n.join([d.page_content for d in docs]) prompt build_prompt(context, history, user_input) answer llm.invoke(prompt) dialog_manager.add_turn(session_id, user_input, answer) return answer这样每一步都清晰可控出问题好定位。LangChain的价值在于它提供了retriever、embedding、llm这些标准组件而不是非要你用它的链式语法。5.2 提示词模板的工程化设计提示词模板决定了模型输出的质量。客服场景的模板我一般包含这几块角色设定、知识库上下文、对话历史、当前问题、输出要求。PROMPT_TEMPLATE 你是一个专业的客服助手请根据下面的知识库内容回答用户问题。 要求 1. 只根据知识库内容回答不要编造信息 2. 如果知识库中没有相关信息如实告知用户 3. 回答要简洁、友好、专业 4. 涉及数字、日期、金额时务必准确 知识库内容 {context} 对话历史 {history} 用户问题{question} 回答几个细节“只根据知识库回答”这句能显著降低幻觉率但也不能保证百分百模型有时候还是会自由发挥。“如实告知”给了模型一个退路避免它硬编。输出要求里明确“简洁”能防止模型啰嗦。实操心得提示词里的顺序有讲究。把知识库放在前面、问题放在后面模型对最近的内容注意力更强回答更聚焦。如果反过来模型容易被历史对话带偏。5.3 流式输出与响应速度优化客服系统用户对延迟很敏感等5秒才出字体验很差。Ollama支持流式输出LangChain也封装了stream方法for chunk in llm.stream(prompt): print(chunk, end, flushTrue)流式输出让用户看到字一个个蹦出来感知延迟大幅降低。虽然总时间没变但体验好很多。响应速度优化还有几个方向检索加速Chroma建索引数据量大时用HNSW、模型量化用q4量化版模型速度快一倍质量损失很小、缓存相同问题直接返回缓存答案。缓存对客服场景特别有效因为用户问的问题重复率很高热门问题缓存命中率能到30%以上。5.4 会话隔离与并发处理多个用户同时用会话必须隔离。每个用户分配一个session_id对话历史按session_id分开存。简单实现用字典sessions {} # {session_id: DialogManager}但字典在内存里进程重启就丢了。生产环境要持久化可以存Redis或者SQLite。并发方面Python的GIL限制了多线程CPU并行但Ollama推理是IO密集等模型返回用异步或者多线程能提升吞吐。FastAPI配async def接口是常见做法。如果并发量真的上来了单机Ollama扛不住可以考虑多实例部署加负载均衡或者用vLLM这类高吞吐推理框架替换Ollama。但那是另一个量级的工程了个人项目和小团队用Ollama单实例足够。6. 常见问题排查与实战避坑指南6.1 模型加载与推理报错速查实际跑起来会遇到各种报错我整理了一张速查表报错信息可能原因解决办法500 internal server error: llama-server process显存不足或模型损坏关其他程序释放显存或删模型重拉model not found模型名写错或没拉取ollama list确认模型名ollama pull拉取connection refusedOllama服务没启动ollama serve启动服务context length exceeded输入超过模型上下文窗口减少历史轮数或检索片段数CUDA out of memory显存不够换小模型或用量化版context length exceeded这个特别常见因为很多人不控制历史长度。qwen2.5:7b虽然标称32K但实际用的时候输入越长推理越慢建议控制在8K以内。6.2 检索不准的排查思路检索不准的表现是明明知识库里有答案但模型说不知道或者答非所问。排查步骤第一步单独测检索。把用户问题直接丢给retriever看召回的片段是什么。如果召回的就是无关内容问题在检索层如果召回正确但模型答错问题在生成层。第二步检查切分。把召回的片段打印出来看是不是被切得七零八落语义不完整。如果是调整chunk_size和overlap。第三步检查embedding。用几个语义相近但表述不同的句子测embedding相似度看模型能不能正确判断。如果相似度区分度低换更强的embedding模型。第四步检查查询重写。多轮场景下如果重写后的query偏离原意检索肯定不准。把重写结果打印出来人工检查。6.3 回答质量差的调优手段回答质量差有几种表现答非所问、编造信息、啰嗦、格式乱。对应调优手段答非所问通常是检索没召回正确内容或者提示词没约束好。先解决检索再在提示词里强调“根据以下内容回答”。编造信息降低temperature设0.1-0.3提示词里加“不知道就说不知道”检索时提高相似度阈值过滤噪声。啰嗦提示词里明确“回答控制在100字以内”或者用few-shot给几个简洁回答的示例。格式乱提示词里规定输出格式比如“用分点列表回答”或者用输出解析器后处理。temperature这个参数值得单独说。客服场景我建议设0.1到0.3要的是稳定准确不是创意。设太高模型会自由发挥设0又可能过于死板。0.2是个不错的平衡点。6.4 性能瓶颈定位与优化清单系统跑起来慢定位瓶颈的方法是在每个环节打时间戳import time t0 time.time() rewritten query_rewriter.rewrite(user_input, history) t1 time.time() docs retriever.invoke(rewritten) t2 time.time() answer llm.invoke(prompt) t3 time.time() print(f重写:{t1-t0:.2f}s 检索:{t2-t1:.2f}s 生成:{t3-t2:.2f}s)一般生成占大头7B模型生成100字大概2-5秒看硬件。检索通常几十毫秒重写几百毫秒。如果检索特别慢检查Chroma的索引和集合大小如果生成特别慢考虑换量化模型或升级硬件。优化清单按性价比排序流式输出体验提升最大改动最小、缓存热门问答命中率高时效果显著、模型量化速度翻倍质量损失小、减少检索片段数k从5降到3上下文短了生成快、升级硬件GPU比CPU快一个数量级但成本高。6.5 上线前的检查清单系统开发完准备上线过一遍这个清单知识库覆盖度测试问题集里多少能正确回答目标80%以上兜底话术检索为空、模型超时、异常输入都有兜底回复会话隔离多用户并发测试确认历史不串持久化重启后知识库和会话状态能恢复日志每轮对话的输入、检索结果、输出都记日志方便排查限流防止单用户高频请求打爆服务敏感词过滤用户输入和模型输出都过一遍过滤我个人在实际操作中的体会是知识库的质量比模型的选择重要得多。同样的模型知识库整理得好回答准确率能到90%知识库乱七八糟再强的模型也救不回来。所以前期在文档整理、切分策略、测试集构建上多花时间后期调优会轻松很多。另外多轮对话系统一定要用真实的多轮场景去测单轮测试通过不代表多轮没问题指代消解和上下文继承的坑只有多轮测试才能暴露出来。
![OpenClaw 实战06：CLI 命令体系与[特殊字符]龙虾常用命令速查（TaoToken 配置版）](http://pic.xiahunao.cn/yaotu/OpenClaw 实战06：CLI 命令体系与[特殊字符]龙虾常用命令速查（TaoToken 配置版）)
