Skip to main content
Ajuste fino do modelo Qwen

Fine-tune with the API or CLI

Ajuste modelos Qwen no Model Studio por meio da API (HTTP) ou CLI (shell). Três métodos de ajuste são suportados: ajuste fino supervisionado (SFT), pré-treinamento contínuo (CPT) e otimização direta de preferência (DPO).

Pré-requisitos

A API suporta apenas faturamento baseado em tokens. Para usar unidades de treinamento de modelo (pré-pagas ou pós-pagas), crie o job no console.

Envie arquivos de ajuste

Preparação de arquivos de ajuste fino

  • Conjunto de treinamento SFT
Os dados de treinamento no formato SFT ChatML (Chat Markup Language) suportam conversas de múltiplas rodadas e várias configurações de função.
Os parâmetros name e weight do OpenAI não são suportados. Todas as saídas do assistente serão treinadas.
# A single line of training data (in JSON format) has the following typical structure when expanded:
{"messages": [
  {"role": "system", "content": "System input 1"},
  {"role": "user", "content": "User input 1"},
  {"role": "assistant", "content": "Expected model output 1"},
  {"role": "user", "content": "User input 2"},
  {"role": "assistant", "content": "Expected model output 2"}
  ...
]}
Para obter informações sobre as diferenças entre system, user e assistant, consulte Overview. Conjuntos de dados de treinamento de exemplo: SFT-ChatML_format_example.jsonl, SFT-ChatML_format_example.xlsx. Os formatos XLS e XLSX suportam apenas conversas de rodada única.Todas as linhas de assistente em uma única entrada de dados de treinamento suportam o parâmetro "loss_weight", que define a importância relativa dessa linha durante o treinamento. (Intervalo: 0.0 a 1.0. Um valor maior indica maior importância.)
Este parâmetro está disponível para visualização por convite. Para usá-lo, entre em contato com seu gerente de conta.
 {"role": "assistant", "content": "Expected model output 1", "loss_weight": 1.0},
 {"role": "assistant", "content": "Expected model output 2", "loss_weight": 0.5}

Você também pode baixar um modelo de dados no console do Model Studio.

Abaixo da área de upload de arquivo na página Create Dataset, você encontra o link para download do data template.

Faça upload do arquivo de ajuste fino para o Model Studio

  • OpenAI-compatible Files API
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with api_key="sk-xxx" and use your Model Studio API key.
    # API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the URL for the Singapore region. If you use a service in the China (Beijing) region, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl is a local sample file.
file_object = client.files.create(file=Path("test.jsonl"), purpose="fine-tune")

print(file_object.model_dump_json())
Limitações:
  • O tamanho máximo de um único arquivo é de 300 MB.
  • O tamanho total de todos os arquivos não excluídos é limitado a 5 GB.
  • É possível armazenar no máximo 100 arquivos não excluídos.
  • Os arquivos são armazenados indefinidamente.

Ajuste fino de modelo

Crie uma tarefa de ajuste fino

  • HTTP
No Windows CMD, substitua ${DASHSCOPE_API_KEY} por %DASHSCOPE_API_KEY% . No PowerShell, use $env:DASHSCOPE_API_KEY .
curl --location "https://dashscope.aliyuncs.com/api/v1/fine-tunes" \
--header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
    "model":"qwen3-8b",
    "training_file_ids":[
        "<your_training_file_id_1>",
        "<your_training_file_id_2>"
    ],
    "hyper_parameters":
    {
        "n_epochs": 3,
        "batch_size": 16,
        "max_length": 8192,
        "learning_rate": "1.6e-5",
        "lr_scheduler_type": "linear",
        "split": 0.9,
        "warmup_ratio": 0.05,
        "eval_steps": 50,
        "data_augmentation": true,
        "augmentation_ratio": "0.1,0.05,0.15",
        "augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
        "save_strategy": "epoch",
        "save_total_limit": 10
    },
    "training_type":"sft"
}'

Parâmetros

Parâmetro

Obrigatório

Tipo

Localização

Descrição

training_file_ids

Sim

