企业官网建设流程全解析

我做了一个免费开源的本地AI学习软件，核心就是“不花钱、不联网、数据不出门”的前提下，把大模型真正跑在自己的电脑上，并且围绕“学AI、练AI、调AI”这件事，把常用的对话、资料问答、参数调试、模型切换都糅合到一个界面里。这段时间我把它整理开源了，仓库在 GitHub 上，项目名叫 Lanr（仓库地址后面细说）。

这篇文章不是来“宣传”工具的，我更想把从零开始选型、部署、调优、踩坑的完整过程记录下来。适合三类人看：想入门本地 AI 但被各种概念劝退的初学者，已经装了 Ollama 但觉得“命令行太折腾”的人，以及正在考虑做类似开源项目的开发者。我会尽量把每一步的“为什么”也讲清楚，而不是只丢给你几条命令。

1. 为什么我非要做一个本地跑的AI学习软件

1.1 被在线模型的三个问题逼到动手

先说说动机。我在在线对话模型上花了不少时间和钱，用得越多，三个痛点越明显。

第一个是数据边界问题。工作中有些代码片段、内部文档、还没公开的思路，我实在不敢贴在网页对话框里。哪怕对话平台有隐私声明，但“数据会用于模型优化”这种选项常年默认开启，谁也说不清哪天自己的资料就被拿去当训练语料了。对个人开发者来说这不是“公司合规”问题，而是最基本的心理安全感。

第二个是成本问题。订阅制按人头收费，API 按 token 收费，我属于典型的重度使用者，动辄一整个下午都在跟模型来回对话调提示词，账单累积起来真的肉疼。而本地跑一个 7B 或者 8B 参数的量化模型，除了电费几乎等于零成本，哪怕一天聊几百轮也不用担心余额。

第三个是功能限制问题。网页版模型不能自定义系统提示词模板，不能微调温度、Top P，不能随时切换一个更懂代码的模型，更不能把我的知识文档喂给模型当参考资料。本地部署之后这些限制全部消失了，想怎么调就怎么调，想换模型就换模型。

1.2 “本地运行”这四个字，到底意味着什么

所谓本地运行，不是指把网页版照搬到本地浏览器，而是模型权重文件直接下载到你的硬盘上，推理过程由本地硬件完成。你在界面上输入一句话，这句话通过本机的 HTTP 服务发送给推理引擎，推理引擎加载模型进行计算，把 token 一个一个生成出来，再返回给界面展示。整个过程不经过任何第三方服务器。

为了让你更清楚这个概念，一句话总结：你的输入和模型的输出都跑在自己机器上，关掉网络，软件照常能用。

这带来的好处是隐私可控，坏处是对硬件有要求。后面我会给出我在不同机器上的实测数据，方便你判断自己手里的设备能不能跑起来。

1.3 这个软件到底能拿来做什么

我给它起名叫“学习软件”，是因为它能帮你在几个方面系统性地接触本地 AI：

• 对话学习：内置多种模型，边聊边理解不同模型风格的差异。
• 资料问答：导入 PDF、TXT、Markdown 文档，模型基于本地知识库回答问题。
• 参数实验：实时调整温度、上下文长度、重复惩罚等参数，观察输出变化。
• 模型管理：可视化查看已安装模型、大小、量化等级，一键切换默认模型。

适合的场景包括：想系统学习 prompt engineering 但不舍得花钱的人，需要用本地大模型处理敏感资料的研究者，以及想在项目里集成本地模型但需要先跑通全流程的开发者。

2. 选型过程：这一整套技术栈是怎么定下来的

2.1 为什么选 Ollama 作为推理运行时

项目启动时我面临第一个抉择：推理层是自己写，还是用现成方案。自己写意味着要处理模型格式转换、量化、GPU 算子适配、KV Cache 管理……那是个无底洞，至少三个月出不了可用的东西。所以我决定站在巨人的肩膀上，最终选定了 Ollama 作为推理后端。

选 Ollama 的理由很直接：

• 安装零门槛：Windows 和 macOS 都有官方安装包，装完即用。
• 模型拉取简单：一条命令就能从模型仓库下载已量化好的模型，不需要自己做量化。
• 自带 HTTP API：默认监听 11434 端口，任意编程语言都能通过 REST 接口调用。
• 社区生态活跃：热门的 Llama、Qwen、Mistral 系模型都有官方支持的版本。

我知道有人会说我“偷懒”，但做软件最重要的是控制复杂度。Ollama 把最难的模型推理部分封装好了，我就能把精力全部放在学习交互、知识库、参数可视化这些真正能给用户带来体验的部分。

