前阵子模型部署门槛降下来之后我就一直在琢磨一件事能不能把 AI 真正变成自己学习体系里的一部分而不是每次都要打开网页、贴资料、等回复、再手动保存结果。答案是可以的但需要专门为“学习”这个场景做一个顺手的小工具而不是把通用聊天机器人换个皮肤。于是就有了这么个东西一个本地运行的 AI 学习软件模型完全跑在你自己电脑上免费、开源、不需要联网、不需要订阅所有学习资料和对话记录都留在本地磁盘里。这篇文章就专门聊聊这个项目从想法到落地的完整过程包括为什么非本地不可、技术选型背后的权衡、每个功能到底怎么设计、实际搭建时每一步怎么做以及我踩过的坑和排查思路。这不是一个面向所有人的产品它的目标用户很具体需要长期整理资料的自学者、备考期间反复回顾知识点的人、每天跟文档和代码打交道的开发者以及所有不想把个人学习记录传到云端的用户。你不一定需要多高端的显卡纯 CPU 也能跑起来不需要为模型付费本地开源模型已经足够应付大部分学习场景也不需要理解复杂的机器学习原理整个部署过程可以跟着这篇文章一步步操作。下面我按项目本身的拆解顺序来说明。1. 为什么我要做一个本地 AI 学习软件1.1 在线 AI 工具解决不了的三件事在线大模型确实很强但把它用在系统的学习过程里时间一长你会遇到几个绕不开的问题。第一个问题是资料没法形成长期记忆。在线工具每次对话都是独立的它不会替你保存“我昨天整理的那篇论文笔记”也不了解你收集的几十份 PDF 里写了什么。我试过的做法是把关键段落复制进去再提问资料一多就成了体力活而且对话窗口一旦变长遗忘就开始出现很多细节要反复解释。第二个问题是成本。高能力的在线服务大多是订阅制一年下来不是一笔小钱而且免费额度对认真学习的人来说根本不够用。如果你每天要处理几万字的学习资料对话轮次很快就触顶了。第三个问题也是我最在意的一点是隐私。学习笔记、错题记录、还在构思中的想法这些都是非常私人的数据。把笔记上传到云端然后让 AI 来分析虽然方便但我始终觉得不够踏实。本地运行从根源上解决了这个顾虑——模型在你电脑上跑资料不出硬盘聊天记录不出内存断网时一切照常工作。所以项目的定位从最开始就很明确不是为了做一个“看起来很酷的 AI 玩具”而是为了解决长期学习场景下的记忆、成本和隐私这三件具体的事。1.2 谁适合用这个软件谁不适合做工具最忌讳的是什么都想要第二忌讳的是用户画像模糊。我在设计之前先明确了两类最适合的用户。第一类是手头有大量资料、但不知道怎么高效利用的人。比如你在备考专业认证电脑里堆了几十个 PDF 和网页另存的文件传统的文件搜索只能按关键词找名字但你的真实需求是“这些资料里关于某个概念的论述有哪些不同角度”这个需求只有让 AI 读过资料内容之后才能回答。第二类是持续性学习者不管是写代码的、做研究的还是学语言的每天都会接触新概念需要有人用更直白的方式解释并把疑点记录下来。这个软件可以把解释、笔记、问答记录都结构化地保存下来形成自己的知识库。反过来如果你的需求是闲聊、创作、写文案这类开放型任务说实话本地小模型的现有效果还不如在线大模型这个项目就不适合你。它做的是资料问答、内容解释、复习整理这些相对聚焦的活儿。2. 整体设计与技术选型2.1 四层架构模型、知识库、服务、界面各司其职这个软件采用了一个相对清晰的四层设计。最底层是模型运行层负责加载和调用本地大模型对外提供统一的 API 接口。往上一层是知识库层负责把用户导入的资料切块、向量化、建立索引并在用户提问时做语义检索。再往上是服务层负责把“检索到的相关段落”和“用户的提问”组装成合适的提示词交给模型处理完结果再格式化返回。最顶层是界面层一个本地 Web 页面用户在浏览器里完成资料上传、问答、笔记管理等操作。这个分层的主要考虑是解耦。模型可以随时换比如从 7B 参数模型升级到 14B 参数模型只需要改配置不需要动其他层知识库也可以独立更新用户可以随时往索引里加新资料不用重启服务界面层和服务层通过 HTTP 接口通信以后想做移动端或者桌面客户端只要复用同一套 API 就行。对一个开源项目来说分层还有一个额外好处贡献者可以只关注自己感兴趣的那一层。有人对模型调优感兴趣有人对检索算法感兴趣有人只写前端界面大家的工作边界很清晰。2.2 模型运行层为什么选 Ollama 而不是自己写推理代码最先要确定的是模型怎么跑。选项有三个直接用 Python 加载模型权重自己做推理用 Transformers 这类库跑推理或者用 Ollama 这类本地模型管理工具。自己写推理代码是学习成本最高、维护成本也最高的方案。你要处理分词、注意力机制、KV 缓存、量化反量化、显存管理这一大堆底层细节即使跑通了换一个模型格式又要折腾一遍。用 Transformers 库跑推理相对专业也能方便地使用各个生态里的模型但显存管理、并发处理、模型缓存这些都需要自己写对普通用户的门槛偏高。所以我选了 Ollama。它本身就是为“本地运行模型”设计的工具跨平台支持 Windows、macOS 和 Linux能用一行命令拉取模型也能轻松切换不同模型。对开发者来说最重要的是它的兼容性——尽量兼容 OpenAI API 格式这意味着绘图工具、聊天前端、自动化脚本都可以无缝接进来不需要为每个模块单独适配。这个选择不是因为它功能最多而是因为它让“本地模型”这件事变得足够简单简单到普通人也能上手。模型规格的选择也值得展开。在中文学习场景里我目前默认推荐 Qwen2.5 系列的 7B 和 14B 指令模型它们在中文理解和指令跟随上的表现比较均衡而且对硬件相对友好。如果你的电脑是纯 CPU建议选 7B 量化版有 6GB 以上显存可以带得动 7B Q4 量化有 12GB 以上显存可以考虑 14B Q6 量化。这些都是基于我个人多次实测得出的经验值见下表电脑配置推荐模型量化级别内存/显存占用实际体验纯 CPU 16GBqwen2.5:7bQ4_K_M约 5GB 内存可用回答较慢6GB 显存qwen2.5:7bQ4_K_M约 5GB 显存流畅质量可接受12GB 显存qwen2.5:14bQ6_K约 11GB 显存质量明显更好24GB 显存qwen2.5:32bQ5_K_M约 20GB 显存接近在线模型体验2.3 知识库层先切块再向量化这是“AI 能读懂你的资料”的关键光有模型还不够模型本身并不了解你的 PDF 里写了什么。要让软件做到“基于你的资料回答问题”必须先做一套知识库管线核心是三步切块、向量化、索引。切块是把长文档拆成小段落。原因很直接模型上下文窗口有限而且学习场景下回答一个问题通常只需要参考文档里的几段话很少需要全文。切块大小我默认设置为 500 个字符相邻块之间保留 50 字符的重叠。500 字符能基本保证一个完整观点不会太碎重叠部分则可以避免知识点恰好被切在边界上导致检索不到。向量化是给每块文本生成一个向量表示。这一步用的是嵌入模型它把“语义”转成“坐标”语义相近的文本在向量空间里距离更近。用户提问时系统把问题做同样的向量化然后在索引里找出最接近的几个块作为上下文。这里有一个很重要的细节训练和查询必须使用同一个嵌入模型如果后续更换了嵌入模型已经生成的向量全部需要重新计算否则检索结果会直接乱掉。索引我用的是一个本地向量数据库数据落在本机磁盘不需要任何外部服务。整个知识库模块设计成了可插拔的用户导入新资料后会自动增量更新索引不用手动重建。2.4 界面层一个本地 Web 应用而不是桌面壳子界面层我选择做成本地 Web 应用而不是 Electron 桌面应用。原因很简单本地 Web 应用可以依赖系统自带的浏览器渲染前端代码量少、调试方便、跨平台成本低。用户启动服务后打开一个本地地址就能看到全部界面。交互上只保留几个核心动作上传或导入文档、打开一个资料夹并提问、查看回答中的引用出处、管理错题卡片。界面尽量克制因为用户来这里是为了学习不是为了玩界面。我曾经加过一些花哨的动效实测下来只会分散注意力后来全部移除了。3. 核心功能拆解与实际用法3.1 资料问答让模型基于你自己的文档说话资料问答是整个软件使用频率最高的功能。用户把 PDF、Markdown、Word 或纯文本文件导入之后就可以像聊天一样提问。比如你把一本操作系统的复习笔记导入进去问“进程和线程的核心区别是什么最好结合笔记里的例子”系统会先去知识库检索相关段落再把段落到提示词里一并发送给模型最后输出回答同时标注答案来源是哪一章节第几个切片。这个设计最关键的是引用溯源。没有引用机制的知识库问答看起来像模像样但实际上模型可能是在自由发挥回答里混入了资料中没有的观点。加了引用之后用户能立刻确认哪些内容是真正有出处的这比“答案看起来对”要重要得多。而且在复习场景里有出处的回答可以直接指引你回到原始资料效率提升非常明显。我建议一些效率技巧提问时尽量带上具体限定比如“只基于我导入的资料回答”“给出三个要点每个要点不超过 50 字”。这样模型输出的稳定性和针对性都会好很多。3.2 即时解释把看不懂的段落一键讲透这个功能源于我自己读英文论文时的痛点。论文里经常有一整段话每个单词都认识、连起来不知道在说什么手动翻译成中文也不解决问题因为翻译本身就不通顺。在软件里你只需要选中段落点击解释系统就会根据当前学习科目自动生成一种适合的解释方式。如果是技术概念它用类比法解释如果是数学推导它分步骤展示推理过程如果是历史背景它补充上下文脉络。这种定向解释比单纯翻译有用得多。解释的输出格式我也做了约束先一句话总结核心意思再展开关键概念最后给一个贴近生活的类比。这个格式来自我的使用经验很多在线模型直接回答时会绕来绕去而明确指定格式之后回答质量稳定很多。3.3 错题与卡片把“遇到过的问题”固化为知识学习过程里错题比正确题更值钱。所以我设计了一个轻量的错题卡片模块。用户可以把容易混淆的概念、做错的题目、答错的原因手动记录成卡片也可以从一次问答结果里一键把回答保存成卡片。卡片支持打标签比如“操作系统”“网络协议”“英语长难句”方便后续按主题梳理。卡片还有一个配套的复习计划功能可以按遗忘曲线的时间节点提醒你回顾。模型本身不参与记忆曲线的计算它只负责一件事当你在卡片上补充笔记时AI 会根据你写的内容给出一个概括和延伸提问帮你把卡片从“记录”升级成“理解”。这个功能实际用下来比单纯堆卡片有意思得多。3.4 本地优先的权限设计既然是学习工具数据安全不能只停留在口号层面。软件默认所有数据都存在本地数据库文件、模型文件、向量索引、日志文件都在同一个目录下。没有任何遥测功能不收集使用数据不上传任何文件。用户完全可以使用防火墙规则禁止该软件访问外部网络不影响任何功能工作。源码是开放的任何人都可以审计它到底做了什么。这个项目的仓库地址放在这里https://github.com/lanr 。代码量不算大如果你想把它接到自己的其他工具里或者给它加一个手机端界面都是可行的。4. 从零到一完整搭建过程4.1 环境准备装好运行时和基础依赖搭建的第一步是准备环境。软件本体不需要复杂的依赖核心就是 Ollama 和一个 Python 环境。Windows 用户直接下载 Ollama 安装包装完在终端里执行 ollama --version 确认安装成功。Linux 用户可以用官方安装脚本也可以下载二进制包手动解压放在 /usr/local/bin 下。macOS 用户同样下载安装包即可。Python 环境建议 3.10 以上创建一个独立的虚拟环境来装依赖避免污染系统环境python -m venv venv source venv/bin/activate # Windows 上执行 venv\Scripts\activate pip install fastapi uvicorn chromadb这个步骤里最常见的坑是 Python 版本过低导致向量数据库依赖装不上所以特别强调一下 3.10 这个下限。4.2 拉取模型选择合适参数并完成下载下一步是拉取模型。在终端里执行ollama pull qwen2.5:7b这条命令会下载模型到本地。下载过程可能需要一段时间取决于你的网速。下载完成之后你可以用 ollama list 查看本地已有的模型列表。如果你的电脑配置更高想要更好的回答质量可以拉取 14B 版本ollama pull qwen2.5:14b知识库嵌入模型也要拉取ollama pull nomic-embed-text这里要注意一个常见的误区有人会试图同时把所有模型都拉下来然后用的时候来回切换。实际体验下来模型不在多而在精。学习场景下固定用一个 7B 或 14B 模型就够了频繁切换不仅消耗大量磁盘空间还会让每次对话的冷启动时间变长。4.3 启动核心服务几个必须知道的配置参数所有东西下载完成后开始配置服务。Ollama 默认监听本机的 11434 端口。如果不想用默认配置可以设置环境变量# Linux / macOS export OLLAMA_HOST127.0.0.1:11434 export OLLAMA_MODELS/path/to/your/models # Windows PowerShell $env:OLLAMA_HOST127.0.0.1:11434 $env:OLLAMA_MODELSD:\modelsOLLAMA_MODELS 变量比较重要如果你 C 盘空间紧张把它指到数据盘可以避免磁盘容量报警。具体模型文件的保存目录可以通过 ollama show 看到细节。模型运行参数我也踩过几次坑。默认情况下 Ollama 的上下文长度是 2048但这对于知识库问答来说太短了经常导致模型忘记提示词开头的参考文档内容。建议在调用时把 num_ctx 设置为 8192根据模型规格适当增加但要留意它会按比例占用更多显存ollama run qwen2.5:7b --num-ctx 8192在 Python 服务端设置默认参数可以参考options { temperature: 0.6, top_p: 0.8, repeat_penalty: 1.1, num_ctx: 8192, }温度设置在 0.5 到 0.7 之间比较适合学习场景太低会变得机械太高容易跑题。4.4 导入资料并完成第一次问答服务起来之后打开本地 Web 界面先新建一个知识库再把测试资料上传进去。建议第一次导入用一份你非常熟悉的内容比如一门课的复习笔记这样你能快速判断回答质量是否靠谱。导入完成后试着提问一个你本来就知道答案的问题比如“这份笔记的核心观点是什么”。系统应该会经历一个流程把问题向量化在索引中检索相关文档片段把片段组装成提示词调用模型生成回答再把引用来源标注出来。这个过程在普通的 6GB 显存机器上7B Q4 量化模型的生成速度大约是每秒 20 到 30 个 token一个 300 字的回答大概 10 到 15 秒。纯 CPU 模式会慢一些但能接受。如果回答看起来不像来自你导入的资料优先检查两个地方一是导入文件是否成功进入向量库可以在界面上看文档列表二是提问时是否明确要求“仅基于导入资料回答”。很多看似模型变笨的问题其实是因为用户没切换对问答模式。5. 常见问题与排查技巧实录5.1 最容易踩的五个问题我在开发和内测阶段遇到过不少问题挑五个最有代表性的整理成了一张表现象可能原因解决思路启动后访问页面空白前端静态文件路径配置错误检查本地服务日志确认静态目录指向正确提问后模型完全不看资料提示词中没有强调引用来源在服务层强制拼接“基于以下资料回答”模板检索结果总是老旧的文档向量库索引未增量更新手动触发重建索引确认新文档已向量化回答到一半显存爆掉num_ctx 设置过大或并发数过高降低上下文长度减少并行任务数模型输出重复循环temperature 过高或重复惩罚过低把 temperature 降到 0.6 以下repeat_penalty 提到 1.1 以上这五个问题里最隐蔽的是第二个。一开始我图省事直接把用户问题发给模型完全没拼接知识库内容结果模型的回答看起来流畅但完全没用上我导入的资料。后来改成强制模板拼接才解决了“答非所问”的问题。5.2 显存不够用时的降级方案本地模型最容易遇到的硬件瓶颈就是显存。如果跑 7B Q4 模型时遇到显存不足有两条降级路径。第一条是升级模型交换回退方式。Ollama 支持模型层被交换到内存即使显存不够也能继续跑但速度会明显下降。如果只是偶尔用一次这个方案完全可接受如果每天高频使用还是建议降低模型规格更现实。第二条是把量化级别从 Q4_K_M 降到 Q3_K_M模型体积会进一步缩小回答质量会有可感知的损失但在“完全不能用”和“勉强能用”之间它至少保证软件还能正常运转。我个人的建议是优先保证知识库检索流程的顺畅运行因为这个环节就算模型弱一些只要检索到的资料正确、提示词组织得好输出质量并不会差太多。模型能力只是这个系统的一部分知识库质量往往更决定最终体验。5.3 排查思路与心得最后分享一点排查问题的总体思路。本地 AI 系统的链路比传统软件更长资料处理、向量检索、模型生成、前后端交互每一环都可能出问题。遇到问题不要先急着怀疑模型我的做法是逐层定位先确认基础服务是否正常用 curl 调用一次模型接口看能不能返回内容然后检查检索环节在日志里打印出检索到了哪些文档片段确认它们确实和问题相关再检查提示词模板看参考内容是否真的拼进去了最后才去调整模型参数。按照这个顺序排查大部分问题五分钟内就能定位。我也逐步形成了一些使用习惯每导入一批新资料就手动触发一次索引重建每换一次嵌入模型就全量重建向量库每改一次提示词模板就用同一个测试问题跑三遍确认输出稳定。这些都是简单但有效的质量保障手段。这个项目目前还在持续迭代后续计划补充导出功能、多知识库串联问答以及更细粒度的引用定位。如果你也在做本地 AI 相关的工具或者在学习场景里遇到了现有工具解决不了的问题欢迎去仓库里看看提 issues 或者直接交代码。我个人一直相信一件事工具是长出来的不是写出来的真正好用的功能一定来自日常使用中反复打磨的细节。