Skip to main content

Compréhension des images et vidéos

Les modèles de compréhension visuelle répondent à des questions en s'appuyant sur les images ou vidéos que vous fournissez. Ils acceptent une ou plusieurs images en entrée et conviennent à diverses tâches telles que le sous-titrage d'images, la réponse aux questions visuelles et la localisation d'objets.

Essayer en ligne : Accédez à la console Alibaba Cloud Model Studio. Dans l'angle supérieur droit de la page, sélectionnez la région cible. Ensuite, accédez à la page Vision Models pour tester les modèles.

Premiers pas

Prérequis
  • Obtenez une clé API et configurez-la comme variable d'environnement.
  • Pour effectuer des appels avec un SDK, installez le SDK. Le SDK DashScope Python doit être en version 1.24.6 ou ultérieure, et le SDK DashScope Java en version 2.21.10 ou ultérieure.
Les exemples suivants montrent comment appeler un modèle pour décrire le contenu d'une image. Pour plus d'informations sur les fichiers locaux et les limites applicables aux images, consultez Transmettre des fichiers locaux et Limites relatives aux images.
  • Compatibilité OpenAI
  • DashScope
  • Python
  • Node.js
  • Java
  • curl
from openai import OpenAI
import os

client = OpenAI(
    # API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. When you make a call, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.chat.completions.create(
    model="qwen4-max",  # This example uses qwen3.7-plus. You can replace it with another model as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"
                    },
                },
                {"type": "text", "text": "What scene is depicted in the image?"},
            ],
        },
    ],
)
print(completion.choices[0].message.content)

Réponse

This is a photo taken on a beach. In the photo, a person and a dog are sitting on the sand with the sea and sky in the background. The person and the dog seem to be interacting, with the dog's front paw on the person's hand. Sunlight shines from the right side of the frame, adding a warm atmosphere to the scene.

Performances des modèles

Questions-réponses sur les images

Décrivez le contenu d'une image, ou classez-la et étiquetez-la en identifiant par exemple des personnes, des lieux, des animaux ou des végétaux.

p1021359

Quel objet de cette image dois-je utiliser si le soleil est trop fort ?

Si le soleil est trop fort, utilisez les lunettes de soleil roses sur l'image. Les lunettes de soleil atténuent la lumière intense, réduisent les dommages causés aux yeux par les UV et contribuent à protéger la vue et à améliorer le confort visuel en plein soleil.

Écriture créative

Générez des descriptions textuelles vivantes à partir du contenu d'une image ou d'une vidéo. Cette fonctionnalité convient aux scénarios créatifs tels que la rédaction d'histoires, la conception de textes publicitaires ou l'écriture de scripts pour vidéos courtes.

vl-Q&A

Rédigez une publication intéressante pour les réseaux sociaux à partir du contenu de l'image.

Bien sûr. Cette image évoque la fête de la mi-automne en associant habilement des éléments classiques et modernes. À partir de ses principaux éléments, voici plusieurs propositions de publications dans différents styles.

Style poétique

Ce soir, la lune brille pour tous, mais qui sait où se poseront les pensées d'automne ? Chang'e s'envole vers la lune et le Lapin de jade prépare son remède. La poésie des anciens s'illumine ce soir. Puisse cette lune éclairer votre retour et porter mes pensées les plus sincères. Joyeuse fête de la mi-automne !

Vœux chaleureux

La lune est pleine, les familles réunies : la nuit de la mi-automne est la plus douce. Contemplez les feux d'artifice et la pleine lune, savourez un gâteau de lune et faites un vœu de bonne santé. Puissent tous nos souhaits se réaliser. Joyeuse fête de la mi-automne à tous et bonheur à vos familles !

Reconnaissance de texte et extraction d'informations

Reconnaissez du texte et des formules dans des images, ou extrayez des informations à partir de reçus, de certificats et de formulaires. La sortie au format texte structuré est prise en charge.

-q2cdz6jy89b6m3kp

Extrayez de l'image les champs suivants: ['Invoice Code', 'Invoice Number', 'Destination', 'Fuel Surcharge', 'Fare', 'Date', 'Departure Time', 'Train Number', 'Seat Number']. Fournissez la réponse au format JSON.

{

"Invoice Code": "221021325353",

"Invoice Number": "10283819",

"Destination": "Development Zone",

"Fuel Surcharge": "2.0",

"Fare": "8.00<Full>",

"Date": "2013-06-29",

"Departure Time": "Rolling",

"Train Number": "040",

"Seat Number": "371"

}

Résolution de problèmes multidisciplinaires

Résolvez des problèmes de mathématiques, de physique, de chimie et d'autres disciplines à partir d'images. Cette fonctionnalité convient à l'enseignement primaire et secondaire, universitaire et à la formation des adultes.

