课程讲义中心

课前准备：Ollama 本地 GGUF 部署与调用验证教程 ​

适用课次：第6次课《本地模型部署与调用验证》
目标：课前完成 Ollama 安装、下载一个本地 .gguf 模型；课堂上用 Modelfile 导入模型，并用命令行和标准 HTTP 接口完成验证。
完成标准：ollama -v 能输出版本；curl http://localhost:11434 能返回 Ollama is running；本机已导入 qwen3:8b。高配同学可继续导入 qwen3-vl:8b。

1. 机型方案与课前检查 ​

课堂默认演示 Qwen3-8B 文本模型，导入后的模型名固定为 qwen3:8b。配置较高的同学可选装 Qwen3-VL-8B 多模态模型；如果电脑暂时跑不动 8B，先关闭大型应用再试；仍不能运行时使用教师指定的更小文本 GGUF 作为补救方案。

方案模型适用同学必需文件建议
标准演示qwen3:8b全班默认Qwen3-8B-Q4_K_M.gguf（约 4.68 GB）纯文本、工具调用和课堂主流程。
高配扩展qwen3-vl:8b内存/磁盘充足，想体验看图主模型约 4.7 GB + mmproj 约 1.1 GB需要两个文件都导入。
低配补救更小文本 GGUF8B 明显卡顿的同学教师指定的 0.6B/1.7B 量化文件只用于保底完成导入链路，课堂讲解仍以 8B 为例。
检查项课堂建议说明
操作系统macOS、Windows 10/11 或常见 LinuxOllama 官方下载页提供这些平台入口。
内存8B 建议 16GB 及以上；至少 8GB 并关闭大型应用VL 模型建议预留更多可用内存。
磁盘标准方案预留 8GB；追加 VL 再预留 8GB给下载缓存、模型文件、Ollama 存储和课程作业留空间。
网络课前下载或从 U 盘复制课中重点做导入和调试，不把时间耗在大文件下载。
权限允许安装软件、打开终端macOS/Linux 使用终端，Windows 建议使用 PowerShell。
终端环境macOS、Linux 用终端；Windows 用 PowerShell课堂的命令行和接口验证都在这里执行。

选模型时确认：文件是 .gguf；模型是 instruct/chat 模型；量化等级优先 Q4_K_M；文件名不含中文和空格。

2. 安装 Ollama ​

2.1 macOS ​

  1. 打开 https://ollama.com/download。
  2. 下载 macOS 版本。
  3. 解压后把 Ollama 拖入“应用程序”。
  4. 首次启动时，允许系统提示中的必要权限。

2.2 Windows ​

方法 A：图形安装

  1. 打开 https://ollama.com/download。
  2. 下载 Windows 安装包。
  3. 双击安装，按提示完成。
  4. 打开 PowerShell 继续后面的验证。

方法 B：PowerShell

powershell
irm https://ollama.com/install.ps1 | iex

2.3 Linux ​

打开终端执行：

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

安装结束后关闭并重新打开终端，让 ollama 命令进入新的 PATH。

3. 验证 Ollama 服务 ​

重新打开终端或 PowerShell，执行：

bash
ollama -v

能输出版本号，说明命令可用。再执行：

bash
curl http://localhost:11434

预期输出类似：

text
Ollama is running

如果 macOS 或 Windows 桌面版没有自动启动服务，先打开 Ollama 应用，再重新执行上面的 curl。若 Linux 下服务未启动，按安装完成提示启动 ollama serve，不要关闭该终端。

4. 下载 Qwen3-8B 文本模型 ​

推荐使用国内直连镜像下载；官方 Hugging Face 源内容一致，但需要代理。

bash
mkdir -p ~/ai-course/lesson06/models

curl -L -o ~/ai-course/lesson06/models/Qwen3-8B-Q4_K_M.gguf "https://hf-mirror.com/Qwen/Qwen3-8B-GGUF/resolve/main/Qwen3-8B-Q4_K_M.gguf"

