企业官网建设流程全解析

最近集中把 Gemma 4 12B 部署到了本地，配合 Ollama 搭了一套内部知识库问答的底层模型，跑了小半个月，整体稳定。这篇文章不写官方主页上的废话，直接把我从硬件评估、量化选择、部署命令，到接入 FastGPT 做文档问答的整个过程整理出来。如果你想在 16GB 显存左右的机器上跑一个能力尚可的本地大模型，或者想把手头积累的技术文旦交给模型来回答，这份文档可以当作一份直接可抄的作业。

文章本身也是一份“技术文档”，我会刻意按照技术文档的规范来组织：编号标题、前置条件、命令行、预期结果、坑点复盘，所有命令都能在常见环境里直接跑通。Gemma 4 12B 这个型号属于 Google Gemma 系列里偏中大体量的版本，本地部署核心要解决的问题有三个：显存怎么分配、量化怎么选、API 怎么接业务系统。下面按我实际操作的顺序展开。

1. 先从需求说起：为什么要在本地跑 Gemma 4 12B

1.1 12B 参数模型的“甜点区”

部署之前得先搞清楚一件事：12B 到底是个什么量级。大模型参数规模可以粗暴分成三档：7B 以下的轻量模型，跑起来非常轻松，但理解和生成能力在稍复杂的任务里会明显露怯；30B 到 70B 甚至更大的重模型，效果当然好，可显存要求跟着翻倍，一张消费级显卡很难舒服地跑起来。

12B 正好卡在中间：比 7B 更聪明，又不像 27B 那样动辄需要 24GB 以上的显存才跑得动。我在实际测试里最直观的感受是，让它做代码补全、技术文档摘要、结构化信息抽取、中文翻译这类任务，输出的质量和稳定性都远好于 7B 档位。对绝大多数想把大模型搬进内网、又没有 A100 这种大卡的人来说，12B 就是性价比非常高的甜点位置。

顺带说一句，Gemma 系列模型本身是开放的权重，不像很多闭源 API 那样把能力锁在云端，适合做本地化定制。这也是我选它的一个重要原因：数据不出内网，推理不产生调用费用，想怎么调参数就怎么调。

1.2 本地部署解决了哪些真问题

很多人觉得“既然网上有那么多免费的 API，为什么还要费劲本地部署？”问题在于真实业务场景并不总是允许把数据往外发。我这次部署的背景是内部技术文档的问答：几百篇 PDF、Markdown、Word 混在一起，内容涉及内部系统设计、接口约定、历史故障记录。这些资料直接丢到公网 API 上，哪怕只是文本片段，合规风险也摆在那里。本地部署之后，所有文档和请求都留在内网，模型本身就是个本地进程，数据流转路径完全可控。

另一方面是成本。知识库问答这种场景，调用频率可以非常高，一天几千次甚至上万次请求，如果用云端 API，每百万 Token 的价格算下来也是一笔不小的开销。本地部署的边际成本几乎为零，显卡是现成的，电费可以忽略，跑多少都不心疼。这也是我最终把 Gemma 4 12B 定为核心推理引擎的原因：它既能消化知识库问答这种高频任务，又能保住数据的私密性。

1.3 这篇技术文档按什么标准来写

我写这类文档的习惯是参考阮一峰老师提出的《中文技术文档的写作规范》：标题编号清晰，同一个层级的标题职责统一，代码块和普通段落严格区分，命令给出前置条件，并且每一步都标注预期结果。这样做的好处是读者不需要逐字读，扫一眼标题就能定位到问题，复制命令就能复现，遇到异常还能在“常见问题”里找到解法。

后面所有章节都会围绕“可直接复现”来展开。我的目标很简单：你拿到一篇标题、一台电脑，按着顺序执行，就能把 Gemma 4 12B 跑起来，并且能通过 API 或者 FastGPT 真正用起来。不绕弯子，不给理论空谈。