-5jwcstcvmdpqghaj

Résolvez pas à pas le problème mathématique présenté dans l'image.

-answer

Programmation visuelle

Générez du code à partir d'images ou de vidéos. Utilisez cette fonctionnalité pour produire du code HTML, CSS et JS à partir de maquettes de conception, de captures d'écran de sites web, et bien plus encore.

code

Créez une page web en HTML et CSS à partir de mon croquis. La couleur principale doit être le noir.

code-preview

Aperçu de la page web

Localisation d'objets

La localisation 2D et 3D est prise en charge. Cette fonctionnalité permet de déterminer l'orientation d'un objet, les changements de perspective et les relations d'occlusion. La localisation 3D constitue une nouvelle capacité introduite dans le modèle Qwen3-VL.
La localisation d'objets du modèle Qwen2.5-VL est fiable pour les résolutions comprises entre 480 × 480 et 2560 × 2560. En dehors de cette plage, la précision peut diminuer et les cadres de détection peuvent parfois être décalés.
Pour savoir comment représenter les résultats de localisation sur l'image d'origine, consultez la FAQ.
Localisation 2D
-530xdcos1lqkcfuy
  • Coordonnées Box (boîte englobante) : détectez tous les aliments dans l'image et renvoyez leurs coordonnées bbox au format JSON.
  • Coordonnées Point (centre) : localisez chaque aliment sous forme de point et renvoyez ses coordonnées au format XML.
Visualisation des résultats de localisation 2D
-mu9podu1eyvph1zd
3d
Détectez la voiture dans l'image et prédisez sa position 3D. Sortie JSON : [{"bbox_3d": [x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw], "label": "category"}].
3d-result

Analyse de documents

Analysez des documents sous forme d'image (tels que des copies numérisées ou des PDF image) pour les convertir au format QwenVL HTML ou QwenVL Markdown. Ce format permet non seulement de reconnaître le texte avec précision, mais aussi d'obtenir les informations de position d'éléments tels que les images et les tableaux. Le modèle Qwen3-VL ajoute la capacité d'analyse vers le format Markdown.
Les prompts recommandés sont les suivants : qwenvl html (pour une sortie HTML) ou qwenvl markdown (pour une sortie Markdown).

image

qwenvl markdown.

-result

Visualisation des résultats

Compréhension vidéo

Analysez le contenu d'une vidéo pour localiser des événements spécifiques et obtenir leurs horodatages, ou générez des résumés de périodes clés.
Décrivez la suite d'actions de la personne dans la vidéo. Renvoyez l'heure de début (start_time), l'heure de fin (end_time) et l'événement (event) au format JSON. Utilisez HH:mm:ss pour l'horodatage.{"events": [{"start_time": "00:00:00","end_time": "00:00:05","event": "The person walks towards the table holding a cardboard box and places it on the table."},{"start_time": "00:00:05","end_time": "00:00:15","event": "The person picks up a scanner and scans the label on the cardboard box."},{"start_time": "00:00:15","end_time": "00:00:21","event": "The person puts the scanner back in its place and then picks up a pen to record information in a notebook."}]}

Fonctionnalités principales

Activer ou désactiver le mode de réflexion

  • Les modèles des séries qwen3.8, qwen3.7, qwen3.6, qwen3.5 et qwen3-vl-plus sont des modèles à réflexion hybride. Ils peuvent réfléchir avant de répondre ou répondre directement. Le paramètre enable_thinking permet d'activer ou de désactiver le mode de réflexion :
    • true : active le mode de réflexion. La valeur par défaut des modèles des séries qwen3.8, qwen3.7, qwen3.6 et qwen3.5 est true.
    • false : désactive le mode de réflexion. La valeur par défaut des modèles de la série qwen3-vl-plus est false.
  • Les modèles dont le nom se termine par thinking fonctionnent uniquement en mode de réflexion. Ils réfléchissent toujours avant de répondre et ce comportement ne peut pas être désactivé.
  • Configuration du modèle : Dans les conversations générales sans appel d'outil par un agent, ne définissez pas de System Message afin de conserver des performances optimales. Vous pouvez transmettre les instructions de rôle et les exigences de format de sortie dans le User Message.
  • Privilégier la sortie en streaming : Lorsque le mode de réflexion est activé, les sorties en streaming et sans streaming sont prises en charge. Privilégiez le streaming pour éviter les délais d'expiration liés à des réponses trop longues.
  • Limiter la longueur de réflexion : Les modèles de réflexion approfondie produisent parfois un raisonnement long. Le paramètre thinking_budget permet d'en limiter la longueur. Si le nombre de tokens générés pendant la réflexion dépasse thinking_budget, le raisonnement est tronqué et le modèle commence immédiatement à produire la réponse finale. Par défaut, thinking_budget correspond à la longueur maximale de la chaîne de raisonnement du modèle. Pour plus d'informations, consultez la liste des modèles.
  • Compatibilité OpenAI
  • DashScope
