大模型应用开发 / 系统课时

macOS 安装与环境验证

macOS 安装与环境验证

学习目标

完成本课后,你将能够:

  • 在受支持的 macOS 系统中安装 Ollama
  • 验证 Ollama 应用、CLI 路径和默认 API
  • 判断设备是 Apple 芯片还是 Intel 架构
  • 使用日志和进程信息排查应用启动问题

安装前确认

macOS 版 Ollama 推荐通过 .dmg 安装为图形应用。应用启动后会检查 ollama CLI 是否可从 PATH 访问;如果缺少链接,会请求权限在 /usr/local/bin 创建命令链接。安装前确认:

  • 系统为 macOS Sonoma 14 或更新版本。
  • Apple M 系列设备可以使用 CPU 和 GPU 加速。
  • Intel Mac 主要使用 CPU。
  • 磁盘有足够空间保存应用和模型。
  • 当前用户有权限把应用放入 /Applications。
  • 企业设备没有禁止登录项、后台应用或命令链接。

检查系统版本:

bash
sw_vers

预期输出:

text
ProductName:            macOS
ProductVersion:         <MACOS_VERSION>
BuildVersion:           <BUILD_VERSION>

检查处理器架构:

bash
uname -m

Apple 芯片设备的常见输出:

text
arm64

Intel Mac 的常见输出:

text
x86_64

检查硬件信息:

bash
system_profiler SPHardwareDataType

预期输出中应包含:

text
Chip: <CHIP_NAME>
Total Number of Cores: <CORE_COUNT>
Memory: <MEMORY>

Intel 设备的字段可能显示处理器名称而不是 Chip。

安装 Ollama 应用

操作步骤:

  1. 从 Ollama 官方下载页面获取 macOS 安装包。
  2. 打开下载的 .dmg 文件。
  3. 将 Ollama 应用拖入 /Applications。
  4. 从“应用程序”启动 Ollama。
  5. 首次启动时,允许创建 CLI 链接。
  6. 确认菜单栏出现 Ollama 图标。
  7. 打开新的终端进行验证。

安装过程不需要伪造或依赖教程截图。只要应用位于 /Applications、菜单栏后台应用正常,并且 CLI 与 API 验证通过,即可判定安装成功。

验证应用是否存在

bash
test -d /Applications/Ollama.app && echo "Ollama.app exists"

预期输出:

text
Ollama.app exists

如果没有输出,检查应用是否放在其他目录,或是否仍停留在已挂载的安装镜像中。

验证 CLI 路径和版本

bash
command -v ollama
ollama --version

预期输出:

text
/usr/local/bin/ollama
ollama version is <VERSION>

版本号会随安装版本变化。CLI 路径也可能因自定义安装方式不同而变化。检查链接指向:

bash
ls -l "$(command -v ollama)"

预期输出示例:

text
<PERMISSIONS> <OWNER> <GROUP> <SIZE> <DATE> /usr/local/bin/ollama -> /Applications/Ollama.app/Contents/Resources/ollama

链接格式和日期会变化。验收标准是命令最终指向 Ollama 应用中的可执行文件。

如果 command -v ollama 没有输出:

  1. 退出 Ollama。
  2. 重新启动应用。
  3. 接受创建命令链接的提示。
  4. 检查 /usr/local/bin 是否位于 PATH。
  5. 必要时创建指向应用内 CLI 的符号链接。

创建链接前先验证目标文件:

bash
test -x /Applications/Ollama.app/Contents/Resources/ollama && echo "CLI binary exists"

预期输出:

text
CLI binary exists

只有目标文件存在时,才执行:

bash
sudo ln -sf /Applications/Ollama.app/Contents/Resources/ollama /usr/local/bin/ollama

预期结果:

text
命令正常结束,重新执行 command -v ollama 可输出 CLI 路径。

验证应用进程

bash
pgrep -fl Ollama

预期输出示例:

text
<PID> /Applications/Ollama.app/Contents/MacOS/Ollama
<PID> <OLLAMA_COMPONENT>

实际进程数量和名称可能随版本变化。若没有输出,可执行:

bash
open -a Ollama

预期结果:

text
命令正常结束,菜单栏出现 Ollama,随后 pgrep -fl Ollama 能看到相关进程。

验证默认 API

使用 curl 调用模型列表接口:

bash
curl --fail --silent --show-error http://localhost:11434/api/tags

新安装且没有模型时,预期输出可能是:

json
{"models":[]}

若已有模型,数组中会包含模型详情。验收标准是命令退出码为 0 且返回合法 JSON。进一步查看 HTTP 状态码:

bash
curl --silent --output /dev/null --write-out "%{http_code}\n" \
  http://localhost:11434/api/tags

预期输出:

text
200

若返回连接失败,先确认应用进程是否存在,再查看服务日志。

检查默认端口

bash
lsof -nP -iTCP:11434 -sTCP:LISTEN

预期输出示例:

text
COMMAND    PID    USER    FD    TYPE    DEVICE    SIZE/OFF    NODE    NAME
<COMMAND>  <PID>  <USER>  <FD>  IPv4    <DEVICE> 0t0         TCP     127.0.0.1:11434 (LISTEN)

具体命令名和监听地址可能不同。验收标准是端口 11434 处于 LISTEN 状态。

检查 Apple 芯片运行环境

确认 Metal 信息:

bash
system_profiler SPDisplaysDataType | grep -E "Chipset Model|Metal"

预期输出示例:

text
Chipset Model: <GPU_OR_CHIPSET>
Metal Support: <METAL_VERSION>

不同 macOS 语言和设备可能显示不同字段。该命令用于确认系统能识别显示和 Metal 能力,不代表某个模型已经加载到 GPU。后续下载并运行模型后,应使用:

bash
ollama ps

预期输出示例:

text
NAME       ID          SIZE      PROCESSOR    CONTEXT    UNTIL
<MODEL>    <MODEL_ID>  <SIZE>    <PROCESSOR>  <CONTEXT>  <UNTIL>

PROCESSOR 列用于判断实际处理器分布。没有正在运行的模型时,列表可能为空。

查看日志

查看服务日志最后 100 行:

bash
tail -n 100 ~/.ollama/logs/server.log

预期输出:

text
<最近的 Ollama 服务日志>

持续观察新日志:

bash
tail -f ~/.ollama/logs/server.log

预期结果:

text
终端持续等待;当 Ollama 发生新事件时输出新增日志。按 Control+C 结束。

应用日志通常位于:

text
~/.ollama/logs/app.log

服务启动、端口监听、GPU 发现和模型加载问题优先查看 server.log;应用自身启动问题可以同时检查 app.log。

修改模型存储位置

使用 OLLAMA_MODELS 指定新的模型目录。对于通过 macOS 应用启动的 Ollama,应设置登录会话可继承的环境变量,并重启应用。创建目录:

bash
mkdir -p "$HOME/OllamaModels"

预期结果:

text
命令正常结束,$HOME/OllamaModels 目录存在。

设置当前登录会话变量:

bash
launchctl setenv OLLAMA_MODELS "$HOME/OllamaModels"
launchctl getenv OLLAMA_MODELS

预期输出:

text
<HOME_PATH>/OllamaModels

<HOME_PATH> 为当前用户主目录。设置后从菜单栏退出 Ollama,再执行:

bash
open -a Ollama

预期结果:

text
Ollama 重新启动,后续下载的模型写入新目录。

launchctl setenv 的持久性受登录会话影响。生产环境应使用可维护的启动配置管理环境变量,并在升级后复验。

常见安装问题

1. 应用仍在安装镜像中运行

表现:卸载 .dmg 后应用无法启动,或 CLI 目标路径失效。

修复:把 Ollama 拖入 /Applications,再从“应用程序”启动。

2. CLI 链接不存在

表现:

text
zsh: command not found: ollama

修复:确认应用内 CLI 存在,再创建 /usr/local/bin/ollama 符号链接。

3. API 无法连接

检查顺序:

bash
pgrep -fl Ollama
lsof -nP -iTCP:11434 -sTCP:LISTEN
tail -n 100 ~/.ollama/logs/server.log

预期结果:

text
依次确认应用进程、端口监听和具体错误日志。

4. Apple 芯片设备仍表现缓慢

安装成功不能证明模型完全使用 GPU。运行模型后检查 ollama ps,同时观察模型大小、上下文长度和内存压力。

5. 磁盘空间不足

执行:

bash
df -h "$HOME"
du -sh ~/.ollama 2>/dev/null

预期输出示例:

text
Filesystem    Size    Used    Avail    Capacity    Mounted on
<DEVICE>      <SIZE>  <USED>  <FREE>   <PERCENT>   <MOUNT>

<OLLAMA_SIZE> <HOME_PATH>/.ollama

若空间不足,先停止下载,再规划模型目录迁移。

本课练习

练习 1:验证安装链路

任务目标:证明应用、CLI 和 API 三部分均正常。初始条件:已完成 Ollama 安装。

实现要求:验证 /Applications/Ollama.app、command -v ollama、版本和 /api/tags。

验收条件:每项都有实际输出,并能说明它验证的是应用、命令还是服务。

练习 2:检查芯片与处理器分布

任务目标:区分硬件能力与模型实际运行位置。初始条件:使用 Apple 芯片 Mac 并已运行一个模型。

实现要求:记录 uname -m、硬件信息和 ollama ps。

验收条件:解释为什么 arm64 只能证明架构,不能单独证明模型正在使用 GPU。

练习 3:排查 API 连接失败

任务目标:建立 macOS 启动问题排查路径。初始条件:curl 返回无法连接 localhost:11434。实现要求:按应用进程、端口、日志、重启顺序排查。

验收条件:每一步都写出命令、预期结果和失败后的下一步。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

macOS 安装与环境验证

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通