2. 部署前需要搞定的硬件与工具

2.1 显存到底要多大，数据算给你看

本地部署大模型，最先碰到的就是显存。Gemma 4 12B 有 120 亿参数，不同精度下占用的显存差距非常大，很多人卡在这一步不敢动手，其实只要把量化概念弄清楚，16GB 显卡完全有机会跑得动。

先理解一个基础换算：1 个参数用 FP16（半精度）存储需要 2 字节，120 亿参数就是 120 亿 × 2 字节，大约是 24GB 权重，再加上推理时的中间状态、KV 缓存，显存没到 32GB 基本跑不动。这就是为什么一堆人问“为什么显存都 24G 了还是加载失败”。但是换成 4bit 量化，同样 120 亿参数只需要 120 亿 × 0.5 字节，也就是 6GB 左右权重，加上推理开销，12GB 显存就能勉强带起来。

我对照实际项目整理了一张表，按不同量化等级估算显存需求：

重点看 Q4_K_M 这一档，它是我在 16GB 显存机器上验证过的比较稳的选择。8GB 权重加 KV 缓存和中间张量，总占用可以压在 11GB 以内，剩余的显存刚好够跑 8K 左右的上下文窗口。如果你的机器显存只有 8GB，也不是完全不能跑，只是要把上下文长度压得更低，比如 4K，同时选择 Q4_0 量化，体验会偏紧但能跑通。

内存建议 32GB 起步，因为 Ollama 在加载模型时会先把模型文件映射到内存，再进行显存分配，内存太小容易出现“模型加载到一半被系统杀掉”的情况。磁盘方面，模型文件本体大约 8GB（Q4 量化）到 24GB（FP16），再加上日志和后续向量库数据，建议至少留出 50GB 空余。

2.2 部署工具选型，为什么主力用 Ollama

本地部署大模型不是只有一条路。我试过 llama.cpp、vLLM、Ollama，也看过 FastGPT 和 Dify 这类上层应用，最后还是把 Ollama 作为主力推理服务。原因有三个。

第一，安装和操作足够简单。Ollama 把模型管理、量化、服务暴露、OpenAI 兼容 API 全部集成了，几乎没有编译过程。拉取模型、启动服务、调用接口，全部系统化操作，出问题也容易排查。

第二，资源占用可控。Ollama 会根据显存情况自动决定是否把部分层放到 CPU 内存里跑，这听起来像是“作弊”，但对只有一张显卡的人来说非常实用：显存不够时模型慢一点，但至少不会启动失败。

第三，社区生态成熟。Ollama 模型仓库里可以直接搜索到 Gemma 系列的各种版本和量化标签，FastGPT、Dify、Open WebUI 这些工具默认就有 Ollama 的连接配置。我后面要做的文档问答系统，只需要把 Ollama 暴露成 OpenAI 兼容 API，上层应用就能无缝对接。

顺便做个对比，让没选型经验的人少走弯路：

如果只是自己用，或者最多五六个人同时访问，Ollama 是性价比最高的选择。如果要做大规模线上服务，再考虑把 Gemma 4 12B 迁到 vLLM 上。

2.3 软件准备工作清单

部署前先确认以下软件环境，缺一样都会导致后续步骤报错：

• 操作系统：Windows 10/11、Ubuntu 20.04 及以上、macOS 12 及以上。
• 显卡驱动：NVIDIA 用户务必更新到较新的驱动，确保 CUDA 12.x 能被识别。
• 基础工具：Windows 建议装 Git Bash 或 PowerShell 7，Linux 环境则准备 curl 和 tar。
• Docker（仅接入 FastGPT 时需要）：用于跑 FastGPT 容器。

实际测试中，我最常遇到的软件问题反而不是模型本身，而是驱动版本过旧导致 Ollama 无法调用 CUDA，输出里全是“CPU only”警告。如果你发现推理速度极慢，先别急着调模型，用nvidia-smi看一眼驱动和 CUDA 版本是不是匹配。

