企业官网建设流程全解析

最近在折腾本地化的AI助手，把Ollama和Vue这套组合跑通了，整体体验超出预期。先说结论：如果你也不想把聊天记录和代码片段全部交给云端，又希望有一个可以自己完全掌控的问答小伙伴，这套方案是目前最省心的落地路径之一。本篇文章我会从选型思路、环境搭建、前端实现到踩坑记录，完整复盘一遍。适合正在选型的前端开发者、想用本地模型做私有化工具的团队，也适合刚接触Ollama的小白。

1. 整体设计与方案选型

1.1 为什么优先选择本地模型

做这个项目之前，我其实纠结了很久：到底要不要直接用云端大模型API？说实话，云端大模型效果确实好，随便调一下接口就能拿到高质量回答，写起来也很快。但真到了实际落地环节，几个问题特别刺人。

第一是隐私。我自己的使用场景里有大量代码片段、本地文档、业务数据，这些东西直接发到云端服务，心理上始终过不去。哪怕签署再多的隐私协议，数据出了本机就是出了本机，作为开发者需要对数据安全主动权有掌控感。第二是成本。聊天看起来是小流量，但真正高频使用之后，token费用一天下来也不少，尤其是带着长上下文反复问答，账单涨得很快。第三是稳定性。如果网络波动或者服务商升级接口，应用就会跟着抽风。本地模型没有这些烦恼，模型一次性下载到本机，断网也能聊，调用量完全不受配额限制。

本地部署的常见方案里，我重点比较过llama.cpp、Ollama和LocalAI。llama.cpp自由度最高，但对普通开发者来说编译配置有点劝退，跑量化时还有一堆参数要调。LocalAI兼容性不错，可是项目文档有时候更新跟不上版本节奏。最终我选了Ollama，理由很直接：安装简单、开箱即用，自带一个很干净的HTTP API，不需要额外写模型加载逻辑。对前端Vue项目来说，只需要把它当成一个本地服务，请求返回个JSON对象即可。这种低侵入感是我最看重的。

1.2 Ollama与Vue的分工协作

这套方案里，Ollama是“大脑”，负责模型加载、推理、token生成；Vue是“脸面”，负责人机交互、消息展示、状态管理。两者通过HTTP接口通信，互相不依赖具体实现。Ollama只管把用户的输入变成模型输出，它不需要知道输入是从网页来的还是从命令行来的。Vue只管把用户的提问渲染成界面，然后等待模型结果回流、展示流式token。

这个分工有一个隐含的好处：前端可以自由替换模型。今天想用7B模型快问快答，明天想换13B模型跑复杂推理，只需要在Ollama中切换模型名，前端代码几乎不用动。反过来，如果不想用Vue，也可以换成React、Electron甚至手机App，因为Ollama提供的API足够通用。这种前后端松耦合的设计，让项目后续迭代特别从容。

1.3 整体架构与数据流设计

我最终确定的架构分三层。最底层是Ollama服务，监听在11434端口。中间层没有单独写后端，而是用Vite开发服务器做了一层代理，把Vue应用发起的/api/chat请求转发给Ollama的真实地址。最上层是Vue3组件，聊天框发送消息后，把消息追加到数组，然后通过fetch发起流式请求，逐步读取返回内容并渲染。

数据流走的是这样一条链路：

1. 用户在输入框提交文本，前端把消息写入会话列表。
2. 前端携带当前会话的上下文消息，请求 /api/chat。
3. Vite代理把请求转发到本机11434端口。
4. Ollama调用底层模型进行推理，以流式NDJSON格式返回。
5. 前端通过ReadableStream逐段读取，解析出“delta”内容并追加到当前回答。
6. 流结束后，前端把完整回答写入历史记录，等待下一轮输入。

这套设计在早期并没有加代理，而是直接让Vue请求http://localhost:11434，结果被CORS拦了。加上代理之后顺滑很多，而且部署到生产环境时还能无缝换成Nginx反向代理，不需要改业务代码。