Le paramètre enable_thinking n'est pas un paramètre standard OpenAI. Si vous utilisez le SDK Python OpenAI, transmettez-le via extra_body.
python
import os
from openai import OpenAI

client = OpenAI(
    # API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. When you make a call, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""  # Define the complete thinking process
answer_content = ""     # Define the complete response
is_answering = False   # Determine whether to end the thinking process and start responding
enable_thinking = True
# Create a chat completion request
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "How do I solve this problem?"},
            ],
        },
    ],
    stream=True,
    # The enable_thinking parameter enables the thinking process, and the thinking_budget parameter sets the maximum number of tokens for the inference process.
    # Use the enable_thinking parameter to switch the thinking mode.
    extra_body={
        'enable_thinking': enable_thinking,
        "thinking_budget": 81920},

    # Uncomment the following lines to return token usage in the last chunk.
    # stream_options={
    #     "include_usage": True
    # }
)

if enable_thinking:
    print("\n" + "=" * 20 + "Thinking process" + "=" * 20 + "\n")

for chunk in completion:
    # If chunk.choices is empty, print the usage.
    if not chunk.choices:
        print("\nUsage:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # Print the thinking process.
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content is not None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # Start responding.
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "Complete response" + "=" * 20 + "\n")
                is_answering = True
            # Print the response process.
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "Complete thinking process" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "Complete response" + "=" * 20 + "\n")
# print(answer_content)

Entrée de plusieurs images

Les modèles de compréhension visuelle permettent de transmettre plusieurs images dans une seule requête, ce qui est utile pour des tâches telles que la comparaison de produits et le traitement de documents multipages. Pour cela, incluez simplement plusieurs objets image dans le tableau content du user message.
Le nombre d'images est limité par le quota total de tokens du modèle pour les images et le texte. Le nombre total de tokens pour l'ensemble des images et du texte ne doit pas dépasser la limite d'entrée maximale du modèle.
  • Compatibilité OpenAI
  • DashScope
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. When you make a call, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen4-max",  #  This example uses qwen3.7-plus. You can replace it with another model as needed. For a list of models, see https://www.alibabacloud.com/help/model-studio/getting-started/models
    messages=[
        {"role": "user","content": [
            {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},},
            {"type": "image_url","image_url": {"url": "https://dashscope.oss-ap-southeast-1.aliyuncs.com/images/tiger.png"},},
            {"type": "text", "text": "What content do these images depict?"},
            ],
        }
    ],
)

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

Réponse

Image 1 shows a scene of a woman and a Labrador retriever interacting on a beach. The woman is wearing a plaid shirt and sitting on the sand, shaking hands with the dog. The background is the ocean waves and the sky, and the whole picture is full of warmth and joy.

Image 2 shows a scene of a tiger walking in a forest. The tiger's coat is orange with black stripes. It is stepping forward, surrounded by dense trees and vegetation, and the ground is covered with fallen leaves. The whole picture gives a feeling of wild nature.

Compréhension vidéo

Les modèles de compréhension visuelle analysent le contenu vidéo fourni sous forme de liste d'images (frames vidéo) ou de fichier vidéo. Les exemples suivants illustrent comment traiter des vidéos en ligne ou des listes d'images spécifiées par une URL. Pour plus d'informations sur les limites vidéo ou le nombre d'images transmissibles dans une liste, consultez Limites vidéo.
Pour améliorer la compréhension des fichiers vidéo, utilisez les versions latest ou les versions snapshot récentes des modèles.
  • Fichiers vidéo
  • Liste d'images
Les modèles de compréhension visuelle analysent le contenu vidéo en extrayant une séquence de frames de la vidéo. Vous pouvez contrôler la stratégie d'extraction des frames à l'aide des deux paramètres suivants :
  • fps : contrôle la fréquence d'extraction des images. Une image est extraite toutes les 1/fps secondes. Les valeurs sont comprises dans [0.1, 10] et la valeur par défaut est 2.0.
    • Pour les scènes avec des mouvements rapides, augmentez fps pour capturer davantage de détails.
    • Pour les scènes statiques ou les longues vidéos, réduisez fps pour améliorer les performances.
  • max_frames : nombre maximal d'images à extraire d'une vidéo. Le système calcule le nombre total d'images à partir de la valeur fps de la vidéo. Si ce nombre dépasse la limite, il échantillonne automatiquement les images à intervalles réguliers pour respecter celle-ci. Ce paramètre est disponible uniquement avec le SDK DashScope.
  • Compatibilité OpenAI
  • DashScope