Array

Body

Lista de IDs de arquivo para o conjunto de treinamento.

validation_file_ids

Não

Array

Body

Lista de IDs de arquivo para o conjunto de validação.

model

Sim

String

Body

ID do modelo base ou ID de um modelo previamente ajustado.

hyper_parameters

Não

Map

Body

Hiperparâmetros da tarefa de ajuste fino. Os valores padrão variam conforme o modelo; consulte o console para detalhes específicos.

Os parâmetros a seguir são obrigatórios, pois afetam o custo do treinamento: n_epochs, batch_size e max_length.

training_type

Não

String

Body

Método de ajuste fino. Valores válidos:

cpt

sft

efficient_sft

dpo_full

dpo_lora

job_name

Não

String

Body

Nome da tarefa de ajuste fino.

model_name

Não

String

Body

Nome do modelo ajustado (diferente do ID gerado pelo sistema).

Resposta

{
    "request_id": "635f7047-003e-4be3-b1db-6f98e239f57b",
    "output":
    {
        "job_id": "ft-202511272033-8ae7",
        "job_name": "ft-202511272033-8ae7",
        "status": "PENDING",
        "finetuned_output": "qwen3-8b-ft-202511272033-8ae7",
        "model": "qwen3-8b",
        "base_model": "qwen3-8b",
        "training_file_ids":
        [
            "9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"
        ],
        "validation_file_ids":
        [],
        "hyper_parameters":
        {
            "n_epochs": 3,
            "batch_size": 16,
            "max_length": 8192,
            "learning_rate": "1.6e-5",
            "lr_scheduler_type": "linear",
            "split": 0.9,
            "warmup_ratio": 0.05,
            "eval_steps": 50,
            "data_augmentation": true,
            "augmentation_ratio": "0.1,0.05,0.15",
            "augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
            "save_strategy": "epoch",
            "save_total_limit": 10
        },
        "training_type": "sft",
        "create_time": "2025-11-27 20:33:15",
        "workspace_id": "llm-8v53etv3hwb8orx1",
        "user_identity": "1654290265984853",
        "modifier": "1654290265984853",
        "creator": "1654290265984853",
        "group": "llm",
        "max_output_cnt": 10
    }
}

Modelos suportados

  • Singapore
  • North China 2 (Beijing)
  • Geração de texto
  • Compreensão visual (Qwen-VL)

Nome do modelo

Código do modelo

Treinamento SFT com parâmetros completos (sft)

Treinamento SFT eficiente (efficient_sft)

Qwen3-14B

qwen3-14b

×

Suportado

Comparação dos métodos de ajuste fino

Recurso

CPT (Pré-treinamento Contínuo)

SFT (Ajuste Fino Supervisionado)

DPO (Otimização Direta de Preferência)

Resumo

Complementa conhecimento (Injeta conhecimento de domínio)

Aprende a executar tarefas (Segue instruções)

Executa tarefas com maior qualidade (Alinha-se às preferências humanas)

Dados de entrada

Mais de 10 milhões de tokens

Texto de domínio não rotulado

Mais de 1.000 entradas

Pares "pergunta-resposta" de alta qualidade

Mais de 100 conjuntos

Pares de respostas "melhor-pior" para a mesma instrução

Objetivo principal

Adaptação ao domínio. Aprende vocabulário especializado e fatos.

Ensina ao modelo formatos de conversa e capacidades de execução de tarefas.

Faz com que as saídas do modelo se alinhem melhor aos valores e preferências humanos.

Método de aprendizado

Aprendizado auto-supervisionado (Prevê a próxima palavra)

Aprendizado supervisionado (Imita o ground truth)

Aprendizado direto de preferência (Aumenta a probabilidade de boas respostas e diminui a de respostas ruins)

Estágio do modelo

Geralmente antes do SFT

Após o CPT e antes do DPO

Geralmente após o SFT, como etapa final de alinhamento.

Comparação dos padrões de treinamento

Treinamento com parâmetros completos

Treinamento eficiente (LoRA, recomendado)

Cenários

