多模态理解

多模态理解（Multimodal Understanding）允许模型在同一次对话中接收文本之外的输入——图片、视频、文件等，并基于这些内容回答问题。常见场景：图片描述、截图问答、视频摘要、文档抽取、OCR 识别等。

与图片生成的区别

• 多模态理解（本文）：输入图片/视频/文件，模型输出文本。
• 图片生成：输入文本描述，模型输出图片，详见图片生成。

支持的模型

各模型支持的多模态输入类型，见可用模型列表中的「图片 / 视频 / 文件」三列。该页同时给出各厂商官方文档索引，本文不再重复维护对照表。

常用多模态模型速查：

模型	可接受的输入
glm-5.3-flash、glm-5.3-flashx	图片、视频、文件
kimi-k3、kimi-k2.8-preview、kimi-k2.7-code、kimi-k2.7-code-highspeed、kimi-k2.6	图片、视频
minimax-m3.1-flash、minimax-m3、mimo-v2.6-pro、mimo-v2.6-flash、step-5-preview	图片、文本、视频
hy-vision-2.0-instruct、hunyuan-t1-vision-20250916	仅图片
hunyuan-turbos-vision-video-20250728	仅视频

备注

• 上表只列常用模型，完整对照与各厂商官方文档索引见可用模型列表。
• 纯文本模型（如 deepseek-v4-pro、glm-5.3、hy3）在调用时传入图片/视频会被忽略或报错。

模型差异要点

• 传入方式：图片和视频可用 URL 直链、Base64 或厂商 Files API 传入，各厂商支持程度不同，具体以厂商官方文档为准。
• 视频限制：视频通常只接受公网可访问的 URL，部分厂商不支持以 Base64 传视频，且视频处理耗时较长。
• 文件支持：目前仅 glm-5.3-flash、glm-5.3-flashx 支持 PDF / TXT / DOC 等文档输入，且只能通过 URL 传入。
• 混合限制：glm-5.3-flash / glm-5.3-flashx 不允许在同一请求中同时传入图片、视频、文件三类不同媒体——需要拆分为多次调用。
• 图片大小：Base64 形式建议单张不超过 5 MB。URL 形式需保证图片可被服务端访问（公网直链）。

消息格式

多模态请求遵循 OpenAI Chat Completions 标准协议：将 messages[n].content 由字符串改为对象数组，每个对象表示一段内容（文本、图片、视频或文件）。

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: { url: string } }
  | { type: "video_url"; video_url: { url: string } }
  | { type: "file"; file: { file_url: string } };

文本块

{ type: "text", text: "请描述这张图片的内容" }

图片块

URL 直链：

{
  type: "image_url",
  image_url: { url: "https://example.com/photo.jpg" }
}

Base64：

const fs = require("fs");
const base64 = fs.readFileSync("./photo.jpg").toString("base64");

{
  type: "image_url",
  image_url: { url: `data:image/jpeg;base64,${base64}` }
}

视频块

{
  type: "video_url",
  video_url: { url: "https://example.com/clip.mp4" }
}

文件块（仅 glm-5.3-flash / glm-5.3-flashx）

{
  type: "file",
  file: { file_url: "https://example.com/contract.pdf" }
}

使用方式

图片理解

CloudBase SDK

const model = ai.createModel("cloudbase");

const res = await model.generateText({
  model: "glm-5.3-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "这张图里有几只猫？颜色分别是什么？" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/cats.jpg" }
        }
      ]
    }
  ]
});

console.log(res.text);

OpenAI SDK

const OpenAI = require("openai");

const client = new OpenAI({
  apiKey: "<YOUR_API_KEY>",
  baseURL: "https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase"
});

const completion = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "这张图里有几只猫？颜色分别是什么？" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/cats.jpg" }
        }
      ]
    }
  ]
});

console.log(completion.choices[0].message.content);

小程序

const model = wx.cloud.extend.AI.createModel("cloudbase");

const res = await model.generateText({
  data: {
    model: "glm-5.3-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "这张图里有几只猫？颜色分别是什么？" },
          {
            type: "image_url",
            image_url: { url: "https://example.com/cats.jpg" }
          }
        ]
      }
    ]
  }
});

console.log(res.text);

cURL

curl -X POST 'https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "这张图里有几只猫？颜色分别是什么？"},
          {"type": "image_url", "image_url": {"url": "https://example.com/cats.jpg"}}
        ]
      }
    ]
  }'

使用 Base64 传入本地图片

适用于图片不在公网或不便上传的场景：

const fs = require("fs");
const path = require("path");

const filePath = path.resolve(__dirname, "./local.jpg");
const base64 = fs.readFileSync(filePath).toString("base64");
const dataUrl = `data:image/jpeg;base64,${base64}`;

