Gemma 4 / PaliGemma 2 / Ollama / Open WebUI 本地部署复盘

Gemma 4 / PaliGemma 2 / Ollama / Open WebUI 本地部署复盘

• 日期：2026-04-20
• 环境：WSL2 Ubuntu (gkubuntu2004)
• 目标：
  • 本地部署Gemma 4
  • 本地部署PaliGemma 2
  • 使用Ollama提供交互式聊天能力
  • 使用Open WebUI提供图形化聊天界面
  • 尝试将PaliGemma 2用于图像检测并返回标注图片

1. 总体结论

这次链路最终打通了以下几个部分：

1. Gemma 4 31B-it已完整下载并可本地使用。
2. PaliGemma 2 28b-mix-448已完整下载并可本地使用。
3. Ollama已手动安装成功，并可正常运行gemma4:31b。
4. Open WebUI已跑起来，但在 Docker Desktop + WSL 环境下，需要特别注意它连接的是哪一套Ollama。
5. 为PaliGemma 2增加了检测并返图的脚本，可以保存检测后的图片和 JSON。

同时也确认了几个关键经验：

• Gemma 4是多模态理解模型，不是图像生成模型，不能生图。
• PaliGemma 2可以做detect/segment，但要靠额外脚本把输出解析成可视化框图或后续矢量结果。
• Open WebUI默认连到的Ollama未必是当前 WSL 里的那套，需要明确指定。
• 超大模型下载在当前网络环境下最好用“镜像 + 断点续传 + 后台日志”的方式，不要依赖前台会话。

2. 文件与目录约定

2.1 Python 环境

复用的虚拟环境：

/root/gemma4/.venv

激活方式：

source/root/gemma4/.venv/bin/activate

2.2 模型目录

Gemma 4：

/root/models/gemma-4-31B-it

PaliGemma 2：

/root/models/paligemma2-28b-mix-448

2.3 脚本目录

Gemma 4 脚本：

/root/gemma4/

PaliGemma 2 脚本：

/root/paligemma2/

3. Gemma 4 本地部署

3.1 依赖安装

在/root/gemma4/.venv中安装的核心依赖：

python3-mvenv /root/gemma4/.venvsource/root/gemma4/.venv/bin/activate pipinstall-Upip setuptools wheel pipinstall-Utorch torchvision transformers accelerate bitsandbytes pillow sentencepiece safetensors huggingface_hub

3.2 下载 Gemma 4 31B-it

由于 Hugging Face 官方站点直连受限，实际采用了镜像方式下载：

HF_ENDPOINT=https://hf-mirror.com python /root/gemma4/download_gemma4.py\--modelgoogle/gemma-4-31B-it\--local-dir /root/models/gemma-4-31B-it

3.3 完整性检查

检查目录大小：

du-sh/root/models/gemma-4-31B-it

检查权重索引与分片是否齐全：

python3 -<<'PY' import json, os base='/root/models/gemma-4-31B-it' p=os.path.join(base,'model.safetensors.index.json') d=json.load(open(p)) print('expected_bytes', d['metadata']['total_size']) files=sorted(set(d['weight_map'].values())) for fn in files: fp=os.path.join(base, fn) print(fn, os.path.exists(fp), os.path.getsize(fp)) PY

实际结果：

• 总目录大小约59G
• 2 个权重分片都存在
• 模型完整可用

3.4 启动方式

单次文本问答：

source/root/gemma4/.venv/bin/activate python /root/gemma4/run_gemma4_text.py\--model/root/models/gemma-4-31B-it\--prompt"用中文介绍一下你自己"

交互式文本聊天：

source/root/gemma4/.venv/bin/activate python /root/gemma4/chat_gemma4.py\--model/root/models/gemma-4-31B-it

单次图像理解：

source/root/gemma4/.venv/bin/activate python /root/gemma4/run_gemma4_image.py\--model/root/models/gemma-4-31B-it\--image/path/to/test.png\--prompt"描述这张图"

3.5 关于显卡

如果要只用第二块显卡：

CUDA_VISIBLE_DEVICES=1python /root/gemma4/run_gemma4_text.py...

但注意：

• Gemma 4 31B-it的 Hugging Face 原始权重体积较大
• 单张 48GB 显卡直接bf16/fp16不一定稳
• 更适合双卡切分或量化后运行

4. PaliGemma 2 本地部署

4.1 模型与权限问题

PaliGemma 2 的目标模型为：

google/paligemma2-28b-mix-448

这个仓库是gated repo，需要：

1. 在 Hugging Face 模型页申请访问权限
2. 使用拥有授权的 HF token 下载

下载过程中遇到过：

• 账号未授权
• awaiting review
• 门禁通过后才能真正下载权重

4.2 下载命令

最终采用：

source/root/gemma4/.venv/bin/activateHF_TOKEN=你的tokenHF_ENDPOINT=https://hf-mirror.com\python /root/paligemma2/download_paligemma2.py\--modelgoogle/paligemma2-28b-mix-448\--local-dir /root/models/paligemma2-28b-mix-448

4.3 下载过程中的问题

