Referência de uso legado e mapeamento de migração de 1.x para 2.0 do SDK Python do DashScope, para projetos existentes que ainda usam a versão 1.x.
Esta página destina-se a projetos existentes que ainda usam o SDK Python do DashScope 1.x. Ela reúne em um só lugar os usos típicos das interfaces 1.x e mostra o código 2.0 equivalente.
A versão 1.x é configurada por variáveis globais no nível do módulo; a 2.0 é configurada pelos argumentos do construtor
Tarefas passo a passo (1.x
O controle passo a passo (antigo
A versão 1.x usa classes de callback (
O reconhecimento pontual de arquivo local (1.x
Na 1.x,
A síntese pontual usa
Embeddings em lote (1.x
As chamadas de aplicação em streaming mantêm o parâmetro
Além dos nomes das interfaces, observe estas diferenças de comportamento ao migrar:
Mapeamento de migração de interfaces
| Capacidade | Interface 1.x | Interface 2.0 |
|---|---|---|
| Geração de texto | Generation.call / AioGeneration.call | client.chat.completions.create |
| Chat multimodal | MultiModalConversation.call | client.multimodal.chat.create |
| Geração de imagens | ImageSynthesis.call/async_call/fetch/wait | client.images.generate / client.images.jobs.* |
| Geração de vídeo | VideoSynthesis.call/async_call/fetch/wait | client.videos.generate / client.videos.jobs.* |
| Transcrição de arquivos de áudio | Transcription.async_call/fetch/wait | client.audio.asr.transcribe / client.audio.asr.jobs.* |
| Reconhecimento de fala em tempo real | Recognition.start/send_audio_frame/stop | client.audio.asr.recognize(...) context manager |
| Síntese de fala | SpeechSynthesizer (tts_v2 callback style) | client.audio.tts.synthesize/stream/connect |
| Embeddings de texto | TextEmbedding.call / BatchTextEmbedding | client.embeddings.create / client.embeddings.jobs.* |
| Rerank | TextReRank.call | client.rerank.create |
| Aplicação de agente | Application.call | client.apps.completions.create |
| Gerenciamento de arquivos | Files.upload/list/get/delete | client.files.upload/list/get/delete |
| Lista de modelos | Models.list/get | client.models.list/get |
Construção do cliente e autenticação
A versão 1.x é configurada por variáveis globais no nível do módulo; a 2.0 é configurada pelos argumentos do construtor Client (prioridade: construtor > dashscope.settings > variáveis de ambiente > ~/.dashscope/config.toml).
Geração de texto
Chat multimodal
Geração de imagens
async_call/fetch/wait) correspondem a client.images.jobs.create/fetch/wait; a verificação do status da tarefa muda de rsp.output.task_status == 'SUCCEEDED' para job.succeeded.
Geração de vídeo
Na versão 1.x,
extend_prompt de VideoSynthesis tem padrão True; na 2.0 ele se chama prompt_extend e o padrão é decidido pelo servidor. Chamadas que dependiam do padrão antigo devem passar prompt_extend=True explicitamente.Transcrição de arquivos de áudio
async_call + laço fetch) corresponde a client.audio.asr.jobs.create + um laço jobs.fetch.
Reconhecimento de fala em tempo real
A versão 1.x usa classes de callback (Recognition + RecognitionCallback); a 2.0 usa um gerenciador de contexto + iteração de eventos.
Recognition.call(file)) corresponde a for event in client.audio.asr.recognize_file(path, model=...):.
Síntese de fala
Na 1.x, tts_v2 recebe o áudio via callbacks; na 2.0 usa-se o estilo de iteração/sessão.
client.audio.tts.synthesize(text, model=..., voice=...); o streaming puro itera client.audio.tts.stream(text, ...).
Embeddings e rerank
BatchTextEmbedding) correspondem a client.embeddings.jobs.create/fetch/wait. O TextReRank.call corresponde a client.rerank.create, e os resultados passam de resp.output.results[i] para resp.results[i].
Chamadas de aplicações de agente
incremental_output (ele determina o formato dos frames); a saída por frame passa de response.output.text para partial.text.
Diferenças de comportamento
Além dos nomes das interfaces, observe estas diferenças de comportamento ao migrar:
- Tratamento de erros: a 1.x verifica
status_code/codena resposta; a 2.0 lança por padrão a família de exceçõesDashScopeError(come.code/e.status_code/e.request_id/e.message). Para um comportamento no estilo envelope, construaClient(raise_on_error=False). - Saída em streaming: na 1.x,
Generation.call(stream=True)reproduz por padrão o texto completo em cada frame (incremental_output=Truepara deltas); na 2.0 os streams são sempre incrementais. As aplicações do Model Studio (apps.completions) mantêm a opçãoincremental_output. - Espera de tarefas assíncronas: o
waitda 1.x espera indefinidamente por padrão e retorna uma resposta de erro no tempo limite; ojobs.waitda 2.0 tem um orçamento total padrão de 24 horas, sondagem com backoff exponencial e lança exceção em tarefas FAILED. - Estrutura da resposta: a 1.x envolve o conteúdo útil sob
output(response.output.choices[...]); a 2.0 é plana (response.choices[...]), com atalhos comoresp.output_textejob.succeeded. - Parâmetros fora da assinatura: os métodos de recursos da 2.0 têm assinaturas nomeadas fechadas; parâmetros específicos do modelo repassados na 1.x devem ir via
parameters={...}(materiais de imagem viaextra_input=).
Documentação relacionada
- Instalação e atualização: Instale o SDK
- Geração de texto: Geração de texto, Streaming output, Conversas de múltiplos turnos
- Imagens e vídeo: Geração de imagens, Geração de vídeo
- Voz: Transcrição de arquivos de áudio, Reconhecimento de fala em tempo real, Síntese de fala em tempo real
- Embeddings e rerank: Embedding, Rerank
- Chamadas de aplicações: Application Calling