GLM 5.2 Vision API:图像理解、分析与多模态用例

GLM 5.2(模型 ID:glm-4-plus)不只是文本模型。它由 Zhipu AI 于 2025 年 5 月发布,自带完整的多模态支持 —— 意味着它可以在一次 API 调用中,与文本一起读取、描述和推理图像。对构建文档处理器、视觉问答工具或产品目录流水线的开发者来说,这打开了一个成本约为 GPT-4o Vision 三分之一的高性价比替代选项。

本教程覆盖图像输入的精确 API 格式、接受哪些图像类型、GLM 5.2 能可靠处理哪些视觉任务,以及一组面向真实多模态应用、可直接运行的 Python 示例。

如果你对模型的文本 API 还不熟,先看 GLM 5.2 API 集成指南 —— vision API 建立在同样的认证和 base_url 配置之上。

GLM 5.2 Vision 支持什么

写代码之前,先明确具体的边界:

图像输入格式: JPEG、PNG、WEBP 和 GIF(动图只取第一帧)
图像投递方式: base64 编码的 data URI,或公开可访问的 HTTPS URL
最大图像尺寸: 每张约 10 MB
每请求最大图像数: 单个 messages 数组里最多 10 张
上下文窗口: 1,048,576 tokens(1M),意味着你可以把丰富的文本提示词和多张图像搭配使用而不撞上限
支持的任务: 文档理解、图表读取、截图分析、视觉问答、OCR 相邻任务、产品图像描述

API 完全兼容 OpenAI。如果你有现成的 GPT-4o Vision 代码,迁移只需换 base_url 和 model 名称 —— 不需要新 SDK。

痛点:搞对精确的 API 格式

大多数开发者扫一眼文档就确认 GLM 5.2 支持 vision,然后撞墙 —— 因为精确的 message 结构不是总能配着可复制的 Python 清楚地展示出来。关键细节:图像输入要放进 content 数组,作为带 type: "image_url" 的对象 —— 不是一个顶层参数,也不是一个裸 URL 字符串。

图像和文本提示词住在同一个 content 数组里。数组内的顺序不影响输出质量,但把图像放在问题之前,呼应了人类展示视觉信息的习惯,也是常见惯例。下面是一个视觉请求的最小正确结构:

{
    "role": "user",
    "content": [
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/chart.png"
            }
        },
        {
            "type": "text",
            "text": "Describe what this chart shows."
        }
    ]
}

看到这个,剩下的自然就通了。下面看完整可运行的示例。

通过 URL 发送图像

最简单的方式是传一个公开的图像 URL。无需编码步骤 —— 只要确保 Zhipu 的服务器能访问到这个 URL(不要在认证、VPN 或 localhost 后面)。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-4-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
                    },
                },
                {
                    "type": "text",
                    "text": "Describe what you see in this image in detail.",
                },
            ],
        }
    ],
    max_tokens=512,
)

print(response.choices[0].message.content)

你可以从 Zhipu AI 开放平台获取 API key。如果想在投入集成之前交互式地验证模型的视觉输出,glm5.app 让你不写任何代码就能上传图像并跑提示词。base_url 必须像示例那样带结尾斜杠 —— 省略会导致路径路由错误。

通过 Base64 发送本地图像

对不公开托管的图像 —— CI 流水线的截图、磁盘上的文件、从视频抽出的帧 —— 把文件编码成 base64,作为 data URI 嵌入:

import os
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

def encode_image(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

image_path = "screenshot.png"
b64 = encode_image(image_path)

response = client.chat.completions.create(
    model="glm-4-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{b64}"
                    },
                },
                {
                    "type": "text",
                    "text": "What does this screenshot show? Identify any error messages.",
                },
            ],
        }
    ],
    max_tokens=1024,
)

print(response.choices[0].message.content)

data URI 前缀(data:image/png;base64,)必须与真实文件类型匹配。把 image/png 换成 image/jpeg 或 image/webp 以匹配你的文件。模型用这个提示正确解码负载。每张图像保持在 10 MB 以下 —— 大图会被直接拒绝,而不是静默截断。

