【JavaAI】LangChain4J(1) Windows 安装 Ollama 本地大模型

@TOC(【JavaAI】LangChain4J(1) Windows 安装 Ollama 本地大模型)

🎯 本系列第 1 篇（本地篇） ：把「Ollama 本地大模型」从安装、选模型、下载、启动、运维到 Postman 联调一次性吃透 。

📅 整理日期：2026-08-25 ｜ 🖥️ 适用平台：Windows ｜ 🔗 官方站点：https://ollama.com（下载 / 模型库）

💡 阅读顺序：功能（1）→ 安装（2）→ 选模型（3）→ 日常命令（4、5）→ Postman 联调（6）。

---

🦙 第 1 部分：Ollama 是什么？（功能全解）

Ollama 是一个开源的本地大模型运行与管理系统，口号是「像 Docker 管容器一样管大模型」------把「下载模型、启动推理服务、提供 API」打包成几条命令。

🎯 功能	说明	对你的价值
一键下载模型	ollama pull <模型>，自动拉取 GGUF 格式模型到本地	不用去 HuggingFace 手动下载/解压
一键运行对话	ollama run <模型> 进入交互式聊天	命令行直接体验模型
内置 REST API	服务默认跑在 http://localhost:11434，提供 /api/chat、/api/generate、/api/tags 等接口	⭐ Postman / 程序 / LangChain4J 都能直接调
OpenAI 兼容端点	提供 /v1/chat/completions 兼容接口	老代码换 base-url 即可对接本地模型
跨平台	Windows / macOS / Linux	本文讲 Windows
GPU 加速	自动检测 NVIDIA GPU（CUDA）加速推理；无 GPU 退化为 CPU	有显卡更快，没显卡也能跑小模型
模型管理	list（已装）/ ps（运行中）/ rm（删除）/ cp/show	本地模型库尽在掌握
Modelfile 定制	类 Dockerfile，可改模板/参数/系统提示词、合并模型	定制你自己的"私有模型"
量化格式	模型自带 Q4/Q5/Q8 等量化版本，2.5GB 就能跑 4B 模型	普通电脑也能玩

工作原理一句话 ：ollama serve 启动常驻服务 → 请求到达 localhost:11434 → 按 model 名加载对应 GGUF 模型 → GPU/CPU 推理 → 返回文本（可流式）。

💡 与云端 API 的对比：数据不出本机、免费无限调用、离线可用、延迟低；代价是模型能力上限取决于你的硬件。

---

🪟 第 2 部分：Windows 下载安装与验证

2.1 硬件要求

配置项	最低要求	推荐配置
内存 RAM	8 GB	⭐ 16 GB 及以上
显卡 GPU	无（CPU 可跑小模型）	NVIDIA（CUDA）8GB 显存以上
磁盘	10 GB 可用	100 GB（多装几个模型）
系统	Windows 10 22H2+ / 11	64 位

⚠️ 判断依据：模型量化体积 ≈ 参数量 × 0.7（Q4 量化）。4B 模型约需 2.5~4GB；8B 约需 5~6GB；14B 约需 9~10GB。内存不足会崩溃或极慢。

2.2 下载与安装

1. 打开官网 https://ollama.com/download/windows；
2. 下载 OllamaSetup.exe（约 500MB+，含 GPU 运行库）；
3. 双击安装（默认装到 C:\Users\<你>\AppData\Local\Programs\Ollama）；
4. 安装完成后，系统托盘会出现 🦙 图标，服务已自动启动。

💡 安装器已内置 CUDA/ROCm 运行时，无需手动装驱动；如需 NVIDIA 驱动请到官网更新。

官网下载比较慢，也可以直接windows商店下载

2.3 ✅ 验证安装成功（三种方式）

方式一：命令行版本

ollama --version

正常输出示例：ollama version is 0.9.x（🟢 出现版本号即成功）

方式二：查 API 版本（PowerShell / CMD）

curl http://localhost:11434/api/version

正常输出：{"version":"0.9.x"}（🟢 服务已就绪）