下载大模型时，曾反复出现：

FileNotFoundError: ... .incomplete

这意味着：

• 某些 shard 下载过程中中断
• 临时分片文件丢失
• 最终形成了“看似完成、实际有空文件”的状态

典型例子：

model-00003-of-00012.safetensors

曾经是0 字节空文件。

4.4 修复方法

不要整个目录重下，优先：

1. 删掉损坏分片
2. 继续断点续传

例如：

rm-f/root/models/paligemma2-28b-mix-448/model-00003-of-00012.safetensors

然后续传：

source/root/gemma4/.venv/bin/activateHF_TOKEN=你的tokenHF_ENDPOINT=https://hf-mirror.com\python /root/paligemma2/download_paligemma2.py\--modelgoogle/paligemma2-28b-mix-448\--local-dir /root/models/paligemma2-28b-mix-448

4.5 完整性校验

最终校验方式：

python3 -<<'PY' import json, os base='/root/models/paligemma2-28b-mix-448' p=os.path.join(base,'model.safetensors.index.json') d=json.load(open(p)) expected=d['metadata']['total_size'] files=sorted(set(d['weight_map'].values())) missing=[] sizes=[] for fn in files: fp=os.path.join(base, fn) if os.path.exists(fp): sizes.append(os.path.getsize(fp)) else: missing.append(fn) print('expected_bytes', expected) print('present_files', len(sizes)) print('present_bytes', sum(sizes)) print('missing_files', len(missing)) PY

最终状态：

• 12 个权重分片齐全
• 无.incomplete文件
• 模型完整可用

5. PaliGemma 2 的使用方式

5.1 单次图像理解

source/root/gemma4/.venv/bin/activate python /root/paligemma2/run_paligemma2_image.py\--model/root/models/paligemma2-28b-mix-448\--image/root/gemma4/data/R-C.png\--prompt"describe en"

5.2 检测提示词

检测：

detect building detect road detect water

分割：

segment building segment road

5.3 自动画框返图

增加了脚本：

/root/paligemma2/detect_and_draw.py

用法：

source/root/gemma4/.venv/bin/activateCUDA_VISIBLE_DEVICES=1python /root/paligemma2/detect_and_draw.py\--model/root/models/paligemma2-28b-mix-448\--image/root/gemma4/data/R-C.png\--objectbuilding\--output/root/gemma4/data/R-C.detected.png\--json-output /root/gemma4/data/R-C.detected.json\--load-in-4bit

说明：

• --load-in-4bit：便于单张 48GB 显卡运行 28B 模型
• --output：保存画好框的图片
• --json-output：保存解析后的检测结果 JSON
• CUDA_VISIBLE_DEVICES=1：只用第二块显卡

6. 为什么 PaliGemma 2 不适合直接做“矢量化勾画主链路”

虽然PaliGemma 2可以做：

• detect
• segment
• 图像问答

但它并不是最稳妥的像素级边界提取主模型。

更合理的链路应是：

1. VLM做识别与提示
2. SAM2/samgeo做精确分割
3. GDAL polygonize做矢量化

也就是说：

• PaliGemma 2可以用于原型验证和对象提示
• 真正生产级的“掩膜 -> 矢量”仍建议配合专门分割工具

7. Ollama 安装

7.1 自动安装失败原因

官方安装脚本：

curl-fsSLhttps://ollama.com/install.sh|sh

在当前环境下失败，根因不是ollama.com不通，而是：

• ollama.com/download最终重定向到 GitHub Release
• 当前网络到github.com下载超时

典型报错：

curl: (7) Failed to connect to github.com port 443: Connection timed out

7.2 手动安装成功

手动下载好的文件：

/root/Downloads/ollama-linux-amd64.tar.zst

解压安装：

tar-Izstd-C/usr/local-xvf/root/Downloads/ollama-linux-amd64.tar.zst

验证：

/usr/local/bin/ollama--version

实际版本：

0.21.0

8. 用第二块显卡启动 Ollama

只使用第二块显卡启动：

CUDA_VISIBLE_DEVICES=1OLLAMA_HOST=0.0.0.0:11434 ollama serve

后台方式：

nohupbash-lc'CUDA_VISIBLE_DEVICES=1 OLLAMA_HOST=0.0.0.0:11434 /usr/local/bin/ollama serve'>/root/ollama.log2>&1&

8.1 拉取参数最多的 Gemma 4

注意：

• ollama pull gemma4默认不是最大版
• 最大版应显式指定：

ollama pull gemma4:31b

运行：

ollama run gemma4:31b

9. Open WebUI 部署

9.1 Docker 情况

起初发现：

• Windows 侧装了 Docker Desktop
• 但 WSL 集成没开

打开 Docker Desktop 的WSL Integration后，WSL 中的 Docker 才能正常用。

9.2 镜像拉取

最终拉取官方镜像：

dockerpull ghcr.io/open-webui/open-webui:main

9.3 第一次启动的问题

最开始使用的是：

dockerrun-d\--network=host\-vopen-webui:/app/backend/data\-eOLLAMA_BASE_URL=http://127.0.0.1:11434\--nameopen-webui\--restartalways\ghcr.io/open-webui/open-webui:main

