Skip to main content

Comprensión de imágenes y videos

Los modelos de comprensión visual pueden responder preguntas basándose en las imágenes o videos que usted proporcione. Admiten entradas de una o varias imágenes y son adecuados para diversas tareas, como la generación de descripciones de imágenes, la respuesta a preguntas visuales y la localización de objetos.

Pruébelo en línea: Vaya a la consola de Alibaba Cloud Model Studio. En la esquina superior derecha de la página, seleccione la región de destino. Luego, vaya a la página de Modelos de Visión para probar los modelos.

Introducción

Requisitos previos
  • Obtenga una clave API y configúrela como una variable de entorno.
  • Para realizar llamadas utilizando un SDK, instale el SDK. El SDK de Python de DashScope debe ser versión 1.24.6 o posterior, y el SDK de Java de DashScope debe ser versión 2.21.10 o posterior.
Los siguientes ejemplos muestran cómo llamar a un modelo para describir el contenido de una imagen. Para obtener más información sobre archivos locales y límites de imágenes, consulte Pasar archivos locales y Límites de imágenes.
  • Compatible con 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 Singapore 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="qwen3.8-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)

Respuesta 

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.

Rendimiento del modelo

Preguntas y respuestas sobre imágenes

Describa el contenido de una imagen o clasifíquela y etiquétela, como identificar personas, lugares, animales y plantas.

p1021359

¿Qué objeto de esta imagen debería usar si el sol es demasiado brillante?

Si el sol es demasiado brillante, debe usar los lentes de sol rosas que aparecen en la imagen. Los lentes de sol pueden bloquear eficazmente la luz intensa, reducir el daño por rayos UV en sus ojos y ayudar a proteger su visión, mejorando así la comodidad visual bajo la luz solar intensa.

Escritura creativa

Genere descripciones de texto vívidas basadas en el contenido de imágenes o videos, adecuado para escenarios creativos como escritura de historias, redacción publicitaria y guiones de videos cortos.

vl-Q&A

Por favor, escriba una publicación interesante para redes sociales basada en el contenido de la imagen.

Claro. Esta imagen está llena de una rica atmósfera del Festival del Medio Otoño, combinando hábilmente elementos clásicos y modernos. Basándome en los elementos principales de la imagen, he preparado varias publicaciones para redes sociales en diferentes estilos para que usted elija.

Estilo poético y hermoso

Esta noche, la luna brilla para todos, pero ¿quién sabe dónde caerán los pensamientos otoñales? Chang'e vuela hacia la luna y el Conejo de Jade prepara medicinas. El romance de los antiguos se ilumina esta noche. ¡Que esta luna brillante ilumine su camino a casa y lleve mis pensamientos más profundos! ¡Feliz Festival del Medio Otoño!

Estilo de buenos deseos

La luna está llena y las personas se reúnen. La noche del Medio Otoño es la más gentil. Observe los fuegos artificiales florecer, admire la luna llena en el cielo, dé un bocado a un pastel lunar y want buena salud. Que todo aquello que usted y yo want se haga true. ¡Feliz Festival del Medio Otoño a todos, y que sus familias sean felices!

Reconocimiento de texto y extracción de información

Reconozca texto y fórmulas en imágenes, o extraiga información de recibos, certificados y formularios. Admite salida de texto formateado.

-q2cdz6jy89b6m3kp

Extraiga lo siguiente de la imagen: ['Invoice Code', 'Invoice Number', 'Destination', 'Fuel Surcharge', 'Fare', 'Date', 'Departure Time', 'Train Number', 'Seat Number']. Por favor, genere la salida en formato 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"

}

Resolución de problemas multidisciplinarios

Resuelva problemas de matemáticas, física, química y otras materias en imágenes. Adecuado para educación K-12, universitaria y de adultos.

-5jwcstcvmdpqghaj

Resuelva el problema matemático del gráfico paso a paso.

-answer

Programación visual

Genere código a partir de imágenes o videos. Puede utilizar esta función para generar código HTML, CSS y JS a partir de borradores de diseño, capturas de pantalla de sitios web y más.

code

Cree una página web usando HTML y CSS basada en mi boceto. El color principal debe ser negro.

code-preview

Vista previa de página web

Localización de objetos