3. 实操：Ollama 部署 Gemma 4 12B 全流程

3.1 安装 Ollama，三分钟搞定

Ollama 的安装不需要手动编译，直接执行官方安装脚本即可。Linux 和 macOS 环境运行这一条命令：

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

Windows 用户直接到官网下载安装包，安装完成后软件会自动注册系统服务，并且默认监听 11434 端口。安装完成后验证一下服务是否正常：

ollama --version

能输出版本号就说明安装成功。如果提示“ollama: command not found”，把 Ollama 的安装目录加入系统 PATH，或者重新打开终端再试。Windows 下安装包默认路径是C:\Users\你的用户名\AppData\Local\Programs\Ollama，注意权限和杀毒软件拦截。

3.2 拉取模型与量化选择，别一上来就装最大的

安装好 Ollama，下一步就是拉取 Gemma 4 12B 模型。先搜索确认当前可用的模型标签，因为不同的量化版本会有不同的名称后缀：

ollama search gemma4

搜索结果里会列出多个变形，找到 12B 对应的标签。拉取命令很简单：

ollama run gemma4:12b

第一次执行会自动下载模型文件，下载体积取决于量化等级。Q4 量化版本通常在 8GB 左右，下载时间取决于网络环境。拉取完成后，Ollama 会自动把模型放入默认的模型目录，并且进入交互式命令行。

对显存不那么充裕的机器，我建议直接指定量化标签，避免默认拉取精度过高的版本导致爆显存：

ollama run gemma4:12b-q4_K_M

注意上面的代码中具体标签名要以你本地搜索结果为准，因为模型仓库的标签会随版本更新。

这里还要强调一个量化选择的思路：不要一味追求小量化。Q4_K_M 是我试下来质量与显存占用最平衡的选择，Q4_0 虽然更小，但在长句生成、代码补全这种对语义连贯性要求高的任务里，偶尔会出现前后矛盾的情况。显存充足就上 Q6_K 或者 Q8_0，输出质量能感知地提升一个档次。

3.3 调整存储路径与默认端口

默认情况下，Ollama 会把模型文件放在系统盘，这对 C 盘空间紧张的人来说很危险。可以通过环境变量把模型目录改到数据盘。Linux/macOS 下编辑~/.bashrc或~/.zshrc：

export OLLAMA_MODELS="/data/ollama/models" export OLLAMA_HOST="0.0.0.0:11434"

Windows 用户在系统属性——环境变量里新增两个变量：OLLAMA_MODELS指向D:\ollama\models，OLLAMA_HOST设为0.0.0.0:11434。设置完成后重启 Ollama 服务。

第二个环境变量OLLAMA_HOST很关键。默认情况下 Ollama 只监听本机回环地址，外部设备访问不了。如果你想把模型能力共享给局域网内的其他机器，或者给 Docker 容器里的 FastGPT 调用，必须把它改成0.0.0.0:11434。

这里分享一个我踩过的坑：改完环境变量后，随手在浏览器里访问http://服务器IP:11434，如果能看到返回相关提示信息，说明服务正常。如果显示无响应，先检查防火墙是否放行了 11434 端口，再确认进程是否重新加载了环境变量。

3.4 命令行第一跑，验证模型能正常说话

模型拉取完成后，直接在交互式终端里测试一回。执行：

ollama run gemma4:12b

进入对话状态后输入一句简单的中文：

>>> 你好，请用一句话介绍你自己。

正常情况下，几秒到十几秒后模型会返回一段自我介绍。第一次加载会有明显延迟，因为需要把模型权重从磁盘读入内存再搬运到显存，后续对话就会快很多。

如果你发现每条回复都特别慢，可以在对话中查看当前进程状态：

ollama ps