Lorsque vous envoyez directement un fichier vidéo au modèle de compréhension visuelle avec le SDK OpenAI ou HTTP, définissez le paramètre "type" du message utilisateur sur "video_url".
Python
import os
from openai import OpenAI

client = OpenAI(
    # API keys vary by region. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. When you make a call, replace {WorkspaceId} with your workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {
            "role": "user",
            "content": [
                # When you pass a video file directly, set the value of type to video_url.
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                    },
                    "fps": 2
                },
                {
                    "type": "text",
                    "text": "What is the content of this video?"
                }
            ]
        }
    ]
)

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

Transmettre un fichier local (encodage Base64 ou chemin de fichier)

Les modèles de compréhension visuelle acceptent deux méthodes pour charger des fichiers locaux : l'encodage Base64 et le chargement direct par chemin de fichier. Choisissez la méthode appropriée selon la taille du fichier et le type de SDK utilisé. Pour obtenir des recommandations, reportez-vous à Comment choisir une méthode de chargement de fichier. Quelle que soit la méthode retenue, les fichiers doivent respecter les exigences décrites dans Limitations relatives aux images.
  • Téléverser avec un encodage Base64
  • Téléverser avec un chemin de fichier
Convertissez le fichier en chaîne encodée en Base64, puis transmettez-la au modèle. Cette méthode fonctionne avec les SDK OpenAI et DashScope, ainsi qu'avec les requêtes HTTP.
  1. Encodez le fichier : convertissez l'image locale en Base64.
    # Encoding function: Converts a local file to a Base64-encoded string
    import base64
    def encode_image(image_path):
        with open(image_path, "rb") as image_file:
            return base64.b64encode(image_file.read()).decode("utf-8")
    
    # Replace xxx/eagle.png with the absolute path of your local image
    base64_image = encode_image("xxx/eagle.png")
    
  2. Construisez une Data URL au format suivant : data:[MIME_type];base64,{base64_image}.
    1. Remplacez MIME_type par le type de média réel. Il doit correspondre à la valeur MIME Type du tableau Formats d'image pris en charge, par exemple image/jpeg ou image/png.
    2. base64_image est la chaîne Base64 générée à l'étape précédente.
  3. Appelez le modèle : transmettez Data URL avec le paramètre image ou image_url.
  • Image
  • Fichier vidéo
  • Liste d'images
  • Transmettre avec un chemin de fichier
  • Entrée encodée en Base64
Python
import os
import dashscope

# Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
    # Les API Key varient selon la région. Pour obtenir une API Key, voir https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Remplacez "xxx/eagle.png" par le chemin absolu de votre image locale.
local_path = "xxx/eagle.png"
image_path = f"file://{local_path}"
messages = [
                {'role':'user',
                'content': [{'image': image_path},
                            {'text': 'What scene is depicted in the image?'}]}]
response = client.multimodal.chat.create(
    model='qwen3.7-plus',  # Cet exemple utilise qwen3.7-plus. Vous pouvez changer le nom du modèle selon vos besoins. Pour la liste des modèles, voir https://www.alibabacloud.com/help/model-studio/getting-started/models
    messages=messages)
print(response.output_text)

Traitement des images haute résolution

Précision du traitement des images. Pour qwen4-max. Valeur par défaut : high. Lorsque max_pixels est omis :
  • high : traite l’image à sa résolution d’origine, jusqu’à 16777216 pixels.
  • low : limite l’image à 2621440 pixels.
  • auto : identique à low.
Une valeur explicite de max_pixels remplace la limite de pixels choisie par detail. Le maximum est 16777216. Dans Chat Completions, placez max_pixels au même niveau que image_url ; dans DashScope, au même niveau que image. Pour les images haute résolution, high utilise généralement plus de tokens d’entrée que low. Avec Chat Completions, définissez detail dans image_url ou au même niveau. Avec DashScope, définissez-le au même niveau que image.
Chat Completions
{"type":"image_url","image_url":{"url":"https://example.com/image.jpg","detail":"low"}}
DashScope
{"image":"https://example.com/image.jpg","detail":"low"}
L'API du modèle de compréhension visuelle impose une limite au nombre de tokens visuels pour une seule image encodée. Avec les configurations par défaut, les images haute résolution sont compressées, ce qui peut entraîner une perte de détails et nuire à la précision de l'analyse. Activez vl_high_resolution_images ou ajustez max_pixels pour augmenter le nombre de tokens visuels. Cela permet de conserver davantage de détails dans l'image et d'améliorer la compréhension.
Si le nombre de pixels de l'image d'entrée dépasse la limite du modèle, l'image est réduite pour respecter cette limite.

Modèle

Pixels par token

vl_high_resolution_images

max_pixels

Limite de tokens

Limite de pixels

Modèles des séries Qwen4-Max, Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 et Qwen3-VL

32×32

true