Admite localización 2D y 3D. Puede utilizar esta función para determinar la orientación del objeto, cambios de perspectiva y relaciones de oclusión. La localización 3D es una nueva capacidad añadida al modelo Qwen3-VL.
El rendimiento de localización de objetos del modelo Qwen2.5-VL es robusto dentro del rango de resolución de 480 × 480 a 2560 × 2560. Fuera de este rango, la precisión de detección puede disminuir, con deriva ocasional del cuadro de detección.
Para obtener información sobre cómo dibujar los resultados de localización en la imagen original, consulte FAQ.
Localización 2D
-530xdcos1lqkcfuy
  • Devolver coordenadas de caja (bounding box): Detecte todos los alimentos en la imagen y genere sus coordenadas bbox en formato JSON.
  • Devolver coordenadas de punto (centroide): Localice todos los alimentos en la imagen como puntos y genere sus coordenadas de punto en formato XML.
Visualización de resultados de localización 2D
-mu9podu1eyvph1zd
3d
Detecte el automóvil en la imagen y prediga su posición 3D. Salida JSON: [{"bbox_3d": [x_center, y_center, z_center, x_size, y_size, z_size, roll, pitch, yaw], "label": "category"}].
3d-result

Análisis de documentos

Analice documentos basados en imágenes (como copias escaneadas o PDFs de imágenes) para convertirlos al formato QwenVL HTML o QwenVL Markdown. Este formato no solo reconoce el texto con precisión, sino que también obtiene la información de posición de elementos como imágenes y tablas. El modelo Qwen3-VL añade la capacidad de analizar y convertir al formato Markdown.
Los prompts recomendados son los siguientes: qwenvl html (para analizar en formato HTML) o qwenvl markdown (para analizar en formato Markdown).

imagen

Markdown de qwenvl.

-result

Visualización de resultados

Comprensión de video

Analice el contenido del video, como localizar eventos específicos y obtener marcas de tiempo, o generar resúmenes de períodos clave.
Por favor, describa la serie de acciones de la persona en el video. Genere la hora de inicio (start_time), hora de fin (end_time) y evento (event) en formato JSON. Utilice HH:mm:ss para la marca de tiempo.{"events": [{"start_time": "00:00:00","end_time": "00:00:05","event": "La persona camina hacia la mesa sosteniendo una caja de cartón y la coloca sobre la mesa."},{"start_time": "00:00:05","end_time": "00:00:15","event": "La persona toma un escáner y escanea la etiqueta de la caja de cartón."},{"start_time": "00:00:15","end_time": "00:00:21","event": "La persona vuelve a colocar el escáner en su lugar y luego toma un bolígrafo para registrar información en un cuaderno."}]}

Características principales

Habilitar o deshabilitar el modo de pensamiento

  • Las series de modelos qwen3.8, qwen3.7, qwen3.6, qwen3.5 y qwen3-vl-plus son modelos de pensamiento híbrido. Pueden pensar antes de responder o responder directamente. Utilice el parámetro enable_thinking para controlar si se habilita el modo de pensamiento:
    • true: Habilita el modo de pensamiento. El valor predeterminado para los modelos de las series qwen3.8, qwen3.7, qwen3.6 y qwen3.5 es true.
    • false: Desactiva el modo de pensamiento. El valor predeterminado para los modelos de la serie qwen3-vl-plus es false.
  • Los modelos con el sufijo thinking son modelos exclusivos de pensamiento. Siempre piensan antes de responder y esta función no se puede desactivar.
  • Configuración del modelo: En escenarios de conversación general que no implican llamadas a herramientas de Agent, no configure un System Message para mantener un rendimiento óptimo. Puede pasar instrucciones, como configuraciones de rol del modelo y requisitos de formato de salida, a través del User Message.
  • Priorizar la salida en streaming: Cuando el modo de pensamiento está habilitado, se admite tanto la salida en streaming como sin streaming. Para evitar tiempos de espera causados por respuestas excesivamente largas, priorice el uso de la salida en streaming.
  • Limitar la longitud del pensamiento: Los modelos de pensamiento profundo a veces generan procesos de razonamiento extensos. Puede utilizar el parámetro thinking_budget para limitar la longitud del proceso de pensamiento. Si la cantidad de tokens generados durante el proceso de pensamiento del modelo supera el thinking_budget, el contenido de inferencia se trunca y el modelo comienza inmediatamente a generar la respuesta final. El valor predeterminado de thinking_budget es la longitud máxima de cadena de pensamiento del modelo. Para obtener más información, consulte la lista de modelos.
  • Compatible con OpenAI
  • DashScope
