实操讲义：第 06 次课：本地模型部署与调用验证

一、上节课回顾

上节课三个要点：
1. Stable Diffusion 用逐步加噪和去噪生成图像，噪声图是起点，逐步去噪是核心过程。
2. 潜在扩散先在 latent 空间压缩和去噪，再由 VAE 解码为像素图，用部分细节损失换算力效率。
3. CFG、负面提示词、采样步数等条件机制，会改变生成方向、结构和可控性。
已经留下的基础：学生在 LiblibAI 上完成过生图参数对照实验，能区分模型本体、条件输入和界面操作。
今天要接上的问题：前几次课的生成服务都在云端；如果数据不能出课堂、网络不稳定，模型怎么放到自己电脑上跑起来，并被命令行和程序稳定调用？

二、本节课任务与安排

先看结论：完成本课三个环节后，你的电脑上会跑起一个由本地 GGUF 文件驱动的 Ollama 模型，并通过命令行和标准 HTTP 接口两条通道验证它真的能用；最终产出是一个能被调用的本地模型服务，任何按 OpenAI 协议写的应用都可以接进来。

本节课结束时，学生能：

编写 Modelfile，把课前下载的本地 .gguf 文件导入为可调用的 Ollama 模型。
用命令行和 OpenAI 兼容接口两条通道验证模型名称、回复内容和接口地址。
按报错信息定位服务、路径、名称三类常见配置错误并修复。

环境与准备：[课前演练补充]

顺序	环节	学生产出	时间
M1	确认服务并编写 Modelfile	一份指向本地 GGUF 的 Modelfile	16分钟
M2	导入模型并命令行验证	一个能对话的本地模型	20分钟
M3	OpenAI 兼容接口验证	一份 API 连通测试记录	16分钟

三、实操环节

M1：确认服务并编写 Modelfile

任务目标：确认课前安装的 Ollama 服务真的在运行，然后在课程目录里写出一份指向本地 GGUF 文件的 Modelfile。本环节解决“模型文件怎么变成 Ollama 认识的模型”的准备问题：服务在跑、说明书写对，后面的导入才能一次成功。

实操步骤：

1. 确认 Ollama 服务状态

打开终端（Windows 用 PowerShell），检查 Ollama 命令可用。执行后你会看到类似 ollama version is 0.x.x 的版本输出。
bash
```
ollama -v
```
检查后台服务是否在运行。执行后你会看到 Ollama is running。
bash
```
curl http://localhost:11434
```
为什么这么做：Ollama 是“后台服务 + 命令行客户端”的结构，11434 是服务固定端口；服务没起来，后面所有命令都会失败。先确认地基，再盖楼。
如果上一步没有返回 Ollama is running：先打开 Ollama 桌面应用，等菜单栏出现羊驼图标后重新执行 curl。如果还是失败，举手呼叫老师检查安装。
进入课前建好的课程目录，确认模型文件在位。执行后你会看到 models 目录和里面的 .gguf 文件。
bash
```
cd ~/ai-course/lesson06
ls -lh models/
```
模型方案：全班默认使用 Qwen3-8B-Q4_K_M.gguf，导入名为 qwen3:8b。高配同学可按“课前准备 → 第 7 节”追加 Qwen3-VL-8B；8B 明显卡顿时先关闭大型应用，必要时使用老师指定的小文本 GGUF 保底。
注意：.gguf 文件名必须不含中文和空格；如果文件名不对，先改名再继续。

2. 编写 Modelfile

在 ~/ai-course/lesson06/ 下新建名为 Modelfile 的文件（不是 Modelfile.txt），写入以下内容并保存。执行后你会看到目录里多出一个无扩展名的 Modelfile 文件。
dockerfile
```
FROM ./models/Qwen3-8B-Q4_K_M.gguf

PARAMETER temperature 0.7
PARAMETER num_ctx 4096

SYSTEM """你是一个简洁、准确、安全的中文教学助手。"""
```
为什么这么做：Modelfile 是模型的“装配说明书”——FROM 告诉 Ollama 去哪里读模型权重，PARAMETER 定运行参数，SYSTEM 定人设。Ollama 靠这份说明书把裸的 GGUF 文件变成一个可调用的模型。
高配扩展：Qwen3-VL 还要再写一行 FROM ./models/mmproj-Qwen3VL-8B-Instruct-F16.gguf；视觉投影器也用 FROM 导入，完整步骤见“课前准备 → 第 7 节”。
自查两个易错点：文件名没有 .txt 后缀；FROM 路径与 ls 看到的文件位置一致。如果没把握，执行 cat Modelfile 对照上面的内容。

扩展练习：老师带练完成后，学生把 temperature 改成 0.2 另存为 Modelfile-low，先不改其他内容，想一想这个参数会在 M2 造成什么差别，M2 里验证你的猜想。

问题与注意事项：

ollama -v 找不到命令：判断方法是看终端是否提示 command not found。处理办法：关闭并重新打开终端刷新 PATH，仍失败则重装 Ollama。
保存后文件叫 Modelfile.txt：判断方法是打开文件所在文件夹看完整文件名。处理办法：重命名去掉 .txt，并在系统设置里开启扩展名显示。

M2：导入模型并命令行验证

任务目标：用 ollama create 把 GGUF 文件导入成名为 qwen3:8b 的本地模型，并在命令行里完成两轮对话测试。本环节验证“模型真的加载进内存并且听指令”，是两条验证通道里的第一条。

实操步骤：

1. 导入模型