• O modelo precisa adquirir novas capacidades

• Busca de desempenho global ideal.

• Otimização do desempenho do modelo para cenários específicos.

• Cenários sensíveis a custo e tempo.

Tempo de treinamento

Mais longo, com convergência mais lenta.

Mais curto, com convergência mais rápida.

Os parâmetros suportados e seus valores padrão variam conforme o modelo. Para visualizar os valores padrão específicos, acesse o console e selecione o modelo e o método de treinamento .
ParâmetroConfiguração recomendadaTipoDescrição
n_epochs(Número de épocas) [Obrigatório]Tamanho dos dados < 10.000: 3–5Tamanho dos dados > 10.000: 1–2IntegerQuantas vezes o modelo itera sobre todo o conjunto de treinamento.Mais épocas aumentam o tempo e o custo do treinamento.
learning_rate(Taxa de aprendizado)Use o valor padrão recomendado pelo Model Studio.FloatControla o tamanho do passo para atualizações de peso durante o treinamento.
  • Muito alta: o treinamento pode divergir.
  • Muito baixa: convergência lenta com melhoria mínima.
freeze_vit(Congelar backbone visual)Ajuste conforme necessárioBooleanCongela o backbone visual para que seus pesos não sejam atualizados durante o treinamento. Aplica-se apenas aos modelos Qwen-VL.
O faturamento por token está disponível apenas quando freeze_vit é definido como "true".
batch_size(Tamanho do lote) [Obrigatório]Use o valor padrão recomendado pelo Model Studio.IntegerNúmero de exemplos de treinamento por iteração. Valores pequenos aumentam significativamente o tempo de treinamento. Os padrões variam conforme o modelo.
eval_steps(Passos de avaliação)Ajuste conforme necessárioIntegerIntervalo de passos para avaliar a precisão e a perda do treinamento.Controla a frequência com que Validation Loss e Validation Token Accuracy são reportados.
logging_steps(Passos de log)Ajuste conforme necessárioIntegerIntervalo de passos para registrar o progresso do treinamento em log.
lr_scheduler_type(Agendador de taxa de aprendizado)Recomendado linear/Inverse_sqrtStringEstratégia para ajustar a taxa de aprendizado durante o treinamento.Cada estratégia é descrita em Fine-tune a model in the console.
max_length(Comprimento da sequência) [Obrigatório]8192IntegerComprimento máximo da sequência (em tokens) por exemplo de treinamento. Exemplos mais longos são descartados.How to convert between tokens and characters.
max_split_val_dataset_sample(Amostras máximas do conjunto de validação)Use o valor padrão recomendado pelo Model Studio.IntegerQuando "validation_file_ids" não está definido, o conjunto de validação dividido automaticamente pelo Model Studio contém no máximo 1.000 entradas.Este parâmetro não tem efeito quando "validation_file_ids" está definido.
split(Proporção do conjunto de treinamento)Use o valor padrão recomendado pelo Model Studio.FloatSe "validation_file_ids" não estiver definido, o Model Studio divide o arquivo de treinamento: 80% para treinamento, 20% para validação.Quando "validation_file_ids" está definido, este parâmetro não tem efeito.
warmup_ratio(Proporção de aquecimento)Use o valor padrão recomendado pelo Model Studio.FloatFração dos passos de treinamento usada para aquecimento da taxa de aprendizado (aumento linear de quase zero até a taxa alvo).Estabiliza o início do treinamento limitando grandes atualizações de peso.Muito alta: assemelha-se a uma taxa de aprendizado baixa com mudança mínima de desempenho.Muito baixa: assemelha-se a uma taxa de aprendizado alta e pode degradar o desempenho.
Este parâmetro não tem efeito se o agendador de taxa de aprendizado estiver definido como constant.
weight_decay(Decaimento de peso)Use o valor padrão recomendado pelo Model Studio.FloatForça da regularização L2. Ajuda a preservar a generalização, mas valores excessivamente altos reduzem a eficácia do ajuste fino.
Parâmetros para ajuste fino eficiente (suportaefficient_sft e dpo_lora)
Ao realizar uma segunda rodada de ajuste fino eficiente em um modelo que já passou por esse processo, os parâmetros lora_rank, lora_alpha e lora_dropout devem permanecer consistentes.
lora_rank(Rank LoRA)64IntegerRank das matrizes de baixo rank do LoRA. Ranks mais altos podem melhorar os resultados, mas aumentam ligeiramente o tempo de treinamento.
lora_alpha(Alpha LoRA)Use o valor padrão recomendado pelo Model Studio.IntegerFator de escala para combinar os pesos do modelo base com a correção LoRA.Alpha maior: mais peso para as atualizações LoRA específicas da tarefa.Alpha menor: maior retenção do conhecimento do modelo base.
lora_dropout(Dropout LoRA)Use o valor padrão recomendado pelo Model Studio.FloatTaxa de dropout para as matrizes de baixo rank do LoRA. O padrão equilibra a generalização; valores excessivamente grandes diminuem a eficácia do ajuste fino.
Parâmetros para publicação de snapshots de parâmetros do modelo (apenas paraefficient_sft e sft)
save_strategy(Estratégia de salvamento de snapshot)Pode ser definido como epoch ou steps.
  • Quando definido como steps, você pode ajustar o intervalo de salvamento definindo o parâmetro save_steps.
