最近几个月我把工作里能交给 AI 的部分全部收回了本地整个项目代号叫 CortextAI。起名时没想太复杂cortex 加 text想表达的是“自己电脑里长出一个能对话的皮层”。折腾到今天它的定位已经变成一个私人、离线、接近操作系统的东西本地模型推理、本地知识库、本地文件与工具调用、本地任务调度全部绕开云端。这种方案能解决什么适合什么人中间踩过哪些坑下面按我实际搭建的顺序完整说一遍。CortextAI 不是聊天机器人。它更像贴在本地运行环境上的一层“系统”把文件、备忘、日程、历史笔记、待办这些散落资源统一收编然后用自然语言描述“我要写什么、查什么、整理什么、提醒什么”。但它比普通聊天工具多了检索、工具调用、任务编排这几个能力所以我才坚持叫它操作系统。适合它的人第一类是数据不能出本机环境的从业者第二类是有断网办公场景的开发者或写作者第三类是想摆脱各家平台配额和计费规则的效率控。反过来如果你只想装个软件就能获得接近全知全能的答案不想碰任何调试和工程那现在的本地离线方案还不适合你这是需要先说透的。1. 为什么我会把它定义为“私人离线 AI 操作系统”1.1 操作系统说的不是 UI是调度关系我们平时说操作系统更多在说它怎么管理硬件、进程、文件、网络而 Windows、macOS 给我们的只是图形界面。CortextAI 想套用的其实是前一层让 AI 作为中枢调度本机里的各类资源和技能。举个例子我早上起来只需要说一句“把昨天遗留的 TODO 整理成今天的执行清单再和知识库里相关笔记做合并”系统不会只给一段空泛回答。它先要把本地 TODO 文件读出来把知识库检索打开把相关旧笔记找出来再让大模型做去重、归类和生成。这个“识别需求 - 拆分任务 - 调用工具 - 汇总结果”的过程和操作系统的资源调度在逻辑上非常像。没有这一步模型再大也只是个在线问答框算不上私人系统。1.2 它重点解决的三类问题第一是隐私数据不出本机。公司内部文档、个人日记、业务数据落到模型服务商这件事并不是所有人都能接受。CortextAI 的推理、向量化、知识库存储全部在本机完成只要不自己开端口数据就不会离开机器。第二是断网环境可用。飞机上、高铁隧道里、偏远的办公点这些地方远程模型完全不可用但本地模型只要电量和算力还在就能继续做总结、检索和写作辅助。这一点对我来说比性能提升还关键。第三是行为边界完全可控。在线平台今天改个系统提示词明天换个模型你的工作流可能就变了本地方案里模型版本固定工具代码在自己手里想怎么改就怎么改。自己动手折腾的代价是维护成本换来的是确定性和自由度。1.3 这件事的适用边界先泼一盆冷水本地离线 AI 目前离“全知全能”还非常远。7B 或 8B 量级的模型在复杂推理、长文本理解、代码生成上的能力上限明显不如当前顶尖的云端模型。如果你的诉求是“帮我写一篇复杂的法律意见书还要引用最新判例”本地小模型很难做好。所以我把它的定位收缩到“个人知识管理和自动化辅助”而不是“通用 AI 大脑”。它适合处理已有资料的重组、摘要、问答、跨工具调度不适合凭空气生成高专业度的内容。明确了这条边界之后整个系统的架构才会变得很清爽模型负责推理向量库负责记忆工具负责执行各管一摊。2. 总体架构与选型背后的逻辑2.1 我把系统拆成四个层CortextAI 对外是一个整体内部我坚持拆成四层交互层、编排层、工具层、模型层。交互层负责界面和语音入口我用的是本地 Web UI后续可能换成一个更接近桌面的客户端。编排层是核心负责把用户的一句话拆成可执行计划决定先调哪个工具、再把结果交给模型做下一步推理。工具层是各种本地函数比如文件搜索、日历读取、命令执行、HTTP 请求。模型层则是本地推理运行时和嵌入模型。这样做最大的好处是替换成本低。今天我想把 Qwen 换成 Llama只需要改模型层想把聊天界面换掉只需要动交互层。工具层和编排层保持接口稳定系统不会因为换一个组件就推倒重来。这种解耦思路和我以前维护后端服务时的分层逻辑完全一致只是在 AI 场景里多了一个“模型”变量。2.2 为什么选 Ollama 作为本地推理运行时我用过好几个本地推理框架最后留在 Ollama 上。原因很直接模型管理简单命令行一条ollama pull就能拉模型而且自带 OpenAI 兼容 API 和原生 API。写工具层代码时只要能发 HTTP 请求就能把模型接进来不需要额外写 Python 绑定的胶水代码。Ollama 还有一个好用的地方是 Modelfile。我可以把系统提示词、温度、上下文长度固化进去生成一个自定义模型。比如让模型默认“先查资料再回答不能凭空编造”这个行为约束会跟随模型走而不是靠每次调用的参数去碰运气。我建议所有想复刻 CortextAI 的人认真看一遍 Modelfile 语法它是少数能低成本固化经验的入口。2.3 为什么知识库一定要走向量检索曾经有一段时间我想偷懒把几千条笔记全塞进上下文让模型慢慢读。结果非常糟糕上下文窗口有限塞得多了别说 AI连请求长度都超限了。后来我老老实实做了 RAG也就是检索增强生成。原理可以简化成三步先用嵌入模型把文档切片变成向量即一串坐标当用户提问时把问题也变成向量然后在一个本地向量库里做近邻搜索找出最相关的几条片段只把这些内容喂给大模型。这很像去图书馆之前先让索引管理员给你找出三本书而不是把整个图书馆搬进阅读室。没有这层索引大模型对你个人资料的了解永远不会超过它自己记忆里的泛化知识根本算不上私人助理。2.4 为什么 Agent 循环必须支持 Function Calling大模型本质是文本生成器输入一段文字输出一段文字它自己不会打开日历也不会搜索文件。如果要在离线场景里完成真实操作就必须给模型一个“表达执行意图”的出口。Function Calling 就是这种出口模型在回答时返回一个结构化指令比如“调用 search_file参数是 keywordcortext”再由本地的调度代码执行这个函数。我前期的 agent 循环踩过一个误区以为只要把工具说明写进 prompt 里模型就会自己输出 JSON。实际上不稳定的 JSON 解析会占用大量调试时间。后来换用规范的 Function Calling 协议让模型返回结构化的 tool_calls代码侧做统一解析稳定性一下子高了很多。这个设计决策是整套系统从“演示”走向“可用”的关键节点。3. 完整实操从空机器到能用的 CortextAI3.1 硬件基线先想清楚开始动手前要先确认自己的机器能跑什么量级的模型这是最影响体验的一步。我按常见配置给了一个参考范围直接照着看就行。硬件描述推荐模型规模预期体验16GB 内存无独显7B 模型 Q4 量化可用的问答与摘要速度偏慢32GB 内存无独显8B~14B 模型 Q4 量化有一定深度CPU 跑大量任务时会吃力16GB 显存以上 NVIDIA 显卡14B~32B 模型 Q4明显流畅适合多轮 agent 任务内存充足 多卡32B 以上模型可做更高质量推理成本也很可观不要迷信参数越大越好关键看你的硬件能不能把模型稳稳装下。我自己的主力机是 32GB 内存加一张 12GB 显存的显卡长期用的是 14B 模型量化到 Q4既能保证质量又不会在长时间工具循环里爆显存。3.2 部署本地模型并选好量化档位软件部分我默认的环境是 Python 3.10、Ollama、GitWindows / macOS / Linux 都行。Ollama 安装完以后先用几条基础命令验证运行环境ollama pull qwen2.5:7b-instruct-q4_K_M ollama pull bge-m3 ollama list curl http://localhost:11434/api/version第一行拉取我的主力对话模型Qwen2.5 7B 指令版量化到 Q4_K_M第二行拉取嵌入模型 bge-m3后面知识库会用第三行确认模型列表第四行确认本地 API 已启动。为什么要单独选 Q4 量化因为模型文件在 CPU/GPU 间加载时占内存Q4 把参数精度从 4 字节降到 1 字节左右换来体积和显存占用大幅下降代价只是少量推理质量损失。以 7B 模型为例FP16 大概要 14GB 模型文件Q4 往往只要 4~5GB差距非常大。我用模型的经验可以总结成一句话中文内容为主就选 Qwen 系列英文和代码场景可以试试 Llama 3.1追求嵌入质量就在文本检索里用 bge-m3这是目前我实测比较省心的组合。3.3 把个人资料变成可检索的知识库搭建知识库我分成三步解析原始文件、切块、向量化写入。原始文件大部分是 Markdown、TXT、PDF 和 Word 文档。我写了一个简单的 Python 脚本用 PyMuPDF 处理 PDF用内置的文本解析处理 Markdown 和 TXT遇到格式错乱的先清洗掉页码、页眉、无意义空行。切块环节最容易忽略却又直接影响检索质量。我最初按固定 512 字符切结果经常把一句话切开检索时返回残缺片段。现在改用 RecursiveCharacterTextSplitter优先按段落切段落太长再按层级切保留 80 字符的 overlap这样语义完整性会好很多。代码大致是这样from pymupdf import open as pdf_open from langchain_text_splitters import RecursiveCharacterTextSplitter doc pdf_open(note.pdf) text \n.join(page.get_text() for page in doc) text clean_text(text) splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap80, separators[\n\n, \n, 。, , , ], ) chunks splitter.split_text(text)向量化和入库我用 Chroma 的本地持久化版本数据目录就放在项目下的cortext_kb文件夹。这样跑出来的向量库是纯本地文件想备份就复制整个目录不用担心数据库服务更加复杂。import chromadb client chromadb.PersistentClient(path./cortext_kb) col client.get_or_create_collection( namepersonal_kb, metadata{hnsw:space: cosine}, ) col.add( documentschunks, ids[fchunk_{i} for i in range(len(chunks))], metadatas[{source: note.pdf} for _ in chunks], )搜索时调用col.query(query_texts[user_question], n_results5)拿回相似片段再把片段拼进系统上下文这就是一个能通跑的本地知识库。3.4 给模型配上能“动手”的工具知识库只能让模型“查”真正让系统“干活”还需要工具调用。我先从最常用的三个技能开始搜索文件、读取文件、添加日程。每个技能都以函数形式暴露同步在工具描述里写清楚参数。下面以搜索文件为例TOOLS [ { type: function, function: { name: search_file, description: 搜索本地知识库或者缓存目录里的文件, parameters: { type: object, properties: { keyword: {type: string, description: 搜索关键词} }, required: [keyword], }, }, } ]与模型交互时我用 Ollama 的/v1/chat/completions接口消息结构和 OpenAI 的格式一致。核心循环长这样import requests messages [{role: user, content: 找出去年写的季度总结}] while True: resp requests.post( http://localhost:11434/v1/chat/completions, json{model: qwen2.5:7b, messages: messages, tools: TOOLS}, ) msg resp.json()[choices][0][message] messages.append(msg) if not msg.get(tool_calls): break for call in msg[tool_calls]: result run_local_function(call[function][name], call[function][arguments]) messages.append({ role: tool, tool_call_id: call[id], name: call[function][name], content: str(result), }) print(messages[-1][content])这个循环并不复杂但我会特别强调一点工具返回的结果要尽量结构化比如用{status: ok, path: ..., preview: ...}模型才容易正确解读。如果直接扔一堆未经清洗的日志原文模型多半会懵回答内容会非常跳跃。3.5 多 Agent 工作流的落地尝试把单个模型跑起来之后我把编排层升级成多 Agent 模式。具体是在本地同时维护几个不同角色规划者负责拆任务执行者负责调用工具审查者负责检查最终输出。它们共享同一个知识库但上下文相互隔离。比如我需要一份月度复盘规划者把“读取当月笔记、筛选关键事件、按模板生成复盘”切成三步执行者逐步调用工具审查者最后检查遗漏和格式问题。这种多 Agent 协作的真实费力点不在代码而在于把任务边界控制清楚。如果没有清晰的终止条件几个 Agent 很容易互相循环喂任务上下文越来越长最终结果却原地打转。我的做法是给每条 Agent 提示词加上明确的“结束条件”当你拿到完整材料并输出总结后直接结束不要反复确认。4. 离线与私有的细节是要较真的4.1 把流量牢牢按在本机说是离线就要把每一步都关死。Ollama 默认监听回环地址 127.0.0.1也就是只有本机能访问但这还不够。我在系统防火墙里额外禁用了 Ollama 进程的出站网络防止某些配置项把它带回远程服务。检查办法很简单先看进程监听地址别让它绑到0.0.0.0上ss -tlnp | grep 11434如果输出里的监听地址不是 127.0.0.1就通过启动参数或者环境变量重绑。我还会定期用抓包工具确认没有任何请求发往外部 IP尤其在使用第三方依赖的时候。自己装的开源模块也可能有回连行为这一点不会因为模型本地化而自动解决。4.2 配置、Prompt、向量库都需要备份离线系统最怕的不是故障而是数据丢失。模型文件可以随时重新下载但知识库向量化之后如果临时改动了原始文档再重新切块旧向量可能已经失去对应关系。所以我定了一条流程每次重要任务运行完自动备份 Chroma 目录同时把工作流里的 Prompt 文件提交到 Git 仓库。Prompt 在这个系统里就是配置不是可有可无的文本。我把每个角色的系统提示词、温度、上下文长度、模型版本都写成独立文件这样改一版就能回退一版。没有这套版本管理你的系统会越跑越像一团黑盒最后连自己都说不清为什么某次输出变了。4.3 离线方案的边界条件你还需要想清楚“离线”到底指什么。如果整个系统里只有对话模型是本地推理但你没注意自己使用的 OCR、翻译、语音转写模块走了远程 API那它就算不上真正的私有系统。我在搭建时把网络白名单列成一张表凡是需要请求外部的组件要么换成离线替代实现要么直接禁掉。另一个边界是模型更新。拉取新模型、向 Ollama 下载更高质量的权重这些动作终究需要联网。我可以接受“运行时不联网、更新时按需联网”所以在架构上把所有外部依赖都集中在一个更新脚本里平时主程序不访问网络只有明确触发更新时才临时放行。这套约定让“离线”成为一个可维护的默认状态而不是一个需要靠自觉维持的临时状态。5. 踩坑记录与排查速查表5.1 回答泛泛带不动资料信息我最早遇到的问题是模型给出的回答听起来很像那么回事但完全没有引用我知识库里的内容。排查下来不是模型不够好而是检索结果没有真正进入模型上下文。后来我把检索片段加进系统消息并明确要求“优先引用检索片段中的事实”效果立刻改观。另一个办法是把任务缩小。与其让模型一次性总结二十份笔记不如先让检索工具把最相关的三份文件找出来再让模型只对这三份做摘要。上下文越聚焦回答越容易有细节这是我在本地模型上反复验证过的经验。5.2 检索结果错位问东答西情况是用户问“上个月的销售数据”库里有相关文档但检索返回的全是无关片段。最常见的原因有三个切块太碎导致语义被切碎嵌入模型不适合中文向量检索距离函数选错。我的调整顺序是先确认中文嵌入模型用的是 bge-m3其次检查切块策略保证每个块至少是一个完整段落再次把距离函数换成 cosine。问题如果还没解决就用一条具体问题做检索测试逐段调整解析和清洗逻辑。检索质量的调试本质上是需要不停做语义相关性测试的活。5.3 工具调用不触发或者乱触发本地模型对 Function Calling 的支持差异很大。有的模型会自动把工具描述当成普通文本回答完全不返回 tool_calls有的模型则会把所有工具都轮番调用一遍把任务拆得七零八落。实测下来 Qwen2.5 指令版对 Function Calling 的支持比较稳定我最终把它作为对话模型的默认选择。工具描述也有讲究。如果你的 description 写得太抽象模型就不知道什么时候该用如果写得太复杂模型又会过度使用。我现在会为每个工具加一个“触发条件”字段比如“当用户需要查找项目文件时使用”这比仅仅写“搜索文件”要精准得多。5.4 推理太慢、内存爆炸、闪退类的性能问题纯粹的 CPU 推理7B 模型在小笔记本上跑一个稍长的答案可能要几分钟这会让 agent 循环像卡死一样。优化顺序是先降低并发数让 Ollama 每次只加载一个模型并把并行会话数降到 1export OLLAMA_NUM_PARALLEL1 export OLLAMA_MAX_LOADED_MODELS1然后考虑更小的量化档位或者换 7B 模型。如果仍然内存溢出就要检查是不是一个进程把向量库全部加载进内存了Chroma 默认在数据量很小时问题不大但本地库文件变大后最好配置成惰性加载或者定期压缩索引。最后提醒一句开太多浏览器标签又把本地模型跑满机器一定会卡这不是程序 bug是物理上限。5.5 一个可以直接抄的排查表现象可能原因处理建议回答空洞、不引资料检索结果未进入上下文把检索片段注入系统消息返回内容总是英文系统提示词没限定语言添加“必须使用中文回答”知识库问东答西嵌入模型中文能力弱换用 bge-m3重跑向量化工具调用不触发模型对 Function Calling 支持差换 Qwen2.5调整工具描述工具调用频繁死循环缺少结束条件在提示词里加入终止条件推理速度慢并发和显存配置太高设置单模型加载、降并发程序跑完就崩溃向量库索引过大定时清理、备份并重建索引6. 一些阶段性的个人体会把这套系统从演示跑到真正稳定的过程比我想象中要费时间。最大开销不是部署模型而是反复调上下文、工具返回格式和检索质量这三者之间的匹配关系。模型今天能理解同一个提示词不代表换个模型版本还能理解所以我把每条 Prompt 都当代码一样管理每一次改动都有记录可查。如果问我给后来者的最重要建议我会说不要一开始就扑向“大而全”的多 Agent 平台。先把一个最小闭环跑通本地读文件本地切片本地检索本地生成答案最后落回本地待办清单。当这五个动作稳定之后再往上面加调度、加多 Agent、加更花哨的入口。CortextAI 这个代号能不能成立不在于模型多大而在于它是否真的成了那个替你管好本地事务、又能完全听你安排的私人系统。