问题：

• 容器是健康的
• 但浏览器访问localhost:8080失败

在Docker Desktop + WSL这套环境下，--network=host并不稳定，不适合这个场景。

9.4 重建为端口映射模式

改成：

dockerrm-fopen-webuidockerrun-d\-p3000:8080\--add-host=host.docker.internal:host-gateway\-eOLLAMA_BASE_URL=http://host.docker.internal:11434\-vopen-webui:/app/backend/data\--nameopen-webui\--restartalways\ghcr.io/open-webui/open-webui:main

然后访问：

http://localhost:3000

10. 为什么 Open WebUI 看不到gemma4:31b

这个问题最终定位为：

• Open WebUI 并没有连到当前 WSL 里的Ollama
• 它连到了另一套Ollama

容器内部实际看到的模型是：

• nomic-embed-text:latest
• deepseek-r1:70b

而不是当前 WSL 里的：

• gemma4:31b

10.1 根因

容器环境变量中使用的是：

OLLAMA_BASE_URL=http://host.docker.internal:11434

但这个地址在当前环境下指向的不是 WSL 当前实例的 Ollama，而是另一处宿主服务。

10.2 修复方法

先查出当前 WSL IP：

hostname-I

例如：

172.19.2.83

然后重建容器：

dockerrm-fopen-webuidockerrun-d\-p3000:8080\-eOLLAMA_BASE_URL=http://172.19.2.83:11434\-vopen-webui:/app/backend/data\--nameopen-webui\--restartalways\ghcr.io/open-webui/open-webui:main

这样 Open WebUI 才能连到当前 WSL 里的Ollama，前端才能看到：

• gemma4:31b

10.3 注意事项

WSL 的 IP 重启后可能变化。
如果以后 Open WebUI 又看不到本地模型，优先重新执行：

hostname-I

然后按新 IP 重建容器。

11. 当前可直接用的命令清单

11.1 Gemma 4 文本聊天

source/root/gemma4/.venv/bin/activate python /root/gemma4/chat_gemma4.py--model/root/models/gemma-4-31B-it

11.2 Gemma 4 图像理解

source/root/gemma4/.venv/bin/activate python /root/gemma4/run_gemma4_image.py\--model/root/models/gemma-4-31B-it\--image/path/to/test.png\--prompt"描述这张图"

11.3 PaliGemma 2 检测并返图

source/root/gemma4/.venv/bin/activateCUDA_VISIBLE_DEVICES=1python /root/paligemma2/detect_and_draw.py\--model/root/models/paligemma2-28b-mix-448\--image/root/gemma4/data/R-C.png\--objectbuilding\--output/root/gemma4/data/R-C.detected.png\--json-output /root/gemma4/data/R-C.detected.json\--load-in-4bit

11.4 Ollama 服务

CUDA_VISIBLE_DEVICES=1OLLAMA_HOST=0.0.0.0:11434 ollama serve

11.5 拉取 Gemma 4 最大版

ollama pull gemma4:31b

11.6 Open WebUI 连接当前 WSL 内 Ollama

dockerrm-fopen-webuidockerrun-d\-p3000:8080\-eOLLAMA_BASE_URL=http://当前WSL_IP:11434\-vopen-webui:/app/backend/data\--nameopen-webui\--restartalways\ghcr.io/open-webui/open-webui:main

12. 经验总结

这次过程里最重要的经验有五条：

1. 大模型下载一定要能做完整性校验。
   “目录看起来很大”不等于模型完整，必须检查 index、分片数量、文件大小。

2. 断点续传优先于重头再下。
   尤其是 PaliGemma 2 这种 50GB+ 体量模型，优先删损坏分片再续传。

3. WSL + Docker Desktop 环境下不要轻信host.docker.internal。
   它很可能连到另一套宿主服务，而不是当前 WSL 的本地服务。

4. Gemma 4 和 PaliGemma 2 的定位不同。

   • Gemma 4：更适合图文理解与交互式问答
   • PaliGemma 2：更适合检测/分割类视觉任务原型

5. 交互式聊天和结构化检测最好拆成两套入口。

   • Ollama + Open WebUI适合聊天
   • PaliGemma 2 + 自定义脚本/服务适合返图、返 JSON、后续矢量化

13. 后续建议

如果后续继续往业务化推进，建议优先做：

1. 给PaliGemma 2检测脚本增加：

   • 多类别一次检测
   • 不同颜色绘制
   • 批量处理目录

2. 将检测结果与地理信息绑定：

   • 保留切片时的仿射变换和 CRS
   • 后续可回写矢量坐标

3. 将PaliGemma 2包成简单 Web 服务：

   • FastAPI
   • Gradio
   • 统一上传图片 -> 返回检测图/JSON

4. 如果需要精确边界与矢量结果，改成：

   • PaliGemma 2做对象提示
   • SAM2/samgeo做分割
   • GDAL polygonize做矢量化

14. 本文档位置

/root/codexfile/gemma_paligemma_ollama_openwebui_recap_2026-04-20.md