2. 环境准备与模型选型

2.1 Ollama安装与基础配置

Ollama的安装我用的是官方脚本，一条命令搞定。

curl -fsSL https://ollama.com/install.sh | sh

Windows和macOS用户可以直接下载对应安装包，安装完会在后台自动运行一个本地服务。安装好后，先用一下命令行，确认服务正常：

ollama --version ollama list

如果版本号正常输出，说明服务已经起来了。此时Ollama会监听在127.0.0.1:11434，所有API调用都走这个端口。

接下来需要拉取模型。以我常用的qwen2.5:7b为例：

ollama pull qwen2.5:7b

这个模型在7B参数级别里中文表现不错，代码理解力也够用。拉取的时候能看到进度条，模型文件默认会存在一个用户目录下的models文件夹里。如果想修改模型存储位置，可以设置OLLAMA_MODELS环境变量，比如我把它放到了独立的数据盘上，避免系统盘空间被撑爆。

很多人在第一步容易忽略的是：Ollama默认只监听本地回环地址，如果你的Vue应用跑在Docker容器里，或者需要局域网内其他设备访问，必须打开OLLAMA_HOST环境变量，比如设置为0.0.0.0:11434。不过为了方便调试，我这里没开，只让本机访问。

2.2 不同模型对比与选择建议

模型选择直接决定助手的体验上限。我实机拉过几个不同体量的模型，主要对比了响应速度、中文效果和显存占用：

我最终日常用的是qwen2.5:7b，因为我的显卡显存刚好8GB，跑4bit量化的7B模型还能留出一些余量给浏览器和系统。如果纯CPU推理，建议直接上3B或更小体量的模型，否则每个token都要等上好几秒，体验很难受。

这里还要提一句量化版本的思路。Ollama的模型标签里像qwen2.5:7b默认就是量化过的，不同后缀对应不同精度。追求更快响应就选Q4，对准确率更敏感就选Q8，但也要看硬件能不能撑住。我自己的习惯是先用默认标签跑通流程，等确认质量达标后再考虑换量化标签。

2.3 Vue项目初始化和基础依赖

前端我用的是Vue3加Vite，新建项目一步到位：

npm create vue@latest

选择自己需要的特性即可，我勾选了TypeScript、Vue Router、Pinia，这样就算后面要扩展成多页面应用也有基础。项目创建完，我还要装一个用于markdown渲染的依赖，因为模型返回的结果经常带代码块和列表，直接用纯文本会很丑：

npm install remark-gfm npm install @vueup/vue-markdown

当然，如果不想引入额外依赖，也可以先写一个简单的文本渲染组件，把换行和空格处理掉。但实测下来，AI回复里出现代码块的频率非常高，没有一个Markdown渲染层的话，整个聊天界面会显得特别难用。

项目初始化之后，第一步工作是在vite.config.ts里配置代理，把/api路径转发到Ollama：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { proxy: { '/api': { target: 'http://localhost:11434', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } })

这里有个关键点：rewrite很重要。我在前端请求路径写的是/api/chat，但Ollama真实的路径是/chat，需要把/api前缀去掉。如果不写rewrite，代理会请求到/api/chat然后返回404。这个坑我一开始找了半天，后来用curl测试代理服务才发现是路径拼接问题。

3. 前端交互与流式请求实现

3.1 聊天界面组件结构设计

聊天界面我拆成了三个组件：一个消息列表组件、一个输入框组件、一个会话容器组件。消息列表负责渲染数组中的每一条消息，输入框负责捕获用户输入，会话容器负责组装请求逻辑和状态管理。

单条消息的结构定义如下：

interface ChatMessage { id: string role: 'user' | 'assistant' content: string status?: 'pending' | 'streaming' | 'done' error?: string }

