Skip to main content

API d'embedding multimodal

Les modèles d'embedding multimodal convertissent le texte, les images et les vidéos en embeddings au sein d'un espace sémantique partagé. Cette fonctionnalité permet la recherche intermodale, la classification de contenu et la recherche par similarité.

Fonctionnalités principales

  • Recherche intermodale : Effectuez des recherches sémantiques entre différents types de contenu, par exemple du texte vers l'image, de la vidéo vers l'image ou d'une image à une autre.
  • Similarité sémantique : Mesurez la proximité sémantique entre divers types de contenus dans un espace d'embedding unifié.
  • Classification et clustering de contenu : Regroupez, étiquetez et organisez le contenu en clusters selon les embeddings sémantiques.
Fonctionnalité clé : Les embeddings de toutes les modalités (texte, images et vidéo) partagent le même espace sémantique, ce qui permet la comparaison et la mise en correspondance directes entre modalités via des méthodes telles que la similarité cosinus. Consultez Embedding textuel et multimodal pour plus de détails sur la sélection et l'utilisation des modèles.
qwen3-vl-embedding et multimodal-embedding-v1 sont disponibles uniquement dans la région Chine (Pékin). tongyi-embedding-vision-plus et tongyi-embedding-vision-flash sont disponibles uniquement dans la région Singapore. Pour appeler un modèle, vous devez utiliser une clé API de la région correspondante.

Types d'embeddings

Le modèle d'embedding multimodal prend en charge deux méthodes de génération d'embeddings :
  • Embedding indépendant multimodal : Génère un embedding distinct pour chaque entrée (texte, image, vidéo ou plusieurs images) spécifiée dans contents. Par exemple, une requête contenant une chaîne de texte et une image renvoie deux embeddings indépendants. Cette méthode convient parfaitement à la comparaison d'éléments individuels, comme lors de recherches image-image ou texte-image.
  • Embedding fusionné multimodal : Fusionne toutes les entrées de contents en un seul embedding afin d'obtenir une représentation sémantique intermodale unifiée. Ce mode est adapté aux scénarios nécessitant une compréhension globale du contenu multimodal, par exemple la fusion d'une image produit avec sa description textuelle pour faciliter la recherche. Pour qwen3-vl-embedding, activez la fusion en définissant enable_fusion=true. L'embedding fusionné prend en charge les combinaisons suivantes :
    • Fusion de texte et d'image
    • Fusion de texte et de vidéo
    • Fusion de plusieurs images avec du texte (en passant plusieurs entrées image)
    • Fusion combinant images, vidéo et texte
tongyi-embedding-vision-plus et tongyi-embedding-vision-flash prennent en charge uniquement les embeddings indépendants.
Pour une présentation des modèles, des conseils de sélection et des instructions d'utilisation, consultez Embedding textuel et multimodal.

Aperçu des modèles

  • Singapore
  • China (Beijing)

Modèle

Dimensions de l'embedding

Limite de longueur du texte

Limite de taille d'image

Limite de taille vidéo

Prix (pour 1 M de tokens)

Quota gratuit(Remarque)

tongyi-embedding-vision-plus

1152 (par défaut), 1024, 512, 256, 128, 64

1 024 tokens

Jusqu'à 3 Mo par image. Prend en charge jusqu'à 8 images.

Jusqu'à 10 Mo par fichier vidéo

Image/Vidéo : 0,09 $

Texte : 0,09 $

1 million de tokens

Ce quota gratuit est valable pendant 90 jours à compter de la date d'activation de Model Studio, de la publication du modèle ou de l'approbation de la demande, selon la date la plus tardive.

tongyi-embedding-vision-flash

768 (par défaut), 512, 256, 128, 64

Image/Vidéo : 0,03 $

Texte : 0,09 $

Formats d'entrée et limites d'utilisation

