DashScope SDK Expert

​

Início rápido

1. Prepare a API key e a base_url: crie uma key (com o prefixo sk-) no console do Model Studio, em "API Key Management"; as keys são específicas por região. Configure por variável de ambiente ou com /setup na sessão:
   Copy

   export DASHSCOPE_API_KEY=sk-xxxxxxxx
   export DASHSCOPE_HTTP_BASE_URL=https://{workspace-id}.{region}.maas.aliyuncs.com/api/v1
   
   A base_url varia por região; para o mapeamento de domínios, consulte Base URL overview.
2. Instale ou atualize o SDK: o SDK Expert foi introduzido no dashscope Python SDK 1.27.3.
   Copy

   # se falhar, substitua pip por pip3
   pip install -U dashscope
   
3. Inicie a CLI: execute dashscope (sem subcomando) para entrar na sessão interativa do SDK Expert; ou python -m dashscope.acli (acli é o módulo de entrada da CLI do SDK Expert). Na primeira execução, será solicitado o download do pacote de conhecimento do SDK Expert (que inclui as skills api-doc/diagnose, entre outras); também é possível instalá-lo manualmente:
   Copy

   dashscope
   # ou instale manualmente o pacote de conhecimento do SDK Expert
   python -m dashscope.acli example download dashscope-sdk-expert
   
4. Consulte a ajuda: digite /help para ver todos os commands e skills. Commands são operações da sessão (por exemplo, /clear /help /exit); skills são chaves de recursos por domínio (/skill <nome>). Em caso de dúvida, basta perguntar em linguagem natural e o SDK Expert seleciona a skill automaticamente.
5. Pergunte conforme a necessidade: descreva o que você precisa em linguagem natural, por exemplo:
   • "Gere saída em streaming com qwen-plus e conte o consumo de tokens"
   • "O que significa o erro Throttling.RateQuota e como corrigi-lo?"
   • "Leia gen.py e diagnostique a causa raiz do erro InvalidParameter"
   Também é possível usar Ctrl+T para entrada por voz, @caminho-do-arquivo para anexar um arquivo que o SDK Expert vai ler e ↑ para o histórico de comandos.

​

Visão geral da cobertura

​

Prática recomendada 1: apenas informe o que precisa — sem ler documentação, receba código executável

1. Comparar com a base de conhecimento interna do SDK (lista de modelos/parâmetros/estrutura de entrada e saída/códigos de erro)
2. Verificar a versão local do SDK (avisando para atualizar em caso de divergência)
3. Gerar código executável e realmente executá-lo, mostrando a saída

> Gere um parágrafo em streaming com qwen-plus e conte o consumo de tokens

SDK Expert:
1. Seleciona a skill api-doc/sdk-example e confere a versão local do dashscope
2. Gera um script e o executa, mostrando a saída em streaming e as estatísticas de tokens (veja abaixo)

import os, dashscope
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
for chunk in dashscope.Generation.call(
    model="qwen-plus",
    messages=[{"role": "user", "content": "Escreva um poema sobre o outono"}],
    result_format="message", stream=True, incremental_output=True,
):
    if chunk.status_code == 200:
        print(chunk.output.choices[0].message.content, end="", flush=True)
# o último chunk contém usage (input/output tokens)

As folhas de outono caem... (streaming caractere por caractere)
usage: input=10 output=52

• Especifique linguagem/framework: por exemplo, "Encapsule como um endpoint FastAPI", "Chame com async/await"
• Especifique a versão: "Usamos o dashscope 1.20.x — esse parâmetro é suportado?" — o SDK Expert verifica a versão instalada antes de responder
• Pergunte detalhes: "Qual é a faixa de valores do parâmetro?" "Quais outros modelos estão disponíveis?"

​

Prática recomendada 2: solução de problemas — deixe o SDK Expert localizar e corrigir bugs

1. Cole o código/mensagem de erro → /skill error-code <código> (por exemplo, /skill error-code Throttling.RateQuota) → o SDK Expert informa o significado do código de erro + sugestões de correção aplicáveis (ajustar a concorrência/alterar parâmetros/solicitar cota) + um trecho de código opcional.
2. Informe o caminho do arquivo de código com problema → /skill diagnose <caminho do arquivo> (por exemplo, /skill diagnose gen.py) → o SDK Expert lê o código-fonte, compara com causas raiz comuns (mistura do formato antigo de prompt, estrutura de messages incorreta, api_key/workspace não configurados, tarefa assíncrona sem polling correto) e apresenta a causa raiz suspeita + pontos de correção sugeridos.
3. Ciclo de correção automática → /skill diagnose localiza a causa raiz → gera uma prévia de diff para você confirmar → após a confirmação, o SDK Expert aplica a correção e reexecuta o script para validar → formando o fluxo "ler → diagnosticar → corrigir → validar". O SDK Expert pede confirmação antes de alterar arquivos e permite rollback.

> Ao executar gen.py aparece InvalidParameter: url error, me ajude a corrigir

SDK Expert:
1. /skill diagnose gen.py → identifica que um caminho local foi passado em image_url
2. Gera um diff para confirmação (veja abaixo)
3. Aplica após a confirmação, reexecuta o script e retorna 200

- image_url="/tmp/photo.jpg"
+ image_url="https://example.com/photo.jpg"

• Inclua o request_id junto com o erro para correlacionar com os logs do servidor (o request_id está no campo response.request_id do corpo da resposta ou nos atributos do objeto de erro)
• Em problemas complexos, primeiro peça ao SDK Expert para "explicar a lógica deste código" (/skill explain-code) e confirmar o entendimento antes de corrigir
• Se o próprio SDK tiver defeitos ou não atender à sua necessidade, abra uma Issue no GitHub

​

Perguntas frequentes