max_pixels est ignoré

16,384 tokens

16,777,216 (c'est-à-dire 16,384 × 32 × 32)

false (par défaut)

Personnalisable. La valeur par défaut est 2,621,440 et la valeur maximale est 16,777,216.

Déterminé par max_pixels, soit max_pixels / 32 / 32

max_pixels

Série open source Qwen2.5-VL et série QVQ

28 × 28

true

max_pixels est ignoré

16,384 tokens

12,845,056 (c'est-à-dire 16,384 × 28 × 28)

false (par défaut)

Personnalisable. La valeur par défaut est 1,003,520 et la valeur maximale est 12,845,056.

Déterminé par max_pixels, soit max_pixels / 28 / 28

max_pixels

  • Lorsque vl_high_resolution_images=true, l'API utilise une politique de résolution fixe et ignore max_pixels. Ce mode convient à la reconnaissance de petits caractères, de petits objets et de détails riches dans les images.
  • Lorsque vl_high_resolution_images=false, la limite finale de pixels dépend du paramètre max_pixels.
    • Pour réduire la consommation de tokens visuels lorsque le coût est prioritaire, conservez la valeur par défaut de max_pixels ou réduisez-la. max_pixels influe surtout sur le nombre de tokens visuels et le coût de l'appel. Nos tests n'ont pas montré d'effet significatif de sa réduction sur le temps de réponse de bout en bout.
    • Si vous souhaitez examiner certains détails et acceptez un traitement plus lent, augmentez max_pixels selon vos besoins.
  • Compatibilité OpenAI
  • DashScope
Le paramètre vl_high_resolution_images n'est pas standard dans l'API OpenAI. La méthode pour le transmettre varie selon les SDK :
  • SDK Python : le paramètre doit être transmis dans le dictionnaire extra_body.
  • SDK Node.js : le paramètre peut être transmis directement au niveau supérieur.
Python
import os
import time
from openai import OpenAI

client = OpenAI(
    # API keys vary by region. To obtain an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Chine (Pékin) region. When you call the API, replace {WorkspaceId} with your actual workspace ID. The URL varies by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {"role": "user","content": [
            {"type": "image_url","image_url": {"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250212/earbrt/vcg_VCG211286867973_RF.jpg"},
            # max_pixels represents the maximum pixel threshold for the input image. It is invalid when vl_high_resolution_images=True. When vl_high_resolution_images=False, it is customizable, and the maximum value varies by model.
            # "max_pixels": 16384 * 32 * 32
            },
           {"type": "text", "text": "What festival atmosphere does this image convey"},
            ],
        }
    ],
    extra_body={"vl_high_resolution_images":True}

)
print(f"Model output: {completion.choices[0].message.content}")
print(f"Total input tokens: {completion.usage.prompt_tokens}")

Autres utilisations

Limites

Limites des fichiers d'entrée

  • Limites des images
  • Limites des vidéos
  • Résolution de l'image :
    • Taille minimale : la largeur et la hauteur de l'image doivent toutes deux dépasser 10 pixels.
    • Rapport hauteur/largeur : le rapport du côté long au côté court ne doit pas dépasser 200:1, pour l'image d'origine comme pour l'image redimensionnée.
      Pour connaître la logique de redimensionnement, consultez la fonction smart_resize dans Calculer les tokens d'image.
    • Nombre maximal de pixels :
      • Maintenez la résolution dans la limite de 8K (7680x4320). Une résolution supérieure peut entraîner un délai d'expiration de l'API à cause de fichiers volumineux et de transferts réseau longs.
      • Redimensionnement automatique : le modèle ajuste les dimensions avec max_pixels et min_pixels. Une résolution élevée n'améliore pas la précision de détection, mais augmente le risque d'échec. Redimensionnez les images à une taille raisonnable côté client avant de les téléverser.
  • Formats d'image pris en charge
    • Pour les résolutions inférieures à 4K (3840x2160), les formats suivants sont pris en charge :

      Format d'image

      Extensions courantes

      Type MIME

      BMP

      .bmp

      image/bmp

      JPEG

      .jpe, .jpeg, .jpg

      image/jpeg

      PNG

      .png

      image/png

      TIFF

      .tif, .tiff

      image/tiff

      WEBP

      .webp

      image/webp

      HEIC

      .heic

      image/heic

    • Pour les résolutions comprises entre 4K (3840x2160) et 8K (7680x4320), seuls JPEG, JPG et PNG sont pris en charge.
  • Taille de l'image : Les limites suivantes s'appliquent à chaque image individuellement. Pour les entrées multi-images, chaque image est évaluée indépendamment et les tailles ne sont pas cumulées.
    • URL publique : une image ne doit pas dépasser 20 MB pour les séries Qwen4-Max, Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 et Qwen3-VL. Pour les autres modèles, la limite est 10 MB.
    • Chemin local : une image ne doit pas dépasser 10 MB.
    • Encodage Base64 (API compatible OpenAI) : pour les séries Qwen4-Max, Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 et Qwen3-VL, le fichier d'origine avant encodage ne doit pas dépasser 20 MB. Pour les autres modèles, la limite est 10 MB. Dans les deux cas, la chaîne Data URI obtenue ne doit pas dépasser 20 MB.
    • Encodage Base64 (API compatible Anthropic) : l'ensemble du corps de la requête ne doit pas dépasser 6 MB. Plusieurs images partagent ce quota.
    Ces limites dépendent du modèle utilisé. L'achat d'une offre supérieure ou le changement de version ne permet pas de les augmenter.
    Pour compresser un fichier, consultez Comment compresser une image ou une vidéo à la taille requise ?.
  • Nombre d'images : le nombre maximal d'images en entrée multiple dépend du mode de transmission :
    • URL publiques ou chemins locaux :
      • Séries Qwen3.8-Max, Qwen3.8-Flash et Qwen3.7-Plus : jusqu'à 2,048 images
      • Séries Qwen3.7-Flash, Qwen3.6-Plus, Qwen3.6-Flash, Qwen3.5-Plus, Qwen3.5-Flash, Qwen3-VL, Qwen-VL et QVQ : jusqu'à 256 images
      • Pour la série Qwen-Omni, consultez Multimodal intégral.
    • Chaînes encodées en Base64 : jusqu'à 250 images