方式三：跑一个最小模型验证推理链路

ollama run qwen3:0.6b

出现 >>> 提示符并正常对话 = 🟢 全链路可用（模型会自动下载，约 500MB）。

🔴 若 ollama --version 提示"不是内部或外部命令"：① 重开终端；② 检查环境变量 PATH 是否包含 %USERPROFILE%\AppData\Local\Programs\Ollama；③ 重启电脑。

2.4 常用配置（环境变量，可选）

环境变量	作用	示例
OLLAMA_MODELS	🎯 模型存放目录（默认 C:\Users\<你>\.ollama\models）	set OLLAMA_MODELS=D:\ollama-models
OLLAMA_HOST	服务监听地址（默认 127.0.0.1:11434；局域网共享可设 0.0.0.0）	set OLLAMA_HOST=0.0.0.0:11434
OLLAMA_KEEP_ALIVE	模型驻留内存时长（默认 5 分钟，设 -1 常驻）	set OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL	并行请求数（默认 1，调高需大显存）	set OLLAMA_NUM_PARALLEL=4

📌 Windows 设置：此电脑 → 属性 → 高级系统设置 → 环境变量 新增即可；改完需重启 Ollama（托盘图标 → Quit，再启动）。

---

📚 第 3 部分：可选模型与推荐

3.1 主流模型总览（Ollama 官方库）

模型	命令标签	参数量	体积(Q4)	定位
🐉 Qwen3 系列	qwen3:0.6b / 1.7b / 4b / 8b / 14b / 32b	0.6B~32B	0.5~20GB	⭐ 中文最强开源系，全能
🔷 Llama 3.3	llama3.3:70b	70B	~40GB	英文通用旗舰
🔷 Llama 3.2	llama3.2:3b / 1b	1B~3B	2~2.5GB	轻量端侧
🧠 DeepSeek-R1	deepseek-r1:1.5b / 7b / 8b / 14b / 32b	1.5B~32B	1~20GB	⭐ 推理/数学强，带思考链
🤖 Qwen2.5 系列	qwen2.5:0.5b ~ 72b	0.5B~72B	0.4~45GB	上一代全能稳定
🔮 Gemma 3	gemma3:4b / 12b / 27b	4B~27B	3~17GB	Google 出品，多模态
🦊 Phi-4	phi4:14b	14B	~9GB	微软，数学/代码
✨ Mistral	mistral:7b	7B	~4.7GB	法语/欧洲语言强
📦 MoE 大模型	qwen3:30b-a3b / 235b-a22b	30B~235B	18~142GB	总参大但活跃参数少

🔍 完整列表与实时搜索：https://ollama.com/search（按 tags 排序、按大小筛选）。

3.2 🎯 推荐组合（按你的硬件选）

硬件	推荐模型	理由
🖥️ 8GB 内存（无 GPU）	qwen3:4b（含 4b-instruct） 、qwen3:1.7b	4B 是普通电脑的甜点：中文好、2.5GB、CPU 可跑
💻 16GB 内存 / 4~8GB 显卡	qwen3:8b 、qwen2.5:7b、deepseek-r1:7b	质量与速度平衡，8B 是性价比之王
🚀 32GB+ / 12~24GB 显卡	qwen3:14b、deepseek-r1:14b、phi4:14b	更强推理/代码
🏢 服务器级	qwen3:32b、llama3.3:70b、MoE 系	接近云端能力

3.3 各模型优缺点速览

模型	👍 优点	👎 缺点
qwen3:4b	中文好、体积小（2.5GB）、Apache 2.0 可商用、256K 长上下文、支持推理/非推理切换	复杂推理与 8B+ 有差距；深度代码略弱
qwen3:8b	中文+英文均衡、代码/工具调用强、性价比最高	需 8GB+ 内存才流畅
deepseek-r1:7b/14b	数学/逻辑推理强、输出带思考链	中文日常对话有时"过度思考"、速度偏慢
llama3.2:3b	极轻量、英文流畅	中文一般
phi4:14b	数学/代码/结构化输出强	体积大、日常闲聊一般
gemma3:4b	支持图片输入（多模态）、多语言	中文弱于 qwen

