从零构建本地AI平台：模型管理、知识库与API网关的架构实践

如果你只是想在本机跑一个大模型聊聊天现在的工具其实多到有点挑花眼但如果你想要的是一个开源的、完全运行在本地、又能当正经生产力工具的 AI 平台——能管理模型、能挂知识库、能调用工具、能同时给几个人用、还能对外提供标准 API——你会发现市面上几乎没有现成答案。我花了大概八个月做了一个取名 Hearth核心目标就一句话一台不出网的机器也能把这套东西跑起来并且用得不难受。文章会把这套平台的架构、选型理由、核心模块、本地化优化的实战经验以及开源之后被用户折腾出来的教训从头到尾完整拆一遍。适合两类人读一类是准备自己搭本地 AI 平台的技术负责人或独立开发者另一类是手里有开源项目、想提前知道发布后会面对什么的朋友。1. 从本地能跑模型到本地 AI 平台中间隔着一整个工程1.1 我最初想解决的痛点开始动手之前我桌上已经摆了好几个现成工具Ollama 负责拉模型Open WebUI 做聊天界面AnythingLLM 挂知识库。说实话如果只是零散地聊聊天这套组合完全够用。但真正把 AI 放进日常工作流之后痛点一个接一个地冒出来模型装多了没人管GGUF、AWQ、GPTQ 各种格式混在同一个目录里时间一长根本分不清哪个文件对应哪个版本想给知识库加一批文档得自己另外搭一套向量库和分块流程中间任何一个环节不对检索效果就稀烂最难受的是想让自己写的脚本调用本地模型结果发现各家接口根本不兼容有的只支持 chat不支持 embeddings更别谈 function calling。这些零散问题加在一起指向的其实不是再找一个聊天前端而是一个能自己掌控的完整平台。1.2 full fledged到底指什么全功能这个词很容易变成营销话术所以我一开始就给自己划了一条明确的验收线把能力拆成可逐项检查的条目。后面所有迭代都跟着这条线走而不是凭感觉加功能。能力维度最低可用标准Hearth 的做法模型管理能装、能删、能切换模型仓库 量化信息识别 热切换对话引擎多会话、流式输出、上下文可控上下文压缩、token 级统计知识库能传文档、能检索、能标来源分块 混合检索 重排答案带引用工具调用模型能触发外部动作原生 function calling 插件机制API 网关兼容主流 SDK实现 OpenAI chat / embeddings / models 接口多用户权限隔离、配额、审计角色权限 Token 配额 操作日志离线部署断网可用、可迁移离线模型包 全量依赖 vendoring这张表后来变成了 README 的功能清单也变成了每次发版前的验收标准。没有它全功能很容易做成什么都沾一点什么都用不顺。实际开发时这张表还帮我挡掉了很多需求膨胀凡是不能对应到表里某一行的功能我一律先不做等真的有人需要再说。2. 架构取舍为什么是 Python 后端 本地推理引擎 适配器层2.1 核心数据流整体是一个比较传统的单体加插件架构没有一开始就上微服务。本地平台的用户量级决定了微服务带来的运维成本远大于收益一套 docker compose 能拉起来的系统没必要拆成七八个服务互相调用。请求路径大概是这样的浏览器或外部 SDK 先到 API 网关网关完成鉴权、配额和路由把请求交给会话服务会话服务负责取历史消息、计算 token 数、必要时压缩上下文然后是模型路由根据用户选的模型、当前负载和硬件资源把请求发到对应的推理后端推理结果以流式方式一路返回前端。可见的部分分成三大块FastAPI 写的后端服务、Vue3 写的前端界面、可插拔的推理适配层。存储层默认用 SQLite配置项里可以一键切成 PostgreSQL——本地单机场景 SQLite 完全够用还少一个常驻服务要维护。推理适配层是整套架构里最重要的抽象它决定了平台能接多少种后端也决定了未来更换运行时的时候要不要动上层代码。2.2 模型运行时三选一我为什么没全押本地推理的运行时选项很多我实际对比过三类直接内嵌 llama-cpp-python、外部 Ollama 进程、vLLM 服务。三者的取舍非常典型很多人在选型时会犹豫很久。直接内嵌部署最简单一个进程解决所有问题跨平台支持好但并发和长上下文表现一般而且 llvm-cpp 的 Python 绑定在 Windows 上编译经常翻车。Ollama模型管理和命令行体验一流但作为外部进程平台想拿到细粒度的运行参数、做动态显存调度会比较绕。vLLM吞吐和并发是王者但要求 Linux 加足够显存CUDA 依赖很重普通用户的桌面环境很难伺候。我的选择是默认内置 llama-cpp-python同时提供 Ollama 和 OpenAI 兼容端点的适配器。普通用户开箱即用想上规模的人可以外接 vLLM想用远端模型的人也能把 Hearth 当成统一入口。多维护一层适配器的代价是每个新版本都要在不同后端之间做回归测试但换来的是平台不被任何一个运行时绑架。选型这种事最怕的就是因为大家都在用而跟风一定要回到你自己的部署场景里去看。2.3 前端为什么用 Vue3 而不是 Next.js做本地平台前端框架我也纠结过一段时间。最后选了 Vue3 Naive UI不是 React 不好而是本地应用几乎不需要服务端渲染Next.js 的一部分优势在这里发挥不出来。Vue3 的单文件组件和响应式系统写管理后台类界面效率很高Naive UI 的组件风格偏简洁适合做成 Chat 类产品的干净界面。流式对话用 WebSocket 推前端按 token 逐字渲染配合虚拟列表处理长对话实测几千条消息的会话滚动起来也不卡。另一个考虑是之后套桌面壳方便Vue3 构建出来的纯静态产物不管塞进 Electron 还是 Tauri 都很省事不会遇到 SSR 应用在桌面环境里的各种水土不服。2.4 为什么不直接套 Open WebUI这个问题被问过无数次。我实际试过在那些成熟的 WebUI 项目上做二次开发聊天交互做得确实好但它们的定位是给 Ollama 用的聊天前端不是为平台设计的没有统一的模型抽象层API 权限控制弱插件机制相对封闭。我需要的是一套从模型管理、知识库到 API 网关都长在自己地盘上的系统而不是在别人的前端里缝缝补补。自己写前端的代价是工作量大但换来的是每一层都能按自己的需求裁剪。对开源项目来说这种可控性在后期的迭代速度上体现得非常明显——改一个按钮位置不用去 fork 整个上游项目。3. 让平台配得上full fledged的六个模块3.1 模型管理下载、校验、量化识别与热切换模型管理我做了三层模型仓库、运行时实例、请求路由。模型仓库负责目录和元数据每个模型在磁盘上有一个独立目录里面除了 GGUF 文件还有一份 manifest 文件记录来源 URL、SHA256、参数量、量化格式、推荐上下文长度。这样的目录结构让人哪怕直接打开文件系统也能一眼看明白models/ └── Qwen2.5-7B-Instruct/ ├── Q4_K_M.gguf ├── Q8_0.gguf ├── config.json └── manifest.yaml下载走 HuggingFace 和 ModelScope 两个渠道国内用户可以直接切 ModelScope断点续传和 SHA256 校验都做了。量化识别这步特别容易被忽略但非常重要同一个模型可能同时有 Q4_K_M、Q8_0、FP16 三个文件界面上必须明确区分不然用户以为自己换了更好的模型其实只是换了个更大的文件速度还变慢了。热切换的意思是用户切换模型只影响新请求正在进行的会话完全不受影响。实现上就是路由层维护一个模型 ID 到当前实例的映射切换只改映射不杀进程不中断已有连接。3.2 知识库不只是往向量库塞文本知识库模块是我踩坑最深的。很多人以为把 PDF 丢进去、切片、embedding、检索就完事了实际做出来的效果会很差。我最后落地的流程是文档解析、清洗、结构化分块、混合检索、重排、带引用生成。分块策略上按标题层级做切片而不是按固定字符数硬切因为按标题切能保留上下文边界每块之间保留 80 到 120 字符的重叠避免检索时把关键句拦腰截断。表格和代码块单独保留不塞进普通文本块里否则检索出来要么缺列头要么缺缩进。Embedding 模型用的 bge-m3维度和多语言表现都够用。检索阶段做两路召回一路 BM25 关键词一路向量相似度两路结果合并后交给 reranker 模型重新排一遍最后把得分最高的几段拼进提示词。这里最核心的一条经验是纯向量检索在专有名词、缩写、版本号面前表现很差BM25 补位之后效果提升非常明显。引用来源是硬需求所有生成回答必须标出材料出处否则在正经工作场景里没人敢用。我自己在内部跑过一个测试没有来源标注的回答评审几乎全部驳回加上来源之后通过率直接翻倍。3.3 工具调用与 Agent让模型不再只是聊天窗口工具调用是平台从聊天机器变成执行器的分水岭。我实现了 OpenAI 风格的 function calling模型在回复里声明要调用的工具和参数平台侧校验参数、执行、把结果送回模型再由模型生成最终答案。内置工具包括代码解释器在隔离容器里跑 Python、定时任务、系统信息查询以及一个可扩展的插件机制。插件协议做得很轻一个 manifest.yml 声明名称、描述、参数 JSON Schema一个 Python 入口文件实现执行函数用户不必改主程序就能给平台加技能。安全方面有一条底线我特别坚持默认所有工具都在沙箱里执行代码解释器必须跑在独立容器中不能直接碰宿主机文件系统。这个设计被一些用户嫌多此一举但等他们把平台部署到公司内网、要过安全评审的时候这条底线反而成了最有力的卖点。工具调用的调试也比普通对话麻烦我在界面上加了工具调用日志面板模型传进来的参数、工具返回的结果、最终生成的内容三个阶段分开展示排查问题的时候能省掉大量时间。3.4 兼容 OpenAI API 的对外网关这是我认为full fledged和自嗨之间的分水岭平台必须能当一个标准 API 服务来用而不是只能在网页里聊天。我实现了 /v1/chat/completions、/v1/embeddings、/v1/models 这些主流接口支持流式 SSE 和 JSON 结构化输出。外部任何用 OpenAI SDK 的项目只要把 base_url 指到 Hearth把 key 换成平台分配的 key就能把本地模型接进原有系统。这个兼容层让我现有的工具链几乎没有改动就接上了平台价值非常大。这里有个很实际的兼容性细节部分带思考模式的推理模型在响应里除了 content 还会返回一个 reasoning_content 字段。如果你保存多轮对话时把这个字段丢了下一轮请求就可能在服务端返回 400 错误。所以网关在落库消息时把思考内容和正文分开存再次发送时按对端要求原样带回。这类细节不做实测是发现不了的我当初是在接某个推理模型的时候被报错连番轰炸才意识到消息落库的字段设计要更细。3.5 多用户、配额与审计本地平台不等于单机单人。小团队部署之后最常见的使用方式是几个人共用一个推理服务这时候用户体系就是刚需。我做了最轻的一版管理员创建账号、分配角色角色控制能看到哪些模型、能否管理知识库每个用户每天有 token 上限防止某个人一次性把显存占满其他人全部排队。配额真正跑起来之后我才意识到限制用户一天用多少 token 不只是成本控制还能倒逼大家把提示词写得更精简服务器负载明显下降。审计日志这点被很多自部署用户低估。所有涉及模型切换、知识库变更、工具执行的敏感操作都写进日志真到了公司内部要汇报数据流向、做安全审计的时候这是最直接的证据。权限模型我尽量做成声明式配置而不是把规则写死在代码里这样管理员改角色权限的时候不用碰代码直接在界面上勾选就行。3.6 离线安装与断网使用本地可用对我的严格含义是断网也要可用。Hearth 为此做了两件事一是所有依赖都支持离线安装提供带完整 wheel 包的内网安装包二是模型可以提前打包成模型包导入不需要现场从网上下载。系统启动时会检测网络状态如果远端仓库不可达就自动切换到本地缓存模式所有下载入口变成从模型包导入。这个功能在隔离网段里特别有用。我不止一次收到用户反馈说公司机器不允许连外网之前他们只能放弃本地 AI 方案现在终于可以有边界地解决了。离线模型包的格式我定义为 tar.zst 压缩包里面包含模型文件、配置文件、许可证文本导入时自动校验 SHA256防止传输过程中文件损坏。这套机制看起来不起眼却是企业用户决定要不要长期使用的关键因素。4. 本地化真正的难点显存、性能、依赖地狱与打包4.1 24GB 显存也撑不起什么都跑很多人以为买了大显存显卡就万事大吉实际一跑起来才会发现显存大头不只是权重。以 7B 模型 Q4_K_M 量化为例GGUF 文件大约 4.7GB看起来 24GB 显卡绰绰有余但如果上下文开 32KKV Cache 会多吃掉好几个 GB再开并行支持多人同时用每增加一路并发KV Cache 又翻一倍。所以显存规划要按权重 目标上下文 × 并发数来算而不是只看模型文件大小。我因此在平台里加了一个显存估算器用户选模型和上下文长度的时候界面直接显示预计占用避免生成到一半爆显存。实测下来24GB 显卡比较舒服的组合是7B 或 8B 模型 16K 上下文 2 到 4 路并发往上跑 32B 模型就建议开 CPU offload或者干脆换 48GB 以上的机器。很多人不愿意面对这个现实总想着反正显存有 24G直接上最大的模型结果要么被 OOM 折磨要么速度慢到没法用。4.2 CPU 推理怎么做到能等得起不是所有人都有好显卡所以纯 CPU 环境我也花了不少功夫。最重要的经验有三条一是尽量用 Q4 量化模型推理速度和内存占用比高阶量化好太多二是上下文长度要克制CPU 上开 32K 上下文简直是自虐生成速度和稳定性都会明显下滑三是利用 llama.cpp 的层数参数做部分 GPU offload哪怕只有几层能放到 GPU 上效果也聊胜于无。另一个容易被忽略的点是 Apple Silicon 用户。llama.cpp 的 Metal 后端在 M 系列芯片上表现很不错不需要 NVIDIA 显卡也能获得可以日常使用的速度。我在文档里专门放了一张按硬件推荐模型档位的表很多用户照着选就不再纠结了。CPU 环境下首 token 延迟比生成速度更影响体验所以我把这块的优化重点放在 prompt 缓存上重复前缀的请求直接复用计算结果实测能省掉不少重复计算时间。4.3 依赖地狱llama-cpp-python 编译失败的真相本地 Python 项目最头疼的依赖就是 llama-cpp-python。这个包在 Windows 上从源码安装经常失败报错末尾通常能看到类似 cl.exe failed with exit status 2 的信息。本质原因不是代码问题而是 Windows 上缺少完整的 MSVC 编译环境或者 CMake 版本不对Python 正试图现场编译 C 扩展。我的处理方式分三层第一发布预编译 wheel让绝大多数用户用 pip 直接装不用碰编译器第二文档里给出 Windows 上安装 Visual Studio Build Tools 和 CMake 的精确步骤给确实需要自己编译的人留一条路第三安装脚本默认从预编译源走只有用户显式开启本机构建才会去现场编译。另一个依赖坑是 PyTorch。很多 embedding 方案离不开它但对一个推理平台来说为了一个 embedding 模型拖进两三个 GB 的 PyTorch实在不划算。我后来把 embedding 和 reranker 都改成了 ONNX Runtime 或 llama.cpp 原生支持默认安装路径完全不需要 PyTorch只有用户主动开启某些高级功能才会装上。这个改动把基础安装包体积直接砍掉了一大截对国内网速不稳定的用户来说体感差异非常明显。4.4 打包分发三种安装方式本地平台如果只有一个 git clone 教程基本等于没发布。Hearth 现在提供三种安装途径Docker Compose 一键起服务适合部署到 NAS 或家庭服务器官方安装脚本适合 Linux 和 macOS 上愿意自己折腾的人桌面版用 Tauri 套壳适合 Windows 用户双击安装。三种方式共享同一套后端只是包装不同。打包过程中我吃过两个教训一是 Windows 长路径问题模型目录层级深了之后很容易超过 260 字符安装器里必须默认开启长路径支持否则用户解压模型包到一半就报错二是杀毒软件误报早期用 PyInstaller 打的包经常被 Windows Defender 拦下来后来换成 Tauri 套壳并做了代码签名误报率才明显下降。这类问题在开发机上完全遇不到只有真的发给大量用户之后才会集中暴露。4.5 我的实测性能参考整理一份测试环境的数据供参考这些数字只是典型的可用水平不代表上限不同模型和量化档位差异很大硬件环境模型量化上下文生成速度RTX 3090 24GB7BQ4_K_M8K约 50-70 tokens/sRTX 3090 24GB32BQ4_K_M8K约 12-18 tokens/s纯 CPU i7-127007BQ4_K_M4K约 4-6 tokens/sApple M3 Max7BMetalQ4_K_M8K约 25-35 tokens/s生成速度只是体验的一半prompt 处理的 prefill 速度决定了首 token 延迟。很多人只盯着生成速度结果首 token 等半天体感还是崩盘。我在界面上把首 token 延迟和生成速度分开展示用户才能真正判断瓶颈在哪个环节。这部分数据对性能调优的指导意义比任何跑分软件都大。5. 开源之后从 issue、许可证和 CI 里学到的教训5.1 最高频的 issue 其实与技术无关项目发出去之后我原本以为最难的会是模型效果或者性能结果收到最多的 issue 是安装失败和使用困惑。很多人在 Windows 上装不对 Python 版本、装不上 CUDA 依赖、或者不知道下载哪个模型。这件事让我意识到一个很现实的问题开源项目最大的成本不是写代码而是把新用户从零跑起来这件事做到位。后来我把安装文档重写成按操作系统分支的方式每个分支带截图和完整命令还加了一个诊断工具用户跑一下就能把环境信息一次性贴进 issue。命令大概长这样hearth doctor它会检测 Python 版本、CUDA 驱动、磁盘空间、端口占用并输出一份标准化报告。这个改动之后真正无效的 issue 少了很多能复现的问题也更容易定位。开源维护者如果不想被装不上类 issue 淹没一定要尽早把诊断工具做出来。5.2 License、模型协议与合规开源代码是一回事模型是另一回事。平台代码用 Apache-2.0但模型本身有各自的许可证Llama 系、Qwen 系、其他社区模型的条款都不一样混用的时候很容易踩坑。我在平台里做了一个模型详情页下载哪个模型就展示对应许可证摘要并且不允许在没有用户确认的情况下自动下载商用条款不明的模型。这点在开源社区非常加分因为很多企业用户第一件事就是确认许可证。另外项目自身的仓库里我没有捆绑任何大模型文件仓库体积保持精简也避免了模型许可证对代码许可证的污染。如果有用户需要定制化预装模型的发行版就走独立的构建流程把模型和代码分开交付。许可证这件事没出事的时候觉得无所谓真出事就是法律风险一定要在一开始就处理干净。5.3 我最后悔没早点做的事回看整个开发周期如果重来一遍我会更早做三件事。第一写详细的技术决策记录把每个模块为什么这样选型写下来省得三个月后自己都忘了当初的考虑也让贡献者知道不是随便一拍脑袋定的。第二建一个跨平台的自动测试矩阵在 CI 里把 Windows、macOS、Linux 三种环境的安装和核心流程都跑一遍很多 bug 其实早该在合并前被拦住。第三把错误信息写得像人话而不是把 Python traceback 直接甩给用户。这三个都不是看起来最酷的工作但它们是开源项目能持续活下来的地基。最后再说一点个人体会。做本地 AI 平台这两年我最大的感受是本地并不是一个限制反而是一种解放。不依赖外部服务就不受配额、限流和接口变动的影响数据在自己手里很多部署障碍自动消失模型可以随便换不用迁就任何供应商。这个项目现在已经是我日常工作的默认生产力入口知识库、代码解释器、API 网关天天在跑。如果你也在酝酿做一个本地优先的 AI 项目我的建议很简单先把一个人离线环境下用它完成一件真实工作走通再谈功能和开源。想交流具体实现细节的朋友欢迎在项目仓库的讨论区找我。