最近在折腾一个叫 MyPal3 的自部署 AI 助手项目也就是这个系列要开坑的主角。先说结论它能让你在本地跑起自己的大语言模型聊天助手还能挂上私人文档做知识库问答所有对话记录和文件数据都留在本机不经过任何第三方云端。名字里的 “Pal” 是伙伴的意思“3” 是第三个迭代版本这也是我把它作为系列第一篇的原因——这个版本在架构上做了比较大的调整值得单独拎出来聊聊。这篇我会从项目定位、技术选型、部署环境和基础功能逐层拆开把我实际踩过的坑和验证过能用的配置方案都写出来。不管你是第一次接触自部署 AI 助手的新手还是之前玩过同类项目想迁移过来的老手都能在里面找到对应的参考。这一篇先把地基打牢后续几篇再展开知识库、语音交互和自动化工作流这些进阶玩法。1. MyPal3 到底是个什么东西1.1 为什么我会自己搭一个 AI 助手市面上现成的 AI 助手产品不少网页版、手机 App、各种套壳客户端一抓一大把。但用多了就会发现几个绕不开的问题对话记录全在别人服务器上涉及工作笔记、家庭事务、个人想法这类内容时总是心里没底想让它读取本地文件做问答要么文件上传大小受限要么格式支持有限更关键的是通用助手默认回答太“泛”没有我积累的文档和笔记做支撑很多问题只能给出框架性的答案落不了地。MyPal3 这个项目就是为了解决这几个痛点出现的。它把模型推理、对话存储、知识库索引全部放到本地我自己的 Markdown 笔记、PDF 文档、思维导图导出的文本都可以直接喂进去。跑起来之后它就不再是一个“什么都知道一点但什么都不精”的通用助手而是一个真正了解我工作上下文和个人资料库的私有助手。对于隐私敏感、需要本地化运行、又希望保留完整可控性的场景这套方案几乎是刚需。从版本命名也能看出来这个项目的演进逻辑。“1” 和 “2” 时代我主要在用单一模型做简单的中转对话功能上更像是一个带界面的模型调用工具。到了 “3”核心变化是引入了本地向量数据库和模块化的 Agent 框架模型可以挂工具、查资料、执行多步任务。这个架构上的换血意味着整个部署方式也变了所以我才决定从第一篇开始按新架构重新梳理一套完整的上手指南。1.2 技术选型为什么选这套组合先说模型层。MyPal3 默认支持 Ollama 和 llama.cpp 两种本地推理后端前者适合快速验证后者适合深度调优。我实际主力用的是 Ollama原因很简单它把模型管理、上下文长度、GPU 显存分配都封装成了统一接口一条命令就能拉起 Llama 3.1、Qwen2.5 或者 Mistral 系模型省去了手动编译和二进制管理的麻烦。再往上是服务层。MyPal3 提供了一套基于 FastAPI 的本地 API 服务所有对话请求通过localhost走 HTTP 访问这样前端界面、手机 App、命令行脚本都能共用一套后端逻辑。选 FastAPI 而不是 Flask 或者 Node.js纯粹是因为异步性能和 OpenAPI 文档自动生成这两点太香了调试接口的时候直接访问/docs就能看到所有可用端点省了好多事。知识库这块用的是 ChromaDB一个嵌入式向量数据库。选它而不是 Milvus 或 Qdrant是因为在单机场景下 ChromaDB 的开箱体验最好——不需要单独维护数据库服务Python 进程内直接读写配合all-MiniLM-L6-v2这样的轻量 Embedding 模型普通文档索引速度完全够用。如果你只是给自己一个人用真没必要为知识库引入一套分布式重型方案。2. 部署前的硬性准备2.1 硬件与系统环境先说硬件底线。如果你只想跑 7B 级别的量化模型比如 Qwen2.5-7B-Q4需要至少 8GB 显存且推荐纯 GPU 推理。16GB 显存可以把 14B 模型跑起来内存至少 32GB 才算舒服。我自己的机器是 RTX 4070 12GB跑 Qwen2.5-14B 的 4bit 量化版稍微有点吃紧长对话下偶发显存溢出但把上下文长度调到 8192 之后基本能稳定用。如果是纯 CPU 推理除非你对速度完全无所谓否则我不建议碰 7B 以上的模型——生成速度会掉到每秒几个 token问答体验几乎是不可用的。操作系统方面Windows 11、Ubuntu 22.04、macOS 14 我都试过。最省心的是 Ubuntu因为 Ollama 的 CUDA 版本对 Linux 支持最完善Windows 用户记得装好最新 Nvidia 驱动并且在安装 CUDA 版本 Ollama 时留意是否额外需要 CUDA 运行时macOS 的话Apple Silicon 机器可以跑 Metal 加速M 系列芯片的 32GB 版本运行 7B 模型效果还行但 14B 会比较吃力。这里给一个可复制的部署路径先别急着配环境把机器重启到一个干净状态关掉不必要的后台进程把 Nvidia 驱动锁死在一个稳定版本上Linux 下建议用nvidia-driver-535系列再开始装依赖。我最早就是没管驱动版本结果 Ollama 怎么都探测不到 GPU排查了整整一下午最后发现是驱动太新和 CUDA 版本不匹配。2.2 依赖安装与模型准备MyPal3 本体是一个 Python 项目建议用虚拟环境隔离避免搞乱系统 Python。项目拉下来之后核心依赖主要是fastapi、uvicorn、chromadb、sentence-transformers、requests这几个requirements.txt里都有。安装命令我放在下面git clone https://github.com/your-repo/mypal3.git cd mypal3 python -m venv venv source venv/bin/activate pip install -r requirements.txt装完之后先测试模型是否能正常调用。如果你用的是 Ollama先拉取一个基础模型比如qwen2.5:7b-instruct-q4_K_M然后运行ollama pull qwen2.5:7b-instruct-q4_K_M ollama run qwen2.5:7b-instruct-q4_K_M能正常对话再继续。这一步如果出问题后面所有功能都跑不起来所以要单独验证。我当时第一次拉模型时网速只有几百 KB/s一个 4GB 多的模型文件下了一个多小时中途还断过一次Ollama 的断点续传做得不错重新执行ollama pull会从断点继续不用全部重下。另外一个容易被忽略的依赖是 Embedding 模型。MyPal3 的知识库功能需要把文本转成向量首次运行时sentence-transformers会自动下载all-MiniLM-L6-v2这个文件大概 90MB。如果网络环境不稳定建议先手动执行一次python -c from sentence_transformers import SentenceTransformer; SentenceTransformer(all-MiniLM-L6-v2)下载好模型缓存免得后面启动到一半直接卡住。3. 核心功能的落地实操3.1 服务启动与基础对话配置环境配好之后打开配置文件mypal3.yaml这里有几个关键参数要按自己的硬件调整。模型后端默认是ollama如果是 llama.cpp 后端要改成llama_cpp并指定模型路径。上下文长度context_window我建议 7B 模型用 819214B 模型可以尝试 4096 或 8192但要注意显存占用是随上下文长度线性增大的。温度参数temperature默认 0.7做代码生成或结构化输出时调到 0.2 以下会更严谨日常闲聊保持默认即可。启动命令很简单uvicorn mypal3.api:app --host 0.0.0.0 --port 8000加上--host 0.0.0.0是为了让局域网内其他设备也能访问这样可以在手机或平板上通过同一个局域网 IP 使用助手。打开浏览器访问http://localhost:8000能看到对话管理页面需要 API 调试的话直接看http://localhost:8000/docs。第一次启动会有十几秒的模型加载时间属于正常现象日志里出现Model loaded successfully就说明服务就绪了。基础对话验证可以写一个最简单的 Python 脚本确认从 API 到模型再到响应的整条链路是通的import requests resp requests.post(http://localhost:8000/api/chat, json{ message: 用一句话介绍你自己, session_id: test-session }) print(resp.json()[reply])返回如果能正常回答基础链路就算通了。我特别建议第一步就验证 API而不是直接打开界面操作因为 API 出错时错误信息更直白能直接定位到是模型层、服务层还是网络层的问题。3.2 知识库接入与参数调优知识库是 MyPal3 区别于普通聊天工具的核心功能。项目的knowledge/目录下放你要导入的文档支持.md、.txt、.pdf格式每个文件会按照 512 字符的窗口切分重叠 128 字符这是为了保持语义连贯避免一句完整的话被切断在两个片段里。首知识库初始化执行脚本 python mypal3/scripts/ingest.py --source knowledge/ --persist ./chroma_store这个命令会把文档全部向量化并写入本地 ChromaDB 存储。首次运行会慢一些主要是 Embedding 模型要逐段处理文本一份 10 万字的笔记大概需要 5 到 8 分钟。索引完成后对话时 MyPal3 会先从向量库检索相关片段再拼接进 Prompt 让模型基于这些内容回答。这里有个参数很关键检索条数top_k。默认取 4 条如果你的文档本身比较零散、经常需要跨多篇内容综合回答建议调到 8。但不要盲目调高因为大模型对上下文里的罗嗦内容会“迷失在中间”检索条数太多反而会把不相关的段落塞进去干扰模型判断。我实测下来对于个人笔记类知识库6 条是一个兼顾覆盖率和准确率的平衡点。多轮对话时还建议开启“引用溯源”选项回答末尾会附上命中的文档来源。这样如果一个回答明显引错了资料你能直接定位是哪个文档片段干扰了模型而不是整个知识库从头查起。3.3 会话管理与 Prompt 行为调优MyPal3 的会话管理支持多 session 隔离每个 session 对应一段独立的聊天历史。这对实际使用场景很重要——聊工作笔记的时候不要让你上周末家庭聚会的对话记录掺杂进来否则模型抓取上下文时会混乱。前端界面上我会按主题建 session比如“项目笔记”“读书摘录”“生活琐事”各归各的位。Prompt 调优可能是投入产出比最高的环节。如果你想改变助手的行为风格不需要改代码在系统 Prompt 里加一句就行。我给 MyPal3 设置的默认风格是“直接给结论再补充简要理由不要废话”。如果你希望它像朋友一样寒暄把这段改成“回答语气亲切随意可以在给出信息前先简单回应情绪”。模型对角色描述的感知很灵敏这一点值得多试几个版本找到自己最顺手的对话节奏。另一个值得调的是max_tokens也就是单次回复的最大长度。系统默认 512写代码或总结长文档时明显不够。我一般调到 1024如果经常让助手写方案或博文草稿可以调到 2048。需要注意的是max_tokens是从生成的结果开始计算的如果 Prompt 本身很长比如塞入了知识库片段要留意上下文总长度不要超过 Backend 的context_window。3.4 语音输入与移动端远程访问MyPal3 第三个大版本加入了对语音输入的支持调本机的 Whisper 服务做语音转文字。配置项里stt_engine选whisper模型大小base就够日常使用small精度更好但响应会慢上两秒左右。我个人使用下来手机上通过浏览器访问局域网地址按住说话然后自动转文字再送进对话整套流程比敲键盘舒服太多尤其是在沙发上看资料的时候。如果想让手机在外面也能访问家里的 MyPal3可以用内网穿透工具或者自建反向代理。但这里我必须强调一句如果直接暴露到公网没有加身份认证的话你的助手机器人相当于裸奔任何人都能翻阅你的私有笔记。我的做法是只在局域网内开放外网访问一律走带密码的公网网关。这不是复杂度问题是隐私底线问题。4. 我踩过的那些坑4.1 显存不足与模型加载失败最容易遇到的坑就是显存不足。现象是服务启动到一半日志报错CUDA out of memory然后进程直接退出。这通常是显存和上下文长度两个参数叠加导致的——单纯模型文件本身也许塞得下但一旦运行时要分配 KV Cache显存一下就爆了。排查思路很简单先看模型量化等级。Q8 换成 Q4_K_M 能直接砍掉近一半显存占用再把context_window从 8192 降到 4096最后检查是不是多个进程同时占了显存比如浏览器硬解视频或者其他 CUDA 程序。我自己的解决方案是用 12GB 显存跑 14B Q4把上下文降到 6144同时关掉 ChromaDB 的持久化日志级别稳定运行一周没再出问题。如果你真的只有 8GB 显存我的建议是别硬扛 14B老老实实跑 7B。单论生成质量7B 专业场景下和 14B 的差距没有想象中那么大尤其在知识库提供充分上下文的时候7B 完全够用。等以后换了更大显存的机器再升级模型也不迟。4.2 Embedding 模型下载失败导致知识库卡死有网友反馈知识库导入时程序中途卡住不动日志没有任何报错。我排查后发现是sentence-transformers在后台联网下载 Embedding 模型网络超时后没有正确抛出异常直接挂起。这个问题的特征是卡住时 CPU 占用很低网络连接却还挂着。解决办法分两步先手动下载好模型再启动服务或者设置HF_ENDPOINT环境变量指向可用的镜像仓库。下载完成后模型会被缓存在~/.cache/huggingface/hub下之后再初始化知识库就不会联网了。另外如果你导入了超大 PDF切分和向量化的过程确实会持续好几分钟这期间看起来“像卡死”其实是在正常干活可以看 CPU 占用判断——向量化时 CPU 会持续高负载。4.3 中文问答质量明显偏弱刚开始我用 Llama 3.1 跑中文问答效果勉强能懂但遣词造句总有股翻译腔而且古诗词、成语理解经常跑偏。后来换到 Qwen2.5 的指令微调版中文表现直接提升了一个档次很多口语化表达和潜台词都能接住。如果你主要用中文对话模型选型优先级应该是 Qwen2.5 大于 Yi 大于 Llama 系。还有一个容易忽略的细节Prompt 里尽量用中文写系统指令别中英混杂。模型对系统 Prompt 的语言非常敏感你用英文限制了 “be concise”再用中文提问“给我讲讲量子纠缠”它输出的语气和结构很容易变得怪怪的。统一用中文描述角色和行为约束输出稳定很多。4.4 局域网访问时端口被防火墙拦截手机访问http://192.168.x.x:8000打不开但同一局域网电脑访问localhost却没问题多半是防火墙把端口拦了。Linux 下执行sudo ufw allow 8000Windows 下需要在“高级安全 Windows Defender 防火墙”里新建入站规则放行 8000 端口。这个问题不大但是属于那种“明明服务在跑却怎么都连不上”的经典陷阱先检查防火墙再检查服务状态顺序别反了。5. 从第一版到第三版我的使用体会写到最后说点跟技术无关但我觉得更重要的东西。MyPal3 从第一版到现在最大的变化反而不是功能和代码而是我对“AI 助手到底该承担什么角色”的理解。第一版我把所有对话都丢给模型它答什么我就用什么后来发现自己整理笔记、总结资料的次数越来越少思维好像越来越依赖现成答案。所以在新版本里我刻意把知识库的定位从“答案库”改成“素材库”——模型不是直接把我笔记里的原话复制出来而是基于笔记内容做归纳、对比和延伸。这样的回答更有用也逼着我自己保持对信息的掌控感。第三版给我的最大获得感是它让我重新意识到工具真正有价值的地方是放大已有信息的使用效率而不是替我替掉思考过程。如果你也打算搭一套自己的私有 AI 助手我的建议是先别追求功能大而全把基础对话、知识库导入、多端访问这三步跑透再考虑加语音或自动化工具。这个项目后续我还会继续更系列文章包括给 MyPal3 接入日历与邮件、用 Agent 方式做定时任务汇总、以及把本地知识库同步到手机端离线使用。先把第一篇的基础工程补扎实后面升级就有底子了。