El parámetro enable_thinking no es un parámetro estándar de OpenAI. Si utiliza el SDK de Python de OpenAI, páselo a través de extra_body.
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 Singapore 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="qwen3.8-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)

Entradas de múltiples imágenes

Los modelos de comprensión visual admiten pasar múltiples imágenes en una sola solicitud, lo cual puede utilizarse para tareas como comparación de productos y procesamiento de documentos de varias páginas. Para hacerlo, simplemente incluya múltiples objetos de imagen en el arreglo content del user message.
El número de imágenes está limitado por el límite total de tokens del modelo para imágenes y texto. El recuento total de tokens para todas las imágenes y texto no debe exceder la entrada máxima del modelo.
  • Compatible con 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 Singapore 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="qwen3.8-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-cn-beijing.aliyuncs.com/images/tiger.png"},},
            {"type": "text", "text": "What content do these images depict?"},
            ],
        }
    ],
)

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

Respuesta 

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.

Comprensión de video

Los modelos de comprensión visual pueden entender el contenido de video proporcionado como una lista de imágenes (fotogramas de video) o como un archivo de video. Los siguientes ejemplos muestran cómo entender videos en línea o listas de imágenes especificadas mediante una URL. Para obtener más información sobre los límites de video o la cantidad de imágenes que se pueden pasar en una lista de imágenes, consulte Límites de video.
Para obtener un mejor rendimiento al comprender archivos de video, utilice las versiones más recientes o las versiones snapshot recientes de los modelos.
  • Archivos de video
  • Lista de imágenes
Los modelos de comprensión visual analizan el contenido del video extrayendo una secuencia de fotogramas del video. Puede controlar la estrategia de extracción de fotogramas con los siguientes dos parámetros:
  • fps: Controla la frecuencia de extracción de fotogramas. Se extrae un fotograma cada 1/fps segundos. El rango de valores es [0.1, 10], y el valor predeterminado es 2.0.
    • Para escenas con movimiento rápido, establezca un valor de fps más alto para capturar más detalles.
    • Para escenas estáticas o videos largos, establezca un valor de fps más bajo para mejorar el rendimiento.
  • max_frames: El número máximo de fotogramas a extraer de un video. El sistema calcula el total de fotogramas basándose en los fps del video. Si el número total de fotogramas supera este límite, el sistema muestrea automáticamente los fotogramas de manera uniforme para cumplir con el límite. Este parámetro solo está disponible al utilizar el SDK de DashScope.
  • Compatible con OpenAI
  • DashScope
Cuando envía un archivo de video directamente al modelo de comprensión visual utilizando el SDK de OpenAI o HTTP, establezca el parámetro "type" en el mensaje del usuario en "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 Singapore 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="qwen3.8-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)

Pasar un archivo local (codificación Base64 o ruta de archivo)

Los modelos de comprensión visual admiten dos métodos para cargar archivos locales: codificación Base64 y carga directa mediante ruta de archivo. Puede elegir un método de carga según el tamaño del archivo y el tipo de SDK. Para recomendaciones, consulte Cómo elegir un método de carga de archivos. Ambos métodos deben cumplir con los requisitos de archivo descritos en Limitaciones de imágenes.
  • Subir mediante codificación Base64
  • Subir mediante ruta de archivo
Convierta el archivo a una cadena codificada en Base64 y luego páselo al modelo. Este método es aplicable a los SDKs de OpenAI y DashScope, y a solicitudes HTTP.
  1. Codificar el archivo: Convierta la imagen local a una codificación 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. Construya una Data URL con el siguiente formato: data:[MIME_type];base64,{base64_image}.
    1. Reemplace MIME_type con el tipo de medio real. Asegúrese de que coincida con el valor MIME Type en la tabla Formatos de imagen admitidos, como image/jpeg o image/png.
    2. base64_image es la cadena Base64 generada en el paso anterior.
  3. Llamar al modelo: Pase la Data URL utilizando el parámetro image o image_url.
  • Imagen
  • Archivo de video
  • Lista de imágenes
  • Pasar mediante ruta de archivo
  • Entrada codificada en Base64