多图像请求

GLM 5.2 每个请求最多接受 10 张图像。content 数组按顺序列出它们即可。这对对比任务、前后分析、文档页面或一连串 UI 截图很有用。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

image_urls = [
    "https://example.com/chart-q1.png",
    "https://example.com/chart-q2.png",
    "https://example.com/chart-q3.png",
]

content = []
for url in image_urls:
    content.append({
        "type": "image_url",
        "image_url": {"url": url},
    })

content.append({
    "type": "text",
    "text": (
        "These are three quarterly revenue charts. "
        "Identify which quarter shows the highest year-over-year growth "
        "and summarize the trend across all three."
    ),
})

response = client.chat.completions.create(
    model="glm-4-plus",
    messages=[{"role": "user", "content": content}],
    max_tokens=1024,
)

print(response.choices[0].message.content)

因为上下文窗口有 1M token,你在多张图像之外还有充足的余量放丰富的 system prompt —— 构建需要详细提取指令或 few-shot 示例的文档处理流水线时,这是一个实实在在的优势。

实用用例:JSON 模式发票提取

这个示例把 vision 和 JSON 模式结合起来,从发票图像中提取结构化字段。这是应付账款自动化里常用的模式。

import os
import json
import base64
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

def extract_invoice(image_path: str) -> dict:
    with open(image_path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode("utf-8")

    response = client.chat.completions.create(
        model="glm-4-plus",
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a document extraction assistant. "
                    "Return only valid JSON with these fields: "
                    "invoice_number, date, vendor_name, "
                    "total_amount, currency, line_items (array of "
                    "{description, quantity, unit_price, total})."
                ),
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "image_url",
                        "image_url": {"url": f"data:image/jpeg;base64,{b64}"},
                    },
                    {
                        "type": "text",
                        "text": "Extract all fields from this invoice.",
                    },
                ],
            },
        ],
        max_tokens=2048,
    )

    return json.loads(response.choices[0].message.content)

result = extract_invoice("invoice.jpg")
print(json.dumps(result, indent=2))

response_format={"type": "json_object"} 参数保证每次输出都可解析。按每百万输入 token $1.40 算,每月跑数万张发票的这个流水线,API 费用只是同样工作流在 GPT-4o Vision 上的一小部分。

流式视觉响应

对用户面对的应用,渐进式显示能提升感知性能,流式对视觉输入的工作方式与文本完全一样:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

stream = client.chat.completions.create(
    model="glm-4-plus",
    stream=True,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/architecture-diagram.png"},
                },
                {
                    "type": "text",
                    "text": "Walk me through this architecture diagram component by component.",
                },
            ],
        }
    ],
    max_tokens=1024,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
print()

按每秒 158 token(据 Artificial Analysis benchmark),GLM 5.2 的首 token 时间很快 —— 适合客户支持工具、实时 UI 调试工作流这类实时应用。

GLM 5.2 Vision 擅长什么

基于模型的 benchmark 画像(GPQA Diamond 89%、SWE-bench Pro 62.1%)和它 753B 总 / 40B 激活的 MoE 架构,视觉任务受益于一个真正能干的推理引擎,而不是一个轻量级看图模型。

文档与表单理解。 扫描 PDF 转成的图像、收据、发票和已填写的表单,处理准确率都很高。字段标签、手写内容和表格结构都处理得很好。

图表读取。 带轴标签和数值的柱状图、折线图、饼图和散点图都能被正确描述。模型能识别趋势、比较序列、报告近似值 —— 对自动化报告分析很有用。

截图分析。 Web 或桌面应用的 UI 截图理解得很好。模型能识别菜单项、表单字段、错误弹窗和布局结构 —— 对自动化 QA 流水线和无障碍描述生成很实用。

产品图像描述。 电商产品照片被详细描述,包括颜色、材质和推断的尺寸。结合批处理模式(Zhipu 平台提供),可以经济地扩展到大型目录运营。