2.2 主力模型为什么是 Llama 3 及其量化版

模型选择这件事，我折腾过很多版本。最初用的是 Qwen2.5-7B-Instruct，中文表现不错，但总觉得代码能力差口气；后来试过 Llama 3.1-8B 的官方原版，又感觉显存压力太大，集成显卡机器根本跑不动。

最终我把主力模型定为Llama 3 8B 的 Q4_K_M 量化版，也就是 Ollama 仓库里的llama3:8b-instruct-q4_K_M。原因有三点：

• 8B 参数量是消费级硬件的甜点区，16GB 内存的笔记本勉强能跑，32GB 内存的台式机体验流畅。
• Q4_K_M 量化在“体积”和“生成质量”之间平衡得很好，模型文件只有约 4.7GB。
• 英文能力和代码理解力在同尺寸模型里表现突出，配合中文提示词模板使用，输出质量够用。

我还把 Qwen2.5-7B、Mistral-7B 放在可选模型列表里，用户可以在界面里一键切换对比。不同的模型不是单纯的好坏之分，而是擅长的领域不同，这个对比本身就是很好的学习素材。

2.3 知识库检索：如何让本地模型“记住”你的资料

对话模型本质上没有长期记忆，它只知道训练数据截止时间之前的事情。你上传的 PDF 如果不做处理，模型是读不到的。为了让“资料问答”这个功能成立，我引入了一个轻量的 RAG（检索增强生成）链路：

• 文档解析：用文本提取器把 PDF、TXT、Markdown 里的内容抽出来。
• 分块处理：按固定长度（比如 512 字符）切块，相邻块保持一点重叠，避免把一句话拦腰切断。
• 向量化：用 embedding 模型把每个文本块转成向量。
• 相似度检索：用户提问时，把问题也转成向量，然后计算余弦相似度，取出最相关的几块。
• 答案合成：把相关资料和用户问题一起塞进提示词，让模型基于资料作答。

最开始我想用在线 embedding API，后来一想这不又回到“数据出本机”的老路上了吗？所以 embedding 也改成了本地小模型，完整链路全离线。这部分代码我写在项目里的rag/目录下，核心流程只有两百多行。

2.4 前端与服务端如何组织

整个项目我采用了“轻量前后端分离”的方案：

• 前端是纯静态页面，原生 HTML + JavaScript，不需要构建工具，打开即用。
• 服务端用 Python 的 FastAPI 写，负责调用 Ollama 的 API、管理对话历史、执行知识库检索。
• 两者之间通过 HTTP 通信，前端访问服务端 8000 端口，服务端转发请求到 Ollama 的 11434 端口。

虽然技术上很简单，但工程结构我刻意划分清楚，每个模块只干一件事，方便别人拿到代码后快速看懂、修改、提交 Pull Request。

3. Windows 11 下从零部署：安装 Ollama、下载模型、跑通软件的全过程

3.1 安装 Ollama 时最容易被忽略的几步

在 Windows 11 上装 Ollama 本身不难，官网下载安装程序，双击、下一步、完成。但我推荐你在装完之后立刻做两件事，否则后面一定会回来补课。

第一件事是验证是否安装了正确的 GPU 加速版本。安装完成后打开 PowerShell，输入以下命令：

ollama --version

如果正常输出版本号，再运行：

ollama list

此时应该显示 no models 或者空列表，说明服务和命令都已经可用。如果你的电脑有 NVIDIA 显卡，还可以跑一下：

ollama run llama3:8b-instruct-q4_K_M

首次运行会先下载模型，完成后再进入交互模式，简单问一个问题，观察显卡占用，确认 GPU 加速生效。

第二件事是提前确认模型下载目录的磁盘空间。Ollama 默认把模型放在C:\Users\你的用户名\.ollama\models下，一个 8B 量化模型差不多 4.7GB，算上后续可能下载的 embedding 模型和测试模型，建议预留 30GB 以上。如果你的 C 盘比较紧张，务必提前设置模型目录环境变量。

3.2 拉取模型卡住不动：修改下载源的实操

这一步是我排查了最久的问题。第一次执行ollama run llama3时，模型下载进度条长时间停在 0%，报错信息晦涩难懂。重试几次之后才意识到，默认的模型仓库地址在当时的网络条件下下载不稳定，需要切换到一个访问更顺畅的仓库源。

在 Windows 上，通过设置系统环境变量来指定镜像地址。操作路径是：设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 新建系统变量，变量名填OLLAMA_HOST，变量值填本机服务地址；再新建一个变量指向镜像仓库 URL，不同镜像仓库的地址格式略有不同，建议以你选择的镜像服务提供方文档为准。