Python
import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Al llamar a la API, sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si la variable de entorno no está configurada, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las claves de API varían según la región. Para obtener una clave de API, véase https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Reemplace xxx/eagle.png con la ruta absoluta de su imagen local
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',  # Este ejemplo usa qwen3.7-plus. Puede cambiar el nombre del modelo según sea necesario. Para una lista de modelos, véase https://www.alibabacloud.com/help/model-studio/getting-started/models
    messages=messages)
print(response.output_text)

Procesar imágenes de alta resolución

La API del modelo de comprensión visual tiene un límite en la cantidad de tokens visuales para una sola imagen codificada. Con las configuraciones predeterminadas, las imágenes de alta resolución se comprimen, lo que puede causar pérdida de detalles y afectar la precisión de la comprensión. Habilite vl_high_resolution_images o ajuste max_pixels para aumentar la cantidad de tokens visuales. Esto conserva más detalles de la imagen y mejora la comprensión.
Si el recuento de píxeles de la imagen de entrada supera el límite de píxeles del modelo, la imagen se reduce para ajustarse al límite.

Modelo

Píxeles por token

vl_high_resolution_images

max_pixels

Límite de tokens

Límite de píxeles

Modelos de las series Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 y Qwen3-VL

32×32

true

max_pixels no es válido

16,384 tokens

16,777,216 (es decir, 16,384 × 32 × 32)

false (predeterminado)

Personalizable. El valor predeterminado es 2,621,440 y el valor máximo es 16,777,216.

Determinado por max_pixels, que es max_pixels / 32 / 32

max_pixels

Modelos de las series de código abierto Qwen2.5-VL y QVQ

28 × 28

true

max_pixels no es válido

16,384 tokens

12,845,056 (es decir, 16,384 × 28 × 28)

false (predeterminado)

Personalizable. El valor predeterminado es 1,003,520 y el valor máximo es 12,845,056.

Determinado por max_pixels, que es max_pixels / 28 / 28

max_pixels

  • Cuando vl_high_resolution_images=true, la API utiliza una política de resolución fija e ignora la configuración de max_pixels. Esto es adecuado para reconocer texto fino, objetos pequeños o detalles ricos en imágenes.
  • Cuando vl_high_resolution_images=false, el límite final de píxeles depende del valor del parámetro max_pixels.
    • Para escenarios sensibles a costos donde usted want reducir el consumo de tokens visuales: Utilice el valor predeterminado de max_pixels o establézcalo en un valor menor.
    • Si usted want centrarse en ciertos detalles y puede aceptar una velocidad de procesamiento menor, aumente el valor de max_pixels según sea necesario.
  • Compatible con OpenAI
  • DashScope
vl_high_resolution_images no es un parámetro estándar de OpenAI. El método para pasarlo varía según los diferentes SDKs de lenguaje:
  • Python SDK: Debe pasarse a través del diccionario extra_body.
  • Node.js SDK: Se puede pasar directamente como un parámetro de nivel superior.
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 Singapore 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="qwen3.8-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}")

Más usos

Límites