Modèle multimodal fusionné
ModèleTexteImageVidéoLimite de requête
qwen3-vl-embeddingPrend en charge 33 langues principales, dont le chinois, l'anglais, le japonais, le coréen, le français et l'allemand.
Chinois, japonais, coréen, indonésien, vietnamien, thaï, anglais, français, allemand, russe, portugais, espagnol, italien, suédois, danois, tchèque, norvégien, néerlandais, finnois, turc, polonais, swahili, roumain, serbe, grec, kazakh, ouzbek, cebuano, arabe, ourdou, persan, hindi/devanagari et hébreu.
JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS et SGI (URL ou Base64 pris en charge)MP4, AVI et MOV (URL uniquement)Le nombre total d'éléments de contenu dans une requête unique ne peut pas dépasser 20. Le nombre d'images ne peut pas excéder 5. Les images, le texte et les vidéos partagent cette limite.
Modèle multimodal indépendant
ModèleTexteImageVidéoLimite de requête
tongyi-embedding-vision-plusChinois/AnglaisJPG, PNG et BMP (URL ou Base64 pris en charge)MP4, MPEG, AVI, MOV, MPG, WEBM, FLV et MKV (URL uniquement)Aucune limite sur le nombre d'éléments de contenu. Le nombre total de tokens d'entrée ne doit pas dépasser la limite de tokens.
tongyi-embedding-vision-flash
multimodal-embedding-v1Le nombre total d'éléments de contenu dans une requête unique ne peut pas dépasser 20. Une requête peut contenir au maximum une image, une vidéo et 20 entrées de texte. Ces éléments partagent la limite totale.
Tous les modèles acceptent des entrées de texte, d'image et de vidéo, individuellement ou combinées. Les modèles tongyi-embedding-vision-plus , tongyi-embedding-vision-flash prennent également en charge multi_images pour les séquences d'images.

Capacités des modèles

Modèle

Dimension par défaut

Type de vecteur

Entrées prises en charge

Description

qwen3-vl-embedding

2560

Indépendant / Fusion

texte, image, vidéo, images multiples

Le mode fusion, activé via le paramètre enable_fusion, combine les entrées multimodales en un seul vecteur.

tongyi-embedding-vision-plus

1152

Indépendant uniquement

