文档首页/ MaaS模型即服务/ 模型调用/ 图像理解
更新时间：2026-05-09 GMT+08:00
查看PDF
分享

图像理解

在多媒体内容处理领域，用户经常需要对图片或视频中的视觉信息进行分析和理解。然而，传统的处理方法往往需要复杂的图像处理技术和算法，这不仅增加了开发成本，也提高了技术门槛。部分大模型具备视觉理解能力，如当您传入图片或视频时，大模型可以理解图片或视频里的视觉信息，并结合这些信息完成如描述其中的物体等视觉相关任务。如何利用这些大模型简化多媒体内容的处理流程？

通过这篇教程，您可以学习到如何通过调用大模型API来识别传入图片和视频里的信息，从而降低开发成本和技术门槛。图像理解大模型支持单图或多图的输入，适用于图像描述、视觉问答、物体定位等多种任务，可用于自动化视频内容审核、智能监控分析等，大幅节省人工成本，适用于智能安防、体育赛事分析、媒体内容管理等领域。

计费说明

按Token计费：统计模型进行实时推理服务时消耗的Token数量，按Token数量付费。具体价格请以MaaS控制台为准。详情请见MaaS图像理解模型。

前提条件

  • 已在“模型推理 > 在线推理 > 预置服务”页签开通预置服务。详情请见开通MaaS预置服务。
  • （可选）如果需要控制服务调用流量，可提前创建自定义接入点，详情请参见MaaS创建自定义接入点。

支持模型

支持图像理解的模型请参见图像理解。

快速开始

支持图像理解的大模型当前支持在请求中传入图片的Base64编码内容，图片信息需要作为用户角色输入信息传给大模型，即“role”:“user”，下面是以qwen2.5-vl-72b模型为例，调用模型描述图像内容示例代码，输入图片转为Base64编码格式。

提示词支持图片和文字混排，但图文顺序可能对模型的输出效果产生影响。在提示词构成多张图片+1段文字，建议将文字放在提示词最后。

import base64
import httpx
from openai import OpenAI

base_url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址
api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key

#  图片转Base64编码格式
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

base64_image = encode_image("test.png")

client = OpenAI(api_key=api_key, base_url=base_url, http_client=httpx.Client(verify=False))

response = client.chat.completions.create(
    model = "qwen2.5-vl-72b", # model参数
    messages = [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "描述下图片里的内容"},
                {
                    "type": "image_url",
                    # 需要注意，Base64，图像格式（即image/{format}）需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
                    # PNG图像：  f"data:image/png;base64,{base64_image}"
                    # JPEG图像： f"data:image/jpeg;base64,{base64_image}"
                    # WEBP图像： f"data:image/webp;base64,{base64_image}"
                    "image_url": {
                        "url": f"data:image/png;base64,{base64_image}"
                    }
                }
            ]
        }
    ]
)

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

模型回复预览：

{
    "id": "chatcmpl-4e59963b1117f7fc23836254ef6cf238",
    "object": "chat.completion",
    "created": 1765193821,
    "model": "qwen2.5-vl-72b",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "reasoning_content": null,
                "content": "这张图片是一只可爱的柯基犬，它正坐在地上，舌头伸出来，看起来非常开心和友好。背景是户外的地面和一些绿色植物。",
                "tool_calls": []
            },
            "logprobs": null,
            "finish_reason": "stop",
            "stop_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 283,
        "total_tokens": 911,
        "completion_tokens": 628,
        "prompt_tokens_details": null
    },
    "prompt_logprobs": null,
    "kv_transfer_params": null
}
curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MAAS_API_KEY" \
  -d '{ 
    "model": "qwen2.5-vl-72b",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "描述下图片里的内容"},
          {"type": "image_url", "image_url": {"url": "data:image/png;base64,$BASE64_IMAGE"}}
        ]
      }
    ]
  }'

模型回复预览：

{
    "id": "chatcmpl-4e59963b1117f7fc23836254ef6cf238",
    "object": "chat.completion",
    "created": 1765193821,
    "model": "qwen2.5-vl-72b",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "reasoning_content": null,
                "content": "这张图片是一只可爱的柯基犬，它正坐在地上，舌头伸出来，看起来非常开心和友好。背景是户外的地面和一些绿色植物。",
                "tool_calls": []
            },
            "logprobs": null,
            "finish_reason": "stop",
            "stop_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 283,
        "total_tokens": 911,
        "completion_tokens": 628,
        "prompt_tokens_details": null
    },
    "prompt_logprobs": null,
    "kv_transfer_params": null
}