StringEstratégia para salvar snapshots de parâmetros do modelo (checkpoints): epoch (após cada época) ou steps (em um intervalo de passos especificado).
save_steps(Passos de salvamento)Se precisar modificar manualmente, defina como um múltiplo inteiro do parâmetro eval_steps.IntegerIntervalo, em passos de treinamento, entre os salvamentos de snapshot.
save_total_limit(Limite de salvamento de snapshots)10IntegerNúmero máximo de snapshots a serem retidos. Snapshots mais antigos são excluídos automaticamente quando o limite é atingido.

Consultar um job de fine-tuning

Utilize o job_id retornado na resposta de criação para obter os detalhes do job.
  • HTTP
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

Parâmetros da requisição

Parâmetro

Tipo

Localização

Obrigatório

Descrição

job_id

String

Path

Sim

ID do job de fine-tuning.

Resposta de sucesso

{
    "request_id": "d100cddb-ac85-4c82-bd5c-9b5421c5e94d",
    "output":
    {
        "job_id": "ft-202511272033-8ae7",
        "job_name": "ft-202511272033-8ae7",
        "status": "RUNNING",
        "finetuned_output": "qwen3-8b-ft-202511272033-8ae7",
        "model": "qwen3-8b",
        "base_model": "qwen3-8b",
        "training_file_ids":
        [
            "9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"
        ],
        "validation_file_ids":
        [],
        "hyper_parameters":
        {
            "n_epochs": 3,
            "batch_size": 16,
            "max_length": 8192,
            "learning_rate": "1.6e-5",
            "lr_scheduler_type": "linear",
            "split": 0.9,
            "warmup_ratio": 0.05,
            "eval_steps": 50,
            "data_augmentation": true,
            "augmentation_ratio": "0.1,0.05,0.15",
            "augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
            "save_strategy": "epoch",
            "save_total_limit": 10
        },
        "training_type": "sft",
        "create_time": "2025-11-27 20:33:15",
        "workspace_id": "llm-8v53etv3hwb8orx1",
        "user_identity": "1654290265984853",
        "modifier": "1654290265984853",
        "creator": "1654290265984853",
        "group": "llm",
        "max_output_cnt": 10
    }
}

Status do job

Descrição

PENDING

O job aguarda início.

QUEUING

Job em fila de espera. Apenas um job de fine-tuning executa por vez.

RUNNING

Execução em andamento.

CANCELING

Cancelamento em processo.

SUCCEEDED

Job concluído com sucesso.

FAILED

Falha na execução do job.

CANCELED

Job cancelado pelo usuário.

Após a conclusão bem-sucedida do job, o campo finetuned_output conterá o ID do modelo pronto para implantação.