官方源：

bash
curl -L -o ~/ai-course/lesson06/models/Qwen3-8B-Q4_K_M.gguf "https://huggingface.co/Qwen/Qwen3-8B-GGUF/resolve/main/Qwen3-8B-Q4_K_M.gguf"

如果已经从 U 盘拿到文件，直接复制到课程目录：

bash
cp /Volumes/AIGC-LESSON06/Qwen3-8B-Q4_K_M.gguf ~/ai-course/lesson06/models/

U 盘卷标和路径按实际电脑显示调整。复制后检查文件：

bash
ls -lh ~/ai-course/lesson06/models/Qwen3-8B-Q4_K_M.gguf

确认大小约为 4.68 GB，不是 0B、4.7K 或未完成的分片临时文件。

5. 编写标准文本模型 Modelfile ​

在 ~/ai-course/lesson06/ 下新建 Modelfile（不是 Modelfile.txt），写入：

dockerfile
FROM ./models/Qwen3-8B-Q4_K_M.gguf

PARAMETER temperature 0.7
PARAMETER num_ctx 4096

SYSTEM """你是一个简洁、准确、安全的中文教学助手。"""

字段含义：

字段作用课堂建议
FROM指向本地 .gguf 文件路径起点是 Modelfile 所在目录。
PARAMETER temperature控制输出随机性0.2–0.7 适合课堂演示。
PARAMETER num_ctx设置上下文窗口4096 足够课堂测试。
SYSTEM设置系统提示词定义课堂演示用的教学助手人设。

常见错误：

  1. 文件保存成 Modelfile.txt。
  2. FROM 指向的模型文件名、大小写或路径不一致。
  3. 把 base 模型当聊天模型使用。
  4. num_ctx 设置过高导致内存压力过大。

6. 导入并验证 qwen3:8b ​

确认终端在 Modelfile 所在目录：

bash
cd ~/ai-course/lesson06

导入课堂默认模型：

bash
ollama create qwen3:8b -f ./Modelfile

查看模型列表：

bash
ollama list

应能看到 qwen3:8b。再检查导入后的配置：

bash
ollama show qwen3:8b --modelfile

命令行测试：

bash
ollama run qwen3:8b "你好"

再测试系统提示词是否生效：

bash
ollama run qwen3:8b

进入对话后发送：

text
你的名字是什么？你的角色是什么？

完成后输入 /bye 退出。

7. 高配扩展：导入 Qwen3-VL-8B ​

Qwen3-VL 的 GGUF 是“主模型 + 视觉投影器（mmproj）”两个文件，两个都必须下载。

在国内直连镜像下载：

bash
curl -L -o ~/ai-course/lesson06/models/Qwen3VL-8B-Instruct-Q4_K_M.gguf "https://hf-mirror.com/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/main/Qwen3VL-8B-Instruct-Q4_K_M.gguf"

curl -L -o ~/ai-course/lesson06/models/mmproj-Qwen3VL-8B-Instruct-F16.gguf "https://hf-mirror.com/Qwen/Qwen3-VL-8B-Instruct-GGUF/resolve/main/mmproj-Qwen3VL-8B-Instruct-F16.gguf"

官方源只需要把域名 hf-mirror.com 换成 huggingface.co，其余路径保持一致。

新建 Modelfile-vl：

dockerfile
FROM ./models/Qwen3VL-8B-Instruct-Q4_K_M.gguf
FROM ./models/mmproj-Qwen3VL-8B-Instruct-F16.gguf

导入并验证：

bash
ollama create qwen3-vl:8b -f ./Modelfile-vl
ollama list
ollama run qwen3-vl:8b "描述这张图" /path/to/some/image.jpg

最后一条命令中的图片路径换成你本机真实图片路径。若要通过接口调用 VL 模型，把请求里的 model 换成 qwen3-vl:8b，并在 messages 的 content 中传入图片的 base64 编码或图片 URL。