💡 选型口诀：中文任务无脑 qwen3 系；推理数学上 deepseek-r1；先 4b 起步验证，再按硬件往上加。

3.4 qwen3 全系对照（本文主角族）

标签	参数量	体积	适合
qwen3:0.6b	0.6B	~0.5GB	玩具/极低配
qwen3:1.7b	1.7B	~1.2GB	手机/低延迟
qwen3:4b / qwen3:4b-instruct	4B	~2.5GB	⭐ 本文主角：普通电脑首选
qwen3:8b	8B	~5.2GB	默认推荐（ollama run qwen3 默认即 8b）
qwen3:14b	14B	~9GB	强推理
qwen3:32b	32B	~20GB	高配
qwen3:30b-a3b	30B(MoE)	~18GB	高吞吐代码
qwen3:235b-a22b	235B(MoE)	~142GB	企业级

📌 4b 与 4b-instruct 差异：instruct 是更新模板的指令微调版 （对话体验更规范），体积一致；日常用 qwen3:4b-instruct 即可。

---

📥 第 4 部分：下载、启动、查看模型

4.1 下载大模型（拉取）

ollama pull qwen3:4b-instruct        :: 下载指定模型（约2.5GB）
ollama pull qwen3                     :: 拉取默认标签（= qwen3:latest，即8b）

🐢 国内网络慢的解决办法（三种任选）：

① 命令行代理：set HTTPS_PROXY=http://127.0.0.1:7890 后再 pull；

② 换镜像源：配置 OLLAMA_HOST/镜像仓库（如社区镜像站）；

③ 断点重试：Ollama 支持断点续传，多试几次即可完成。

4.2 启动模型（运行）

ollama run qwen3:4b-instruct         :: 进入交互对话模式（自动加载，缺则先下载）

出现 >>> 后即可中文对话，如：你好，介绍一下你自己；

输入 /bye 或 Ctrl+D 退出交互。

🧠 Qwen3 的思考模式切换（在提示词末尾加标签）：

• /think → 深度推理模式（输出思考链，更严谨但慢）
• /no_think → 非推理模式（快速直接，响应更干净，生产推荐）

4.3 查看已下载模型

ollama list

输出列	含义
NAME	模型名（含标签，如 qwen3:4b-instruct）
ID	模型指纹
SIZE	实际占用（含量化后体积）
MODIFIED	最近修改时间

🎯 其他查看方式：

• ollama ps：查看当前加载在内存的模型（推理速度关键------加载中=慢，常驻=快）；
• API：GET http://localhost:11434/api/tags 返回已装模型 JSON 列表。

4.4 服务化启动（API 常驻，Postman 前置）

ollama serve        :: 前台启动 API 服务（监听 11434）
:: 或直接 `ollama run` 打开过一次后，托盘 Ollama 服务本身就在跑

💡 Windows 安装后 Ollama 服务默认自启 ；ollama serve 仅在服务没跑时手动启用。

---

🛠️ 第 5 部分：运维命令大全

5.1 命令速查表

命令	作用	示例
ollama serve	启动 API 服务	ollama serve
ollama create	从 Modelfile 创建模型	ollama create mybot -f Modelfile
ollama show	查看模型详情（参数量/模板/参数/许可）	ollama show qwen3:4b-instruct
ollama run	运行模型（交互/带提示词）	ollama run qwen3:4b-instruct "你好"
ollama pull	下载模型	ollama pull qwen3:4b-instruct
ollama push	上传模型到仓库	ollama push myns/mybot
ollama list	已下载模型列表	ollama list
ollama ps	内存中运行的模型（含占用/速度）	ollama ps
ollama cp	复制模型	ollama cp qwen3:4b my-qwen
ollama rm	删除模型（释放磁盘）	ollama rm qwen3:0.6b
ollama stop	停止正在运行的模型	ollama stop qwen3:4b
ollama login	登录仓库（上传用）	ollama login ollama.com
ollama version	版本信息	ollama --version

