GLM-4.6V-Flash-WEB 部署与常见问题排查指南

1.3 检查端口 7860 是否被占用

镜像默认绑定 0.0.0.0:7860。若宿主机已有其他服务（如旧版 Stable Diffusion WebUI、JupyterLab）占用了 7860，新服务将无法绑定，日志中会出现 OSError: [Errno 98] Address already in use，但脚本不会主动提示。

排查命令：
在 Jupyter 终端中运行：

lsof -i :7860 # 或（若 lsof 不可用）netstat -tuln | grep :7860

若返回非空结果，说明端口被占。临时解决方案：
编辑 /root/1 键推理.sh，将最后一行 python webui.py改为：

python webui.py --port 7861

然后重新运行脚本，并通过 http://<你的实例 IP>:7861访问。

2. 网页能打开，但上传图片就报错？重点排查文件路径与格式

网页界面加载成功，说明 Web 服务已跑通。但一上传图片就弹窗报错'Error: Unsupported image format'或控制台显示 PIL.UnidentifiedImageError——这几乎 100% 是图像预处理环节的问题，而非模型本身。

2.1 不是所有'.jpg'都是合法 JPG

GLM-4.6V-Flash-WEB 底层使用 PIL（Pillow）解码图像。某些手机截图、微信转发图、甚至 PS 导出的'JPG'实际是 JPEG-XR、HEIC 封装或带非标准 EXIF 头的变体。PIL 无法识别，直接抛异常。

验证方法：
将出问题的图片下载到本地，用命令行检查：

file your_image.jpg # 正常应输出：your_image.jpg: JPEG image data, JFIF standard 1.01
# 若输出包含 "HEIC", "PNG", "WebP" 或 "data"，则非标准 JPG

通用修复方案（无需重装）：
在 Jupyter 中运行以下代码，批量转为标准 RGB JPG：

from PIL import Image
import os

def safe_convert_to_jpg(input_path, output_path):
    try:
        img = Image.open(input_path)
        # 强制转换为 RGB（处理 RGBA/CMYK 等）
        if img.mode in ("RGBA", "LA", "P"):
            background = Image.new("RGB", img.size, (255, 255, 255))
            background.paste(img, mask=img.split()[-1] if img.mode == "RGBA" else None)
            img = background
        elif img.mode != "RGB":
            img = img.convert("RGB")
        img.save(output_path, "JPEG", quality=95)
        print(f"✓ 已转换：{input_path} -> {output_path}")
    except Exception as e:
        print(f"✗ 转换失败 {input_path}: {e}")

# 示例：转换当前目录下所有非 JPG 文件
for f in os.listdir("."):
    if not f.lower().endswith(('.jpg', '.jpeg')):
        safe_convert_to_jpg(f, f.rsplit('.', 1)[0] + ".jpg")

2.2 图片路径含中文或空格？WebUI 会静默失败

镜像中的 WebUI 组件对 URL 编码支持不完善。当上传文件名含中文、空格、括号（如 我的截图 (1).png）时，前端生成的临时路径可能被截断，后端收到空路径，触发 FileNotFoundError。

规避方法：

• 上传前，将文件重命名为纯英文 + 数字（如 test_img_01.jpg）
• 或使用 API 方式绕过 WebUI 限制（见第 4 节）

3. API 调用返回 500 或空响应？检查请求体结构与 Content-Type

镜像同时提供 WebUI 和 API 接口（POST /api/chat），但 API 对请求格式极其严格。一个常见的错误是：用 Postman 或 curl 发送 JSON，却忘记设置 Content-Type: application/json，或把图片 Base64 字符串放在了错误字段。

3.1 正确的 API 请求结构

API 要求 multipart/form-data 格式（非 JSON），必须包含两个字段：

❌ 错误示例（application/json）：

{
 "image": "/9j/4AAQSkZJRgABAQAAA...",
 "prompt": "描述这张图"
}

正确 curl 命令：

curl -X POST "http://<你的 IP>:7860/api/chat" \
 -F "image=@/path/to/your/image.jpg" \
 -F "prompt=这张图里有几只猫？"

3.2 API 响应为空？检查模型是否完成加载

首次 API 调用时，若模型尚未加载完毕，服务会返回 HTTP 200 但 body 为空字符串。这不是错误，而是'正在加载中'的静默状态。等待 10-20 秒后重试即可。

主动确认加载状态：
访问 http://<你的 IP>:7860/api/status，正常返回：

{"status":"ready","model_name":"GLM-4.6V-Flash-WEB","device":"cuda:0"}

若返回 {"status":"loading"}，请耐心等待。

4. 想批量处理？别硬改 WebUI，用内置 CLI 更稳

WebUI 设计为单次交互，强行修改前端实现批量上传极易引发内存溢出（尤其处理百张图时）。镜像其实内置了稳定可靠的命令行工具 glm_vision_cli.py，专为批量场景优化。

4.1 CLI 基础用法（支持文件夹/URL/CSV）

进入 Jupyter 终端，执行：

# 处理整个文件夹（自动跳过非图片文件）
python /root/glm_vision_cli.py --input_dir ./my_images --prompt "提取图中所有文字"

# 处理 URL 列表（每行一个图片 URL）
echo -e "https://example.com/1.jpg\nhttps://example.com/2.png" > urls.txt
python /root/glm_vision_cli.py --input_urls urls.txt --prompt "描述场景"

# 输出为 CSV，含原始文件名与结果
python /root/glm_vision_cli.py --input_dir ./imgs --prompt "识别商品名称" --output_csv results.csv

4.2 关键参数说明（避坑必看）

推荐生产命令（T4 + 800×600 图）：

python /root/glm_vision_cli.py \
 --input_dir ./batch_input \
 --prompt "请用中文列出图中所有可见文字，用分号隔开" \
 --batch_size 4 \
 --max_new_tokens 64 \
 --output_csv ./batch_output.csv

5. 其他高频问题速查表

以下问题出现频率高，但原因单一，按表排查可 5 分钟内解决：

6. 总结：踩坑的本质，是理解它的'工程诚实'

GLM-4.6V-Flash-WEB 没有隐藏复杂性，它把选择权交给了你：

• 它不自动降级到 CPU，因为那会误导你对性能的判断；
• 它不强行转码所有图片，因为那会掩盖数据质量问题；
• 它不封装所有 API 为 JSON，因为 multipart 才是图像服务的事实标准。

所谓'踩坑'，不过是这套系统在用最直接的方式告诉你：'这里需要你确认一下'。每一次报错，都对应一个真实的工程约束——显存边界、文件规范、协议标准。避开它们，不是靠玄学重启，而是靠精准定位：是驱动？是路径？是格式？还是并发？

当你把 lsof -i :7860、file xxx.jpg、curl -F变成肌肉记忆，那些曾让你皱眉的报错，就会变成一行行可预测、可解决的日志。而这，正是从'能跑起来'迈向'跑得稳、跑得久'的真正起点。