8. U 盘机房分发方案 ​

给学校机房使用时，不要每台机器都从网上拉 5GB 文件。提前把文件拷入 U 盘或移动硬盘：

text
AIGC-LESSON06/
├── Qwen3-8B-Q4_K_M.gguf
├── Qwen3VL-8B-Instruct-Q4_K_M.gguf
└── mmproj-Qwen3VL-8B-Instruct-F16.gguf

最小课堂只需要第一个文件；高配机房再复制后两个文件。学生机只需要把文件复制到 ~/ai-course/lesson06/models/，再按上文执行一次 ollama create。

文本模型执行：

bash
ollama create qwen3:8b -f ./Modelfile

多模态模型执行：

bash
ollama create qwen3-vl:8b -f ./Modelfile-vl

两个模型可以共存，调用时按任务选择模型名：纯文本和工具调用用 qwen3:8b，看图任务用 qwen3-vl:8b。

9. 用 OpenAI 兼容接口验证 ​

Ollama 提供 OpenAI 兼容的聊天接口。执行：

bash
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明Ollama的作用"
      }
    ]
  }'

检查三点：

  1. HTTP 请求没有报错。
  2. JSON 中能找到回复内容。
  3. model 字段是 qwen3:8b。

Windows PowerShell 中如遇单引号转义问题，可改用双引号并对内部引号转义，或把 JSON 保存为文件后用 -d @request.json 发送。

10. 常见故障排查 ​

现象常见原因处理方法
ollama -v 找不到命令PATH 未刷新或未完成安装关闭并重新打开终端；重装后重启终端。
curl http://localhost:11434 失败Ollama 服务没有启动打开 Ollama 桌面应用，或启动 ollama serve。
模型下载中断网络波动或代理断开重新执行 curl -L -o；优先使用 hf-mirror 或 U 盘复制。
下载文件只有几 KB链接跳转页或鉴权失败确认使用 curl -L 和完整 resolve/main 地址。
ollama create 报找不到文件FROM 路径错误在 Modelfile 所在目录执行；用 ls -lh models/ 确认。
明明有文件却导入失败文件名是 Modelfile.txt重命名为 Modelfile；开启系统扩展名显示。
qwen3:8b 加载慢或失败内存不足、文件不完整、后台占用过高关闭大型应用；必要时使用教师指定的小文本 GGUF。
VL 模型不能看图缺少 mmproj 或第二个 FROM 路径错误确认两个文件都存在，并检查 Modelfile-vl 的两个 FROM。
model 字段写了近似名手写模型名导致不匹配复制 ollama list 中的名称原样填入请求。
能聊天但不听指令GGUF 是 base 模型或系统提示词不当使用 instruct/chat 模型，重设 SYSTEM。

11. 课堂演示顺序 ​

  1. ollama -v：确认命令。
  2. curl http://localhost:11434：确认服务。
  3. 打开 Modelfile：确认 FROM 指向 Qwen3-8B-Q4_K_M.gguf。
  4. ollama create qwen3:8b -f ./Modelfile：导入标准文本模型。
  5. ollama list：确认模型名。
  6. ollama run qwen3:8b "你好"：CLI 验证。
  7. curl 调 /v1/chat/completions：API 验证。
  8. 高配同学导入 qwen3-vl:8b，用带图片路径的请求验证看图任务。

12. 课后作业 ​

使用课前下载的 Qwen3-8B-Q4_K_M.gguf 创建 qwen3:8b，并完成两条通道的验证。提交：

  1. ollama -v 截图。
  2. curl http://localhost:11434 截图。
  3. Modelfile 内容截图。
  4. ollama list 截图。
  5. curl 调用兼容接口返回的 JSON 截图（能看到 content 回答）。
  6. 不超过 300 字的故障排查记录。

高配同学额外提交 qwen3-vl:8b 的看图任务验证截图。若中途失败，不要删除失败记录；写清最后一条错误、你改了什么、结果如何。

参考入口 ​