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 -m venv /root/gemma4/.venv
source /root/gemma4/.venv/bin/activate
pip install -U pip setuptools wheel
pip install -U torch 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 \
  --model google/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=1 python /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/activate
HF_TOKEN=你的token HF_ENDPOINT=https://hf-mirror.com \
python /root/paligemma2/download_paligemma2.py \
  --model google/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/activate
HF_TOKEN=你的token HF_ENDPOINT=https://hf-mirror.com \
python /root/paligemma2/download_paligemma2.py \
  --model google/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/activate
CUDA_VISIBLE_DEVICES=1 python /root/paligemma2/detect_and_draw.py \
  --model /root/models/paligemma2-28b-mix-448 \
  --image /root/gemma4/data/R-C.png \
  --object building \
  --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 -fsSL https://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 -I zstd -C /usr/local -xvf /root/Downloads/ollama-linux-amd64.tar.zst

验证：

/usr/local/bin/ollama --version

实际版本：

0.21.0

8. 用第二块显卡启动 Ollama

只使用第二块显卡启动：

CUDA_VISIBLE_DEVICES=1 OLLAMA_HOST=0.0.0.0:11434 ollama serve

后台方式：

nohup bash -lc 'CUDA_VISIBLE_DEVICES=1 OLLAMA_HOST=0.0.0.0:11434 /usr/local/bin/ollama serve' > /root/ollama.log 2>&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 镜像拉取

最终拉取官方镜像：

docker pull ghcr.io/open-webui/open-webui:main

9.3 第一次启动的问题

最开始使用的是：

docker run -d \
  --network=host \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://127.0.0.1:11434 \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

问题：

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

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

9.4 重建为端口映射模式

改成：

docker rm -f open-webui

docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  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

然后重建容器：

docker rm -f open-webui

docker run -d \
  -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://172.19.2.83:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  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/activate
CUDA_VISIBLE_DEVICES=1 python /root/paligemma2/detect_and_draw.py \
  --model /root/models/paligemma2-28b-mix-448 \
  --image /root/gemma4/data/R-C.png \
  --object building \
  --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=1 OLLAMA_HOST=0.0.0.0:11434 ollama serve

11.5 拉取 Gemma 4 最大版

ollama pull gemma4:31b

11.6 Open WebUI 连接当前 WSL 内 Ollama

docker rm -f open-webui

docker run -d \
  -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://当前WSL_IP:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  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
# 深度学习 # 数据挖掘 # 大数据 # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

Python第三方库：Click

avatar AtomGit开源社区

AI生成代码的合规、版权与漏洞治理（传统IT转型专项课题）

《传统IT转型中AI生成代码的合规治理体系研究》 针对传统IT研发引入AI编码工具面临的版权、合规与安全风险，本文构建了一套全流程治理体系。核心风险包括：AI生成代码存在版权归属模糊、开源协议冲突、隐性漏洞及合规流程缺失等问题。解决方案涵盖三大维度：1）版权治理，通过权属规则制定、开源代码比对和全流程溯源；2）合规闭环，从Prompt管控、代码审核到归档审计；3）漏洞防控，结合安全约束Prompt

avatar AtomGit开源社区
cover

【Embodiment Gap in Robot Learning: A Comprehensive Survey】

avatar AtomGit开源社区