视觉问答与通用场景理解。 物体识别、空间关系、图像中的文字(OCR 相邻)和通用场景描述都表现强劲。

模型可能落后的地方: 高度复杂的视觉推理 —— 杂乱场景中的细粒度计数、需要多跳逻辑的跨图像推理,或解读模糊、低质量的图像 —— 可能落后于 GPT-4o 的最佳表现。对大多数生产级文档和截图负载,差异不构成实际问题,但高风险场景请在你自己数据上跑 benchmark。

相对 GPT-4o Vision 的成本与上下文优势

对大规模跑视觉负载的团队来说,定价是实打实的因素。GLM 5.2 的定价是每百万输入 token $1.40、每百万输出 token $4.40 —— 大约是 GPT-4o Vision 的三分之一。1M 上下文窗口约为 GPT-4o 128K 的八倍,长文档工作流不再需要切块。

特性	GLM 5.2 (glm-4-plus)	GPT-4o(写作时)
输入价格	$1.40 / 1M tokens	约 $5.00 / 1M tokens
输出价格	$4.40 / 1M tokens	约 $15.00 / 1M tokens
上下文窗口	1,048,576 tokens	128,000 tokens
速度	158 tokens/sec	约 90–120 tokens/sec
图像输入	URL 或 base64	URL 或 base64
每请求最大图像数	最多 10 张	最多 10 张
GPQA Diamond	89%	约 88%
许可证	MIT 开放权重	专有

图像 token 计入输入 token 用量。一张典型的高分辨率文档页在 JPEG 压缩下,根据分辨率和内容密度消耗几百到几千个输入 token。按 GLM 5.2 的定价,每月处理 50,000 份文档的发票提取流水线,API 费用比等价的 GPT-4o 工作流便宜约 3 倍。

对有数据隐私需求的团队,MIT 开放权重许可证值得一提。权重在 HuggingFace 上可供自托管,这意味着图像输入在需要时可以完全留在本地。

生产环境中的边界情况处理

走出原型阶段后,有几个模式值得注意:

预先校验图像大小。 超过 10 MB 上限的图像会被 API 拒绝。加一个客户端检查,在调用端点前压缩或缩放。对文档页,1920×1080 标准 JPEG 质量远在上限之内。

私有图像用 base64。 URL 必须能从 Zhipu 的基础设施公开访问。任何在认证、VPN 或 IP 白名单后面的东西,都必须改用 base64 发送。

GIF 只取第一帧。 动图 GIF 只会处理第一帧。如果你需要分析视频帧,把它们逐帧提取出来,作为单独的 PNG 传进去。

system prompt 锚定输出格式。 对提取任务,带明确 JSON schema 预期的详细 system prompt 能大幅提升输出一致性。配合 response_format={"type": "json_object"} 保证响应可解析。

记录 usage.prompt_tokens。 每张图像都会计入你的输入 token 数。记录每个请求的用量,才能跟踪实际成本,并抓住悄悄溜过尺寸检查的超大图像。

下一步

GLM 5.2 的 vision API 紧密遵循 OpenAI 的 messages 格式,对已经在用 chat completions 的团队来说集成摩擦很小。关键点:图像以 image_url 对象放进 content 数组;本地或私有文件用 base64;每次调用最多批量 10 张图像;1M 上下文窗口给你充足空间,在图像之外放详细指令和 few-shot 示例。

在投入集成之前,先用你自己的图像测模型 —— glm5.app 提供交互式网页界面,你可以直接上传图像跑提示词 —— 这是写任何代码之前,快速验证 GLM 5.2 能否处理你特定文档类型或视觉任务的方式。

Sources

Zhipu AI 开放平台与 API 文档:https://open.bigmodel.cn
HuggingFace 上的 GLM-4 模型家族(MIT 权重):https://huggingface.co/THUDM/glm-4
Artificial Analysis GLM-4-Plus benchmark 条目:https://artificialanalysis.ai/models/glm-4-plus
Zhipu AI 定价页:https://open.bigmodel.cn/pricing