`0-qwen3-vl-demo.ipynb` 代码说明

这份 notebook 在做什么

这份 notebook 做的事情其实很简单：

读入一张本地图片
把图片转成模型能接收的 base64 字符串
构造一个标准的 Ollama chat 请求
把文字问题和图片一起发给 qwen3.5:0.8b
显示模型返回的视觉理解结果

如果你把它和前面 3/2-prog/0-qwen3-chat-demo.ipynb 对照着看，会发现：

文本版 demo：只传文字
视觉版 demo：在文字之外，再多传一个 images

也就是说，视觉模型的调用方式并没有“完全换一套”，只是输入结构多了一层图片。

先看整体结构

这份 notebook 可以分成 6 步：

导入依赖，指定图片路径
展示图片，先让人眼确认输入
把图片转成 base64
构造 payload
请求本地 Ollama
改 prompt，观察模型输出如何变化

Cell 0：标题页

这一格只是告诉你：

这里调用的是本地 Ollama
模型是 qwen3.5:0.8b
目标是做一个最小视觉 demo

它本身不执行代码，但它很重要，因为它定义了 notebook 的任务边界：
不是训练模型，而是调用现成模型。

Cell 1：说明图片路径

这一格告诉你默认图片在哪里：

examples/example.png

这一步的意义是：

先固定输入
避免一开始就让学生自己找图片、改路径、排错

Cell 2：导入依赖并检查图片

这一格的代码是：

from pathlib import Path
import base64
import json
import mimetypes
import urllib.request
from IPython.display import Image, display
import argparse
import os
import sys
import urllib.error

image_path = Path('examples/example.png')
image_path.exists()

逐块看：

from pathlib import Path 作用：更方便地处理文件路径。
import base64 作用：把图片二进制内容转成文本字符串，方便放进 HTTP 请求。
import json 作用：把 Python 字典变成 JSON 请求体。
import mimetypes 作用：根据文件后缀猜图片类型，比如 png、jpg。
import urllib.request 作用：用 Python 标准库发 HTTP 请求。
from IPython.display import Image, display 作用：在 notebook 里直接显示图片。
import os 作用：后面用来清理代理环境变量。
import sys 作用：处理错误输出。
import urllib.error 作用：捕获 HTTP 和网络请求错误。

这里的：

image_path = Path('examples/example.png')

表示：

新建一个路径对象
指向当前目录下的示例图片

而：

image_path.exists()

只是做一个最简单的检查：

如果返回 True，说明图片路径有效
如果返回 False，后面肯定跑不起来

Cell 3：显示图片

display(Image(filename=str(image_path)))

这一格特别适合课堂展示，因为它做了两件很实际的事：

让学生先看见输入图片
避免“模型说错了，到底是图错了还是模型错了”这种混乱

逐行解释：

str(image_path) 把 Path 对象转成普通字符串路径。
Image(filename=...) 告诉 notebook 去加载这张图片。
display(...) 让它直接显示在输出区。

Cell 4：说明要转成 base64

这一格在提醒学生：

图片不能直接作为 Python 对象塞进 JSON
要先转成字符串

这里最重要的概念是：

base64 不是“让图片更清晰”
它只是把二进制文件编码成文本形式，方便通过 JSON 传输

Cell 5：把图片转成 base64

代码是：

mime_type, _ = mimetypes.guess_type(str(image_path))
if mime_type is None:
    mime_type = 'image/png'

image_base64 = base64.b64encode(image_path.read_bytes()).decode('utf-8')
image_base64[:80]

逐行解释：

mimetypes.guess_type(str(image_path)) 根据文件名猜类型。例如图片可能被识别成 image/png。
mime_type, _ = ... 左边第一个变量拿到 MIME 类型，第二个变量这里不用，所以写成 _。
if mime_type is None: 如果没猜出来，就手动给一个默认值。
mime_type = 'image/png' 把默认值设成 PNG。

真正关键的是：

image_path.read_bytes()

它表示：

直接按二进制方式读取整张图片

再看：

base64.b64encode(...)

它表示：

把二进制内容转成 base64 编码

最后：

.decode('utf-8')

表示：

把编码结果从字节串转成普通 Python 字符串

这一格最后只显示：

image_base64[:80]

不是为了看完整图片内容，而是为了确认：

它确实已经变成了一长串字符串

Cell 6：说明要构造 payload

这一格的重点是提醒学生：

请求视觉模型时，图片不是单独发
而是和文字问题一起放进 messages

这是理解多模态接口最重要的一步。

Cell 7：构造请求体

代码是：

payload = {
    'model': 'qwen3.5:0.8b',
    'stream': False,
    'messages': [
        {
            'role': 'user',
            'content': '请描述这张图片的主要内容，并指出你最有把握的三个视觉细节。',
            'images': [image_base64],
        }
    ],
}

payload

逐项解释：

'model': 'qwen3.5:0.8b' 指定本次要调用哪个本地模型。
'stream': False 表示不要流式返回，而是一次性拿完整结果。这样更适合教学和调试。
'messages': [...] 这是 Ollama 的对话输入结构。
'role': 'user' 说明这条消息来自用户。
'content': '...' 这是用户提出的问题。
'images': [image_base64] 这里是视觉版本和文本版本最大的区别。它表示：除了文字问题，再给模型一张图片。