Obter logs do job de fine-tuning

  • HTTP
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/logs?offset=0&line=1000' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'
Utilize offset (linha inicial) e line (quantidade máxima de linhas retornadas) para paginar a saída de log.
Exemplo de resposta:
{
    "request_id":"1100d073-4673-47df-aed8-c35b3108e968",
    "output":{
        "total":57,
        "logs":[
            "{Fine-tuning log 1}",
            "{Fine-tuning log 2}",
            ...
            ...
            ...
        ]
    }
}

Consultar e publicar checkpoints do modelo

Somente o fine-tuning SFT ( efficient_sft e sft ) permite salvar e publicar checkpoints a partir de estados intermediários de treinamento.

Listar checkpoints de um job de fine-tuning

curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/checkpoints' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'
Parâmetros da requisição

Parâmetro

Tipo

Localização do parâmetro

Obrigatório

Descrição

job_id

String

Path Parameter

Sim

ID do job de fine-tuning.

Exemplo de resposta
O campo checkpoint contém o ID do checkpoint, que especifica qual checkpoint publicar na API Model publishing (optional). O campo model_name armazena o ID do modelo usado para implantação. Já o campo finetuned_output na resposta original do job de fine-tuning corresponde ao model_name do checkpoint final.
{
    "request_id": "c11939b5-efa6-4639-97ae-ed4597984647",
    "output":
    [
        {
            "create_time": "2025-11-11T16:25:42",
            "full_name": "ft-202511272033-8ae7-checkpoint-20",
            "job_id": "ft-202511272033-8ae7",
            "checkpoint": "checkpoint-20",
            "model_name": "qwen3-8b-instruct-ft-202511272033-8ae7",
            "status": "SUCCEEDED"
        }
    ]
}

Status

Descrição

PENDING

Checkpoint pendente de publicação. É necessário publicá-lo pela API Model publishing antes de usá-lo para model deployment and invocation.

PROCESSING

Publicação do checkpoint em andamento.

SUCCEEDED

Checkpoint publicado com êxito. Agora está disponível para model deployment and invocation.

FAILED

Falha ao publicar o checkpoint.

Publicação do modelo (opcional)

Após concluir um job de fine-tuning, exporte um checkpoint antes de implantar o modelo.Os checkpoints exportados ficam armazenados no cloud storage e não estão disponíveis para download.
curl --request GET 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/export/<checkpoint_id>?model_name=<model_name>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'
Parâmetros da requisição

Parâmetro

Tipo

Localização do parâmetro

Obrigatório

Descrição

job_id

String

Path Parameter

Sim

ID do job de fine-tuning.

checkpoint_id

String

Path Parameter

Sim

ID do checkpoint a ser publicado.

model_name

String

Path Parameter

Sim

ID personalizado a ser atribuído ao modelo publicado.

Exemplo de resposta
{
    "request_id": "ed3faa41-6be3-4271-9b83-941b23680537",
    "output": true
}
A publicação ocorre de forma assíncrona. Utilize a API List checkpoints for a fine-tuning job para monitorar o status.

Outras operações de fine-tuning

Listar jobs de fine-tuning

curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

Cancelar um job de fine-tuning

Cancela um job de fine-tuning em execução.
curl --request POST 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/cancel' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

Excluir um job de fine-tuning

Não é possível excluir um job de fine-tuning enquanto ele estiver em execução.
curl --request DELETE 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

Implantação e invocação do modelo

Implantação do modelo

Para implantar o modelo, acesse o console de implantação de modelos.

Invocação do modelo

Quando o status da implantação for RUNNING, invoque o modelo ajustado como qualquer outro modelo. Também é possível obter o Model Code no console de implantação de modelos. Uso e parâmetros: DashScope API Reference.
curl 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY}  \
--header 'Content-Type: application/json' \
--data '{
    "model": "<your_model_instance_id>",
    "input":{
        "messages":[
            {
                "role": "user",
                "content": "Who are you?"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'
Plano de Tokens
Playground de Modelos
  • Music generation
Inferência do Modelo
Avaliação
Compressão de Modelos
Estatísticas e Monitoramento
Suporte