这条命令会显示模型具体跑在 GPU 还是 CPU 上。如果显示100% CPU，说明模型完全没进显卡，多半是驱动或者量化选择问题。如果显示100% GPU，速度还是慢，就要检查上下文长度是不是设置得太高，导致 KV 缓存占用过多。

确认对话正常之后，输入/bye退出交互模式。到这里，Gemma 4 12B 已经能在命令行里用了，但这只是开始，接下来要做的是把它变成真正的服务，让上层应用能调用它。

4. 从命令行走向业务：调用与集成

4.1 OpenAI 兼容 API，一行命令唤起服务

Ollama 从某个版本开始内置了 OpenAI 兼容的 API 接口，只要服务在运行，就可以直接用标准 OpenAI 格式调用，Gemma 4 12B 不再只是命令行里的玩具。

默认 OpenAI API 地址是：

http://localhost:11434/v1

用 curl 发起一次最简单的请求：

curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gemma4:12b", "messages": [ {"role": "user", "content": "用三句话总结一下什么是RAG"} ], "temperature": 0.7 }'

返回结果会包含choices、message、content等标准字段，和云端 API 几乎一致。这里有个小细节：api_key是任意字符串，因为 Ollama 本地服务不校验身份，但在局域网环境暴露时要注意访问控制，不要轻易暴露到不可信网络。

4.2 用 Python 写一个标准调用示例

日常开发中，直接用 Python 接入更高效。安装官方 OpenAI Python SDK：

pip install openai

然后写一个最简调用脚本：

from openai import OpenAI client = OpenAI( base_url="http://localhost:11434/v1", api_key="ollama" ) resp = client.chat.completions.create( model="gemma4:12b", messages=[ {"role": "system", "content": "你是技术文档助手，请用中文给出简洁准确的回答。"}, {"role": "user", "content": "Ollama 部署后如何修改模型存储路径？"} ], temperature=0.3, max_tokens=1024 ) print(resp.choices[0].message.content)

运行后就能看到模型根据内置知识返回的答案。这里我刻意把temperature调成了 0.3，因为技术问答场景需要确定性高的输出，温度太高容易“自由发挥”。

需要注意，本地模型没有联网检索能力，它只能基于训练阶段学到的知识回答。如果问题涉及你内部才有的文档或数据，它大概率会编造一个答案，这就是下一节要解决的问题。

4.3 接入 FastGPT 做文档问答机器人

把 Ollama 部署的大模型装进 FastGPT，是很多人问得最多的一步。FastGPT 本身是一款开源知识库问答平台，它负责文件解析、向量化、知识库检索，然后把你上传的技术文档片段送进大模型，由大模型整理成最终回答。用本地模型替换云端模型之后，整个链路完全内网化。

先说 FastGPT 的部署，通常用 Docker 方式启动。核心配置是修改模型供应商列表，让 FastGPT 认识 Ollama 暴露出来的模型。重点在这里：如果 FastGPT 也跑在 Docker 容器里，不能直接用localhost:11434访问宿主机上的 Ollama，必须使用 Docker 内部访问宿主机专用的地址：

http://host.docker.internal:11434/v1

如果是通过 Docker Compose 部署，可以在 FastGPT 的模型配置文件中添加一个模型配置：

{ "model": "gemma4:12b", "name": "Gemma 4 12B Local", "maxContext": 8000, "baseUrl": "http://host.docker.internal:11434/v1", "apiKey": "ollama" }

配置完成后，在 FastGPT 的知识库页面上传技术文档。文件经过切片和向量化后会被存入向量数据库，这个过程不需要大模型参与。等到用户提问时，FastGPT 会先做向量检索，把最相关的文档片段交给 Gemma 4 12B，让它基于片段内容生成回答。

