Skip to main content

API synchrone

Le modèle d'embedding de texte généraliste convertit des données textuelles en vecteurs numériques. Ces vecteurs alimentent ensuite des tâches en aval telles que la recherche sémantique, la recommandation, le clustering et la classification.

Présentation des modèles

  • Singapour
  • Chine (Pékin)
  • Chine (Hong Kong)
ModèleDimensions de l'embeddingNombre maximal de lignesNombre maximal de tokens par ligne(Remarque)Tarif (pour 1 M de tokens en entrée)Langues prises en chargeQuota gratuit(Remarque)
qwen3.7-text-embedding2 560, 2 048, 1 536, 1 024 (par défaut), 768, 512, 25620128 0000,07 $Chinois, anglais, espagnol, français, portugais, indonésien, japonais, coréen, allemand, russe, ainsi que plus de 200 autres langues et dialectes majeurs1 million de tokensValidité : 90 jours après l'activation de Model Studio
text-embedding-v4
Fait partie de la série Qwen3-Embedding
2 048, 1 536, 1 024 (par défaut), 768, 512, 256, 128, 64108 1920,07 $Chinois, anglais, espagnol, français, portugais, indonésien, japonais, coréen, allemand, russe, ainsi que plus de 100 autres langues majeures1 million de tokensValidité : 90 jours après l'activation de Model Studio
text-embedding-v31 024 (par défaut), 768, 512Chinois, anglais, espagnol, français, portugais, indonésien, japonais, coréen, allemand, russe, ainsi que plus de 50 autres langues majeures500 000 tokensValidité : 90 jours après l'activation de Model Studio
Pour connaître les limites de taux des modèles, consultez Limitation du débit.

Prérequis

Les utilisateurs familiers de l'écosystème OpenAI peuvent utiliser l'API compatible OpenAI pour une migration rapide. L'API DashScope offre quant à elle des fonctionnalités supplémentaires spécifiques. 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.

Compatibilité OpenAI

Cloud public

Labase_urlà configurer pour les appels SDK : L'endpointà configurer pour les appels HTTP :POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. Labase_urlà configurer pour les appels SDK :
  • Singapour : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
  • Chine (Pékin) : https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
  • Chine (Hong Kong) : https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
L'endpointà configurer pour les appels HTTP :
  • Singapour : POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/embeddings. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
  • Chine (Pékin) : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings
  • Chine (Hong Kong) : POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/embeddings. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Corps de la requête

  • Chaîne en entrée
  • Liste de chaînes en entrée
  • Fichier en entrée
  • Python
  • Java
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # If you use a model in the China (Beijing) region, you must use an API key from that region. Get one at: https://modelstudio.console.alibabacloud.com/?tab=model#/api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # If the environment variable is not set, replace the placeholder with your API key.
    # This is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs differ by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

completion = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input='The clothes are of good quality and look good, definitely worth the wait. I love them.',
    dimensions=1024,
    encoding_format="float"
)

print(completion.model_dump_json())
modelstringobligatoireNom du modèle à appeler. Consultez le tableau Présentation des modèles pour obtenir la liste des noms de modèles.
inputarray<string> or string or fileobligatoireTexte d'entrée à traiter. L'entrée peut être une chaîne, un tableau de chaînes ou un fichier. Les limites de longueur de texte et de taille de lot varient selon la version du modèle :
  • Modèle qwen3.7-text-embedding :
    • Entrée de type chaîne : jusqu'à 128 000 tokens.
    • Entrée de type liste de chaînes ou fichier : jusqu'à 20 éléments (lignes), chaque élément (ligne) pouvant contenir jusqu'à 128 000 tokens.
  • Modèles text-embedding-v3 / v4 :
    • Entrée de type chaîne : longueur maximale de 8 192 tokens.
    • Entrée de type liste de chaînes ou fichier : jusqu'à 10 éléments (lignes), chaque élément (ligne) pouvant contenir jusqu'à 8 192 tokens.