设置完成之后，务必重启 Ollama 服务，让环境变量生效。在 PowerShell 里执行：

ollama stop ollama serve

然后重新执行拉取命令，这一次模型文件就能正常写入本机了。这个过程值得记录下来，因为很多新手第一次接触本地模型，都卡在这一步就放弃了。

3.3 配置服务端口与环境变量

为了让软件顺利调用 Ollama，我会再设置一组环境变量：

• OLLAMA_HOST=127.0.0.1：让服务只监听本机。
• OLLAMA_ORIGINS=*：允许前端跨域调用。

设置完成后，在浏览器访问http://127.0.0.1:11434，如果能看到 Ollama 的响应提示，说明服务正常。我的 LANR 前端默认连接的本机 API 地址就是这个端口。

3.4 从下载代码到第一次对话的完整流程

假设你已经在 GitHub 上把仓库克隆到了本地，接下来做三步就能跑起来。

第一步，安装 Python 依赖：

cd Lanr pip install -r requirements.txt

第二步，启动服务端：

python app.py

服务端会打印出访问地址，通常是http://127.0.0.1:8000。

第三步，浏览器打开地址，在设置页面选择你下载好的模型，开始第一轮对话。

我在实际测试中，第一次对话等待时间会比较长（约几十秒），因为模型需要从磁盘加载进显存。第二次开始就快了，同一个模型的首次响应基本稳定在两秒以内。如果你用 CPU 模式，这个时间会明显变长，后面我会专门说性能调优。

4. 参数调优与实机表现：不同机器上怎么跑得又快又省

4.1 对话参数到底在调什么

很多刚接触本地模型的人，看着界面上温度（Temperature）、Top P、重复惩罚（Repeat Penalty）这些参数一脸懵。我简单解释一下每个参数的实际作用：

• Temperature：控制随机性，值越低回答越保守和可预测，值越高越有创造力和“跑题”风险。写代码、做数学题建议调到 0.2 到 0.4；头脑风暴、写文案可以调到 0.7 到 0.9。
• Top P：控制候选词累计概率阈值，它和 Temperature 可以配合也可以互相替代。一般建议固定 Top P 在 0.9，通过温度来调整风格。
• Max Tokens（最大生成长度）：决定模型一次最多生成多少个 token。代码补全和长文写作要调高，比如 2048 或 4096；简短问答可以调低到 500，节省生成时间。
• Repeat Penalty（重复惩罚）：抑制模型重复说同一句话，聊太久之后会发现模型开始“绕圈”，适当调高这个参数能拉回来。

我在 Lanr 的调试面板里做了实时调整，同一个问题你改成不同参数连问五次，一眼就能看出变化。这比看理论更加直观。

4.2 不同硬件配置的实测表现

我手头有三台测试设备，性能差异很大，用同一模型实测的数据值得参考：

结论：如果你想流畅地上手本地大模型，至少准备 16GB 内存的 CPU 机器或者 8GB 显存的 GPU 机器。8GB 内存只够让模型跑起来，谈不上体验。内存不够的话，要么换更小的模型（比如 3B 或 4B 量化版），要么就接受一个慢一点的节奏。

4.3 显存不足时的降级方案

如果你的 GPU 显存只有 4GB 或者没有独立显卡，也有办法继续用。两种常见的降级方案：

第一种方案是选用更小参数的量化模型。比如把 8B 模型换成 Qwen2.5-3B 或 Llama 3.2-3B，模型文件只有约 2GB，CPU 也能跑得动，虽然智能程度明显下降，但做基础问答和代码片段生成依然够用。

第二种方案是开启 Ollama 的 CPU 模式。在环境变量里强制不启用 GPU，或者直接把OLLAMA_HOST设定到一个纯 CPU 的节点。这样模型会全部跑在内存里，速度慢不少，但至少不会被显存不足的报错打断。

我的软件在设计时就考虑了这两种场景，模型列表里同时收录了 8B、4B、3B 几个档位，切换模型只需一次点击，不用跑命令行。

4.4 磁盘、内存和带宽的真实消耗

一个小型本地模型项目，完整跑起来的资源占用情况大致如下：

• 模型文件：主力模型 4.7GB + embedding 模型 0.5GB + 备用模型若干，总占用 15GB 到 30GB。
• 内存占用：加载 8B 量化模型后，常驻内存约 5GB 到 7GB，CPU 模式下占用更高。
• 显存占用：GPU 模式下约 6GB 到 8GB。
• 网络带宽：纯本地运行基本为 0，只有第一次下载模型时消耗流量。

