MedGemma-1.5-4B 实战：医学影像多模态理解与 Web 集成

如果报错 ModuleNotFoundError: No module named 'medgemma'，说明你还没获得访问权限，或安装的是第三方同名包——请务必卸载 pip uninstall medgemma 后重试官方渠道。

2.3 模型加载与显存优化技巧

MedGemma-1.5-4B 原始权重约 8GB（FP16），在单张 24GB 显卡（如 RTX 4090 / A100）上可全精度运行，但如果你只有 12GB 卡（如 3090），必须启用量化。

我们实测最稳的方案是 4-bit 量化 + Flash Attention 2：

from transformers import BitsAndBytesConfig
import torch

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

model = MedGemmaForConditionalGeneration.from_pretrained(
    "google/medgemma-1.5-4b", # 注意：这是 Hugging Face 上的占位标识，实际权重由 SDK 自动挂载
    quantization_config=bnb_config,
    device_map="auto",
    torch_dtype=torch.bfloat16,
)
processor = MedGemmaProcessor.from_pretrained("google/medgemma-1.5-4b")

关键提示：from_pretrained 中传入的 "google/medgemma-1.5-4b" 并非从 HF 下载，而是触发 SDK 内部逻辑，自动连接你已获授权的 gs:// 路径。首次运行会自动拉取，耗时约 3–5 分钟（取决于网络）。

3. 第一次推理：三行代码让模型'看懂'一张 X 光片

别被'多模态'吓住。对 MedGemma-1.5-4B 来说，'看图说话'的本质就是：把图像转成视觉 token，把文字转成文本 token，然后一起喂给模型。

我们用一张公开的胸部 X 光片（来自 NIH ChestX-ray14 数据集）来演示。你也可以换成自己手边任意 PNG/JPG 格式医学影像。

3.1 准备输入：一张图 + 一句话

from PIL import Image
import requests

# 示例：加载一张标准胸部 X 光片（你可替换为本地路径）
image_url = "https://raw.githubusercontent.com/mlmed/torchxrayvision/master/torchxrayvision/datasets/samples/00000001_000.png"
image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")

# 提出一个具体问题（中文！MedGemma-1.5-4b 原生支持中文指令）
question = "请描述这张 X 光片的主要解剖结构，并指出是否有明显异常区域？"

3.2 编码与推理：两步到位

# 1. 处理图像 + 文本，生成模型输入
inputs = processor(images=image, text=question, return_tensors="pt").to(model.device)

# 2. 模型生成回答（设置 max_new_tokens 防止无限输出）
output = model.generate(
    **inputs,
    max_new_tokens=256,
    do_sample=False, # 关闭采样，保证结果稳定可复现
    num_beams=1,     # 贪心搜索，最快最确定
    temperature=0.0  # 温度设为 0，避免'发挥过度'
)

# 3. 解码并打印结果
response = processor.decode(output[0], skip_special_tokens=True)
print(" 模型回答：\n" + response)

你将看到类似这样的输出：

这是一张标准后前位（PA）胸部 X 光片。可见双侧肺野透亮度基本对称，肺纹理清晰，未见明显渗出、实变或结节影。纵隔居中，心影大小及形态在正常范围内。膈肌光滑，肋膈角锐利。骨骼结构显示良好，胸椎序列自然。整体未见明确急性病理征象，建议结合临床及其他检查综合评估。

你会发现：它没说'正常'，也没下诊断，而是用'未见明确急性病理征象'这样严谨的放射科表述；它提到了'PA 位'、'肺纹理'、'肋膈角'等专业术语，但上下文解释清楚；它甚至主动加了'建议结合临床……'的免责提示——这正是 MedGemma 医学特性的体现。

3.3 中文提问避坑指南（血泪经验）

• 避免模糊提问：'这张图怎么了？' → 模型无法聚焦
• 改为具体指向：'左肺下叶是否存在磨玻璃影？' 或 '气管是否居中？主支气管开口是否对称？'
• 避免长段落输入：MedGemma 对输入文本长度敏感，单次提问建议 ≤ 60 字
• 如需多轮追问，用 Gradio 的 state 保存历史，而非拼接进新 prompt
• 不要混用中英文术语：'pleural effusion（胸腔积液）' → 中文模型对括号内英文识别不稳定
• 统一用纯中文：'胸腔是否有积液？'

4. 构建 Web 界面：Gradio 三步封装，10 分钟上线