dimensions integer facultatifDimension des vecteurs d'embedding en sortie. Doit correspondre à l'une des valeurs suivantes : 2560 (uniquement pour qwen3.7-text-embedding),2048 (uniquement pour text-embedding-v4), 1536 (uniquement pour text-embedding-v4), 1024, 768, 512, 256, 128 ou 64. La valeur par défaut est 1024.
encoding_format string facultatifFormat des embeddings retournés. Actuellement, seul le format float est pris en charge.

Objet de réponse

{
  "data": [
    {
      "embedding": [
        -0.0695386752486229, 0.030681096017360687, ...
      ],
      "index": 0,
      "object": "embedding"
    },
    ...
    {
      "embedding": [
        -0.06348952651023865, 0.060446035116910934, ...
      ],
      "index": 5,
      "object": "embedding"
    }
  ],
  "model": "qwen3.7-text-embedding",
  "object": "list",
  "usage": {
    "prompt_tokens": 184,
    "total_tokens": 184
  },
  "id": "73591b79-d194-9bca-8bb5-xxxxxxxxxxxx"
}
dataarrayListe des objets d'embedding résultants.

Propriété

embeddinglistVecteur d'embedding, retourné sous forme de tableau de nombres à virgule flottante.indexintegerIndex du texte d'entrée correspondant dans le tableau d'entrée.objectstringType d'objet. La valeur est toujours embedding.
modelstringNom du modèle utilisé pour cet appel.
objectstringType d'objet. La valeur est toujours list.
usageobject

Propriété

prompt_tokensintegerNombre de tokens dans le texte d'entrée.total_tokens integerNombre total de tokens dans l'entrée. Ce décompte dépend de la manière dont le tokenizer du modèle analyse la chaîne d'entrée.
idstringIdentifiant unique de la requête, utilisé pour le suivi et le dépannage.

DashScope

Cloud public

base_urlpour les appels SDK : https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1 Endpoint pour les appels HTTP : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. base_urlpour les appels SDK :
  • Singapour : https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
  • Chine (Pékin) : https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
  • Chine (Hong Kong) : https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
Endpoint pour les appels HTTP :
  • Singapour : POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
  • Chine (Pékin) : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding
  • Chine (Hong Kong) : POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding. Remplacez WorkspaceId par votre véritable ID d'espace de travail.
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

Request body

  • Input string
  • Input string list
  • Input file
  • Python
  • Java
  • curl
import os
import dashscope

# Voici la configuration de la région de Singapour (ap-southeast-1). 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 sont spécifiques à chaque région. Pour obtenir une API Key, consultez https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input='A swift wind, a high sky, and the gibbons cry mournfully. A clear islet, white sand, and the birds fly back. Boundless rustling woods shed their leaves. The endless Yangtze River comes rolling in.',
    dimension=1024,  # Spécifie la dimension du vecteur (prise en charge uniquement par qwen3.7-text-embedding, text-embedding-v3 et text-embedding-v4)
    output_type="dense&sparse"
)

print(resp)
modelstringrequiredModèle à utiliser. Pour consulter la liste des modèles disponibles, reportez-vous au tableau Présentation des modèles.
inputstringouarray<string>requiredTexte à traiter. L'entrée peut être une chaîne de caractères, un tableau de chaînes ou un fichier. La longueur du texte et la taille de lot prises en charge varient selon la version du modèle.
  • Modèle qwen3.7-text-embedding :
    • Entrée de type chaîne : jusqu'à 128 000 tokens.
    • Entrée de type liste de chaînes ou fichier : jusqu'à 20 éléments (lignes), chaque élément (ligne) pouvant contenir jusqu'à 128 000 tokens.
  • Modèles text-embedding-v3 / v4 :
    • Entrée de type chaîne : longueur maximale de 8 192 tokens.
    • Entrée de type liste de chaînes ou fichier : jusqu'à 10 éléments (lignes), chaque élément (ligne) pouvant contenir jusqu'à 8 192 tokens.
