从零打造本地AI学习助手：Ollama+PyQt+SQLite离线问答与知识库实践

1. 为什么我要自己做一个本地 AI 学习软件1.1 从“云端对话”到“本地运行”的动机最开始用各种在线 AI 对话工具的时候确实觉得方便打开网页就能问问题。但用久了就发现几个绕不过去的坎一是网络稍微不稳定回答就卡在半路二是有些涉及自己工作内容的问题不太愿意发到别人的服务器上三是很多工具用着用着就开始限制次数、弹广告甚至改收费规则。我想要的其实很简单——一个装在自己电脑上、断网也能跑、数据不出本机、想怎么问就怎么问的学习助手。这个需求听起来不复杂但真正动手做的时候才发现市面上的开源方案要么太“重”部署门槛高得吓人要么太“轻”功能残缺连个像样的对话历史都存不住。于是我就想干脆自己写一个。目标很明确本地运行、免费开源、面向学习场景。不追求什么花哨的功能就是把“问—答—记—复习”这条链路做顺让一个普通用户下载下来双击就能用。这里说的“本地运行”指的是模型推理、数据存储、界面交互全部在你自己的电脑上完成不需要联网请求任何外部服务。模型文件放在本地磁盘对话记录存在本地数据库整个软件就是一个离线可用的学习工具。这一点对很多有隐私顾虑、或者网络环境不稳定的用户来说是刚需。1.2 这个软件到底能做什么具体来说它解决的是“学习过程中的即时问答与知识沉淀”问题。你可以把它理解成一个离线的私人助教遇到不懂的概念直接问它它会基于本地加载的模型给出解释你觉得这个解释有用可以一键收藏进知识库下次复习的时候直接翻知识库就行不用再去翻聊天记录。适合谁来用我总结了这几类学生党宿舍网络时好时坏或者不想花钱买在线服务本地跑一个写作业查资料够用了。开发者想研究本地大模型怎么集成到桌面应用里这个项目可以直接拿去看源码、改功能。隐私敏感用户工作内容涉及内部资料不希望任何数据离开本机。折腾爱好者喜欢自己动手部署、调参、换模型享受“我的软件我做主”的感觉。它不适合谁如果你追求的是“最强模型能力”那本地小模型确实比不过云端大模型这个得实话实说。但如果你要的是“够用、可控、免费、离线”那这个方向就对了。1.3 技术选型背后的取舍逻辑做本地 AI 软件第一个要决定的就是“模型怎么跑”。我试过几种方案方案优点缺点是否采用直接调用在线 API模型能力强开发简单需要联网有隐私风险可能收费否自己写推理引擎完全可控工作量巨大性能难优化否集成 Ollama安装简单模型管理方便社区活跃需要额外安装 Ollama是集成 llama.cpp纯本地无额外依赖编译配置复杂对新手不友好作为备选最终我选了Ollama 作为模型运行时。原因很实际它把模型下载、加载、推理这些脏活累活都封装好了我只需要通过它的本地 HTTP 接口发请求就行。而且 Ollama 支持 Windows、macOS、Linux用户安装成本低。对于想完全离线、连 Ollama 都不想装的用户我也留了 llama.cpp 的接入点但默认走 Ollama因为这条路最顺。界面层我用了Python PyQt。为什么不用 Web 技术栈因为 Web 方案要起服务、开浏览器对普通用户来说多了一步PyQt 打包出来就是一个原生窗口双击 exe 就能跑更像一个“软件”而不是“网页”。数据库用了SQLite单文件、零配置、够用对话记录和知识库都存里面备份就是复制一个文件的事。2. 核心功能拆解与实操要点2.1 本地模型加载与对话流程整个软件的核心链路是这样的用户输入问题 → 软件把问题发给本地 Ollama 服务 → Ollama 调用本地模型生成回答 → 软件把回答显示出来并存入 SQLite。听起来简单但中间有几个关键点容易踩坑。第一模型选择。不是所有模型都适合学习场景。我实测下来7B 参数左右的模型在普通笔记本上能跑但回答质量参差不齐。推荐几个我试过还不错的Llama 3 8B综合能力强中英文都还行适合通用问答。Qwen2 7B中文理解好适合中文学习场景。Phi-3 Mini体积小老电脑也能跑但知识面窄一些。模型文件大小和内存占用直接相关。一个 7B 的量化模型Q4 量化大概 4-5GB运行时需要 8GB 左右内存。如果你的电脑只有 8GB 内存建议选 3B 以下的模型或者用更激进的量化版本。第二Ollama 的接口调用。Ollama 默认在http://localhost:11434提供 HTTP 接口。发一个对话请求的代码大概长这样import requests import json def ask_ollama(prompt, modelllama3): url http://localhost:11434/api/generate payload { model: model, prompt: prompt, stream: False } response requests.post(url, jsonpayload) return response.json()[response]这段代码看起来简单但有几个细节要注意stream参数如果设为True回答会逐字返回体验更好但处理起来麻烦一些model名字必须和ollama list里显示的一致大小写敏感如果 Ollama 没启动请求会直接报连接错误软件里要做好错误提示。第三对话上下文的处理。本地小模型的上下文窗口有限通常 4K 到 8K token。如果对话轮数多了历史记录会撑爆窗口导致模型“忘事”。我的做法是只保留最近 N 轮对话默认 5 轮更早的记录存数据库但不发给模型。这样既控制了 token 消耗又保留了完整历史供用户翻阅。注意不要把所有历史记录一股脑塞给模型小模型处理长上下文时性能下降明显而且容易产生“幻觉”。控制上下文长度是本地 AI 软件必须做的优化。2.2 知识库与学习记录的设计学习软件和普通聊天工具最大的区别就是“知识沉淀”。聊天记录是线性的翻起来费劲知识库是结构化的可以分类、打标签、搜索。我在设计时把这两块分开对话记录自动保存按时间倒序排列支持关键词搜索。知识卡片用户手动收藏的回答可以编辑、打标签、加入复习队列。知识卡片的数据表结构大概是这样CREATE TABLE knowledge_cards ( id INTEGER PRIMARY KEY AUTOINCREMENT, question TEXT NOT NULL, answer TEXT NOT NULL, tags TEXT DEFAULT , created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, review_count INTEGER DEFAULT 0, last_reviewed_at TIMESTAMP );tags字段用逗号分隔的字符串存标签虽然不够规范但胜在简单查询用LIKE也能凑合。如果以后标签多了再拆成独立的标签表也不迟。review_count和last_reviewed_at是为了做“间隔复习”预留的——根据遗忘曲线复习次数越多、间隔越长这个逻辑后面可以慢慢加。这里有个实操心得知识卡片的“问题”字段不要直接复制用户输入而是让用户自己重新组织一遍。为什么因为用户原始输入往往很随意比如“那个啥来着就是那个梯度下降”直接存下来以后根本看不懂。让用户手动改成“梯度下降的基本原理是什么”复习的时候才有价值。这个“重新组织”的过程本身也是一种学习。2.3 界面交互的简化思路PyQt 做界面最容易犯的错就是“功能堆砌”。我第一版做了十几个按钮、五个面板结果自己用着都嫌乱。后来砍到只剩三个区域左侧对话列表显示历史会话点击切换。中间对话区上面是消息流下面是输入框。右侧知识库面板显示收藏的卡片支持搜索和标签筛选。输入框支持CtrlEnter发送Enter换行。这个快捷键设计参考了聊天工具的习惯但和很多在线 AI 工具相反——它们通常是Enter发送。我选CtrlEnter是因为学习场景下用户经常需要输入多行问题比如粘贴一段代码或一段文字Enter直接发送容易误操作。提示如果你要改这个快捷键在settings.py里改SEND_SHORTCUT变量就行不用翻遍代码。界面配色我用了浅色主题因为学习场景通常在白天深色主题看久了眼睛累。字体大小默认 14px可以在设置里调。这些细节看起来小但直接影响“愿不愿意长期用”。3. 从零到一的完整搭建过程3.1 环境准备与依赖安装假设你用的是 Windows 11从零开始搭这个软件需要这几步第一步装 Python。推荐 3.10 或 3.11太新的版本有些库还没适配。去 Python 官网下载安装包安装时勾选“Add Python to PATH”不然命令行里找不到python命令。第二步装 Ollama。去 Ollama 官网下载 Windows 安装包双击安装。装完后打开命令行输入ollama --version能显示版本号就说明装好了。然后拉一个模型ollama pull llama3这个命令会下载 Llama 3 8B 模型大概 4.7GB取决于网速可能要等一会儿。下载完成后用ollama list确认模型在列表里。第三步装项目依赖。把项目代码克隆到本地进入目录创建虚拟环境python -m venv venv venv\Scripts\activate pip install -r requirements.txtrequirements.txt里主要就几个包PyQt5、requests、sqlite3Python 自带。没有乱七八糟的依赖这也是我刻意控制的——依赖越少用户装起来越不容易出错。第四步启动软件。确保 Ollama 在运行托盘图标有显示然后python main.py第一次启动会初始化数据库创建data/目录里面放chat.db。如果一切正常窗口会弹出来左侧是空的对话列表中间是欢迎语。3.2 关键配置参数与调优软件跑起来之后有几个参数值得调参数默认值说明调整建议MODEL_NAMEllama3使用的模型换成qwen2可提升中文效果MAX_CONTEXT_ROUNDS5保留最近几轮对话内存小就调成 3TEMPERATURE0.7回答随机性学习场景建议 0.3-0.5更稳定MAX_TOKENS2048单次回答最大长度调太大会等很久2048 够用DB_PATHdata/chat.db数据库位置想放移动硬盘就改这里TEMPERATURE这个参数特别说一下。它控制模型输出的随机程度值越高回答越“天马行空”值越低回答越“保守确定”。学习场景下我希望答案准确、稳定所以默认设了 0.7但建议用户改成 0.3 左右。改完之后同一个问题问两遍答案基本一致更适合记忆。MAX_TOKENS控制单次回答的长度。设成 2048 意味着模型最多生成 2048 个 token 的回答大概 1500 个汉字。对于学习问答来说够用了。设太大有两个问题一是等得久二是小模型生成太长容易跑偏。3.3 打包成可执行文件开发完了总不能要求每个用户都装 Python 吧。用 PyInstaller 打包pip install pyinstaller pyinstaller --onefile --windowed --name LocalAIStudy main.py--onefile把所有东西打成一个 exe--windowed去掉命令行窗口。打包出来的文件在dist/目录下大概 30-50MB不含模型。用户拿到 exe再自己装个 Ollama、拉个模型就能用了。这里有个坑PyInstaller 打包 PyQt 程序时有时候会漏掉一些 Qt 插件导致运行时报“could not find or load the Qt platform plugin”。解决办法是在 spec 文件里手动加上from PyInstaller.utils.hooks import collect_data_files datas collect_data_files(PyQt5)或者更简单粗暴打包时加--collect-all PyQt5。这个坑我踩了两次第一次打包出来在自己电脑上能跑发给别人就报错折腾了半天才发现是插件没打进去。注意打包后的 exe 首次运行可能会被 Windows Defender 拦截因为 PyInstaller 打包的程序经常被误报。让用户点“仍要运行”就行或者建议用户把 exe 加入白名单。4. 实际使用中遇到的问题与解决记录4.1 模型加载失败与排查问题现象软件启动后发消息一直转圈最后提示“连接 Ollama 失败”。排查思路先确认 Ollama 是否在运行。打开命令行输入ollama list如果报错说明 Ollama 没启动。去开始菜单找 Ollama 启动一下。如果ollama list正常但软件还是连不上检查端口。Ollama 默认用 11434 端口如果被其他程序占用了就会冲突。用netstat -ano | findstr 11434看看端口状态。如果端口被占改 Ollama 的端口或者改软件里的OLLAMA_URL配置。常见原因Ollama 安装后没有设置开机自启用户重启电脑后忘了手动启动。我的做法是在软件启动时自动检测 Ollama 是否可用如果不可用就弹窗提示“请先启动 Ollama”并附上一键启动的按钮调用ollama serve。4.2 回答速度慢的优化问题现象问一个问题等了半分钟才出答案。原因分析本地模型推理速度取决于三个因素——模型大小、硬件性能、量化等级。7B 模型在纯 CPU 上跑每秒大概生成 2-5 个 token一个 200 字的回答要等 1-2 分钟。如果有独立显卡速度能快 5-10 倍。优化方案换小模型从 7B 换成 3B速度翻倍质量下降可接受。用量化版Ollama 默认拉的模型已经是量化版但可以选更激进的量化比如llama3:q4_0比llama3:q8_0快不少。开 GPU 加速如果电脑有 NVIDIA 显卡装 CUDA 版的 Ollama推理会自动走 GPU。限制回答长度把MAX_TOKENS从 2048 降到 1024等待时间减半。我实测下来一台 16GB 内存、无独显的轻薄本跑 Llama 3 8B Q4 量化生成 100 字回答大概 20 秒。换成 Qwen2 1.5B同样的回答 5 秒内出。所以如果追求速度小模型是唯一解。4.3 对话记录丢失的预防问题现象软件崩溃后之前的对话记录全没了。原因SQLite 默认是自动提交模式但如果在写入过程中程序崩溃最后几条记录可能没落盘。另外如果用户把data/目录删了记录自然也没了。解决措施开启 WAL 模式在数据库连接时执行PRAGMA journal_modeWAL;提高写入可靠性。定期备份软件启动时自动把chat.db复制一份到data/backup/保留最近 7 天的备份。导出功能提供“导出对话记录”按钮把记录导成 Markdown 或 JSON用户自己存着。import shutil import datetime def backup_db(): today datetime.date.today().isoformat() backup_path fdata/backup/chat_{today}.db shutil.copy(data/chat.db, backup_path)这个备份逻辑很简单但很管用。我有次改代码把数据库结构改坏了就是靠备份恢复的。4.4 常见问题速查表问题可能原因解决方法软件启动报错“缺少 DLL”没装 Visual C 运行库装一下 VC Redistributable发消息没反应Ollama 没启动启动 Ollama 或点软件里的启动按钮回答乱码模型不支持中文换 Qwen2 或 ChatGLM 等中文模型回答一半停了达到 MAX_TOKENS 限制调大 MAX_TOKENS 或让模型继续界面卡死模型推理阻塞主线程把推理放到子线程用信号槽更新界面打包后无法运行PyInstaller 漏了依赖用--collect-all重新打包界面卡死这个问题特别常见。PyQt 的主线程负责界面刷新如果在主线程里发 HTTP 请求等模型回答界面就会“未响应”。解决办法是用QThread把推理放到后台线程通过信号把结果传回主线程更新界面。这个改动不大但体验提升明显。5. 后续可以扩展的方向5.1 多模型切换与对比现在软件一次只能用一个模型。但不同模型有不同擅长Llama 3 通用Qwen2 中文好CodeLlama 写代码强。如果能在界面上加一个下拉框随时切换模型甚至让两个模型同时回答同一个问题做对比学习价值会大很多。实现思路Ollama 支持同时加载多个模型内存够的话软件里维护一个模型列表发请求时指定model参数就行。对比模式就是发两次请求把两个回答并排显示。5.2 间隔复习与学习统计知识卡片现在只是存着没有“复习提醒”。可以加一个简单的间隔复习算法新卡片 1 天后复习答对则间隔翻倍答错则重置。每天打开软件时自动推送今天该复习的卡片。学习统计也可以做这周问了多少问题、收藏了多少卡片、哪个标签的卡片最多。这些数据都在 SQLite 里写几个查询就能出图表。用 PyQt 的QChart或者直接生成 HTML 报告都行。5.3 文档导入与本地知识库增强现在的问答完全依赖模型自身知识。如果能把本地文档PDF、Word、Markdown导入让模型基于文档内容回答那就真正变成“个人知识库”了。技术路线是 RAG检索增强生成文档切片 → 向量化 → 存向量库 → 提问时检索相关片段 → 拼进 prompt 发给模型。这个功能工作量不小但价值很高。对于学习场景把教材、笔记导入进去问的问题就能得到基于自己材料的回答比通用模型靠谱得多。向量库可以用chromadb或faiss都是本地运行的不破坏“离线”原则。5.4 移动端适配的可行性有人问能不能在安卓上跑。技术上可行但体验会打折扣。安卓上可以用Termux装 Ollama或者用llama.cpp的安卓版。但手机内存有限只能跑 1B-3B 的小模型回答质量下降明显。而且手机发热、耗电都是问题。我的建议是如果真要做移动端不如做成“远程连接”模式——手机 App 连到电脑上的本地服务电脑负责推理手机只做界面。这样既保留了本地运行的优势又能在手机上用。不过这就涉及网络配置复杂度上来了看个人需求取舍。5.5 开源社区协作的注意事项这个项目我打算一直开源。开源之后最需要注意的就是许可证选择和贡献流程。许可证我选了 MIT最宽松别人拿去改、拿去卖都行只要保留版权声明。为什么选 MIT 而不是 GPL因为 GPL 要求衍生作品也必须开源有些公司内部用就不方便。MIT 更自由传播更广。贡献流程上我建议在仓库里放一个CONTRIBUTING.md写清楚怎么提 Issue、怎么提 PR、代码风格是什么。不然收到的 PR 格式五花八门合并起来很痛苦。另外Issue 模板也很重要让用户提问题时自动带上系统信息、Ollama 版本、错误日志省得来回问。提示开源项目最怕“提了 Issue 没人理”。我的做法是设置一个自动回复告诉用户“已收到会在 48 小时内查看”然后尽量做到。哪怕只是回一句“我看看”也比石沉大海强。6. 一些个人体会做这个软件最大的感受是本地 AI 的门槛比想象中低但体验做好比想象中难。让模型跑起来可能就几十行代码但要让一个不懂技术的用户顺利装上、用起来不卡、出了问题能自己解决需要做很多“看不见”的工作——错误提示要清楚、配置要简单、文档要详细、打包要干净。另一个体会是小模型真的够用了。我一开始总想着“等我有好显卡了跑大模型”但实际用下来7B 模型回答学习问题已经绰绰有余。它可能不如云端大模型那么“聪明”但胜在稳定、免费、离线、可控。对于日常学习来说这些优势比“聪明”更重要。最后分享一个小技巧如果你也想做类似的项目先把最小可用版本跑通再慢慢加功能。我第一版就只有一个输入框、一个输出框、一个 SQLite 存记录连界面都没好好做。但那个版本让我确认了“这条路走得通”后面的知识库、标签、复习功能都是在这个基础上长出来的。如果一开始就追求大而全很可能卡在某个技术细节上最后什么都没做出来。这个项目我会继续维护后面打算把 RAG 文档导入做出来再优化一下打包流程让 Windows 用户下载后能一键安装。如果你也在折腾本地 AI 应用欢迎交流踩过的坑我都记在仓库的docs/目录里了。