有了单图推理能力，下一步就是把它变成一个'谁都能用'的 Web 工具。我们选用 Gradio —— 它轻量、启动快、UI 可定制，且对多模态输入原生友好。

4.1 核心界面逻辑：上传 + 提问 + 输出

我们不追求花哨动画，只做三件事： ① 用户拖拽上传一张医学影像（支持 X-Ray/CT/MRI） ② 输入中文问题（带默认示例） ③ 实时显示模型分析结果（带加载状态与错误提示）

import gradio as gr
from PIL import Image

def analyze_medical_image(image: Image.Image, question: str):
    if image is None:
        return " 请先上传一张医学影像（PNG/JPG）"
    if not question.strip():
        return " 请输入您的问题，例如：'这张 CT 中肝脏轮廓是否清晰？'"
    try:
        # 复用前面的 processor & model
        inputs = processor(images=image, text=question, return_tensors="pt").to(model.device)
        output = model.generate(
            **inputs,
            max_new_tokens=320,
            do_sample=False,
            num_beams=1,
            temperature=0.0
        )
        result = processor.decode(output[0], skip_special_tokens=True)
        return result
    except Exception as e:
        return f" 推理失败：{str(e)[:100]}..."

# 构建界面
demo = gr.Interface(
    fn=analyze_medical_image,
    inputs=[
        gr.Image(type="pil", label="上传医学影像（X-Ray / CT / MRI）", height=400),
        gr.Textbox(
            label="提出您的问题（中文）",
            placeholder="例如：这张 MRI 中胼胝体形态是否对称？",
            lines=2
        )
    ],
    outputs=gr.Textbox(label="AI 影像分析结果", lines=8),
    title="🩺 MedGemma Medical Vision Lab —— 医学影像多模态理解助手",
    description="基于 Google MedGemma-1.5-4B 多模态大模型 | 仅用于科研与教学演示，不可替代临床诊断",
    theme=gr.themes.Soft(primary_hue="emerald"),
    allow_flagging="never" # 教学场景无需收集用户反馈
)

4.2 启动服务与性能调优

运行 demo.launch(server_name="0.0.0.0", server_port=7860) 后，打开 http://localhost:7860 即可使用。

但默认配置在医学影像场景下容易卡顿。我们做了三项关键优化：

1. 图像预处理缓存：Gradio 每次上传都会重新 decode 图像。我们在 analyze_medical_image 开头加入尺寸校验与缩放（保持长宽比，最长边 ≤ 1024px），避免超大 DICOM 转 JPG 后爆内存。
2. GPU 批处理禁用：MedGemma 当前不支持 batch inference（多图并行）。强行开启会导致 OOM。因此 batch=False（Gradio 默认），确保每次只处理一张。
3. 显存释放策略：在函数末尾添加 torch.cuda.empty_cache()，防止多次请求后显存缓慢泄漏。

完整优化版函数开头如下：

def analyze_medical_image(image: Image.Image, question: str):
    torch.cuda.empty_cache() # 关键！防显存累积
    if image.width > 1024 or image.height > 1024:
        ratio = min(1024 / image.width, 1024 / image.height)
        new_size = (int(image.width * ratio), int(image.height * ratio))
        image = image.resize(new_size, Image.LANCZOS)
    # ... 后续不变

4.3 界面增强：更贴近医疗工作流

基础版够用，但教学演示时，你可能希望它'看起来更专业'。我们增加了两个实用功能：

• 预设问题模板：在输入框下方加一组按钮，点击即填入典型问题
• 结果高亮关键词：用正则匹配'未见'、'可见'、'建议'、'考虑'等放射科高频词，加粗显示

with gr.Blocks() as demo:
    gr.Markdown("## 🩺 MedGemma Medical Vision Lab")
    with gr.Row():
        with gr.Column():
            img_input = gr.Image(type="pil", label="上传医学影像")
            question_input = gr.Textbox(label="您的问题", placeholder="...")
            # 预设问题按钮组
            with gr.Row():
                gr.Button(" 描述整体结构").click(
                    lambda: "请描述这张影像的主要解剖结构和整体观感。", None, question_input
                )
                gr.Button(" 异常识别").click(
                    lambda: "请指出影像中是否存在异常密度、轮廓变形或信号改变区域。", None, question_input
                )
        with gr.Column():
            result_output = gr.Textbox(label="AI 分析结果", lines=10)
            # 绑定事件
            img_input.change(analyze_medical_image, [img_input, question_input], result_output)
            question_input.submit(analyze_medical_image, [img_input, question_input], result_output)