text_type stringoptional
Lors d'un appel HTTP, placez text_typedans l'objet parameters.
Le texte converti en embeddings peut servir à des tâches en aval telles que la récupération, le clustering et la classification. Pour les tâches asymétriques comme la récupération, il est recommandé de distinguer le texte de requête (query) du texte de document (document) afin d'optimiser les performances. Pour les tâches symétriques telles que l'indexation, le clustering ou la classification, la valeur par défaut du système, document, suffit généralement.
dimension integer optional
Lors d'un appel HTTP, placez dimensiondans l'objet parameters.
Définit la dimension d'embedding pour le vecteur de sortie. Les valeurs valides sont 2560 (uniquement pour qwen3.7-text-embedding),2048 (uniquement pour text-embedding-v4), 1536 (uniquement pour text-embedding-v4), 1024, 768, 512, 256, 128 ou 64. La valeur par défaut est 1024.
output_type string optional
Lors d'un appel HTTP, placez output_typedans l'objet parameters.
Spécifie le type de vecteur de sortie. Ce paramètre s'applique uniquement aux modèles qwen3.7-text-embedding,``text-embedding-v3 et text-embedding-v4. Les valeurs valides sont dense, sparse et dense&sparse. La valeur par défaut est dense, ce qui renvoie uniquement la représentation vectorielle dense.
instruct string optionalFournit des instructions personnalisées pour guider le modèle dans la compréhension de l'intention de la requête. Il est recommandé d'utiliser des instructions en anglais, car elles améliorent généralement les performances de 1 % à 5 %.

Response object

{
    "request_id": "1ba94ac8-e058-99bc-9cc1-7fdb37940a46",
    "embeddings": [
      {
         "index": 0,
         "sparse_embedding":[
           {"index":7149,"value":0.829,"token":"swift"},
           .....
           {"index":111290,"value":0.9004,"token":"mournfully"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 1,
         "sparse_embedding":[
           {"index":246351,"value":1.0483,"token":"islet"},
           .....
           {"index":2490,"value":0.8579,"token":"back"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 2,
         "sparse_embedding":[
           {"index":3759,"value":0.7065,"token":"Boundless"},
           .....
           {"index":1130,"value":0.815,"token":"leaves"}],
         "embedding": [-0.006929283495992422,-0.005336422007530928, ...]
      },
      {
         "index": 3,
         "sparse_embedding":[
           {"index":562,"value":0.6752,"token":"endless"},
           .....
           {"index":1589,"value":0.7097,"token":"in"}],
         "embedding": [-0.001945948973298072,-0.005336422007530928, ...]
      }
    ],
    "usage":{
        "total_tokens":27
    }
}
status_code stringCode de statut HTTP. La valeur 200 indique un succès.
request_id stringIdentifiant unique de la requête. Utilisez cet ID pour tracer et diagnostiquer la requête.
code stringCode d'erreur renvoyé en cas d'échec de la requête. Ce champ est vide pour les requêtes réussies.
message stringMessage d'erreur détaillé en cas d'échec de la requête. Ce champ est vide pour les requêtes réussies.
outputobjectRésultat de la tâche.

Properties

embeddingsarraySortie du modèle pour la requête. Il s'agit d'un tableau d'objets, chaque objet correspondant à un texte d'entrée.
sparse_embedding arrayReprésentation vectorielle creuse de la chaîne correspondante. Cela s'applique uniquement à text-embedding-v3 et text-embedding-v4.
index integerIndex du token dans le vocabulaire.value floatIndique le poids ou le score d'importance du Token. Plus la valeur est élevée, plus l'importance ou la pertinence du Token dans le contexte textuel actuel est grande.token stringTexte du token.
embedding arrayReprésentation vectorielle dense pour la chaîne correspondante.text_index integerIndex du texte correspondant dans le tableau d'entrée.
usageobject

Properties

total_tokens integerNombre de tokens dans l'entrée, tel que calculé par le tokenizer du modèle.

Codes d'erreur

En cas d'échec lors de l'appel d'un modèle, consultez la rubrique Messages d'erreur.