const model = ai.createModel("cloudbase");

const res = await model.generateText({
  model: "kimi-k2.6",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "提取图片中的文字" },
        { type: "image_url", image_url: { url: dataUrl } }
      ]
    }
  ]
});

console.log(res.text);

在小程序/Web 端获取 Base64

• 小程序：wx.getFileSystemManager().readFile({ filePath, encoding: "base64" })
• Web：通过 FileReader.readAsDataURL 拿到完整的 data:image/...;base64,... 字符串。

多图同时输入

将多个 image_url 块依次放入 content 数组即可：

const res = await model.generateText({
  model: "glm-5.3-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "对比下面两张图，说出 3 处差异" },
        { type: "image_url", image_url: { url: "https://example.com/before.jpg" } },
        { type: "image_url", image_url: { url: "https://example.com/after.jpg" } }
      ]
    }
  ]
});

视频理解

视频仅支持公网 URL，且模型必须支持视频输入（如 glm-5.3-flash、kimi-k2.6）：

const model = ai.createModel("cloudbase");

const res = await model.generateText({
  model: "kimi-k2.6",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "用 100 字总结这段视频的内容" },
        {
          type: "video_url",
          video_url: { url: "https://example.com/clip.mp4" }
        }
      ]
    }
  ]
});

console.log(res.text);

备注

视频处理耗时较长，建议配合流式输出使用，避免请求超时。

文件理解（PDF/文本）

仅 glm-5.3-flash / glm-5.3-flashx 支持，且只能通过 URL：

const res = await model.generateText({
  model: "glm-5.3-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "总结这份合同的核心条款，并列出风险点" },
        {
          type: "file",
          file: { file_url: "https://example.com/contract.pdf" }
        }
      ]
    }
  ]
});

注意

glm-5.3-flash / glm-5.3-flashx 不允许在同一请求中同时传入图片、视频、文件三类——需要分别调用。

与流式输出结合

多模态请求往往响应较慢，推荐配合流式输出使用：

const res = await model.streamText({
  model: "glm-5.3-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "详细描述这张图的构图和色彩" },
        { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } }
      ]
    }
  ]
});

for await (const text of res.textStream) {
  process.stdout.write(text);
}

更多用法参考流式输出。

与深度思考结合

部分模型支持在多模态输入上启用深度思考，适合"看图做数学题"、"图表分析"等任务：

const res = await model.generateText({
  model: "glm-5.3-flash",
  reasoning_effort: "high",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "图中函数图像对应哪个表达式？给出推导过程" },
        { type: "image_url", image_url: { url: "https://example.com/chart.png" } }
      ]
    }
  ]
});

const raw = res.rawResponses[0].choices[0].message;
console.log("思考过程:", raw.reasoning_content);
console.log("最终回答:", res.text);

参考深度思考了解 reasoning_effort 用法和模型差异。

多轮对话中的多模态消息

多模态消息可以正常出现在历史 messages 中，但要注意：

• 图片 URL 长期有效性：若图片来自临时签名 URL，过期后历史消息会失效，建议改用 Base64 或对象存储永久链接。
• Token 成本：图片在编码后会占用相当于数百到数千 token，长对话务必使用上下文管理裁剪历史。
• 角色限制：仅 user 角色支持数组形式的 content，assistant 回复仍以纯文本为主。

const messages = [
  {
    role: "user",
    content: [
      { type: "text", text: "图里是哪种花？" },
      { type: "image_url", image_url: { url: "https://example.com/flower.jpg" } }
    ]
  },
  { role: "assistant", content: "这是一朵向日葵。" },
  { role: "user", content: "它的花期一般是几月？" }
];

const res = await model.generateText({ model: "glm-5.3-flash", messages });

常见问题

报错 "model does not support image input"

模型不支持多模态。请改用上方支持的模型列表中的模型。

图片传 URL 时模型说"看不到图片"

• 检查 URL 是否公网可访问、是否需要鉴权（签名 URL 注意有效期）。
• 国外模型有时无法访问国内域名，建议把图片放到云开发文件存储并使用其下载链接。
• 部分模型（如月之暗面系列）只接受 Base64 或文件 ID 引用，公网 URL 会被拒绝。

视频识别效果不理想

• 视频时长越短、画面越清晰，效果越好。建议先用工具压缩到 30 秒内、分辨率 720p 左右。
• 复杂视频可先抽帧成多张图片，作为多图输入也是可行方案。

如何控制图片清晰度（detail 参数）

部分模型支持 image_url.detail（low / high / auto）控制图像分析精度。low 更省 token 但识别能力弱，high 反之。是否生效以具体模型为准。