建议JDK版本为15+。

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Base64;
public class ImageDescriptionExample {
    public static void main(String[] args) throws Exception {
        // 接口地址
        String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
        String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key               
        String image_path = "test.png"; // test.png替换为真实的图片地址
        // 读取图片并转为 Base64
        String base64Image = encodeImageToBase64(image_path);
        String imageDataUrl = "data:image/png;base64," + base64Image;
        // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
        String modelName = "qwen2.5-vl-72b";
        // 构造请求体
        String requestBody = String.format(
                """
                    {
                        "model": "%s",
                        "messages": [
                            {"role": "user",
                            "content": [
                             {"type": "text", "text": "描述下图片里的内容"},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": "%s"
                                }
                            }
                            ]}
                        ]
                    }""", modelName, imageDataUrl);
        // 创建 HttpClient
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        // 创建请求
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + apiKey)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        try {
            // 发送请求并打印结果
            HttpResponse<String> response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            System.out.println("HTTP Status: " + response.statusCode());
            System.out.println("Response Body:\n" + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    /**
     * 将图片文件转换为 Base64 编码字符串
     */
    private static String encodeImageToBase64(String imagePath) throws IOException {
        byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
        return Base64.getEncoder().encodeToString(imageBytes);
    }
}

图像理解使用说明

处理完图片后，文件会从MaaS服务器删除。MaaS不会保留您提交的图片、视频和文本信息等用户数据来训练模型。

  • 图片传入方式

    将本地文件转换为Base64编码字符串，然后提交给大模型。

    如果您需要模型多次理解同一张图片，则每次请求时都需要传入该图片信息。

    1. 文件编码：将本地图像转换为Base64编码。
    2. 构建Data URL：格式如下：data:[MIME_Type];base64,{base64_image}。
      1. MIME_type需替换为实际的媒体类型，确保与图片格式说明表格中MIME Type的值匹配（如image/jpeg、image/png）。
      2. base64_image为上一步生成的Base64字符串。
    3. 调用模型：通过image或image_url参数传递Data URL并调用模型。
  • 图片文件容量

    以Base64编码形式上传图片，需确保编码后的图片小于10MB。

  • Token用量说明

    Token用量根据图片宽高像素计算可得。图片转化为Token的公式为：

    min（图片宽*图片高÷784，单图Token限制）

    例如：

    • 图片尺寸为1280px × 720px ，即宽为1280px，高为720px，传入模型图片Token限制为1312，则理解这张图消耗的Token为1280×720÷784=1176 ，因为小于1312，消耗Token数为1176。
    • 图片尺寸为1920px × 1080px ，即宽为1920 px，高为1080 px，传入模型图片Token限制为1312，则理解这张图消耗的Token为1920×1080÷784=2645 ，因为大于 1312，消耗Token数为 1312 。这时会压缩Token，即图片的细节会丢失部分，如字体很小的图片，模型可能就无法准确识别文字内容。

    https://clouddevops.huawei.com/domains/44229/wiki/5808/WIKI2025122300967待产品验证。

  • 图片格式说明

    支持的图片格式如下表，注意文件后缀匹配图片格式，即图片文件扩展名（URL传入时）、图片格式声明（Base64编码传入时）需与图片实际信息一致。

    • 支持的图像格式如下：
      表1 支持图片格式

      图像格式

      常见扩展名

      MIME Type

      BMP

      .bmp

      image/bmp

      JPEG

      .jpe, .jpeg, .jpg

      image/jpeg

      PNG

      .png

      image/png

      TIFF

      .tif, .tiff

      image/tiff

多图输入场景示例

API可以同时接收并处理多个图像输入，可以通过将这些图像内容转换为Base64编码后输入，模型将结合所有传入的图像和提示词信息来回答问题。

传入Base64编码格式图片时，格式遵循data:image/<图片格式>;base64,<Base64编码> ，其中：

  • 图片格式：jpeg、png、gif等，支持的图片格式详细见图片格式说明。
  • Base64编码：图片的Base64编码。

以下为多图输入的图像理解示例代码，可通过model参数替换模型，model参数详情请参见图像理解。

import base64
import httpx
from openai import OpenAI

base_url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址
api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key

client = OpenAI(api_key=api_key, base_url=base_url, http_client=httpx.Client(verify=False))

response = client.chat.completions.create(
    model = "qwen2.5-vl-72b", # model参数
    messages = [
        {
            "role": "user",
            "content": [{
                "type": "image_url",
                "image_url": {
                    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."
                }
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "data:image/png;base64,WmMnpZKr54yMyLu+pZKrIz...."
                }
             },
            {
                 "type": "text",
                 "text": "描述下图片里的内容"
             }]
         }
     ]
)

print(response.choices[0].message.content)
curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MAAS_API_KEY" \
  -d '{ 
    "model": "qwen2.5-vl-72b",
    "messages": [
      {
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAA...."}},
	    {"type": "image_url", "image_url": {"url": "data:image/png;base64,WmMnpZKr54yMyLu+pZKrIz....}},
            {"type": "text", "text": "描述下图片里的内容"}
        ]
      }
    ]
  }'

建议JDK版本为15+。

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Base64;
/**
 * 多图理解
 */
public class ImageDescriptionExample {
    public static void main(String[] args) throws Exception {
        // 接口地址
        String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
        String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key
        String image_path1 = "test1.png"; // test1.png替换为真实的图片地址
        String image_path2 = "test2.png"; // test2.png替换为真实的图片地址
        // 读取图片并转为 Base64
        String base64Image1 = encodeImageToBase64(image_path1);
        String base64Image2 = encodeImageToBase64(image_path2);
        String imageDataUrl1 = "data:image/png;base64," + base64Image1;
        String imageDataUrl2 = "data:image/png;base64," + base64Image2;
        // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
        String modelName = "qwen2.5-vl-72b";
        // 构造请求体
        String requestBody = String.format(
                """
                    {
                        "model": "%s",
                        "messages": [
                            {"role": "user",
                            "content": [
                             {"type": "text", "text": "描述下图片里的内容"},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": "%s"
                                }
                            },
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": "%s"
                                }
                            }
                            ]}
                        ]
                    }""", modelName, imageDataUrl1, imageDataUrl2);
        // 创建 HttpClient
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        // 创建请求
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + apiKey)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        try {
            // 发送请求并打印结果
            HttpResponse<String> response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            System.out.println("HTTP Status: " + response.statusCode());
            System.out.println("Response Body:\n" + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    /**
     * 将图片文件转换为 Base64 编码字符串
     */
    private static String encodeImageToBase64(String imagePath) throws IOException {
        byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
        return Base64.getEncoder().encodeToString(imageBytes);
    }
}

图文混排场景示例

API支持灵活交错地对提示词和图片信息进行序列编排，可以任意调整图片和文本的顺序，以及在system message或者User message传入图文信息。模型会根据顺序返回处理信息的结果，示例如下。可通过model参数替换模型，model参数详情请参见图像理解。

图文混排场景，图片与文本顺序会影响模型输出效果，如果输入结果与预期不符，可以尝试更换图文和文本的顺序。

提示词支持图片和文字混排输入给模型，但图文顺序可能对模型的输出效果产生影响，特别是在图片较多且只有一段文字的情况下，建议拼接时将文字放在图片之后。

import base64
import httpx
from openai import OpenAI

base_url = "https://api.modelarts-maas.com/v1/chat/completions" # API地址
api_key = "MAAS_API_KEY" # 把MAAS_API_KEY替换成已获取的API Key

client = OpenAI(api_key=api_key, base_url=base_url, http_client=httpx.Client(verify=False))

response = client.chat.completions.create(
    model = "qwen2.5-vl-72b", # model参数
    messages = [
        {
            "role": "user",
            "content": [
                 {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAA...."}},
                 {"type": "text", "text": "文字提取"},
                 {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."}},
	         {"type": "text", "text": "描述下图片里的内容"}
             ]
         }
     ]
)

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

curl -X POST "https://api.modelarts-maas.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MAAS_API_KEY" \
  -d '{ 
    "model": "qwen2.5-vl-72b",
    "messages": [
      {
        "role": "user",
        "content": [
             {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAA...."}},
             {"type": "text", "text": "文字提取"}
             {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU....}},
	     {"type": "text", "text": "描述下图片里的内容"}
        ]
      }
    ]
  }'

建议JDK版本为15+。

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Base64;

public class ImageDescriptionExample {
    public static void main(String[] args) throws Exception {
        // 接口地址
        String apiUrl = "https://api.modelarts-maas.com/v1/chat/completions";
        String apiKey = "MAAS_API_KEY"; // 把MAAS_API_KEY替换成已获取的API Key
        String image_path1 = "test1.png"; // test1.png替换为真实的图片地址
        String image_path2 = "test2.png"; // test1.png替换为真实的图片地址
        // 读取图片并转为 Base64
        String base64Image1 = encodeImageToBase64(image_path1);
        String base64Image2 = encodeImageToBase64(image_path2);
        String imageDataUrl1 = "data:image/png;base64," + base64Image1;
        String imageDataUrl2 = "data:image/png;base64," + base64Image2;
        // 替换为你要调用的模型名称，例如 "qwen2.5-vl-72b"
        String modelName = "qwen2.5-vl-72b";
        // 构造请求体
        String requestBody = String.format(
                """
                    {
                        "model": "%s",
                        "messages": [
                            {"role": "user",
                            "content": [
                             {"type": "text", "text": "描述下图片里的内容"},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": "%s"
                                }
                            },
                            {"type": "text", "text": "文字提取"},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": "%s"
                                }
                            }
                            ]}
                        ]
                    }""", modelName, imageDataUrl1, imageDataUrl2);
        // 创建 HttpClient
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        // 创建请求
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + apiKey)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        try {
            // 发送请求并打印结果
            HttpResponse<String> response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());
            System.out.println("HTTP Status: " + response.statusCode());
            System.out.println("Response Body:\n" + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    /**
     * 将图片文件转换为 Base64 编码字符串
     */
    private static String encodeImageToBase64(String imagePath) throws IOException {
        byte[] imageBytes = Files.readAllBytes(Path.of(imagePath));
        return Base64.getEncoder().encodeToString(imageBytes);
    }

相关文档