Le nombre total de tokens des images est également soumis à la limite d'entrée du modèle. La somme des tokens des images et du texte ne doit pas dépasser cette limite.

Modes de transmission des fichiers

  • URL publique : fournissez une adresse accessible publiquement via HTTP ou HTTPS. Pour améliorer la stabilité et les performances, téléversez le fichier dans OSS pour obtenir une URL publique. Model Studio ne peut pas accéder aux endpoints internes OSS, dont l'adresse contient -internal, comme https://<bucket>.oss-cn-hangzhou-internal.aliyuncs.com/image.jpg. Avec une adresse interne, le téléchargement échoue et InvalidParameter est renvoyé avec le message Failed to download multimodal content. Utilisez un endpoint public OSS, comme https://<bucket>.oss-cn-hangzhou.aliyuncs.com/image.jpg, ou une URL OSS présignée.
    Pour garantir que le modèle puisse télécharger le fichier avec succès, l'en-tête de réponse de l'URL publique doit inclure Content-Length (taille du fichier) et Content-Type (type de média, par exemple image/jpeg). Si l'un de ces champs est manquant ou incorrect, le téléchargement du fichier échouera.
  • Encodage Base64 : convertissez le fichier en chaîne Base64, puis transmettez-la.
  • Chemin local (SDK DashScope uniquement) : transmettez le chemin d'un fichier local.
Pour choisir un mode de transmission, consultez Comment choisir une méthode de téléversement ?.

Utilisation en production

  • Prétraitement des images et vidéos : les modèles imposent des limites de taille. Pour compresser les fichiers, consultez Méthodes de compression des images et vidéos.
  • Traitement de fichiers texte : les modèles de compréhension visuelle traitent uniquement les images et les vidéos, et non les fichiers TXT, Word (.doc/.docx), PDF ou autres fichiers textuels. Utilisez l'une des solutions suivantes :
    • Convertissez le fichier texte en images. Une bibliothèque telle que pdf2image pour Python permet de convertir chaque page en image de haute qualité. Transmettez ensuite les images au modèle avec l'entrée multiple.
    • Utilisez Qwen-Long, qui permet de téléverser des documents et de converser en transmettant leurs informations via file-id.
  • Tolérance aux pannes et stabilité
    • Délais d'expiration : sans streaming, une erreur de délai d'expiration survient si la génération n'est pas terminée en 300 secondes. Le contenu déjà généré est renvoyé dans le corps de la réponse. Un en-tête contenant x-dashscope-partialresponse: true indique ce dépassement. Utilisez le mode partiel, pris en charge par certains modèles : ajoutez le contenu généré au tableau messages et renvoyez la requête pour poursuivre la génération. Consultez Poursuivre une génération incomplète.
    • Délai d'expiration côté client : le délai de 300 secondes décrit ci-dessus concerne le serveur et diffère du délai par défaut du SDK. Pour une grande image, par exemple de 4000 x 4000 pixels, une requête peut dépasser le délai du SDK et être interrompue par une erreur APITimeoutError avant d'atteindre la limite serveur. Utilisez with_options dans le SDK OpenAI Python pour augmenter le délai côté client :