Prend en charge les séquences multi_images (jusqu'à 8 images).

tongyi-embedding-vision-flash

768

multimodal-embedding-v1

1024

texte, image, vidéo

La dimension du vecteur est fixée à 1 024 et ne peut pas être configurée.

Prérequis

Obtenir une clé API et exporter la clé API en tant que variable d'environnement. Si vous utilisez un SDK pour effectuer vos appels, installez le SDK DashScope.

Appel HTTP

POST https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

Requête

  • Embedding indépendant multimodal
  • Embedding fusionné multimodal
L'exemple suivant utilise le modèle tongyi-embedding-vision-plus pour générer un embedding indépendant pour chaque entrée. Vous pouvez remplacer le nom du modèle par un autre modèle pris en charge. Le type multi_images est pris en charge uniquement par tongyi-embedding-vision-plus et tongyi-embedding-vision-flash. Le modèle qwen3-vl-embedding prend également en charge un mode d'embedding fusionné, que vous pouvez activer en définissant enable_fusion=true. Pour plus de détails, consultez l'onglet « Embedding fusionné multimodal ».
curl --silent --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding' \
        --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
        --header 'Content-Type: application/json' \
        --data '{
            "model": "tongyi-embedding-vision-plus",
            "input": {
                "contents": [
                    {"text": "Multimodal embedding model"},
                    {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
                    {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"},
                    {"multi_images": [
                        "https://img.alicdn.com/imgextra/i2/O1CN019eO00F1HDdlU4Syj5_!!6000000000724-2-tps-2476-1158.png",
                        "https://img.alicdn.com/imgextra/i2/O1CN01dSYhpw1nSoamp31CD_!!6000000005089-2-tps-1765-1639.png"
                        ]
                      }
                ]
            }
        }'

En-têtes de requête

Content-Type string (Obligatoire)Le type de contenu de la requête. Doit être application/json.
Authorization string (Obligatoire)Authentifie la requête avec une clé API Model Studio. Exemple : Bearer sk-xxxx.

Corps de la requête

model string(obligatoire)Le nom du modèle. Sélectionnez un modèle dans l'Aperçu des modèles.
input object(obligatoire)Le contenu d'entrée.

Propriétés

contentsarray(obligatoire)Les éléments de contenu à traiter. Chaque élément est un dictionnaire ou une chaîne spécifiant le type de contenu et la valeur au format {"modality_type": "input_string_or_image/video_url"}. Les types de modalité pris en charge sont text, image, video et multi_images.
Le modèle qwen3-vl-embedding prend en charge la génération d'embeddings fusionnés et indépendants. Pour générer un embedding fusionné, ajoutez le champ booléen enable_fusion et définissez-le sur true.
  • Texte : La clé est text et la valeur est une chaîne. Vous pouvez également passer directement la chaîne sans dictionnaire.
  • Image : Utilisez la clé image. La valeur peut être une URL publique ou un Data URI encodé en Base64. Le format Base64 est data:image/{format};base64,{data}, où {format} est le format de l'image, tel que jpeg ou png, et {data} est la chaîne encodée en Base64.
  • Images multiples : Ce type est pris en charge uniquement par les modèles tongyi-embedding-vision-plus, tongyi-embedding-vision-flash. La clé est multi_images et la valeur est une liste d'images. Chaque élément de la liste est une image qui doit respecter le format décrit ci-dessus.
  • Vidéo : La clé est video. La valeur doit être une URL accessible publiquement.
parameters object (facultatif)Paramètres de traitement de l'embedding. Pour les appels HTTP, vous devez encapsuler ces paramètres dans l'objet parameters. Pour les appels SDK, vous pouvez utiliser ces paramètres directement.

Propriétés

output_type string (facultatif)Le format de représentation de l'embedding en sortie. Actuellement, seul le format dense est pris en charge. Les autres valeurs sont ignorées sans erreur et le format dense est renvoyé.dimension integer (facultatif)La dimension de l'embedding en sortie. Les valeurs prises en charge varient selon le modèle :
  • qwen3-vl-embedding : Prend en charge 2560, 2048, 1536, 1024, 768, 512 et 256. La valeur par défaut est 2560.
  • tongyi-embedding-vision-plus : Prend en charge 64, 128, 256, 512, 1024 et 1152. La valeur par défaut est 1152.
  • tongyi-embedding-vision-flash : Prend en charge 64, 128, 256, 512 et 768. La valeur par défaut est 768.
  • multimodal-embedding-v1 : Ne prend pas en charge ce paramètre. Renvoie un embedding fixe de 1024 dimensions.
fps float (facultatif)Le taux d'échantillonnage des frames vidéo. Une valeur plus faible extrait moins de frames. La plage valide est [0, 1] et la valeur par défaut est 1,0. Les valeurs hors de cette plage ne provoquent pas d'erreur.instruct string (facultatif)Une description personnalisée de la tâche pour aider le modèle à comprendre l'intention de la requête. Des instructions en anglais sont recommandées et peuvent améliorer les performances de 1 % à 5 %.enable_fusion bool (facultatif)Spécifie s'il faut générer un embedding fusionné. Ce paramètre est pris en charge uniquement par le modèle qwen3-vl-embedding. Lorsqu'il est défini sur true, tout le contenu multimodal du tableau contents est fusionné en un seul embedding. La valeur par défaut est false, ce qui génère un embedding indépendant pour chaque modalité. Les embeddings fusionnés prennent en charge des combinaisons telles que texte et image, texte et vidéo, images multiples et texte (en passant plusieurs éléments d'image), ainsi qu'un mélange d'images, de vidéos et de texte. Cela convient aux scénarios de recherche nécessitant une compréhension complète du contenu multimodal.

Réponse

  • Réponse réussie
  • Réponse d'erreur
{
    "output": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.026611328125,
                    -0.016571044921875,
                    -0.02227783203125,
                    ...
                ],
                "type": "text"
            },
            {
                "index": 1,
                "embedding": [
                    0.051544189453125,
                    0.007717132568359375,
                    0.026611328125,
                    ...
                ],
                "type": "image"
            },
            {
                "index": 2,
                "embedding": [
                    -0.0217437744140625,
                    -0.016448974609375,
                    0.040679931640625,
                    ...
                ],
                "type": "video"
            }
        ]
    },
    "usage": {
        "input_tokens": 10,
        "input_tokens_details": {
            "image_tokens": 896,
            "text_tokens": 7
        },
        "output_tokens": 3,
        "total_tokens": 906
    },
    "request_id": "1fff9502-a6c5-9472-9ee1-73930fdd04c5"
}
Le champ usage varie selon le modèle. Consultez les descriptions suivantes :
  • Modèles de la série tongyi-embedding-vision-* : Renvoient input_tokens (somme des tokens de texte et d'image), input_tokens_details (incluant image_tokens et text_tokens), output_tokens et total_tokens. L'exemple de réponse ci-dessus correspond à ce type de modèle.
  • qwen3-vl-embedding : Renvoie uniquement input_tokens (tokens de texte uniquement, y compris les tokens de modèle système), image_tokens et total_tokens (= input_tokens + image_tokens). Ne renvoie pas input_tokens_details ni output_tokens. Exemple :
{
    "usage": {
        "input_tokens": 43,
        "image_tokens": 1247,
        "total_tokens": 1290
    }
}
  • multimodal-embedding-v1 : Renvoie input_tokens, image_tokens, image_count et duration. Ne renvoie pas total_tokens, input_tokens_details ni output_tokens.
output objectSortie de la tâche.

Propriétés

embeddings arrayUne liste des embeddings résultants, où chaque objet correspond à un élément d'entrée.

Propriétés

index intL'index du résultat dans la liste d'entrée.embedding arrayLa dimension du tableau d'embeddings généré dépend du modèle et du paramètre dimension.type stringLe type d'entrée pour ce résultat. text, image, video et multi_images correspondent respectivement aux entrées de texte, d'image, de vidéo et d'images multiples. Les types spéciaux incluent : fusion est le type renvoyé par le modèle qwen3-vl-embedding en mode d'embedding fusionné ; vl est le type renvoyé par le modèle qwen3-vl-embedding en mode d'embedding indépendant.
request_id stringIdentifiant unique de la requête pour le suivi et le dépannage.
code stringCode d'erreur. Renvoyé uniquement pour les requêtes ayant échoué. Consultez Codes d'erreur.
message stringMessage d'erreur détaillé. Renvoyé uniquement pour les requêtes ayant échoué. Consultez Codes d'erreur.
usage objectStatistiques sur l'utilisation des tokens.

Propriétés

input_tokens intLe nombre de tokens dans le contenu d'entrée pour la requête actuelle. Pour le modèle qwen3-vl-embedding, cette valeur inclut uniquement les tokens de texte (y compris les tokens de modèle système) et n'inclut pas les tokens d'image ou de vidéo. Pour les modèles de la série tongyi-embedding-vision-*, cette valeur inclut le nombre total de tokens de texte, d'image et de vidéo.input_tokens_details objectUne ventilation détaillée des tokens d'entrée. Ce champ est renvoyé uniquement par les modèles de la série tongyi-embedding-vision-*. Il n'est pas renvoyé par les modèles qwen3-vl-embedding ou multimodal-embedding-v1.

Propriétés

image_tokens intLe nombre de tokens pour les images ou vidéos d'entrée.text_tokens intLe nombre de tokens pour le texte d'entrée.
output_tokens intLe nombre de tokens dans la sortie pour la requête actuelle. Ce champ est renvoyé uniquement par les modèles de la série tongyi-embedding-vision-*.total_tokens intLe nombre total de tokens d'entrée et de sortie. Ce champ est renvoyé par les modèles qwen3-vl-embedding et tongyi-embedding-vision-*, mais pas par le modèle multimodal-embedding-v1. Pour le modèle qwen3-vl-embedding, total_tokens = input_tokens + image_tokens.image_tokens intLe nombre de tokens pour les images ou vidéos d'entrée dans la requête actuelle. Le système échantillonne des frames à partir des vidéos d'entrée, le nombre maximal de frames étant contrôlé par la configuration système, puis calcule les tokens en fonction du résultat traité. Ce champ est renvoyé en tant que champ de premier niveau uniquement par les modèles qwen3-vl-embedding et multimodal-embedding-v1. Pour les modèles de la série tongyi-embedding-vision-*, le nombre de tokens d'image est inclus dans input_tokens_details.image_tokens.image_count intLe nombre d'images dans l'entrée pour la requête actuelle. Ce champ est renvoyé uniquement par le modèle multimodal-embedding-v1.duration intLa durée de la vidéo d'entrée en secondes. Ce champ est renvoyé uniquement par le modèle multimodal-embedding-v1.

Utilisation du SDK

Le paramètre input du SDK correspond à input.contents dans le corps de la requête HTTP, mais leurs structures sont différentes .

Exemples de code

  • Embedding d'image
  • Embedding vidéo
  • Embedding de texte
  • Embedding fusionné
  • Embedding fusionné multi-images
  • Version snapshot 2026-03-06
  • URL d'image
  • Image locale
import os
import dashscope
from dashscope.v2 import DashScopeError
# 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 diffèrent selon la région. Pour obtenir une API Key, consultez https://www.alibabacloud.com/help/model-studio/regions
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)
# En pratique, remplacez l'URL par celle de votre image
image = "https://dashscope.oss-cn-beijing.aliyuncs.com/images/256_1.png"
input = [{'image': image}]
try:
    # Appelle l'API du modèle
    resp = client.multimodal.embeddings.create(
        model="tongyi-embedding-vision-plus",
        input=input
    )
    # Résultat vectoriel : resp.embeddings[i].embedding est le tableau de vecteurs, resp.embeddings[i].index est l'index d'entrée
    print(resp.model_dump_json(indent=4))
except DashScopeError as e:
    print(f"Code de statut HTTP: {e.status_code}")
    print(f"Code d'erreur: {e.code}")
    print(f"Message d'erreur: {e.message}")
    print("Consultez la documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

Exemple de sortie

{
    "request_id": "40532987-ba72-42aa-a178-bb58b52fb7f3",
    "embeddings": [
        {
            "index": 0,
            "embedding": [
                -0.009490966796875,
                -0.024871826171875,
                -0.031280517578125,
                ...
            ],
            "type": "text"
        }
    ],
    "usage": {
        "input_tokens": 10,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 10
        },
        "output_tokens": 1,
        "total_tokens": 11
    }
}

Codes d'erreur

Si l'appel du modèle échoue et renvoie un message d'erreur, consultez Codes d'erreur pour obtenir une solution.