我特意在项目状态栏里显示当前显存/内存占用，目的就是让用户直观感受到“本地 AI 的资源代价”，这也是一种学习。

5. 踩坑排查记录：从“能跑”到“稳定好用”的关键一步

5.1 模型下载失败：根源不在网速，在下载源

前面说了修改环境变量指向镜像仓库的解决办法。这里补充一下判断标准:如果你看到进度条长时间卡在同一个百分比，或者反复重试报错，基本可以判定是源地址的问题。改完镜像之后，下载速度会明显改善，模型文件也能顺利加载。这个问题在网上讨论很多，属于本地模型入门的第一道坎。

5.2 端口被占用：一个低级但特别常见的坑

我的软件默认使用 8000 端口，Ollama 使用 11434 端口。有次用户反馈软件打开后界面能显示，但一直“连接失败”。我远程排查了半天，最后发现是他电脑上的某个开发服务占用了 8000 端口，请求全被转发到了不对的地方。

排查方式很简单，在 PowerShell 里运行：

netstat -ano | findstr "8000" netstat -ano | findstr "11434"

看到端口对应的进程号后，再在任务管理器里找到进程名，结束掉或者换一个端口。Lanr 的设置界面允许自定义服务端口，就是为了应对这种冲突。

5.3 中文输出乱码：提示词模板的锅

用 Llama 3 做中文问答时，前期经常出现输出夹带乱码或者突然切换到英文的情况。一开始我以为是模型问题，后来把完整的提示词模板打印出来才发现，问题出在系统提示词里用了不合适的编码格式。给本地模型指定中文提示词模板，并加上“请始终用中文回答”之类的约束之后，输出就稳定多了。

在 Lanr 的“自定义提示词”面板里，我默认内置了中英文两套模板，新模型接入时可以一键导入，避免重复踩坑。

5.4 对话记录存不下来：目录权限问题

还有一次，用户反馈“对话历史只要关掉页面就没了”，那时我还以为是前端代码的存储逻辑有 bug。后来发现很多人打开软件时窗口是在“管理员权限”下启动的，数据库文件被写到了系统受保护目录的虚拟化路径里，表面上写成功了，实际没有落盘。解决方法是让服务端把数据库放在用户目录下，并降低目录写入权限需求。这个问题也提醒我：开源软件要考虑“不同权限环境下都能正常工作”，而不是假设所有人都在默认环境里运行。

6. 开源仓库说明与后续计划：欢迎改，更欢迎一起做

6.1 项目结构一览

仓库地址在 GitHub 上搜索 Lanr 即可找到。目录结构整理如下：

• app.py：FastAPI 服务入口，负责路由与 API 编排。
• static/：前端静态页面，原生 HTML/JS，没有框架。
• rag/：知识库检索模块，包含分块、向量化、检索逻辑。
• models/：模型配置与提示词模板定义。
• data/：对话历史与知识库的存储目录（默认生成）。
• README.md：完整的使用说明和开发文档。

6.2 二次开发建议

如果你不只是想用，还想基于它学习或者开发自己的功能，我建议从三个地方入手：

• 在models里添加新的模型配置，研究不同模型在同一问题上的回答差异。
• 在rag里改进分块策略，体会 RAG 的每一步变化如何影响最终回答质量。
• 在static里给前端加功能，比如多轮对话导出、Markdown 渲染优化等。

我特意没有用复杂的框架和花哨的架构，目的就是让每一个拿到代码的人都能看懂每个文件在做什么。对一个学习项目来说，“能看懂”比“高大上”重要得多。

6.3 后续想做的计划

目前 Lanr 的对话功能、知识库问答、参数调试已经能正常使用。下一步我计划做三件事：

• 增加插件化能力，让用户可以自定义工具函数，模型可以通过调用函数完成搜索、计算等更复杂的任务。
• 增加多会话隔离和标签管理，把“研究某个主题”的资料、对话单独存放。
• 做一个更完整的模型横向评测工具，让用户对同一个问题直接对比多个模型的输出差异。

说白了，这个项目不会停在现在的样子，开源的意义也在于让它能吸收更多人的想法。

最后分享一点个人体会：做这个软件的过程中，我最大的收获不是“写出了多少行代码”，而是真正搞懂了模型量化、上下文窗口、向量检索这些概念在实际项目中是怎么协作的。看一百遍教程，不如自己把一个 4.7GB 的模型文件拉下来，跑通第一句对话，再把一个 PDF 传进去问出答案。如果你也想入门本地 AI，我建议你从这篇记录里的第三步开始，亲手把这条路走一遍，有问题欢迎在仓库里提 Issue 和我交流。