client = client.with_options(timeout=1800.0)
response = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...]
)
  • Sortie en streaming : définissez stream=True pour recevoir le contenu progressivement au lieu d'attendre une réponse complète. Cela évite les dépassements du délai client liés aux appels longs sans streaming lors du traitement de grandes images :
stream = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content)
  • Nouvelles tentatives : prévoyez une stratégie adaptée, par exemple un délai exponentiel, pour gérer les fluctuations réseau ou une indisponibilité temporaire du service.

Facturation et limitation du débit

  • Facturation : le coût total dépend du nombre de tokens d'entrée et de sortie. Consultez les tarifs dans la console Model Studio.
    • Composition des tokens : les tokens d'entrée comprennent le texte et les images ou vidéos converties en tokens. Les tokens de sortie correspondent au texte généré. En mode de réflexion, le raisonnement est aussi comptabilisé en sortie. S'il n'est pas renvoyé, la facturation applique les tarifs du mode sans réflexion.
    • Calculer les tokens des images et vidéos : utilisez le code suivant pour estimer leur consommation. L'estimation est indicative ; la consommation réelle est celle de la réponse de l'API.
      • Images
      • Vidéos
      Formule : Image Tokens = h_bar * w_bar / token_pixels + 2
      • h_bar, w_bar : hauteur et largeur de l'image redimensionnée. Avant le traitement, le modèle réduit l'image selon une limite de pixels déterminée par max_pixels et vl_high_resolution_images. Consultez Traiter des images haute résolution.
      • token_pixels : nombre de pixels correspondant à chaque token visuel. Il varie selon le modèle :
        • qwen3.8-series, qwen3.7-series, qwen3.6-series, qwen3.5-series, Qwen3-VL : chaque token correspond à 32x32 pixels.
        • QVQ et autres modèles Qwen2.5-VL : chaque token correspond à 28x28 pixels.
      Le code suivant illustre la logique approximative de redimensionnement d'image appliquée par le modèle. Utilisez-le pour estimer le nombre de tokens d'une image. Pour la facturation effective, fiez-vous à la réponse de l'API.Chaque token d’image Qwen4-Max représente 32×32 pixels. Le nombre minimal de pixels est 65536. Définissez model="qwen4-max" dans le code ci-dessous pour utiliser ses règles de detail et de pixels ; un max_pixels explicite est prioritaire.
      import math
      from PIL import Image  # pip install Pillow
      
      def smart_resize(image_path, max_pixels=None, vl_high_resolution_images=False,
                       model="qwen4-max", detail="high", min_pixels=None):
          """Calculates the scaled dimensions of an image based on model parameters to estimate image tokens."""
          image = Image.open(image_path)
          height, width = image.height, image.width
      
          # The scaling factor is 32 for models such as Qwen4-Max, Qwen3.6, Qwen3.5, and Qwen3-VL. For other models, it is 28.
          factor = 32
          h_bar = round(height / factor) * factor
          w_bar = round(width / factor) * factor
      
          if model == "qwen4-max":
              min_pixels = 65536 if min_pixels is None else min_pixels
              if max_pixels is None:
                  max_pixels = 16777216 if detail == "high" else 2621440
          else:
              min_pixels = 4 * factor * factor if min_pixels is None else min_pixels
              max_pixels = 2621440 if max_pixels is None else max_pixels
              if vl_high_resolution_images:
                  max_pixels = 16384 * factor * factor
      
          # Constrains the total number of pixels to the range [min_pixels, max_pixels].
          if h_bar * w_bar > max_pixels:
              beta = math.sqrt((height * width) / max_pixels)
              h_bar = math.floor(height / beta / factor) * factor
              w_bar = math.floor(width / beta / factor) * factor
          elif h_bar * w_bar < min_pixels:
              beta = math.sqrt(min_pixels / (height * width))
              h_bar = math.ceil(height * beta / factor) * factor
              w_bar = math.ceil(width * beta / factor) * factor
      
          return h_bar, w_bar
      
      if __name__ == "__main__":
          # Note: The values of max_pixels and vl_high_resolution_images must match the parameters passed when calling the model.
          h_bar, w_bar = smart_resize("xxx/test.jpg", model="qwen4-max")
          print(f"Scaled image dimensions: Height {h_bar}, Width {w_bar}")
      
          # Each image includes one <vision_bos> and one <vision_eos> token.
          token = int(h_bar * w_bar / (32 * 32)) + 2
          print(f"Number of image tokens: {token}")
      
  • Consulter les factures : consultez les factures ou rechargez votre compte depuis la page Expenses and Costs de la console Alibaba Cloud.
  • Limitation du débit : pour connaître les limites des modèles de compréhension visuelle, consultez Limitation du débit.
  • Quota gratuit (région Singapore uniquement) : les modèles de compréhension visuelle bénéficient d'un quota gratuit de 1 million de tokens. Sa validité de 90 jours commence à l'activation de Model Studio ou à l'approbation de votre demande d'accès au modèle.