这样把 Ollama 和 FastGPT 接起来后，我实际测试了约三百条内部问答。回答准确率明显高于直接问裸模型，原因是所有答案都是有依据的检索结果，模型只需要做归纳和转述，不再凭空编造。你需要确认的是 FastGPT 里有没有配置好向量模型，很多部署方案里默认使用在线 embedding 服务，如果你坚持全本地化，需要另行在配置中指定本地 embedding 模型。

4.4 几个常用推理参数，直接影响输出质量

Gemma 4 12B 到手之后，别急着直接上业务，先搞清楚这几个参数，否则你会觉得模型一会儿聪明一会儿糊涂。

temperature：控制随机性，0 到 1 之间，技术问答建议 0.1 到 0.3，创造性写作可以调到 0.7 以上。num_predict：限制单次生成的最大 Token 数，防止模型在长回答里跑偏，文档问答设置 1024 足够，代码生成可以放宽到 2048。top_p：核采样参数，本地模型我习惯固定 0.9，配合低 temperature 可以让输出更稳定。

还有一个容易忽略的keep_alive参数，它控制模型在显存里的驻留时间。如果请求频率很低，模型可能会在空闲后被卸载，下次请求要重新加载，首次响应会特别慢。可以在启动服务时设置环境变量让模型常驻，或者通过 API 请求参数调整。

实际使用中，我推荐一套基线参数表：

这套参数在内部知识库问答中表现最稳定。如果是代码生成场景，可以适当调高 num_predict，并且把 temperature 降到 0.1，避免写代码时“灵感”过多。

5. 本地部署排坑手册

5.1 显存不够，最常见的三种表现与解法

显存不够不是只有“直接报错”一种表现，实际中我遇到过三种情况，处理思路完全不同。

第一种是最直观的报错：启动对话时直接提示 CUDA out of memory。这说明模型权重加 KV 缓存的总需求超过了显存物理容量，解决办法是换更小的量化版本，比如从 Q8_0 换成 Q4_K_M，或者通过对话内命令缩小上下文长度：

/set num_ctx 2048

第二种是模型加载成功，但ollama ps显示一部分层跑在 CPU 上。这种情况下不会报错，但响应变慢，而且 CPU 内存占用飙升。如果机器内存足够，这种模式还能继续用，只是体验打折。

第三种是多人并发访问时偶发崩溃。一个人测试没问题，多人同时提问就出问题。这其实不完全是显存不够，而是 KV 缓存并发申请导致的，给 Ollama 设置较少的并发数量，或者部署时预留一些显存空闲，可以有效缓解。

5.2 推理速度慢，先从这几个地方查

明明已经确认模型跑在 GPU 上，生成速度还是很慢，这是不少人会遇到的困惑。我总结了一个排查顺序：先看显卡功率是不是没跑满，再看上下文长度是不是设得过大，最后检查 CPU 内存带宽。

实测中 Gemma 4 12B 的 Q4 量化版本在单张 4070 上，生成速度大约有几十 Token 每秒，体感流畅。如果你的速度只有个位数 Token 每秒，多半是上下文长度设得太大，比如 32768 甚至更大，KV 缓存占满显存后，模型层数必须卸载到 CPU，速度自然崩。检查方法是用ollama ps观察显存占用，如果接近上限，就把上下文改小。

另一个常见原因：Ollama 服务在后台运行，同时有其他程序占了显存。我在调试时偶尔开着浏览器硬解视频，显存被吃掉 2GB 后，推理速度立刻有明显下降。部署环境尽量保持干净，关掉不必要的 GUI 程序。

5.3 中文输出不稳定，把提示词和采样参数调稳

本地模型的中文能力往往比云端旗舰模型弱一些，尤其在长文中，容易出现前后用词不一致、偶尔冒出英文短语的问题。我的经验是，让它在所有回答里“克制”输出：System 提示词里明确要求“只使用简体中文回答”，同时在请求参数里把temperature调低，降低随机性。

