大模型应用开发 / 系统课时
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。 - 企业设备没有禁止登录项、后台应用或命令链接。
检查系统版本:
sw_vers预期输出:
ProductName: macOS
ProductVersion: <MACOS_VERSION>
BuildVersion: <BUILD_VERSION>检查处理器架构:
uname -mApple 芯片设备的常见输出:
arm64Intel Mac 的常见输出:
x86_64检查硬件信息:
system_profiler SPHardwareDataType预期输出中应包含:
Chip: <CHIP_NAME>
Total Number of Cores: <CORE_COUNT>
Memory: <MEMORY>Intel 设备的字段可能显示处理器名称而不是 Chip。
安装 Ollama 应用
操作步骤:
- 从 Ollama 官方下载页面获取 macOS 安装包。
- 打开下载的
.dmg文件。 - 将 Ollama 应用拖入
/Applications。 - 从“应用程序”启动 Ollama。
- 首次启动时,允许创建 CLI 链接。
- 确认菜单栏出现 Ollama 图标。
- 打开新的终端进行验证。
安装过程不需要伪造或依赖教程截图。只要应用位于 /Applications、菜单栏后台应用正常,并且 CLI 与 API 验证通过,即可判定安装成功。
验证应用是否存在
test -d /Applications/Ollama.app && echo "Ollama.app exists"预期输出:
Ollama.app exists如果没有输出,检查应用是否放在其他目录,或是否仍停留在已挂载的安装镜像中。
验证 CLI 路径和版本
command -v ollama
ollama --version预期输出:
/usr/local/bin/ollama
ollama version is <VERSION>版本号会随安装版本变化。CLI 路径也可能因自定义安装方式不同而变化。检查链接指向:
ls -l "$(command -v ollama)"预期输出示例:
<PERMISSIONS> <OWNER> <GROUP> <SIZE> <DATE> /usr/local/bin/ollama -> /Applications/Ollama.app/Contents/Resources/ollama链接格式和日期会变化。验收标准是命令最终指向 Ollama 应用中的可执行文件。
如果 command -v ollama 没有输出:
- 退出 Ollama。
- 重新启动应用。
- 接受创建命令链接的提示。
- 检查
/usr/local/bin是否位于PATH。 - 必要时创建指向应用内 CLI 的符号链接。
创建链接前先验证目标文件:
test -x /Applications/Ollama.app/Contents/Resources/ollama && echo "CLI binary exists"预期输出:
CLI binary exists只有目标文件存在时,才执行:
sudo ln -sf /Applications/Ollama.app/Contents/Resources/ollama /usr/local/bin/ollama预期结果:
命令正常结束,重新执行 command -v ollama 可输出 CLI 路径。验证应用进程
pgrep -fl Ollama预期输出示例:
<PID> /Applications/Ollama.app/Contents/MacOS/Ollama
<PID> <OLLAMA_COMPONENT>实际进程数量和名称可能随版本变化。若没有输出,可执行:
open -a Ollama预期结果:
命令正常结束,菜单栏出现 Ollama,随后 pgrep -fl Ollama 能看到相关进程。验证默认 API
使用 curl 调用模型列表接口:
curl --fail --silent --show-error http://localhost:11434/api/tags新安装且没有模型时,预期输出可能是:
{"models":[]}若已有模型,数组中会包含模型详情。验收标准是命令退出码为 0 且返回合法 JSON。进一步查看 HTTP 状态码:
curl --silent --output /dev/null --write-out "%{http_code}\n" \
http://localhost:11434/api/tags预期输出:
200若返回连接失败,先确认应用进程是否存在,再查看服务日志。
检查默认端口
lsof -nP -iTCP:11434 -sTCP:LISTEN预期输出示例:
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 信息:
system_profiler SPDisplaysDataType | grep -E "Chipset Model|Metal"预期输出示例:
Chipset Model: <GPU_OR_CHIPSET>
Metal Support: <METAL_VERSION>不同 macOS 语言和设备可能显示不同字段。该命令用于确认系统能识别显示和 Metal 能力,不代表某个模型已经加载到 GPU。后续下载并运行模型后,应使用:
ollama ps预期输出示例:
NAME ID SIZE PROCESSOR CONTEXT UNTIL
<MODEL> <MODEL_ID> <SIZE> <PROCESSOR> <CONTEXT> <UNTIL>PROCESSOR 列用于判断实际处理器分布。没有正在运行的模型时,列表可能为空。
查看日志
查看服务日志最后 100 行:
tail -n 100 ~/.ollama/logs/server.log预期输出:
<最近的 Ollama 服务日志>持续观察新日志:
tail -f ~/.ollama/logs/server.log预期结果:
终端持续等待;当 Ollama 发生新事件时输出新增日志。按 Control+C 结束。应用日志通常位于:
~/.ollama/logs/app.log服务启动、端口监听、GPU 发现和模型加载问题优先查看 server.log;应用自身启动问题可以同时检查 app.log。
修改模型存储位置
使用 OLLAMA_MODELS 指定新的模型目录。对于通过 macOS 应用启动的 Ollama,应设置登录会话可继承的环境变量,并重启应用。创建目录:
mkdir -p "$HOME/OllamaModels"预期结果:
命令正常结束,$HOME/OllamaModels 目录存在。设置当前登录会话变量:
launchctl setenv OLLAMA_MODELS "$HOME/OllamaModels"
launchctl getenv OLLAMA_MODELS预期输出:
<HOME_PATH>/OllamaModels<HOME_PATH> 为当前用户主目录。设置后从菜单栏退出 Ollama,再执行:
open -a Ollama预期结果:
Ollama 重新启动,后续下载的模型写入新目录。launchctl setenv 的持久性受登录会话影响。生产环境应使用可维护的启动配置管理环境变量,并在升级后复验。
常见安装问题
1. 应用仍在安装镜像中运行
表现:卸载 .dmg 后应用无法启动,或 CLI 目标路径失效。
修复:把 Ollama 拖入 /Applications,再从“应用程序”启动。
2. CLI 链接不存在
表现:
zsh: command not found: ollama修复:确认应用内 CLI 存在,再创建 /usr/local/bin/ollama 符号链接。
3. API 无法连接
检查顺序:
pgrep -fl Ollama
lsof -nP -iTCP:11434 -sTCP:LISTEN
tail -n 100 ~/.ollama/logs/server.log预期结果:
依次确认应用进程、端口监听和具体错误日志。4. Apple 芯片设备仍表现缓慢
安装成功不能证明模型完全使用 GPU。运行模型后检查 ollama ps,同时观察模型大小、上下文长度和内存压力。
5. 磁盘空间不足
执行:
df -h "$HOME"
du -sh ~/.ollama 2>/dev/null预期输出示例:
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。实现要求:按应用进程、端口、日志、重启顺序排查。
验收条件:每一步都写出命令、预期结果和失败后的下一步。