5.2 常用运维场景

场景	命令/操作
🔍 看磁盘被哪个模型占了	ollama list（看 SIZE 列）→ 不需要就 ollama rm <模型>
⚡ 推理突然变慢	ollama ps 看是否模型被换出内存；set OLLAMA_KEEP_ALIVE=-1 常驻
🚫 端口 11434 被占用	`netstat -ano
🧹 换模型存放盘（C 盘满）	设 OLLAMA_MODELS=D:\ollama-models 后重启服务，模型会重新下载到新目录
🔄 升级 Ollama	官网重新下载安装包覆盖安装（模型保留）
📋 查看服务日志	%LOCALAPPDATA%\Ollama\server.log（Windows）
🐛 彻底重置	退出托盘 → 删除 %USERPROFILE%\.ollama 目录（⚠️ 会删光所有模型）

5.3 服务管理（Windows）

• 托盘 🦙 图标：Quit 停止 / 双击启动；
• 开机自启：安装默认启用；关闭自启可在「任务管理器 → 启动」禁用 Ollama。

---

🧪 第 6 部分：Postman 测试案例（qwen3:4b-instruct）

📌 前置：确保 Ollama 服务在跑（curl http://localhost:11434/api/version 有返回）。

Postman 里 Body → raw → JSON 粘贴请求体；接口地址统一为 http://localhost:11434。

案例 0️⃣ 服务健康检查

项	值
方法	GET
URL	http://localhost:11434/api/version
预期响应	{"version":"0.9.x"}

案例 1️⃣ 查看已下载模型（Tags）

项	值
方法	GET
URL	http://localhost:11434/api/tags
预期响应	{"models":[{"name":"qwen3:4b-instruct","model":"...","size":...,"details":{"parameter_size":"4.02B","quantization_level":"Q4_K_M"}}]}

案例 2️⃣ 最简对话（Chat API，推荐）

项	值
方法	POST
URL	http://localhost:11434/api/chat

{
  "model": "qwen3:4b-instruct",
  "messages": [
    {"role": "user", "content": "用一句话介绍你自己"}
  ],
  "stream": false
}

响应要点：

{
  "model": "qwen3:4b-instruct",
  "message": {"role": "assistant", "content": "我是通义千问3-4B..."},
  "done": true,
  "total_duration": 1234567890,
  "eval_count": 42,
  "eval_duration": 987654321
}

字段	含义
message.content	🎯 模型回答正文
done	是否生成完毕
total_duration / eval_duration	总耗时 / 生成耗时（纳秒）
eval_count	生成的 token 数（本地免费用，但可统计耗时性能）

案例 3️⃣ 加 system 角色设定（中文）

{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "messages": [
    {"role": "system", "content": "你是严谨的中文旅游规划师，回答不超过3句话"},
    {"role": "user", "content": "去北京玩3天怎么安排？"}
  ]
}

💡 作用：把人设与约束 注入模型（对应上一份文档的 role=system）；4B 模型对 system 指令遵循度不错，是生产必经步骤。

案例 4️⃣ 多轮对话（携带历史）

{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "messages": [
    {"role": "user", "content": "我的名字叫小明"},
    {"role": "assistant", "content": "好的，小明，很高兴认识你！"},
    {"role": "user", "content": "我叫什么名字？"}
  ]
}

📌 关键点：Ollama 与 OpenAI 一样无状态 ------把完整历史放在 messages 里，模型才能"记住"；问答预期输出"你叫小明"。

案例 5️⃣ 生成参数控制（Generate API + 采样参数）

项	值
方法	POST
URL	http://localhost:11434/api/generate

{
  "model": "qwen3:4b-instruct",
  "prompt": "写一段介绍大模型技术的文案，50字以内",
  "stream": false,
  "temperature": 0.3,
  "top_p": 0.9,
  "top_k": 20,
  "max_tokens": 200,
  "repeat_penalty": 1.1
}

参数对照表（与 OpenAI 协议的区别要留意）：

参数	含义	与 OpenAI 对比
temperature	随机性（0~2）	✅ 同义
top_p	核采样（0~1）	✅ 同义
top_k	只从概率最高 K 个 token 中选	🆕 Ollama 原生支持（OpenAI 不支持）
max_tokens	输出上限	✅ 同义（Ollama 旧字段；新版也认 num_predict）
repeat_penalty	重复惩罚	🆕 Ollama 用词（≈ frequency_penalty）
num_ctx	上下文窗口（默认 2048，长文需调大）	🆕 Ollama 特有

案例 6️⃣ 流式输出（SSE，生产必用）

{
  "model": "qwen3:4b-instruct",
  "messages": [{"role": "user", "content": "给我讲一个关于长城的小故事"}],
  "stream": true
}

• Postman 中响应为多行 NDJSON（每行一个 chunk）：

{"model":"qwen3:4b-instruct","message":{"role":"assistant","content":"长城"},"done":false}
{"model":"qwen3:4b-instruct","message":{"role":"assistant","content":"是"},"done":false}
...
{"message":{"role":"assistant","content":""},"done":true,"eval_count":123}

• 📌 拼接所有 message.content = 完整回答；done:true 结尾。

案例 7️⃣ 强制 JSON 输出（结构化）

{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "format": "json",
  "prompt": "介绍北京和上海，输出JSON，格式：{\"cities\":[{\"name\":\"\",\"intro\":\"\"}]}"
}

• format: "json" 强制输出合法 JSON（🎯 Ollama 特有参数，对应 OpenAI 的 response_format）；
• 输出示例：{"cities":[{"name":"北京","intro":"..."},{"name":"上海","intro":"..."}]}------可直接 JSON.parse 进程序。

案例 8️⃣ OpenAI 兼容端点（衔接上一篇文档）

项	值
方法	POST
URL	http://localhost:11434/v1/chat/completions
Headers	Authorization: Bearer ollama（占位即可）

{
  "model": "qwen3:4b-instruct",
  "messages": [{"role": "user", "content": "用一句话介绍杭州"}],
  "temperature": 0.3,
  "stream": false
}

响应结构与 OpenAI 完全一致 （choices[0].message.content / usage）：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "杭州......"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 18, "completion_tokens": 30, "total_tokens": 48}
}

⭐ 意义重大 ：这个端点让 langchain4j-open-ai-spring-boot-starter 等 OpenAI 系 SDK 改一个 base-url 就能连本地模型 （即上一篇文档 base-url=http://localhost:11434/v1）。

案例 9️⃣ 生产级完整请求（综合）

{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "messages": [
    {"role": "system", "content": "你是客服助手，不知道就说不知道"},
    {"role": "user", "content": "信用卡逾期了怎么办？"}
  ],
  "temperature": 0.3,
  "top_p": 0.9,
  "top_k": 20,
  "max_tokens": 300,
  "repeat_penalty": 1.1,
  "options": {"num_ctx": 8192}
}

💡 options 内可塞底层推理参数（num_ctx 上下文、num_gpu GPU 层数、seed 等），适合高级调优。

---

⚠️ 第 7 部分：常见问题排查

现象	原因	解决
🔴 ollama 不是内部或外部命令	PATH 未配置	重开终端 / 手动加 PATH / 重启
🐢 模型下载慢/失败	国内网络	代理 / 镜像 / 断点重试
💥 运行崩溃/内存不足	模型太大 RAM 不够	换更小模型（4b→1.7b）/ 关其他程序
🐌 生成极慢	无 GPU / 模型换出内存	ollama ps 确认常驻；设 OLLAMA_KEEP_ALIVE=-1
🚫 端口被占	11434 被其他程序占用	换 OLLAMA_HOST 端口
🤷 中文回答差	模型英文向（如 Llama）	换 qwen3 系列
📄 长文本被截断	默认 num_ctx=2048 太小	options: {"num_ctx": 8192} 或更大

---

📚 参考资料

• Ollama 官网：https://ollama.com（下载 / 模型库 / 文档）
• Ollama API 文档：https://github.com/ollama/ollama/blob/main/docs/api.md