Référence API

Pour plus d'informations sur les paramètres d'entrée et de sortie du modèle de compréhension visuelle, reportez-vous à génération de texte.

FAQ

Choisissez la méthode de téléchargement la plus adaptée en fonction du type de SDK, de la taille du fichier et de la stabilité du réseau.

Type de fichier

Spécifications du fichier

SDK DashScope (Python, Java)

API compatible OpenAI / HTTP DashScope

Image

Supérieure à 7 Mo et inférieure à 10 Mo

Indiquer le chemin local

Seules les URL publiques sont prises en charge. Utilisez Alibaba Cloud Object Storage Service.

Inférieure à 7 Mo

Indiquer le chemin local

Encodage Base64

Vidéo

Supérieure à 100 Mo

Seules les URL publiques sont prises en charge. Utilisez Alibaba Cloud Object Storage Service.

Seules les URL publiques sont prises en charge. Utilisez Alibaba Cloud Object Storage Service.

Supérieure à 7 Mo et inférieure à 100 Mo

Indiquer le chemin local

Seules les URL publiques sont prises en charge. Utilisez Alibaba Cloud Object Storage Service.

Inférieure à 7 Mo

Indiquer le chemin local

Encodage Base64

L'encodage Base64 augmente le volume des données. Le fichier d'origine doit être inférieur à 7 MB.
Utilisez Base64 ou un chemin local pour éviter les délais d'expiration des téléchargements côté serveur et améliorer la stabilité.
Les modèles de compréhension visuelle imposent des limites de taille pour les fichiers d'entrée. Appliquez les méthodes suivantes pour compresser vos fichiers.
  • Outils en ligne : utilisez par exemple CompressJPEG pour compresser les images.
  • Logiciels locaux : utilisez par exemple Photoshop pour ajuster la qualité à l'exportation.
  • Exemple de code :
# pip install pillow

from PIL import Image
def compress_image(input_path, output_path, quality=85):
    with Image.open(input_path) as img:
        img.save(output_path, "JPEG", optimize=True, quality=quality)

# Pass the local image
compress_image("/xxx/before-large.jpeg","/xxx/after-min.jpeg")

# Batch compress the images in a directory
import glob
import os

def batch_compress(input_dir, output_dir, quality=85):
    files = (
        glob.glob(os.path.join(input_dir, "*.jpg"))
        + glob.glob(os.path.join(input_dir, "*.jpeg"))
        + glob.glob(os.path.join(input_dir, "*.png"))
    )
    for i, f in enumerate(files, 1):
        try:
            compress_image(f, os.path.join(output_dir, os.path.basename(f)), quality)
            print(f"[{i}/{len(files)}] {os.path.basename(f)} done")
        except Exception as e:
            print(f"[{i}/{len(files)}] {os.path.basename(f)} error: {e}")

batch_compress("/xxx/input_dir", "/xxx/output_dir")
  • Outils en ligne : utilisez par exemple FreeConvert pour compresser les vidéos.
  • Logiciels locaux : utilisez par exemple HandBrake.
  • Exemple de code : utilisez FFmpeg. Pour plus d'informations, consultez le site officiel de FFmpeg.
# Basic transform command
# -i, function: input file path, example: input.mp4
# -vcodec, function: video encoder, common values include libx264 (generally recommended) and libx265 (higher compression ratio)
# -crf, function: controls video quality, value range: [18-28]. The smaller the value, the higher the quality and the larger the file size.
# --preset, function: controls the balance between encoding speed and compression efficiency. Common values include slow, fast, and faster.
# -y, function: overwrite an existing file (no value needed)
# output.mp4, function: output file path

ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset slow output.mp4
Une fois que le modèle de compréhension visuelle a retourné les résultats de localisation des objets, vous pouvez utiliser le code suivant pour tracer les cadres de détection et leurs libellés directement sur l'image d'origine.
  • Qwen2.5-VL : les coordonnées renvoyées sont des valeurs absolues en pixels, relatives à l'angle supérieur gauche de l'image redimensionnée. Pour dessiner les cadres, consultez qwen2_5_vl_2d.py.
  • Séries Qwen3-VL, Qwen3.5, Qwen3.6 et Qwen3.7 (par exemple qwen3.5-plus, qwen3.6-plus et qwen3.7-plus) : les coordonnées renvoyées sont relatives et normalisées dans l'intervalle [0, 999]. Consultez qwen3_vl_2d.py pour la localisation 2D ou qwen3_vl_3d.zip pour la localisation 3D.

Codes d'erreur

En cas d'échec d'appel au modèle, un message d'erreur est retourné. Pour savoir comment résoudre ce problème, reportez-vous à Codes d'erreur.