为什么是列表 []？

因为接口允许一次传多张图
这里只传一张，所以列表里只有一个元素

Cell 8：说明要请求本地 Ollama

这一格的作用是把思路从“组织 Python 数据”切换到“真正发 HTTP 请求”。

学生在这里要建立一个概念：

本地模型调用，本质上还是 API 调用
只是这个 API 运行在自己电脑上

Cell 9：请求本地 Ollama

这是整份 notebook 最核心的一格。

第一部分：

request = urllib.request.Request(
    'http://localhost:11434/api/chat',
    data=json.dumps(payload).encode('utf-8'),
    headers={'Content-Type': 'application/json'},
    method='POST',
)

逐行解释：

'http://localhost:11434/api/chat' 这是本地 Ollama 的聊天接口。
json.dumps(payload) 把 Python 字典转成 JSON 字符串。
.encode('utf-8') 再把字符串转成字节，方便 HTTP 发送。
headers={'Content-Type': 'application/json'} 告诉服务器：这次发的是 JSON。
method='POST' 说明这是一个提交数据的请求。

第二部分：

for key in [
    "http_proxy",
    "https_proxy",
    "HTTP_PROXY",
    "HTTPS_PROXY",
    "all_proxy",
    "ALL_PROXY",
]:
    os.environ.pop(key, None)
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))

这是给初学者特别值得讲清楚的一段。

它的作用是：

强制这次请求直连本机
不要被系统里残留的代理环境变量干扰

为什么要这样写？

很多同学电脑上配过代理
urllib 有时会自动读这些环境变量
结果本来请求的是 localhost
却被错误地转发到 socks5 或别的代理上

os.environ.pop(key, None) 的意思是：

如果这个环境变量存在，就删掉
如果不存在，也不要报错

而：

urllib.request.ProxyHandler({})

表示：

明确告诉 urllib：这次不要用任何代理

第三部分：

try:
    with opener.open(request) as response:
        result = json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as exc:
    print(exc.read().decode("utf-8", errors="ignore"), file=sys.stderr)
except urllib.error.URLError as exc:
    print(f"Failed to reach Ollama: {exc}", file=sys.stderr)

这部分是在做错误处理。

HTTPError 表示服务器收到了请求，但返回了错误状态。例如模型名不存在。
URLError 表示连本地服务都没连上。例如 Ollama 没启动。

最后：

message = result.get("message", {})
print(message.get("content", "").strip())

表示：

从返回 JSON 里取出 message
再取出模型真正回答的文字内容
strip() 去掉首尾空白

Cell 10：说明查看输出

这格只是一个过渡，告诉学生：

到这里请求已经完成
下一格我们只看模型回答

Cell 11：读取模型回答

result['message']['content']

这格很简单，但教学上很重要。

因为它把“完整 JSON 返回”和“我们真正关心的回答内容”分开了。

学生要知道：

API 返回里可能还有很多别的信息
真正的回答通常在 message -> content

Cell 12：第二轮 prompt

这里开始进入更有趣的部分：

同样一张图
改变问题
看输出怎样变化

这一步特别适合课堂互动。

Cell 13：改 prompt 再请求一次

这格本质上是在重复前面的请求流程，只是把：

payload['messages'][0]['content']

换成了新的问题：

“请解释这张图的幽默点，并说明你的判断依据。”

这一步想让学生看到：

模型不是只会“识别图里有什么”
还会尝试做更高层的图文理解

这份 notebook 最值得学生带走什么

视觉模型的调用接口和文本模型很像，只是多了 images 字段。
图片必须先转成 base64，才能通过 JSON 请求发送。
本地调用失败时，常见问题不是“模型不会”，而是代理、服务、模型名、图片路径这些工程细节。
同一张图，换一个 prompt，模型的输出层次会明显变化。

最常见的 4 个报错

1. 图片路径错误

现象：

image_path.exists() 返回 False

说明：

图片文件没找到

2. 本地服务没开

现象：

URLError

说明：

Ollama 没启动

3. 模型名写错

现象：

HTTPError
返回类似 model not found

说明：

本地没有这个模型，或者名字写错

4. 代理干扰本地请求

现象：

看起来请求的是 localhost
却报代理相关错误

说明：

环境变量里的代理设置影响了本地请求

这也是为什么这里专门清理代理变量。

0-qwen3-vl-demo.ipynb 代码说明

这份 notebook 在做什么

先看整体结构

Cell 0：标题页

Cell 1：说明图片路径

Cell 2：导入依赖并检查图片

Cell 3：显示图片

Cell 4：说明要转成 base64

Cell 5：把图片转成 base64

Cell 6：说明要构造 payload

Cell 7：构造请求体

Cell 8：说明要请求本地 Ollama

Cell 9：请求本地 Ollama

Cell 10：说明查看输出

Cell 11：读取模型回答

Cell 12：第二轮 prompt

Cell 13：改 prompt 再请求一次

这份 notebook 最值得学生带走什么

最常见的 4 个报错

1. 图片路径错误

2. 本地服务没开

3. 模型名写错

4. 代理干扰本地请求

`0-qwen3-vl-demo.ipynb` 代码说明