Límites de archivos de entrada

  • Límites de imagen
  • Límites de video
  • Resolución de imagen:
    • Tamaño mínimo: Tanto el ancho como el alto de la imagen deben ser mayores que 10 píxeles.
    • Relación de aspecto: La relación entre el lado largo y el lado corto tanto para las imágenes originales como para las escaladas no debe exceder 200:1.
      Para obtener información sobre la lógica de escalado de imágenes, consulte la función smart_resize en Calcular tokens de imagen
    • Píxeles máximos:
      • Mantenga la resolución de la imagen dentro de 8K (7680x4320). Las imágenes con una resolución mayor pueden causar tiempos de espera en las llamadas API debido a tamaños de archivo grandes y tiempos prolongados de transmisión de red.
      • Escalado automático: El modelo puede ajustar el tamaño de la imagen mediante max_pixels y min_pixels. Proporcionar imágenes de alta resolución no mejora la precisión de la detección; por el contrario, aumenta el riesgo de fallos en las llamadas. Escale las imágenes a un tamaño razonable en el cliente antes de cargarlas.
  • Formatos de imagen compatibles
    • Para resoluciones inferiores a 4K (3840x2160), se admiten los siguientes formatos de imagen:

      Formato de imagen

      Extensiones comunes

      Tipo 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

    • Para resoluciones entre 4K (3840x2160) y 8K (7680x4320), solo se admiten los formatos JPEG, JPG y PNG.
  • Tamaño de imagen: El cuerpo total de la solicitud para todas las interfaces no debe exceder 64 MB; al pasar múltiples imágenes, estas comparten esta cuota global del cuerpo de la solicitud. Los dominios de DashScope limitan el cuerpo de la solicitud a 16 MiB; utilice en su lugar el dominio del espacio de trabajo {WorkspaceId}.{region}.maas.aliyuncs.com.
    • Cuando se pasa como URL pública: Una sola imagen no puede exceder 20 MB para los modelos de las series Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 y Qwen3-VL. Para otros modelos, una sola imagen no puede exceder 10 MB.
    • Cuando se pasa como una ruta local: Una sola imagen no puede exceder 10 MB.
    • Cuando se pasa como codificación Base64: Para las series de modelos Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5 y Qwen3-VL, el archivo de imagen original antes de la codificación no puede exceder 20 MB. Para otros modelos, no puede exceder 10 MB. La cadena Data URI resultante no puede exceder 20 MB en la API compatible con OpenAI y DashScope, o 32 MB en la API compatible con Anthropic.
    Estos límites dependen del modelo que utilice. No se pueden aumentar comprando un plan de nivel superior o actualizando la versión del modelo.
    Para comprimir un archivo, consulte Cómo comprimir una imagen o video al tamaño requerido.
  • Límite de cantidad de imágenes: El número máximo de imágenes admitido para la entrada de múltiples imágenes varía según el método de entrada:
    • Cuando se pasan como URLs públicas o rutas locales:
      • Series Qwen3.8-Max, Qwen3.8-Flash, Qwen3.7-Plus: Hasta 2,048 imágenes
      • Qwen3.7-Flash, Qwen3.6-Plus, Qwen3.6-Flash, Qwen3.5-Plus, Qwen3.5-Flash, Qwen3-VL, Qwen-VL, serie QVQ: Hasta 256 imágenes
      • Para la serie Qwen-Omni, consulte Omni-modal.
    • Cuando se pasan como cadenas codificadas en Base64: Hasta 250 imágenes
El número total de tokens para todas las imágenes también está limitado por el límite máximo de tokens de entrada del modelo. El recuento total de tokens para todas las imágenes y texto no debe exceder la entrada máxima del modelo.

Métodos de entrada de archivos

  • URL pública: Proporcione una dirección de archivo accesible públicamente que admita el protocolo HTTP o HTTPS. Para una estabilidad y un rendimiento óptimos, suba el archivo a OSS para obtener una URL pública. Model Studio no puede acceder a los endpoints internos de OSS, cuyas direcciones contienen -internal, como https://<bucket>.oss-cn-hangzhou-internal.aliyuncs.com/image.jpg. Si pasa una dirección interna, la descarga del archivo fallará y se devolverá InvalidParameter con el mensaje Failed to download multimodal content. Utilice en su lugar un endpoint público de OSS, como https://<bucket>.oss-cn-hangzhou.aliyuncs.com/image.jpg, o una URL de OSS prefirmada.
    Para garantizar que el modelo pueda descargar el archivo correctamente, el encabezado de respuesta de la URL pública debe incluir Content-Length (tamaño del archivo) y Content-Type (tipo de medio, como image/jpeg). Si falta alguno de estos campos o es incorrecto, la descarga del archivo fallará.
  • Codificación Base64: Convierta el archivo a una cadena codificada en Base64 y luego pásela.
  • Ruta de archivo local (solo DashScope SDK): Pase la ruta de un archivo local.
Para recomendaciones sobre cómo elegir un método de entrada de archivos, consulte ¿Cómo elijo un método de carga de archivos?