启动后，界面清爽、操作直观、术语专业——完全可直接用于课堂演示或实验室开放日。

5. 实战注意事项：那些文档里不会写的细节

部署顺利不等于万事大吉。我们在真实测试中发现几个'不踩不知道，一踩就停摆'的细节，这里全部摊开讲：

5.1 图像格式陷阱：DICOM ≠ JPG/PNG

MedGemma 的 processor 只接受标准 RGB 图像（PIL.Image）。但医院最常用的是 DICOM 格式，它包含元数据、窗宽窗位、像素偏移等。直接 Image.open(dcm_file) 会报错。

正确做法：用 pydicom 读取 + matplotlib 或 opencv 调窗 + 转 RGB：

import pydicom
import numpy as np

def dcm_to_pil(dcm_path):
    ds = pydicom.dcmread(dcm_path)
    arr = ds.pixel_array
    # 应用窗宽窗位（以肺窗为例）
    window_center, window_width = 40, 400
    img_min = window_center - window_width // 2
    img_max = window_center + window_width // 2
    arr = np.clip(arr, img_min, img_max)
    arr = (arr - img_min) / (img_max - img_min) * 255
    arr = arr.astype(np.uint8)
    return Image.fromarray(arr).convert("RGB")

提示：Gradio 的 Image 组件不支持直接上传 .dcm 文件（浏览器限制），需前端 JS 转换或后端提供 .dcm 上传接口。教学场景建议提前转为 PNG。

5.2 中文 token 截断：为什么你的问题总被'吃掉'？

MedGemma-1.5-4B 的 tokenizer 对中文支持良好，但它的最大上下文长度是 4096 tokens。一张 1024×1024 的医学影像，经 vision encoder 后会生成约 256 个视觉 tokens；剩余 3840 tokens 给文本。看似充裕，但中文每个字≈1 token，60 字问题就占 60 tokens，再加 system prompt（约 120 tokens），留给思考的空间其实很紧。

解决方案：精简 system prompt。默认 prompt 包含大段英文指令，我们替换成极简中文：

# 替换 processor 的默认 prompt
processor.chat_template = "{% for message in messages %}{% if message['role'] == 'user' %}{{ '<image>' + message['content'] }}{% elif message['role'] == 'assistant' %}{{ message['content'] + '<eos>' }}{% endif %}{% endfor %}"

并在调用时显式传入：

inputs = processor(
    images=image,
    text=f"用户问题：{question}",
    return_tensors="pt"
)

5.3 GPU 利用率低？检查 Flash Attention 是否生效

运行 nvidia-smi 时如果发现 GPU-Util 长期 <30%，大概率是 Flash Attention 2 没启用成功。MedGemma 官方要求 flash-attn>=2.6.3，且必须用 pip install flash-attn --no-build-isolation 安装（否则编译失败）。

验证方法：运行后查看日志，应有 Using flash attention 字样。若无，降级到 flash-attn==2.5.8 通常可解决兼容性问题。

6. 总结：你已经拥有了一个可落地的医学多模态基座

回看整个过程，你完成的不只是'跑通一个模型'，而是构建了一个具备真实工程价值的医学 AI 小系统：

• 模型层：掌握了 MedGemma-1.5-4B 的正确加载、量化、中文提问范式
• 推理层：实现了图像 + 文本联合编码、可控生成、错误捕获与显存管理
• 应用层：封装了 Gradio Web 界面，支持上传、提问、结果展示，且做了医疗场景适配
• 避坑层：搞清了 DICOM 处理、中文 token 限制、Flash Attention 依赖等隐藏关卡

更重要的是，这个系统不是玩具。它能支撑： 🔹 研究者快速验证多模态模型在特定影像任务上的 baseline 能力 🔹 教师在课堂上实时演示'AI 如何理解医学图像'，破除黑箱神秘感 🔹 学生开展课程设计，比如扩展为'对比 MedGemma 与 LLaVA-Med 的异常识别差异'

它不替代医生，但能让医生、研究者、学生，第一次真正'对话'医学影像本身。

下一步，你可以： → 把 Gradio 换成 FastAPI + Vue，做成企业内网部署版 → 接入医院 PACS 系统（需 DICOM Web 网关） → 增加'相似病例检索'模块，用 CLIP 提取影像特征入库 → 尝试 LoRA 微调，让它更熟悉某类专科影像（如眼科 OCT）

路已经铺好，现在，轮到你上传第一张图，提出第一个问题了。