其中status字段非常有用。发送消息时，我先生成一个role为assistant的空消息，status设为streaming，然后随着流式数据逐渐填充content。这样用户能立刻看到一个“正在生成”的状态，而不是傻等接口返回。等流结束后，再把status改为done，方便前端根据状态显示不同的操作按钮，比如复制回答或者重新生成。

3.2 调用Ollama生成接口的封装

Ollama的接口调用格式很简单，官方支持/api/chat这个接口。请求体长这样：

{ "model": "qwen2.5:7b", "messages": [ { "role": "system", "content": "你是一个乐于助人的AI助手，请简短回答问题。" }, { "role": "user", "content": "帮我解释一下函数防抖。" } ], "stream": true }

这里有个容易忽略的点：messages数组里携带的不只是当前问题，而是完整的对话历史。只有把前面的多轮问答都带上，模型才能理解上下文。这一点我会在后面的“上下文管理”章节展开。

我前端封装了一个sendMessage函数，核心代码简化后长这样：

async function sendChat() { const userText = input.value.trim() if (!userText) return messages.push({ id: uuid(), role: 'user', content: userText }) input.value = '' const assistantMessage = { id: uuid(), role: 'assistant', content: '', status: 'streaming' } as ChatMessage messages.push(assistantMessage) const response = await fetch('/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: selectedModel, messages: messages.filter(m => m.role !== 'system').map(m => ({ role: m.role, content: m.content })), stream: true }) }) if (!response.ok) { assistantMessage.status = 'error' assistantMessage.error = `请求失败：${response.status}` return } const reader = response.body!.getReader() const decoder = new TextDecoder() while (true) { const { done, value } = await reader.read() if (done) break decodeStreamChunk(decoder.decode(value, { stream: true })) } }

3.3 流式输出解析与增量渲染

这里最需要小心的是流式数据的解析方式。Ollama在stream模式下返回的是多行NDJSON，每一行都是独立的JSON对象，典型格式如下：

{"model":"qwen2.5:7b","message":{"role":"assistant","content":"防抖"},"done":false} {"model":"qwen2.5:7b","message":{"role":"assistant","content":"是一种"},"done":false} {"model":"qwen2.5:7b","message":{"role":"assistant","content":"函数"},"done":false} {"model":"qwen2.5:7b","message":{"role":"assistant","content":"。"},"done":true}

所以拿到一段二进制流之后，不是简单转成字符串就完事，还要按换行符拆分成多行，然后逐行parse。我封装了decodeStreamChunk函数：

let buffer = '' function decodeStreamChunk(text: string) { buffer += text const lines = buffer.split('\n') buffer = lines.pop() as string for (const line of lines) { if (!line.trim()) continue try { const data = JSON.parse(line) const delta = data.message?.content || '' if (delta) { currentAssistant.content += delta scrollToBottom() } } catch (e) { console.error('JSON解析失败，这行内容会被丢弃', e) } } }

buffer缓存是必须的，因为网络传输时一帧二进制数据可能只带来半个JSON字符串，直接在每段之后parse一定会出错。只有等换行符出现，才说明这是一个完整的JSON对象。这个细节看起来很基础，但如果是第一次接触流式接口，很容易漏掉。

渲染方面，我用的是一个动态高度的消息容器，每次增量更新后，把滚动条拉到底部。为了保证流畅，我用了requestAnimationFrame或者直接nextTick，防止频繁更新DOM导致界面卡顿。实测下来，7B模型在本地生成速度大约每秒20到40个token，界面刷新完全没有压力。

3.4 中止生成与重新生成机制

流式请求跑起来之后，接踵而来的需求就是中止生成。不然模型跑错方向了，只能干等着它把话说完。后来我加了AbortController，在用户点击“停止生成”按钮时执行abort，前端捕获异常后把当前消息标记为中断。

let abortController = new AbortController() async function stopStream() { abortController.abort() currentAssistant.status = 'done' currentAssistant.content += '\n\n[已中止]' } const response = await fetch('/api/chat', { // ...其他配置 signal: abortController.signal })

重新生成也是一样简单，把当前assistant消息清空，状态归零，再重新调用一次sendChat逻辑。这里要注意的是历史消息中不能把这个“半截”回答保留，否则模型会把它当成完整回复，反而影响后续质量。

4. 对话上下文管理与会话扩展

4.1 系统提示词与角色设定

使用Ollama时，系统提示词是很重要的杠杆。本地模型对指令遵循能力不如云端大模型，更适合提前把约束写在system里。这个提示词不参与多轮历史累计，但会出现在每次请求的messages数组首位。

我尝试过几种风格的system提示词：

• 极简型：“你是一个AI助手。”
• 约束型：“你是一个代码助手，只回答与编程相关的问题，不要闲聊。”
• 角色扮演型：“你是一位资深前端工程师，回答时给出具体代码和优化建议。”

实测下来，约束型在业务场景里效果最稳定。因为本地小模型注意力有限，给太多无关设定反而冲淡核心指令。我自己最后用的是一套“精简回答”的提示词：要求回答不超过300字，代码单独展示，不确定时直接说不知道。这样避免模型长篇大论展开，也减少了上下文被无意义内容占满的问题。

4.2 滑动窗口与历史裁剪策略

上下文长度是本地模型最头疼的限制。虽然Ollama默认会处理一部分上下文，但模型本身的context窗口有限，比如7B模型通常只有8192 token左右。如果聊天聊长了，不裁剪历史，前面部分就会被截断或者干脆报错。

我的策略是维护一个消息队列，在发起请求前检查历史token估算值，如果超过预设阈值，就丢弃最早的一部分消息，只保留最近的对话。这里有一个细节：裁剪时不能裁掉system提示词，也不能把同一轮问答拦腰截断。我用的方法是按“完整消息对”为单位裁剪，每裁剪一个用户消息，就把对应的assistant回复也删掉。

const MAX_TOKENS = 4096 function trimHistoryIfNeeded(history: ChatMessage[]) { let estimate = 0 const kept = [] for (const msg of [...history].reverse()) { estimate += estimateTokens(msg.content) if (estimate > MAX_TOKENS) break kept.unshift(msg) } return kept }

这个estimateTokens是粗略函数，一般是字数除以一个系数，不必特别精确。反正只要保证发送给模型的消息总长度低于模型上下文即可。如果还嫌不够，可以在Ollama请求里加上options.num_ctx参数，手动指定上下文大小。但注意调大num_ctx会显著增加KV Cache内存占用，并不是越大越好。

4.3 多会话与持久化保存

单个聊天窗口不够用，我扩展了会话列表。每个会话独立管理自己的消息数组和模型配置。切换会话时，从Pinia store里恢复对应数组即可。

会话数据持久化我用的是最简单的方式：浏览器localStorage。每有新消息完成，整个会话数组就序列化写入一次。这听起来有点原始，但在本地工具场景完全够用。唯一的坑是localStorage有5MB大小限制，聊太多天之后容易撑爆。所以我额外做了数据量提示，当存储快满时提醒用户手工导出或者清理。

导出功能也很实用，把聊天记录转成JSON文件一键下载。这样既满足了备份需求，也避免了数据被云端存储的隐私风险，跟这个项目的初衷完全一致。

5. 常见问题与排查技巧实录

5.1 跨域与代理配置问题

前端直接请求Ollama是本项目最早遇到的坑。正常情况下，浏览器会把http://localhost:11434和http://localhost:5173视为两个不同源，请求会被CORS策略拦截。有两种解决路径。

第一种是配置Ollama服务本身允许跨域，设置环境变量OLLAMA_ORIGINS为前端地址。这种方式适合不想加后端代理的场景。第二种是使用Vite代理，也是我推荐的方式。因为开发环境和生产环境都能一致地使用相对路径 /api/chat，后续换成Nginx只需要替换一段反代配置。

代理配好之后，我遇到过返回404的问题。排查步骤是：先用浏览器访问 /api/chat看返回内容，再用curl访问代理后的完整地址看转发结果。前后一对比就发现问题出在URL路径没有重写。所以如果你也碰到404，第一反应不应该是改Ollama接口，而是检查代理配置里的rewrite规则对不对。

5.2 显存溢出与生成速度慢

模型加载后，最直观的问题是显存占用。我在一台8GB显存的机器上跑qwen2.5:7b，刚加载完就占了约6GB，如果再开着浏览器，很容易触发OOM。后来做了一点优化：把Ollama服务设置为支持多模型时按需卸载，再限制并行请求数量为1。

如果生成速度特别慢，先看一眼任务管理器里CPU或GPU的利用率。CPU推理慢是硬伤，建议直接换小模型。GPU推理慢，则可能原因是GPU没有完全被利用，检查OLLAMA_DEBUG日志，确认是否真的用了CUDA而不是回退到CPU。我的实际经验是，Ollama安装时能自动识别显卡，但如果有多个显卡，偶尔会错选到集显上，此时设置CUDA_VISIBLE_DEVICES定位主卡就行。

5.3 流式输出中文乱码与丢字

流式输出最多出现的问题是末尾字符重复或第一个字丢失。原因通常是TextDecoder在解析多字节UTF-8字符时，字节被TCP分段切开了。我在前面代码里用了TextDecoder.decode(value, { stream: true })，其实正确的做法是让decoder保留内部状态，等待后续字节补全。如果不传{ stream: true }参数，一个汉字被拆成两截时就会变成乱码。

还有一个相关问题是末尾缓冲区残留。如果请求结束后buffer里还有半行内容，可以强制调用一次decoder.decode(undefined)或手动clearBuffer。这不是必须的，但能避免最后一行丢内容。

5.4 常见问题速查表

6. 从能跑到好用：一些实在的优化建议

6.1 接入WebSocket或SSE方案之外的玩法

当前实现基于fetch流式读取，已经够用。但如果要做更复杂的工具，比如让AI助手具备工具调用能力，或者同时连接多个模型做对比，可以考虑把Ollama接入到LangChain等编排框架中。我目前的做法是直接在Vue中处理逻辑，简单直接，但项目复杂度上升后还是需要抽一层服务端逻辑。

另一个值得做的方向是语音输入。浏览器自带的Web Speech API能把语音转成文字，再交给AI助手，对话体验立刻上升一个档次。我试过在Vue中集成，识别准确率取决于浏览器和系统语音包，中文环境下可用性尚可。

6.2 构建多语言与主题适配

Vue应用做国际化非常方便，装一个vue-i18n之后，所有界面文案可以动态切换。对AI助手来说，主题适配更重要。本地模型输出质量参差不齐，界面如果又乱又难看，连测都不想多测。我用了CSS变量定义配色方案，黑白主题切换时无需改组件代码。

6.3 项目后续可扩展方向

这套Ollama加Vue的组合，最让人满意的是可扩展性。我下一步计划把项目接入本地的知识库，用embedding模型把文档向量化，再将用户查询转换成向量检索，找到相关片段后和问题一起发给大模型。这样AI助手就能回答私有文档相关的问题，而不是只靠训练时的记忆。

此外，多模型的A/B对比也值得做。在Ollama中同时拉取多个模型，前端增加一个模型下拉框，随时切换对比回答质量。这个功能我已经用上了，对挑选模型、微调提示词都非常有帮助。

最后再说一点个人体会：我在做这个项目时踩过最大的坑，不是技术难点，而是最开始抱着“一定要做一个完整平台”的心态，结果迟迟没跑通。后来把目标缩小到“先让一个聊天窗口能够流式打字”，整个项目瞬间清晰了。如果你也打算做本地模型AI助手，不妨从最简路径出发，先跑通Ollama加Vue的最小闭环，再慢慢往上加功能。这样每走一步都有正反馈，后续迭代也会顺手很多。