多模态理解

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

与图片生成的区别

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

支持的模型

不同模型在多模态能力上差异较大，下表对比常用模型：

模型	图片输入	视频输入	文件输入	备注
`glm-5v-turbo`	✅ URL / Base64	✅ URL	✅ URL（PDF/TXT/DOC）	图、视频、文件不可在同一请求中混传
`qwen3.5-plus`	✅ URL / Base64	✅ URL	—	默认开启思考，可与 `enable_thinking` 配合
`kimi-k2.6`	✅ URL / Base64	✅ URL	—	Kimi 系列中唯一支持视频的模型
`kimi-k2.5`	✅ URL / Base64	—	—	不支持视频
`kimi-k2.7-code`	✅ 仅 Base64	—	—	编码专用，URL 形式不支持

备注

表格仅列出常见多模态模型，完整列表请参考接入大模型中的模型说明。
不支持多模态的文本模型（如 deepseek-v4-flash、hy3）调用时若传入图片/视频，会被忽略或报错。

模型差异要点

图片传入方式：除 kimi-k2.7-code 仅支持 Base64 外，其他模型均同时支持 URL 直链和 Base64。
视频支持：glm-5v-turbo、qwen3.5-plus、kimi-k2.6 三家支持，且仅接受公网可访问的视频 URL（不支持 Base64）。
文件支持：目前仅 glm-5v-turbo 支持 PDF/TXT/DOC，且只能通过 URL 传入。
混合限制：glm-5v-turbo 不允许在同一请求中同时传入图片、视频、文件三类不同媒体——需要拆分为多次调用。
图片大小：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-5v-turbo`）

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

使用方式

图片理解

CloudBase SDK
OpenAI SDK
小程序
cURL

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

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

console.log(res.text);

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-5v-turbo",
  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-5v-turbo",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "这张图里有几只猫？颜色分别是什么？" },
          {
            type: "image_url",
            image_url: { url: "https://example.com/cats.jpg" }
          }
        ]
      }
    ]
  }
});

console.log(res.text);

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-5v-turbo",
    "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-5v-turbo",
  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-5v-turbo / qwen3.5-plus / 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-5v-turbo 支持，且只能通过 URL：

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

注意

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

与流式输出结合

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

const res = await model.streamText({
  model: "glm-5v-turbo",
  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: "qwen3.5-plus",
  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-5v-turbo", messages });

常见问题

报错 "model does not support image input"

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

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

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

视频识别效果不理想

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

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

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

支持的模型​

模型差异要点​

消息格式​

文本块​

图片块​

视频块​

文件块（仅 glm-5v-turbo）​

使用方式​

图片理解​

使用 Base64 传入本地图片​

多图同时输入​

视频理解​

文件理解（PDF/文本）​

与流式输出结合​

与深度思考结合​

多轮对话中的多模态消息​

常见问题​

报错 "model does not support image input"​

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

视频识别效果不理想​

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