Uso en un entorno de producción

  • Preprocesamiento de imágenes y videos: Los modelos de comprensión visual tienen límites de tamaño para los archivos de entrada. Para comprimir archivos, consulte Métodos de compresión de imágenes o videos.
  • Procesamiento de archivos de texto: Los modelos de comprensión visual solo admiten archivos de imagen y video. No admiten el procesamiento de archivos TXT, Word (.doc/.docx), PDF u otros archivos basados en texto. Utilice una de las siguientes soluciones alternativas:
    • Convierta el archivo de texto a un formato de imagen. Utilice una biblioteca de procesamiento de imágenes, como pdf2image para Python, para convertir el archivo página por página en múltiples imágenes de alta calidad. Luego, pase las imágenes al modelo utilizando el método de entrada de múltiples imágenes.
    • Utilice Qwen-Long, que admite cargar documentos y realizar conversaciones pasando información a través de file-id.
  • Tolerancia a fallos y estabilidad
    • Manejo de tiempos de espera: En llamadas sin streaming, ocurre un error de tiempo de espera si el modelo no termina de generar la salida dentro de 300 segundos. Cuando ocurre un tiempo de espera, el contenido generado se devuelve en el cuerpo de la respuesta. Un encabezado de respuesta que contiene x-dashscope-partialresponse: true indica que la respuesta agotó el tiempo de espera. Utilice la función de modo parcial, que es compatible con algunos modelos. Agregue el contenido generado al arreglo messages y envíe la solicitud nuevamente. Esto permite que el Modelo de Lenguaje Grande (LLM) continúe generando contenido. Para obtener más información, consulte Continuar la generación a partir de una salida incompleta.
    • Configuración de tiempo de espera del lado del cliente: El tiempo de espera mencionado anteriormente es un tiempo de espera del lado del servidor que ocurre cuando el modelo no termina de generar la salida dentro de 300 segundos. Es diferente del tiempo de espera predeterminado del lado del cliente del SDK. Cuando procesa imágenes grandes, como una imagen de 4000 x 4000 píxeles, una solicitud puede tardar más que el tiempo de espera predeterminado del lado del cliente del SDK e interrumpirse con un APITimeoutError, incluso si no se ha alcanzado el límite de 300 segundos del lado del servidor. Para evitar esto, utilice with_options en el SDK de Python de OpenAI para extender el tiempo de espera del lado del cliente:
client = client.with_options(timeout=1800.0)
response = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...]
)
  • Salida en streaming: Configure stream=True para que el modelo devuelva el contenido de forma incremental en lugar de esperar una única respuesta completa. Esto evita los tiempos de espera del lado del cliente causados por llamadas sin streaming de larga duración cuando procesa imágenes grandes:
stream = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[...],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content)
  • Mecanismo de reintento: Diseñe una lógica de reintento de llamadas API razonable, como retroceso exponencial, para manejar fluctuaciones de red o indisponibilidad temporal del servicio.

Facturación y limitación de tasa

  • Facturación:El costo total se calcula en función del número total de tokens de entrada y salida. Los precios de entrada y salida están disponibles en la consola de Model Studio.
    • Composición de tokens: Los tokens de entrada consisten en tokens de texto y tokens convertidos desde imágenes o videos. Los tokens de salida son el texto generado por el modelo. En el modo de pensamiento, el proceso de razonamiento del modelo también se cuenta como tokens de salida. Si el proceso de pensamiento no se genera en el modo de pensamiento, la facturación sigue los precios del modo sin pensamiento.
    • Calcular tokens para imágenes y videos:Utilice el siguiente código para calcular el consumo de tokens para imágenes o videos. El resultado estimado es solo para referencia. El uso real se basa en la respuesta de la API.
      • Imágenes
      • Videos
      Fórmula: Image Tokens = h_bar * w_bar / token_pixels + 2
      • h_bar, w_bar: La altura y el ancho de la imagen escalada. Antes de procesar una imagen, el modelo realiza un preprocesamiento para reducirla a un límite de píxeles específico. Este límite depende de los valores de los parámetros max_pixels y vl_high_resolution_images. Para obtener más información, consulte Procesar imágenes de alta resolución.
      • token_pixels: El valor de píxel correspondiente a cada token visual. Esto varía según el modelo:
        • qwen3.8-series,qwen3.7-series, qwen3.6-series, qwen3.5-series, Qwen3-VL:Cada token corresponde a 32x32 píxeles.
        • QVQ y otros modelos Qwen2.5-VL:Cada token corresponde a 28x28 píxeles.
      El siguiente código demuestra la lógica aproximada de escalado de imágenes utilizada por el modelo. Úselo para estimar los tokens de una imagen. Para la facturación real, consulte la respuesta de la API.
      import math
