Référence d'utilisation héritée et correspondances de migration de la version 1.x vers la 2.0 du SDK Python DashScope, destinée aux projets existants encore en 1.x.
Cette page s'adresse aux projets existants encore sur le SDK Python DashScope 1.x. Elle rassemble en un seul endroit les usages typiques des interfaces 1.x et présente le code 2.0 équivalent.
La version 1.x du SDK se configure via des variables globales au niveau du module ; la 2.0 se configure via les arguments du constructeur
Les tâches pas à pas (1.x
Le contrôle pas à pas (ancienne boucle
La 1.x utilise des classes de callback (
La reconnaissance ponctuelle d'un fichier local (1.x
En 1.x,
La synthèse ponctuelle utilise
Les embeddings par lot (1.x
Les appels d'application en streaming conservent le paramètre
Au-delà des noms d'interfaces, notez ces différences de comportement lors de la migration :
Correspondances de migration des interfaces
| Capacité | Interface 1.x | Interface 2.0 |
|---|---|---|
| Génération de texte | Generation.call / AioGeneration.call | client.chat.completions.create |
| Chat multimodal | MultiModalConversation.call | client.multimodal.chat.create |
| Génération d'images | ImageSynthesis.call/async_call/fetch/wait | client.images.generate / client.images.jobs.* |
| Génération de vidéo | VideoSynthesis.call/async_call/fetch/wait | client.videos.generate / client.videos.jobs.* |
| Transcription de fichiers audio | Transcription.async_call/fetch/wait | client.audio.asr.transcribe / client.audio.asr.jobs.* |
| Reconnaissance vocale en temps réel | Recognition.start/send_audio_frame/stop | client.audio.asr.recognize(...) context manager |
| Synthèse vocale | SpeechSynthesizer (tts_v2 callback style) | client.audio.tts.synthesize/stream/connect |
| Embeddings de texte | TextEmbedding.call / BatchTextEmbedding | client.embeddings.create / client.embeddings.jobs.* |
| Rerank | TextReRank.call | client.rerank.create |
| Application agent | Application.call | client.apps.completions.create |
| Gestion des fichiers | Files.upload/list/get/delete | client.files.upload/list/get/delete |
| Liste des modèles | Models.list/get | client.models.list/get |
Construction du client et authentification
La version 1.x du SDK se configure via des variables globales au niveau du module ; la 2.0 se configure via les arguments du constructeur Client (priorité : constructeur > dashscope.settings > variables d'environnement > ~/.dashscope/config.toml).
Génération de texte
Chat multimodal
Génération d'images
async_call/fetch/wait) correspondent à client.images.jobs.create/fetch/wait ; le contrôle du statut de la tâche passe de rsp.output.task_status == 'SUCCEEDED' à job.succeeded.
Génération de vidéo
En 1.x,
extend_prompt de VideoSynthesis vaut True par défaut ; en 2.0, il s'agit de prompt_extend et la valeur par défaut est décidée par le serveur. Les appels qui reposaient sur l'ancienne valeur par défaut doivent passer prompt_extend=True explicitement.Transcription de fichiers audio
async_call + fetch) correspond à client.audio.asr.jobs.create + une boucle jobs.fetch.
Reconnaissance vocale en temps réel
La 1.x utilise des classes de callback (Recognition + RecognitionCallback) ; la 2.0 utilise un gestionnaire de contexte + une itération d'événements.
Recognition.call(file)) correspond à for event in client.audio.asr.recognize_file(path, model=...):.
Synthèse vocale
En 1.x, tts_v2 reçoit l'audio via des callbacks ; en 2.0, on utilise le style itération/session.
client.audio.tts.synthesize(text, model=..., voice=...) ; le streaming pur itère client.audio.tts.stream(text, ...).
Embeddings et rerank
BatchTextEmbedding) correspondent à client.embeddings.jobs.create/fetch/wait. TextReRank.call correspond à client.rerank.create, les résultats passant de resp.output.results[i] à resp.results[i].
Appels d'application agent
incremental_output (il détermine la forme des trames) ; la sortie par trame passe de response.output.text à partial.text.
Différences de comportement
Au-delà des noms d'interfaces, notez ces différences de comportement lors de la migration :
- Gestion des erreurs : la 1.x vérifie
status_code/codesur la réponse ; la 2.0 lève par défaut la famille d'exceptionsDashScopeError(avece.code/e.status_code/e.request_id/e.message). Pour un comportement de type enveloppe, construisezClient(raise_on_error=False). - Sortie en streaming : en 1.x,
Generation.call(stream=True)renvoie par défaut le texte complet à chaque trame (incremental_output=Truepour les deltas) ; en 2.0, les flux sont toujours incrémentaux. Les applications Model Studio (apps.completions) conservent le commutateurincremental_output. - Attente de tâches asynchrones : en 1.x,
waitattend indéfiniment par défaut et renvoie une réponse d'erreur en cas de délai dépassé ; en 2.0,jobs.waita un budget total par défaut de 24 heures, un sondage à intervalles exponentiels et lève une exception pour les tâches FAILED. - Structure de la réponse : la 1.x encapsule le contenu utile sous
output(response.output.choices[...]) ; la 2.0 est plate (response.choices[...]), avec des raccourcis commeresp.output_textetjob.succeeded. - Paramètres hors signature : les méthodes de ressources de la 2.0 ont des signatures nommées fermées ; les paramètres propres au modèle transmis en 1.x doivent passer par
parameters={...}(les éléments d'image viaextra_input=).
Documentation connexe
- Installation et mise à niveau : Installer le SDK
- Génération de texte : Génération de texte, Sortie en streaming, Conversations multi-tours
- Images et vidéo : Génération d'images, Génération de vidéo
- Voix : Transcription de fichiers audio, Reconnaissance vocale en temps réel, Synthèse vocale en temps réel
- Embeddings et rerank : Embedding, Rerank
- Appels d'application : Application Calling