DashScope Python SDK 1.x 介面的歷史用法速查與 1.x 到 2.0 的遷移對照,供存量項目參考。
本文面向仍在使用 DashScope Python SDK 1.x 的存量項目,集中收錄 1.x 介面的典型用法,並給出對應的 2.0 寫法。
1.x 通過模組級全域變數配置;2.0 通過
分步任務(1.x
分步控制(原
1.x 使用回調類(
本地檔案一次識別(1.x
1.x
一次性合成(短文字整段返回)用
批量向量(1.x
應用流式調用保留
遷移時除介面名外,還需要注意以下行為差異:
介面遷移總對照
| 能力 | 1.x 介面 | 2.0 介面 |
|---|---|---|
| 文字生成 | Generation.call / AioGeneration.call | client.chat.completions.create |
| 多模態對話 | MultiModalConversation.call | client.multimodal.chat.create |
| 圖像生成 | ImageSynthesis.call/async_call/fetch/wait | client.images.generate / client.images.jobs.* |
| 視頻生成 | VideoSynthesis.call/async_call/fetch/wait | client.videos.generate / client.videos.jobs.* |
| 錄音檔案轉寫 | Transcription.async_call/fetch/wait | client.audio.asr.transcribe / client.audio.asr.jobs.* |
| 即時語音辨識 | Recognition.start/send_audio_frame/stop | client.audio.asr.recognize(...) 上下文管理器 |
| 語音合成 | SpeechSynthesizer(tts_v2 回調式) | client.audio.tts.synthesize/stream/connect |
| 文字向量 | TextEmbedding.call / BatchTextEmbedding | client.embeddings.create / client.embeddings.jobs.* |
| 重排序 | TextReRank.call | client.rerank.create |
| 智能體應用 | Application.call | client.apps.completions.create |
| 檔案管理 | Files.upload/list/get/delete | client.files.upload/list/get/delete |
| 模型列表 | Models.list/get | client.models.list/get |
客戶端構造與鑒權
1.x 通過模組級全域變數配置;2.0 通過 Client 構造參數配置(優先順序:構造參數 > dashscope.settings > 環境變數 > ~/.dashscope/config.toml)。
文字生成
多模態對話
圖像生成
async_call/fetch/wait)對應 client.images.jobs.create/fetch/wait;任務狀態判定由 rsp.output.task_status == 'SUCCEEDED' 改為 job.succeeded。
視頻生成
1.x
VideoSynthesis 的 extend_prompt 預設為 True;2.0 為 prompt_extend 且預設由服務端決定,依賴舊預設的調用需顯式傳 prompt_extend=True。錄音檔案轉寫
async_call + 迴圈 fetch)對應 client.audio.asr.jobs.create + 迴圈 jobs.fetch。
即時語音辨識
1.x 使用回調類(Recognition + RecognitionCallback);2.0 改為上下文管理器 + 事件迭代。
Recognition.call(file))對應 for event in client.audio.asr.recognize_file(path, model=...):。
語音合成
1.x tts_v2 使用回調收音頻;2.0 改為迭代/會話式。
client.audio.tts.synthesize(text, model=..., voice=...);純流式用 client.audio.tts.stream(text, ...) 迭代 bytes。
文字向量與重排序
BatchTextEmbedding)對應 client.embeddings.jobs.create/fetch/wait。重排序 TextReRank.call 對應 client.rerank.create,取值由 resp.output.results[i] 改為 resp.results[i]。
智能體應用調用
incremental_output 參數(幀形態由它決定),逐幀取值由 response.output.text 改為 partial.text。
行為差異要點
遷移時除介面名外,還需要注意以下行為差異:
- 錯誤處理:1.x 在響應物件上自查
status_code/code;2.0 預設失敗直接拋DashScopeError異常族(含e.code/e.status_code/e.request_id/e.message),需要信封風格可構造Client(raise_on_error=False)。 - 流式輸出:1.x
Generation.call(stream=True)預設每幀重放全量文字(需incremental_output=True才增量);2.0 流式一律增量。百鍊應用(apps.completions)保留incremental_output開關。 - 非同步任務等待:1.x
wait預設無限等待、超時返回錯誤響應;2.0jobs.wait預設 24 小時總預算、指數退避輪詢、任務 FAILED 拋異常。 - 響應結構:1.x 業務內容包裹在
output欄位下(response.output.choices[...]);2.0 已扁平化(response.choices[...]),並新增resp.output_text、job.succeeded等便捷取值。 - 簽名外參數:2.0 各資源方法為封閉具名簽名,1.x 透傳的模型專屬參數需改走
parameters={...}(圖像素材類走extra_input=)。