第 0 篇：macOS 安装和准备 Ollama

为什么要先完成这一步

本教程中的 Java 程序不会直接加载大模型文件，而是通过 HTTP 调用本机 Ollama：

Java 程序 -> http://localhost:11434 Ollama 服务 -> 加载本地模型 模型生成回答

如果 Ollama 没有安装、后台服务没有启动，或者指定模型尚未下载，后面的 Java 示例都无法运行。

Ollama 是什么

Ollama 是本地大模型运行器，主要负责：

• 下载和管理模型。
• 在 Mac 上加载模型并完成推理。
• 提供终端聊天功能。
• 在localhost:11434提供 HTTP API。

它不是具体模型，也不是 RAG 框架或向量数据库。可以把 Ollama 理解为模型的运行环境，把 Qwen3 理解为由它加载的模型。

第 1 步：检查 Mac 配置

system_profiler SPHardwareDataType|grep-E"Chip|Memory"

这条命令只读取芯片和内存信息，不会修改系统。模型越大，通常需要越多统一内存。

入门时可以参考：

实际速度还会受到芯片、上下文长度和同时运行的软件影响。如果电脑频繁使用交换内存，应改用更小的模型。

本教程当前代码使用qwen3:14b。如果选择其他模型，需要让当前示例使用实际模型名称；各模块的具体修改位置见**《模型切换指南：qwen3 / bge-m3 怎么换》**。

第 2 步：检查 Homebrew

brew--version

Homebrew 用于在 macOS 上安装和管理命令行软件。如果提示command not found，请先按照 Homebrew 官方网站 的说明安装。

第 3 步：安装 Ollama

brewinstallollama

这一步只安装 Ollama 程序，不会自动下载任何大模型。

确认安装结果：

ollama--version

看到版本号就表示命令已经可用。

第 4 步：启动后台服务

brew services start ollama

使用 Homebrew 服务启动后：

• Ollama 在后台运行。
• 关闭当前终端不会停止服务。
• 登录 Mac 后可以自动启动。
• 默认监听127.0.0.1:11434。

检查 HTTP API：

curlhttp://localhost:11434/api/tags

尚未下载模型时，可能看到：

{"models":[]}

这表示服务正常，只是模型列表为空。

常用服务命令：

brew services list brew services restart ollama brew services stop ollama

它们分别用于查看、重启和停止 Ollama 后台服务。

第 5 步：下载模型

本教程使用：

ollama pull qwen3:14b

• qwen3是模型系列。
• 14b表示大约 140 亿参数，不等于文件大小为 14 GB。
• 下载后的量化模型通常会占用数 GB 磁盘。

查看已经下载的模型：

ollama list

列表中应出现qwen3:14b。

模型通常由 Ollama 管理在用户目录下的数据目录中。不要手动修改模型文件；需要删除时使用：

ollamarmqwen3:14b

第 6 步：在终端测试模型

ollama run qwen3:14b

看到>>>后输入：

请用三句话解释什么是 RAG。

第一次运行需要将模型加载到内存，可能比后续请求慢。完成测试后输入：

/bye

这只退出当前聊天，不会删除模型或停止后台服务。

查看当前加载的模型：

ollamaps

第 7 步：验证 Java 将使用的接口

curlhttp://localhost:11434/api/chat\-H"Content-Type: application/json"\-d'{ "model": "qwen3:14b", "messages": [ { "role": "user", "content": "请用一句话解释向量检索" } ], "stream": false, "think": false }'

成功时会返回 JSON，并包含：

{"message":{"role":"assistant","content":"……"},"done":true}

这个接口正是第 1 篇 Java 程序调用的地址。

常见问题

无法连接localhost:11434

查看服务状态：

brew services list

重新启动：

brew services restart ollama

提示模型不存在

查看模型名称：

ollama list

确保 Java 代码中的MODEL与列表中的名称完全一致。

电脑响应很慢

• 关闭暂时不用的高内存应用。
• 缩短输入和对话历史。
• 改用qwen3:8b或qwen3:4b。
• 使用ollama ps检查当前加载状态。

测试类由更高版本 Java 编译

如果看到：

class file version 61.0, this version only recognizes up to 55.0

含义是：代码由 Java 17 编译，但当前测试运行器使用 Java 11。

版本对应关系：

先在终端确认：

java-versionmvn-version

两处都应显示 Java 17 或更高版本。如果终端正常但 IntelliJ 测试失败，检查：

Project Structure -> Project SDK -> 17 Settings -> Build Tools -> Maven -> Importer JDK -> 17 Settings -> Build Tools -> Maven -> Runner JRE -> 17

修改后重新加载 Maven 项目，再执行：

mvn-f01-ollama-basics/pom.xml cleantest

如何停止或卸载

临时停止后台服务：

brew services stop ollama

卸载 Ollama 程序：

brew uninstall ollama

卸载程序不一定会自动删除已经下载的模型。建议先使用ollama list确认模型，再通过ollama rm 模型名逐个删除，避免误删其他数据。

成功标准

完成本篇后应满足：

• ollama --version能显示版本。
• brew services list显示 Ollama 已启动。
• ollama list包含qwen3:14b。
• ollama run qwen3:14b可以正常回答。
• /api/chat返回包含message.content的 JSON。

满足这些条件后，再进入《第1-2篇：Java 调用 Ollama 与解析模型响应》。

本篇小结

1. Java 程序不直接加载大模型文件，而是通过http://localhost:11434调用本机 Ollama，Ollama 只是模型的运行环境。
2. brew install ollama+brew services start ollama让服务常驻后台，默认监听127.0.0.1:11434。
3. 按内存选模型：8 GB 用qwen3:4b，16 GB 用qwen3:8b，24 GB 及以上用qwen3:14b。
4. ollama pull / list / run / ps / rm覆盖了下载、查看、测试、状态与删除的日常操作。
5. 最后用curl调/api/chat验证接口，这正是第 1 篇 Java 程序要请求的地址。

下一篇

完整代码都在 GitHub（欢迎 Star ⭐）

本专栏的全部示例代码都已开源，包含 5 个可独立运行的 Maven 模块、自动化测试和完整分篇教程。建议Fork / Clone下来，边读边跑：

🔗 https://github.com/bysbsh/ai-rag-learning-guide

• 代码与教程同步更新，对照每一篇动手实践效果最好。
• 如果这份教程帮到了你，点个Star就是对我最大的支持，也方便你之后找回最新版本。
• 遇到问题或发现错漏，欢迎在仓库提 Issue / PR。项目采用 MIT 协议，可自由学习与二次创作。