如果面对的是特定格式的输出，比如“请把回答分成步骤 1、2、3”，不要只给一句指令，最好在提示词里带上一个输出示例。模型对示例的模仿能力很强，带示例的提问比不带示例的准确率高很多，这一点在实际调优中非常有用。

另外，中文分词对本地模型仍然是挑战，如果发现模型在回答里频繁重复某个词，可以尝试把repeat_penalty调高。Ollama 交互模式中可以用/set parameter repeat_penalty 1.2快速调整，API 请求里对应参数也能直接设置。

5.4 没有合适的 Web 界面，用 Open WebUI 接一层

不少人部署完 Ollama 后，总觉得只能在命令行里对话有点尴尬，尤其是不想教非技术同事敲命令。这个时候不要自己写前端，直接用 Open WebUI 这类开源项目，它本质上就是给 Ollama 套了一层类似标准对话产品的 Web 界面。

启动 Open WebUI 最简单的办法是 Docker：

docker run -d \ --name open-webui \ -p 3000:8080 \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ -v open-webui:/app/backend/data \ ghcr.io/open-webui/open-webui:latest

启动后访问http://localhost:3000，注册一个本地管理员账号，模型列表里就能看到 Gemma 4 12B。Open WebUI 会帮助管理多轮对话、历史记录、知识文件上传，对小团队来说已经够用。如果只是个人使用，这种方式比直接折腾完整知识库平台轻量很多。

6. 技术文档的写作复盘：一份好说明文档该长什么样

6.1 命令要有前置条件与预期结果

既然这篇文章是按技术文档标准写的，到这儿我也想顺便复盘一下：什么样的说明文档真正好用。我在写部署类文档时，最看重一点：每条命令前要写清楚前置条件，命令后要写清楚预期结果。

很多文档只丢一条命令出来，读者执行完看不到任何输出变化，也不知道到底成功没有，只能瞎猜。文档里应该明确写出“执行后你会看到什么”，比如安装完成会输出版本号，拉取模型会显示进度条，API 调用会返回 JSON。这样读者每一步都能自检，遇到问题能快速定位到是网络、路径、还是显存的问题。

6.2 让新手能直接“抄作业”的段落结构

技术文档最大的价值，是让一个从没做过的人也可以按图索骥地完成操作。我习惯把常见报错和解决办法单独整理成表格，因为新手最怕的不是操作难，而是操作后出现一个看不懂的报错却没人可以问。

结构上，我遵循一条原则：先让别人把环境跑起来，再解释原理。很多技术文档一上来就花半篇讲模型架构、注意力机制、KV 缓存，这些对实际部署帮助有限。先把安装和跑通的路径理顺，让读者获得正反馈，再在“问题排查”“调优参数”的地方解释原因，学习效率会高很多。

6.3 文档完成后应该具备的自检清单

写完一份部署文档，别急着发出去，先对照自检一遍：命令是否可以在全新环境中直接执行；代码块是否标注了语言和平台；每个步骤是否说明了预期输出；常见问题的解法是否覆盖了显存、网络、路径这几个高频故障点；标题编号是否清晰，能否通过目录直接定位内容。

我这次整理 Gemma 4 12B 部署文档时，就按照这个清单回查了三遍。第一遍发现 Windows 和 Linux 的环境变量设置写混了，第二遍发现 API 调用示例里少了base_url，第三遍才算稳定。这也是我自己写文档的习惯：把自己当成第一次接触这个模型的人，把每个步骤在干净环境里重新执行一遍，确保没有任何隐藏依赖。

这份文档里涉及的部署流程和排坑思路，已经在我这边的 16GB 显存机器和一台 24GB 显存服务器上反复验证过。最后再分享一个小技巧：模型部署完成之后，用ollama show gemma4:12b --modelfile查看模型的完整配置，你回发现很多参数是可以直接写进 Modelfile 里做个性化定制的，比如调整默认温度、加入自定义提示词模板。利用好这一点，Gemma 4 12B 能更贴你的业务场景。