在 Modelfile 所在目录执行导入命令。执行后你会看到导入进度提示，最终回到命令提示符。
bash
```
ollama create qwen3:8b -f ./Modelfile
```
查看本地模型列表，确认新模型在列。执行后你会看到 qwen3:8b 和它的大小。
bash
```
ollama list
```
为什么这么做：ollama list 显示的是“Ollama 仓库里已注册的模型名”，后面 M3 调接口和任何上层应用要填的模型名都必须和这里的名字一字不差——这是全课最容易踩的坑。
如果 create 报找不到文件：检查三点——是否在 Modelfile 所在目录执行的命令、FROM 相对路径是否写对、GGUF 文件名是否一致，修正后重新执行第 1 步。

2. 命令行对话测试

启动模型对话。执行后你会看到 >>> 提示符。
bash
```
ollama run qwen3:8b
```
在 >>> 后输入测试问题。执行后你会看到一句简洁的中文回答。
text
```
用一句话说明Ollama的作用。
```
再发一条试探系统提示词的消息。执行后你会看到它以“教学助手”的身份自我介绍。
text
```
你的名字是什么？你的角色是什么？
```
为什么这么做：第二条消息专门验证 SYSTEM 提示词是否生效——如果它自称通用模型而不是教学助手，说明 Modelfile 没有被正确应用，要回到 M1 检查。
测试完成后输入 /bye 退出对话，回到终端提示符。

扩展练习：老师带练完成后，学生用 Modelfile-low 再导入一个 qwen3:8b-low-temp 模型，问 M1 扩展练习里同样的问题，对比两个模型的回答风格差异，把观察写进实验表格——验证 temperature 对输出随机性的影响。

问题与注意事项：

模型加载慢或失败：判断方法是看报错是否提示内存不足或文件损坏。处理办法：关闭大型应用重试；仍失败换更小量化等级的 GGUF。
回答明显不听指令：判断方法是它答非所问或自称 base 模型。处理办法：确认课前下载的是 instruct/chat 模型，再检查 SYSTEM 提示词。

M3：OpenAI 兼容接口验证

任务目标：用 curl 直接调用 Ollama 的 OpenAI 兼容接口，拿到 JSON 格式的模型回复。本环节验证“程序也能用标准协议调用这个本地模型”——这是其他应用接入本地模型的基础，也是企业系统集成的标准方式。

实操步骤：

先在另一个终端确认服务仍在运行（M1 第 2 步的命令）。执行后你会看到 Ollama is running。
bash
```
curl http://localhost:11434
```
调用 OpenAI 兼容聊天接口。执行后你会看到一段 JSON，其中 content 字段是模型回复。
bash
```
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {
        "role": "user",
        "content": "用一句话说明Ollama的作用"
      }
    ]
  }'
```
为什么这么做：OpenAI 的接口格式已经成为行业事实标准——Ollama 兼容它，意味着所有按 OpenAI 协议写的应用都能无缝切换到本地模型，这是本地部署能进企业工作流的关键。
对照检查三件事，并记入实验表格：请求没有报错；JSON 里能找到回复内容；model 字段与 ollama list 显示的名称完全一致。
故意把请求里的 model 改成 qwen3:8（少个 3）再发一次。执行后你会看到一条报错而不是回答。执行完把名称改回来重发，确认恢复正常。
bash
```
curl -s http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3:8", "messages": [{"role": "user", "content": "你好"}]}'
```
为什么这么做：主动制造一次“模型名不匹配”的报错并记住它的样子——接口参数和上层应用里的模型名写错时，报错的根源十有八九就是这个。

扩展练习：老师带练完成后，学生把 messages 里的提问换成自己专业的实际问题，再发一次请求，把 JSON 中的 content 回答抄进实验表格，感受同一个模型换问题后的表现。

问题与注意事项：

Windows PowerShell 下 curl 报转义错误：判断方法是命令还没发出就提示语法问题。处理办法：把 JSON 保存为文件后用 -d @request.json 发送，或改用双引号并转义内部引号。
接口返回报错说模型不存在：判断方法是看报错信息里的模型名。处理办法：复制 ollama list 里的名称原样粘贴，不要手写近似名。

课后巩固

完成本页下方课后巩固题【M1-01】～【M1-05】、【M2-01】～【M2-05】，题目考查本地部署链路（服务、GGUF、Modelfile、兼容接口）背后的原理与排错判断。

资料与下载

课前准备：Qwen3-8B 下载、导入与本地验证：含国内直连源、官方源、VL 模型和机房分发步骤。
实训素材清单：模型权重入口、Modelfile 模板和课前检查表。
课堂命令速查与故障排查表：见上方各环节“问题与注意事项”，完整版以老师课前在学习通发布的资料包为准。
Ollama 官方文档：下载页、Quickstart、Modelfile 说明、OpenAI 兼容接口。
课堂/课后习题：请在学习通对应单元完成，待补充入口链接。

实操讲义：第 06 次课：本地模型部署与调用验证 ​

一、上节课回顾 ​

二、本节课任务与安排 ​

三、实操环节 ​

M1：确认服务并编写 Modelfile ​

1. 确认 Ollama 服务状态 ​

2. 编写 Modelfile ​

M2：导入模型并命令行验证 ​

1. 导入模型 ​

2. 命令行对话测试 ​

M3：OpenAI 兼容接口验证 ​

课后巩固 ​

资料与下载 ​

实操讲义：第 06 次课：本地模型部署与调用验证

一、上节课回顾

二、本节课任务与安排

三、实操环节

M1：确认服务并编写 Modelfile

1. 确认 Ollama 服务状态

2. 编写 Modelfile

M2：导入模型并命令行验证

1. 导入模型

2. 命令行对话测试

M3：OpenAI 兼容接口验证

课后巩固

资料与下载