from PIL import Image  # pip install Pillow

def smart_resize(image_path, max_pixels, vl_high_resolution_images):
    """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 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

    # Token lower limit: 4 tokens
    min_pixels = 4 * factor * factor

    # If vl_high_resolution_images=True, the token upper limit is fixed at 16384, and max_pixels is ignored.
    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", max_pixels=2560 * 32 * 32, vl_high_resolution_images=False)
    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}")
  • Ver facturas:Vea facturas o recargue su cuenta en la página Gastos y Costos en la Consola de Administración de Alibaba Cloud.
  • Limitación de tasa:Para más información sobre las condiciones de limitación de tasa para modelos de comprensión visual, consulte Limitación de tasa.
  • Cuota gratuita (solo región de Singapur): Se proporciona una cuota gratuita de 1 millón de tokens para los modelos de comprensión visual. El periodo de validez de 90 días comienza a partir de la fecha en que usted habilita Model Studio o se aprueba su solicitud de modelo.

Referencia de API

Para más información sobre los parámetros de entrada y salida del modelo de comprensión visual, consulte generación de texto.

FAQ

Elija el método de carga más adecuado según el tipo de SDK, el tamaño del archivo y la estabilidad de la red.

Tipo de archivo

Especificaciones de archivo

DashScope SDK (Python, Java)

Compatible con OpenAI / HTTP de DashScope

Imagen

Mayor que 7 MB y menor que 10 MB

Pasar la ruta local

Solo se admiten URLs de red pública. Utilice Alibaba Cloud Object Storage Service

Menos de 7 MB

Pasar la ruta local

Codificación Base64

Video

Mayor que 100 MB

Solo se admiten URLs de red pública. Utilice Alibaba Cloud Object Storage Service

Solo se admiten URLs de red pública. Utilice Alibaba Cloud Object Storage Service

Mayor que 7 MB y menor que 100 MB

Pasar la ruta local

Solo se admiten URLs de red pública. Utilice Alibaba Cloud Object Storage Service

Menos de 7 MB

Pasar la ruta local

Codificación Base64

La codificación Base64 aumenta el tamaño de los datos. El tamaño del archivo original debe ser menor que 7 MB.
Utilice Base64 o una ruta local para evitar tiempos de espera de descarga en el servidor y mejorar la estabilidad.
Los modelos de comprensión visual tienen límites de tamaño para los archivos de entrada. Utilice los siguientes métodos para comprimir sus archivos.
  • Herramientas en línea: Utilice herramientas en línea como CompressJPEG para comprimir imágenes.
  • Software local: Utilice software como Photoshop para ajustar la calidad al exportar.
  • Implementación de código:
# 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")
  • Herramientas en línea: Utilice herramientas en línea como FreeConvert para comprimir videos.
  • Software local: Utilice software como HandBrake.
  • Implementación de código: Utilice la herramienta FFmpeg. Para más información, consulte el sitio web oficial 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
Después de que el modelo de comprensión visual devuelva los resultados de ubicación de objetos, puede utilizar el siguiente código para dibujar los cuadros de detección y su información de etiqueta en la imagen original.
  • Qwen2.5-VL: Las coordenadas devueltas son valores absolutos en píxeles, relativos a la esquina superior izquierda de la imagen escalada. Para dibujar marcos de detección, consulte el código en qwen2_5_vl_2d.py.
  • Las series Qwen3-VL, Qwen3.5, Qwen3.6 y Qwen3.7 (como qwen3.5-plus, qwen3.6-plus y qwen3.7-plus): Las coordenadas devueltas son relativas y están normalizadas en el rango [0, 999]. Para dibujar marcos de detección, consulte el código en qwen3_vl_2d.py (posicionamiento 2D) o qwen3_vl_3d.zip (posicionamiento 3D).

Códigos de error

Si falla una llamada al modelo, se devuelve un mensaje de error. Para obtener información sobre cómo resolver el error, consulte Códigos de error.