今天是我给自用AI助手“断奶”的第19天。前18天功能全靠云端模型接口能用是能用但心里一直不踏实。直到有一次给同事演示内部资料问答网络一抖整屏白掉当场翻车我下定决心把模型彻底搬到本地。用LangChain接上Ollama之后我总算拥有了一套完全离线的AI助手——断网照样多轮对话本地文档照样能问所有数据都不出这台机器。这篇把从零到一的完整过程写出来包括选型理由、环境搭建、代码实现和五个实打实的坑适合想在完全离线环境里搭AI助手的开发者和技术爱好者参考。1. 为什么要把AI助手彻底离线一次断网引发的“本地化”执念1.1 云上AI的三种“不可用”隐私、延迟、成本先说动机不然你很难理解后面为什么要折腾这一大圈。我在这个项目里要处理的一半是内部的说明文档、总结类文本另一半是我自己攒的笔记和技术资料。这些东西放在云端的聊天框里看着方便但只要一想到它们会被传到外部服务器心里就不踏实。有些资料本身就有明确要求数据不能出内网领导看看可以导出去绝对不行。这是隐私层面最直接的一堵墙也是离线方案最值钱的地方。其次是延迟。云端接口看起来快但一次请求要经过网络、排队、限流做简单问答还好一旦批量总结几十页文档速度非常不稳定。我实测过高峰期接口排队能排到十几秒交互体验远不如本地模型在CPU上慢悠悠但稳定的产出节奏。对一个天天要用的助手来说“稳定地慢”比“偶尔地快”舒服太多了。最后是成本。日调用量一上去账单就开始离谱。我算了一笔账按我这个项目的调用频率一个月省下来的API费用足够买一台二手小主机专门跑本地模型。与其长期把数据交给别人还交钱不如一次性投入把推理能力放在自己手里。1.2 本地模型不是降级现在的开源模型已经够用很多人一听“本地模型”就想到小模型智商不高。说实话两年前确实如此7B模型写几句代码就开始胡编。但最近这一两年开源模型进步非常明显7B到14B这个量级的模型在中文理解、摘要、问答这些常见任务上已经能保质保量地完成。我做了一套简单评测拿几十条工作场景问题分别问了云端模型和本地7B模型结论是日常问答和资料摘要类任务本地模型的表现差距不大只有在特别复杂的长文推理和高质量代码生成上才有明显差距。而对离线助手来说稳定、私有、可复现往往比“偶尔聪明一点”更重要。再加上嵌入模型也可以本地跑整个链路——对话、向量化、检索——没有任何一个环节需要联网。这是真正意义上的“彻底离线”而不是把几个组件简单换成自托管的伪离线。1.3 先定原则再动手我这套方案的四条铁律第一条整条链路任何环节都不允许出现外部HTTP调用违反这一条直接重写。第二条优先中文友好的模型。我最终选定 qwen2.5 系列做对话nomic-embed-text 做向量。第三条少装重型组件。能用一个进程解决的事不引入数据库和中间件。第四条所有模型名、服务地址、上下文长度全部参数化换模型不重写代码。这几条看着简单实际执行时帮我挡掉了很多诱惑。比如有人建议我再上个重型向量数据库、再套一层问答服务框架我全拒绝了——离线场景下组件越少排障越容易依赖越少越不会出现“这台机器装不上”的尴尬。2. Ollama这个模型运行器的正确打开方式安装、拉模型与API初探2.1 从安装到跑通第一个对话五分钟搞定Ollama本质上是一个本地模型运行器它负责下载模型、管理量化权重、调度GPU/CPU推理并对外暴露一个标准的HTTP接口。选它的核心原因就是省心不用手动去配Python推理框架也不用自己折腾显存分配那一大堆东西。安装也简单官网按平台下载安装包即可Linux下可以直接用安装脚本curl -fsSL https://ollama.com/install.sh | sh装完之后验证一下ollama --version ollama pull qwen2.5:7b ollama run qwen2.5:7bollama run会直接进入一个交互式对话界面输入“你好”能看到模型开始逐字回复到这里第一个模型就算跑通了。我这次的环境是Python 3.11、Ollama 0.3.x、langchain-ollama 0.2.x后面给的所有代码都在这套组合下验证过。顺便说几个我高频使用的管理命令ollama list查看本地已下载的模型。ollama ps查看当前正在内存里加载的模型以及它们占用的上下文空间。ollama rm 模型名删除不用的模型。ollama show 模型名查看模型元信息。2.2 量化等级和模型大小内存不够时的取舍表所有通过Ollama下载的模型基本都是GGUF格式的量化权重。量化可以简单理解为“用精度换体积”权重从16位近似压缩到4位或8位文件体积直接缩小好几倍质量损失控制在可接受范围。Ollama拉模型时默认选的是Q4_K_M级别这也是目前公认性价比最高的平衡点。我自己实测的感受Q4_K_M和Q8_0在日常问答里几乎听不出区别但文件体积差了近一倍。所以除非机器内存非常宽裕建议默认就用Q4_K_M。下表是我实际用过的几组模型参考占用情况模型量化级别文件大小约建议运行内存qwen2.5:7bQ4_K_M4.7GB8GB以上qwen2.5:14bQ4_K_M9.0GB16GB以上qwen2.5:32bQ4_K_M19GB32GB以上llama3.1:8bQ4_K_M4.7GB8GB以上nomic-embed-textF16274MB1GB即可注意这里“文件大小”和实际运行时的内存占用不是一回事。模型加载进内存后还需要额外的上下文KV缓存如果你把上下文设到16K甚至更大内存占用会明显上涨。所以内存规划一定要留出余量别卡着表格数字配机器否则一开多轮对话就等着系统卡死。2.3 藏在Ollama背后的HTTP API为什么它是接入一切的钥匙虽然Ollama自带交互终端但它真正的价值是后台那个本地API服务默认监听在127.0.0.1:11434。这意味着任何语言、任何框架都可以通过HTTP和本地模型通信LangChain也只是它的一个客户端而已。我平时调试第一反应就是先打一行curl亲眼确认模型没问题再往上查上层代码curl http://127.0.0.1:11434/api/chat -d { model: qwen2.5:7b, messages: [{role: user, content: 你好请简单介绍一下自己}], stream: false }响应里会带着模型生成的内容、token统计、耗时等元信息。常用的接口还有GET /api/tags列出当前已下载的模型。POST /api/embed生成文本向量。POST /api/generate老版本的单轮补全接口现在多数场景用/api/chat即可。如果想让局域网里的其他机器也能访问启动时把监听地址放出来就行OLLAMA_HOST0.0.0.0 ollama serve这个能力我后面用上了——给同事提供离线问答入口时不需要每台机器都装一套模型一台主机当推理服务器就足够了。提示改监听地址前确认一下自己所在网络的防火墙策略局域网开放服务一定要先想好谁能访问别把API裸奔到不可控的范围。3. 把LangChain接到本地模型的三种姿势从直接调用到RAG再到大模型应用3.1 为什么选LangChain省掉的都是重复轮子断网环境下你当然可以对着Ollama的HTTP API手撸对话服务但一旦要开始做多轮记忆、提示词模板、文档检索你很快就会发现自己在一遍一遍地写重复代码拼接历史消息、切分文档、管理向量库连接……LangChain把这几个高频环节都抽象成了标准组件接上之后确实省事。它给Ollama提供了两个关键封装ChatOllama负责对话补全OllamaEmbeddings负责文本向量化。我安装的是官方拆分后的稳定包pip install langchain-ollama langchain-community langchain-core这里插一句重要的LangChain的版本迭代非常快API变动也频繁尽量优先用拆分后的子包而不是一整套大杂烩。我身边已经不止一个人因为装了过度版本导致接口对不上、满屏过时警告排查到怀疑人生。3.2 最简单的姿势ChatOllama直接对话先看最基础的用法把ChatOllama实例化出来from langchain_ollama import ChatOllama llm ChatOllama( modelqwen2.5:7b, base_urlhttp://127.0.0.1:11434, temperature0.7, num_ctx8192, ) resp llm.invoke(用一句话说清楚什么是RAG) print(resp.content)几个参数值得展开讲model对应Ollama里已经下载的模型名换成qwen2.5:14b之类的名字即可切换。base_urlOllama服务的地址默认本机是http://127.0.0.1:11434远端部署时改成对应IP。temperature控制随机性。总结类任务我调到0.2日常聊天0.7创意类任务才会往上拉。num_ctx上下文窗口长度这个在后半部分踩坑章节还会重点讲。invoke返回的是一个AIMessage对象里面的content字段才是模型生成的文本。新手容易直接打印整个对象结果满屏都是token统计和调用元数据误以为代码出了问题。3.3 再进一步LCEL、Embedding和本地知识库单纯一句对话没什么意思LangChain更擅长的是把多个组件串起来形成管线官方叫LCEL。它的核心思路就是管道操作符|左边组件输出直接喂给右边组件输入代码非常好读from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的助手回答尽量简洁。), (human, {question}), ]) chain prompt | llm | StrOutputParser() print(chain.invoke({question: 离线部署AI助手有什么好处}))这里StrOutputParser把AIMessage对象转成纯文本后面接其他组件时方便很多。接下来是Embeddingfrom langchain_ollama import OllamaEmbeddings embeddings OllamaEmbeddings(modelnomic-embed-text) vec embeddings.embed_query(测试一下这句话的向量) print(len(vec)) # 输出 768别小看这一步本地知识库问答的核心就是把文本切片转成向量存起来用户提问时再把问题转成向量去库里做相似度检索。嵌入模型不联网、体积小、速度快非常适合离线跑。3.4 三种接入方式的对比什么时候用哪个我把这段时间用过的接入方式整理成一张表方便你按场景对号入座接入方式典型场景复杂度我的评价ChatOllama直接invoke单轮对话、快速验证低最快跑通但能力有限LCEL模板链固定格式的任务比如摘要、翻译中代码清晰可控性好RAG检索链 / Agent知识库问答、工具调用高能力最完整排障也最难实际项目中我经常同时用后两种简单对话走LCEL涉及内部资料的问题走RAG检索链。分工明确互不干扰。等你熟悉了这套结构再往上加Agent之类的复杂度也会顺很多。4. 一套可以直接照抄的离线问答助手代码链路4.1 整体架构消息怎么走文档怎么参与这个完全离线的问答助手我把它拆成了两条支路。支路一是普通对话用户输入进来套上系统提示词直接交给ChatOllama返回结果。支路二是知识库问答用户输入先不急着生成答案而是先做向量检索把向量库里最相关的几个文档片段捞出来连同用户问题一起塞进提示词让模型基于这些片段作答。你可能会问为什么非要绕这一圈。原因很简单7B模型没有能力记忆超大语料直接问“手册里怎么重置密码”它要么胡编要么说不知道。而把相关片段塞进上下文之后它就像拿到了一本翻开的书照着念也能答准。这就是所谓RAG的基本逻辑。完整链路是文档加载、文本切分、向量化、存入向量库查询时则是问题向量化、相似度检索、提示词组装、模型生成。整个流程看下来很对称这也是为什么本地模型方案在工程上特别清爽——每块都能独立替换。4.2 本地知识库问答文档切分、向量化、检索、生成下面这段代码是我实际在项目的干净环境里跑过的你照抄基本能通。先处理文档from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter loader TextLoader(guide.txt, encodingutf-8) documents loader.load() splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap80, ) chunks splitter.split_documents(documents) print(f切分成 {len(chunks)} 个片段)chunk_size500表示每个片段大约500个字符chunk_overlap80表示相邻片段之间重叠80个字符。重叠的目的很关键如果一条知识恰好被从中间切断下一个片段还能保留它的前半段检索时不容易漏掉。我实测过重叠参数从0调到80检索命中率有明显提升。然后生成向量并建库from langchain_community.vectorstores import FAISS from langchain_ollama import OllamaEmbeddings embeddings OllamaEmbeddings(modelnomic-embed-text) vectorstore FAISS.from_documents(chunks, embeddings) vectorstore.save_local(faiss_index)FAISS是轻量级的本地向量库不需要额外起服务直接存成文件。这里特别提醒一定要保存到磁盘不然每次启动都要重新把文档向量化一遍又慢又费电。接下来组装RAG检索链from langchain.chains import create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 请只根据下面提供的资料回答问题。如果资料里没有答案就明确说“资料里没有提到”。\n\n资料\n{context}), (human, {input}), ]) retriever vectorstore.as_retriever(search_kwargs{k: 4}) combine_docs_chain create_stuff_documents_chain(llm, prompt) rag_chain create_retrieval_chain(retriever, combine_docs_chain) answer rag_chain.invoke({input: 指南里说重置密码的步骤是什么}) print(answer[answer])检索时k4是让系统把最相关的4个片段都给模型。太少了容易漏答案太多了模型会被无关内容干扰4是我试下来比较稳的数字。这个提示词里“资料里没有答案就直说”也很重要是压制小模型胡编最有效的一句话。4.3 多轮记忆离线下要不要做怎么做最省多轮对话时模型本身是无状态的上一轮说了什么它根本不知道。要让它“记得”就得把历史消息主动拼进去。最省事的方式就是维护一个消息列表每轮对话后把用户消息和模型回复追加进去下次请求时带上最近几轮from langchain_core.messages import HumanMessage, AIMessage history [] # 每轮做三件事 history.append(HumanMessage(contentuser_input)) resp llm.invoke(history[-6:]) # 只带最近6条消息控制上下文占用 history.append(AIMessage(contentresp.content))之所以只用最近6条是因为7B模型虽然在长上下文下不会立刻报错但距离太远的旧消息要么被忽略要么挤占宝贵的上下文空间。对绝大多数离线助手场景“记住最近几轮”比“完整记住整场对话”更实用也更稳。如果对话特别长进阶做法是定期把历史总结成摘要再交给主模型不过这个等真有需求再上也不迟。4.4 前端体验命令行版和API服务版二选一我先把最简单的命令行版本跑通了核心就是个死循环while True: user_input input(你: ) if user_input in (quit, exit): break resp llm.invoke(user_input) print(助手:, resp.content)命令行适合自己调试但同事要用就不能这么原始了。后来我用FastAPI套了一层把问答应答暴露成POST /ask请求体里带question和可选session_id响应里返回答案和命中的文档片段来源from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class AskRequest(BaseModel): question: str session_id: str default app.post(/ask) def ask(req: AskRequest): resp llm.invoke(req.question) return {answer: resp.content, session_id: req.session_id}这样浏览器、内网IM机器人、其他内部系统都能来调整个离线服务就这么活起来了。别急着上太花哨的前端先把这层API稳定住后面想接什么入口都方便。5. 离线化路上那些坑按踩过的先后顺序讲给你听5.1 默认上下文只有2048聊到后面开始“失忆”第一个坑是我在测试多轮对话时踩到的。前面两三轮还好到第五六轮模型开始答非所问甚至把前面说过的话题忘得一干二净。一开始我以为是模型不行后来查Ollama的API文档才发现默认的上下文窗口其实很小旧版本是2048新版本放宽到4096但对多轮对话和RAG来说依然偏小。超出了窗口范围前面的内容直接被截掉模型自然“失忆”。解决方式是在初始化时把num_ctx显式设大。我在ChatOllama里设置了num_ctx8192RAG场景下资料、问题、历史一起塞也能装下。这里要提醒一句上下文越大KV缓存占的内存越多8K上下文在7B模型上大概会额外占用1到2GB内存别盲目上16K或32K。5.2 换了Embedding模型旧向量库直接废掉这个坑相当隐蔽。我一开始用的是某个768维的嵌入模型后来听说另一个嵌入模型效果更好就直接改了OllamaEmbeddings里的model名。结果一查向量库检索出来的内容乱七八糟相似度得分完全没参考价值。原因是两个嵌入模型的输出维度不同语义空间也不同。向量库里已经存的是旧模型生成的向量用新模型生成的问题向量去和旧向量做相似度计算完全是鸡同鸭讲。解决办法只有一个换模型就重建向量库没有捷径。我后来在建库脚本里顺手把嵌入模型名写进了索引文件名的后缀比如faiss_index_nomic_768看到名字就知道里头是什么模型生成的。这个习惯强烈建议养成。提示建库时把模型名、维度、切分参数一起记下来。离线项目周期长隔一个月你自己也不记得当时怎么建的库。5.3 流式输出神秘消失版本匹配的教训做API服务之后我想把流式输出加上让用户看到逐字生成的效果。结果发现前端一直转圈要等全部生成完才一次性吐出整段文字。我先用curl直接打Ollama的APIstream: true模式下逐字输出正常说明问题出在LangChain这一层。顺着排查发现是langchain-ollama的某个版本和当时Ollama服务端的流式响应格式存在兼容问题。我的解决方式比较粗暴但有效先把两边都升级到当前稳定版然后在代码里直接用stream()方法消费生成流for chunk in llm.stream(给我讲讲离线部署的好处): print(chunk.content, end, flushTrue)升级之后一切正常。这里给同样头大的同学一个方向遇到LangChain的怪问题时先用curl验证底层能力再逐层往上定位。别一上来就怀疑模型不行很多问题根本不在模型身上。5.4 模型常驻内存笔记本电脑几分钟后开始卡多模型切换是另一个隐形杀手。我同时拉了好几个模型来回测试笔记本内存很快就吃紧系统开始疯狂交换。检查ollama ps发现刚才用过的模型都还热乎乎地加载在内存里。Ollama默认会让模型在结束请求后驻留一段时间这样下次调用就省去加载时间代价就是内存一直被占着。想释放内存有几种做法调用API时传keep_alive: 0让模型用完立即卸载或者在启动服务时设置环境变量OLLAMA_KEEP_ALIVE0。我最后用了折中方案设为5m既不频繁加载又不会霸占内存太长时间。如果同时加载多个模型还可以把OLLAMA_MAX_LOADED_MODELS设成1让新模型启动时自动踢掉旧模型。5.5 真正离线环境下的模型分发问题最后一个坑发生在我准备往一台完全没外网权限的机器上部署时。那台机器连不上外网ollama pull根本拉不了模型。这个问题的解法是在能联网的机器上先把模型拉好然后把整个~/.ollama/models目录拷过去。注意不同平台目录位置不一样Windows下是C:\Users\你\.ollama\modelsLinux和macOS下是~/.ollama/models。除了模型文件Python依赖也要提前准备好。在有网的机器上用pip download把依赖包下载成whl文件再拷贝到离线机器上离线安装。别到了现场才发现缺包内网环境里想临时装什么都难。这个坑我花了整个下午才填平现在提起来还觉得亏。6. 离线AI助手的下一步模型怎么扩、记忆怎么做、工具怎么用6.1 工具调用的坑小模型的JSON输出并不稳定离线助手跑通之后我开始想让它调用工具比如查本地日程、执行简单脚本。结果7B量化模型在工具调用上频繁翻车要么返回的JSON格式不完整要么工具名拼错、参数少一半。这是小模型的通病——工具调用要求模型在特定位置输出严格格式的内容而量化压缩首先损失的就是这种精确输出能力。我试了几种应对方案最简单有效的是别用JSON设计一套更松散的文本协议。比如让模型输出“查询天气|北京”后端用规则解析字符串而不是硬做JSON解析。格式越简单小模型越不容易出错。真想用JSONOllama API也支持用format: json强制输出JSON但字段内容仍可能不符合预期后端一定要做校验和兜底。6.2 按任务分模型一个Ollama多套配置跑了一阵子之后我的经验是不要试图用一个大模型解决所有问题。我现在的配置是对话用qwen2.5:7b代码相关的任务切到专门的代码模型复杂长文问题切到14b版本。反正模型都放在Ollama里按任务切换只是改一个字符串的事成本极低但体验提升非常明显。切换时别在代码里写死模型名我把模型名放在配置文件里用环境变量管理。比如OLLAMA_CHAT_MODELqwen2.5:7b、OLLAMA_CODER_MODEL某个代码模型这样哪天想换模型改配置重启服务就行不用翻代码。6.3 硬件升级的性价比顺序最后说说硬件。很多朋友问我是不是必须买显卡才能玩离线模型。我的回答是没有也能玩体验差一点而已。纯CPU跑7B模型每秒大概几个token慢但看它一个字一个字吐出来其实也还行16GB内存的机器跑7B Q4很流畅只是上下文别开太大。如果要升级我的建议顺序是先把内存加到32GB再考虑上独立显卡。显存24GB级别基本可以跑32B量级的模型体验会完全不一样。如果用的是近两年带统一内存架构的机型那就更省心内存大的版本直接跑中大规模模型都挺稳。按“内存优先、显存次之”的顺序来性价比最高也最不容易买完后悔。