Executar um trabalho de ajuste fino

Use um trabalho Compute quando precisar de GPUs para uma carga de trabalho finita, como ajuste fino. Você fornece uma imagem de contêiner comum e um comando; o Compute aloca capacidade de GPU, executa a carga de trabalho até a conclusão, transmite logs duráveis e desaloca o hardware automaticamente. O Compute não possui um esquema de ajuste fino. Um trabalho é uma execução genérica de contêiner, portanto este guia faz o ajuste fino com ms-swift puramente como carga útil de trabalho — qualquer stack de treinamento funciona da mesma forma.

Este guia aluga GPUs e executa seu próprio contêiner de treinamento. Para a API gerenciada de ajuste fino que treina modelos da plataforma a partir de arquivos JSONL enviados, consulte Ajustar um modelo.

Antes de começar

Você precisa de:

Requisito	Observações
Chave de API	Envie-a como `Authorization: Bearer <mka1-api-key>` em todas as solicitações.
Compute habilitado para sua organização	O Compute usa uma lista de permissões com falha fechada porque há dinheiro real envolvido. Se as solicitações retornarem `403 tenant_disabled`, peça a um administrador do cluster para habilitar sua organização.
Uma imagem de contêiner com sua stack de treinamento	Qualquer imagem Linux com GPU que o provedor possa obter sem autenticação interativa. Ela deve ser executada como root com `bash`, `curl`, `base64` e GNU coreutils disponíveis, permitir HTTPS de saída e manter a carga de trabalho em primeiro plano.
Chave pública SSH	Opcional. Forneça uma no momento da criação se quiser depurar a execução interativamente. O Compute nunca gera nem armazena chaves privadas.

Os trabalhos passam por requested → allocating → provisioning → running → finalizing e, em seguida, chegam a um estado terminal:

Uma carga de trabalho que sai com 0 termina como succeeded; uma falha em qualquer fase termina como failed.
A terminação explícita, um limite vinculante ou um orçamento da organização esgotado move o trabalho por terminating até terminated.

A cobrança começa na alocação, não quando estiver pronto.Os custos acumulam a partir do momento em que o hardware é alocado; portanto, o tempo de provisionamento e inicializações com falha custam dinheiro. Defina limits.max_runtime_hours e limits.max_cost_usd em todos os trabalhos; um trabalho que atinge um limite vinculante é terminado e desalocado imediatamente.

Etapa 1 - Escolha um acelerador

Liste o catálogo selecionado de aceleradores e escolha um pelo seu name estável.

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({
  bearerAuth: 'Bearer <mka1-api-key>',
});

const accelerators = await sdk.computeCatalog.listAccelerators({});
console.log(accelerators.data);

curl "https://apigw.mka1.com/api/v1/compute/catalog/accelerators" \
  --header 'Authorization: Bearer <mka1-api-key>'

Cada entrada descreve o hardware, as contagens de GPU que você pode solicitar e as interconexões compatíveis:

{
  "name": "nvidia-rtx-4090-24gb",
  "display_name": "NVIDIA GeForce RTX 4090 24GB",
  "vendor": "nvidia",
  "memory_gb": 24,
  "gpu_counts": [1, 2, 3, 4, 5, 6, 7, 8],
  "interconnects": ["pcie"]
}

Etapa 2 - Verifique preço e disponibilidade

Opcionalmente, solicite uma cotação antes de criar qualquer coisa. Uma cotação é uma observação ao vivo do mercado: ela retorna se a configuração está disponível no momento e a faixa de preço por hora, mas não reserva nada.

const quote = await sdk.computeCatalog.createComputeQuote({
  computeQuoteRequest: {
    resourceType: 'job',
    compute: {
      accelerator: 'nvidia-rtx-4090-24gb',
      gpuCount: 1,
      ephemeralDiskGb: 100,
    },
    container: {
      image: 'modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3',
    },
    access: { ssh: true },
  },
});
console.log(quote.available, quote.priceUsdHr);

curl https://apigw.mka1.com/api/v1/compute/catalog/quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "resource_type": "job",
    "compute": {
      "accelerator": "nvidia-rtx-4090-24gb",
      "gpu_count": 1,
      "ephemeral_disk_gb": 100
    },
    "container": {
      "image": "modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3"
    },
    "access": {"ssh": true}
  }'

{
  "available": true,
  "price_usd_hr": {"min": 0.38, "max": 0.69},
  "observed_at": "2026-07-29T12:00:00Z",
  "expires_at": null
}

Uma configuração indisponível ainda é uma resposta 200, com available: false e limites de preço nulos.

Etapa 3 - Crie o trabalho

Crie o trabalho com um cabeçalho Idempotency-Key obrigatório. Repetir a solicitação com a mesma chave e o mesmo corpo retorna o mesmo trabalho com 200, em vez de criar um duplicado; a mesma chave com um corpo diferente retorna 409 idempotency_conflict. Este exemplo executa um pequeno ajuste fino LoRA de Qwen2.5-0.5B-Instruct e mescla o adaptador, correspondendo ao teste de fumaça da plataforma:

const job = await sdk.computeJobs.createJob({
  idempotencyKey: '<unique-request-id>',
  computeJobCreate: {
    name: 'qwen-fine-tune',
    compute: {
      accelerator: 'nvidia-rtx-4090-24gb',
      gpuCount: 1,
      ephemeralDiskGb: 100,
    },
    container: {
      image: 'modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3',
      command: [
        'bash',
        '-lc',
        'swift sft --model Qwen/Qwen2.5-0.5B-Instruct --dataset tatsu-lab/alpaca#64 --max_steps 4 --per_device_train_batch_size 1 --max_length 256 --lora_rank 4 --save_steps 4 --logging_steps 1 --output_dir /tmp/output && swift export --adapters $(ls -d /tmp/output/*/checkpoint-* | sort -V | tail -1) --merge_lora true --output_dir /tmp/merged',
      ],
      env: { USE_HF: '1' },
    },
    access: { sshPublicKey: 'ssh-ed25519 AAAA... you@example.com' },
    limits: { maxRuntimeHours: 2, maxCostUsd: 5 },
  },
});
console.log(job.id, job.state);

curl https://apigw.mka1.com/api/v1/compute/jobs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'Idempotency-Key: <unique-request-id>' \
  --data '{
    "name": "qwen-fine-tune",
    "compute": {
      "accelerator": "nvidia-rtx-4090-24gb",
      "gpu_count": 1,
      "ephemeral_disk_gb": 100
    },
    "container": {
      "image": "modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3",
      "command": ["bash", "-lc", "swift sft --model Qwen/Qwen2.5-0.5B-Instruct --dataset tatsu-lab/alpaca#64 --max_steps 4 --per_device_train_batch_size 1 --max_length 256 --lora_rank 4 --save_steps 4 --logging_steps 1 --output_dir /tmp/output && swift export --adapters $(ls -d /tmp/output/*/checkpoint-* | sort -V | tail -1) --merge_lora true --output_dir /tmp/merged"],
      "env": {"USE_HF": "1"}
    },
    "access": {"ssh_public_key": "ssh-ed25519 AAAA... you@example.com"},
    "limits": {"max_runtime_hours": 2, "max_cost_usd": 5}
  }'

Notas sobre os campos:

Campo	Observações
`compute.accelerator`, `compute.gpu_count`	Obrigatórios. Um nome de acelerador do catálogo e de 1 a 8 GPUs em um único nó.
`compute.ephemeral_disk_gb`	Obrigatório, sem valor padrão. Dimensione-o para a imagem mais todos os downloads; a imagem ms-swift acima sozinha precisa da maior parte de 60 GB.
`container.command` ou `container.script_b64`	Exatamente um é obrigatório. `command` é um argv; `script_b64` é um script bash codificado em base64, o que é mais fácil para cargas de trabalho com várias etapas.
`container.env`	Variáveis de ambiente simples. Apenas nomes `MKA1_*` são reservados; todos os outros nomes, incluindo `HF_ENDPOINT`, podem ser definidos por você.
`container.secret_env`	Variáveis de ambiente resolvidas a partir de segredos armazenados na inicialização. Use isto para tokens para que nunca apareçam nas especificações de pods do provedor — consulte a seção mka1-repos.
`limits`	Opcional, mas recomendado. Os limites de tempo de execução e custo são independentes, e qualquer um deles termina o trabalho quando atingido.

A resposta é 201 com o trabalho durável no estado requested:

{
  "id": "job_9f2kQxWv3bT8mLpZ",
  "name": "qwen-fine-tune",
  "state": "requested",
  "reason": null,
  "compute": {"accelerator": "nvidia-rtx-4090-24gb", "gpu_count": 1, "ephemeral_disk_gb": 100},
  "accrued_usd": 0,
  "limits": {"max_runtime_hours": 2, "max_cost_usd": 5},
  "endpoints": [],
  "created_at": "2026-07-29T12:01:00Z",
  "started_at": null,
  "terminal_at": null
}

Uma criação bem-sucedida significa que a solicitação foi aceita, não que existe capacidade disponível. Esgotamento de capacidade, erros do provedor e falhas de bootstrap surgem posteriormente por meio de state, reason, logs e eventos — nunca como um erro HTTP em uma criação que já retornou 201.

Etapa 4 - Consulte até terminar

const job = await sdk.computeJobs.getJob({ id: 'job_9f2kQxWv3bT8mLpZ' });
console.log(job.state, job.accruedUsd, job.ssh?.command);

curl https://apigw.mka1.com/api/v1/compute/jobs/job_9f2kQxWv3bT8mLpZ \
  --header 'Authorization: Bearer <mka1-api-key>'

Durante a execução, o trabalho informa o hardware que realmente obteve, o preço por hora registrado na alocação, o custo acumulado até o momento e um comando SSH pronto para uso, caso você tenha fornecido uma chave:

{
  "id": "job_9f2kQxWv3bT8mLpZ",
  "name": "qwen-fine-tune",
  "state": "running",
  "reason": null,
  "compute": {"accelerator": "nvidia-rtx-4090-24gb", "gpu_count": 1, "ephemeral_disk_gb": 100},
  "hardware": {"accelerator": "nvidia-rtx-4090-24gb", "gpu_count": 1, "gpu_memory_gb": 24},
  "price_usd_hr": 0.44,
  "accrued_usd": 0.07,
  "allocated_at": "2026-07-29T12:03:12Z",
  "ssh": {"host": "203.0.113.7", "port": 22022, "user": "root", "command": "ssh -p 22022 root@203.0.113.7"},
  "limits": {"max_runtime_hours": 2, "max_cost_usd": 5},
  "endpoints": [],
  "created_at": "2026-07-29T12:01:00Z",
  "started_at": "2026-07-29T12:04:40Z",
  "terminal_at": null
}

Quando a carga de trabalho sai com 0, o trabalho passa por finalizing até succeeded, exit_code é registrado, o recurso do provedor é desalocado automaticamente e o custo deixa de acumular. Uma saída diferente de zero termina em failed com uma reason explicando o motivo. Trabalhos terminais permanecem legíveis para auditoria e uso.

Etapa 5 - Leia logs e eventos

Os logs são duráveis e paginados por cursor, e distinguem a saída da sua carga de trabalho da saída do sistema.

const logs = await sdk.computeJobs.listJobLogs({
  id: 'job_9f2kQxWv3bT8mLpZ',
  source: 'user',
  order: 'desc',
  limit: 50,
});
for (const line of logs.data) {
  console.log(line.timestamp, line.stream, line.message);
}

curl "https://apigw.mka1.com/api/v1/compute/jobs/job_9f2kQxWv3bT8mLpZ/logs?source=user&order=desc&limit=50" \
  --header 'Authorization: Bearer <mka1-api-key>'

{
  "data": [
    {
      "id": "log_01J1",
      "timestamp": "2026-07-29T12:06:02Z",
      "source": "user",
      "stream": "stdout",
      "message": "{'loss': 2.31, 'epoch': 0.25, 'step': 1}"
    }
  ],
  "next_cursor": null,
  "total": 412
}

Use source=system para saída de alocação e bootstrap, e order=asc (o padrão) para paginar do mais antigo para o mais recente. Transições de ciclo de vida, como provider_allocated, workload_started e workload_exited, também estão disponíveis como eventos estruturados:

const events = await sdk.computeJobs.listJobEvents({ id: 'job_9f2kQxWv3bT8mLpZ' });
console.log(events.data.map((event) => event.type));

curl "https://apigw.mka1.com/api/v1/compute/jobs/job_9f2kQxWv3bT8mLpZ/events" \
  --header 'Authorization: Bearer <mka1-api-key>'

Etapa 6 - Interrompa um trabalho antecipadamente

A terminação é explícita, idempotente e retorna o recurso atual.

const job = await sdk.computeJobs.terminateJob({ id: 'job_9f2kQxWv3bT8mLpZ' });
console.log(job.state);

curl https://apigw.mka1.com/api/v1/compute/jobs/job_9f2kQxWv3bT8mLpZ/terminate \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>'

Não há DELETE: o registro é mantido para auditoria, uso e reconciliação. Um trabalho que atinge limits.max_runtime_hours, limits.max_cost_usd ou um orçamento da organização é terminado da mesma forma, sem período de tolerância e sem garantia de resultado parcial; portanto, publique artefatos de dentro da carga de trabalho antes que ela termine.

Use mka1-repos para conjuntos de dados e pesos

O Compute não armazena artefatos de carga de trabalho. O caminho recomendado é mka1-repos, o serviço de repositório compatível com Hugging Face da plataforma para modelos e conjuntos de dados: seu trabalho obtém o conjunto de dados dele e publica os pesos mesclados de volta nele, tudo de dentro da carga de trabalho. Este é o mesmo acesso ao Hugging Face que você usa da sua própria máquina — consulte Gerenciar repositórios. O ms-swift com USE_HF=1 usa esse protocolo, portanto --model e --dataset aceitam referências <org>/<name> diretamente e não são necessárias alterações no código. Três valores de ambiente fazem isso funcionar. O Compute os trata como variáveis de ambiente comuns — são as ferramentas do Hugging Face dentro do seu contêiner que os leem, por estes nomes exatos:

HF_ENDPOINT aponta para o endpoint de artefatos do seu cluster. Ferramentas compatíveis com Hugging Face — huggingface_hub, ms-swift com USE_HF=1, vLLM — resolvem identificadores <org>/<name> em relação a ele, para que as cargas de trabalho alcancem mka1-repos sem nenhuma alteração de código. O console o preenche automaticamente quando você cria uma carga de trabalho; defina-o você mesmo ao chamar a API diretamente ou aponte-o para outro local para obter dados de outro hub.
mka1-repos autentica com sua chave de API MKA1. Armazene a chave como um segredo do Compute e injete-a como HF_TOKEN por meio de secret_env, para que ela nunca apareça embutida na especificação do trabalho.
Defina HF_HUB_DISABLE_XET=1 ao enviar pesos. Versões atuais do huggingface_hub podem selecionar automaticamente o caminho de transferência Xet, enquanto o mka1-repos oferece suporte ao caminho padrão de envio Hub/LFS. Desabilitar o Xet mantém HfApi.upload_folder e hf upload no caminho compatível.

Crie o segredo uma vez:

const secret = await sdk.computeSecrets.createComputeSecret({
  computeSecretCreate: {
    name: 'artifact-repository',
    data: { HF_TOKEN: '<mka1-api-key>' },
  },
});
console.log(secret.id, secret.keys);

curl https://apigw.mka1.com/api/v1/compute/secrets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "name": "artifact-repository",
    "data": {"HF_TOKEN": "<mka1-api-key>"}
  }'

Os valores dos segredos são somente para gravação; a resposta retorna apenas o id e os nomes das chaves:

{
  "id": "sec_Vb3nRk8sQw1xYz2M",
  "name": "artifact-repository",
  "keys": ["HF_TOKEN"],
  "created_at": "2026-07-29T11:58:00Z"
}

Em seguida, escreva a carga de trabalho como um script que treina a partir do seu repositório de conjunto de dados e publica os pesos mesclados. Este exemplo continua o treinamento de meetkai/functionary e publica de volta nele, para que cada execução se baseie na anterior.

HF_ENDPOINT redireciona toda consulta ao Hugging Face na carga de trabalho, portanto identificadores do hub público deixam de ser resolvidos enquanto ele está definido. Para fazer ajuste fino a partir de um modelo base público, primeiro espelhe-o em um repositório próprio ou deixe HF_ENDPOINT não definido e obtenha-o do hub público.

--model_type e --template são obrigatórios sempre que o modelo base vier de um repositório, em vez do hub público. O ms-swift compara ambos pelo nome do modelo upstream, e os pesos obtidos do seu próprio repositório chegam como um diretório local que não carrega tal nome, portanto ele não consegue inferir nenhum dos dois e para com Failed to automatically match. As duas falhas ocorrem uma após a outra — model_type primeiro, depois template — e ambas acontecem após o download da imagem e a execução do treinamento, portanto uma flag ausente custa uma execução completa faturável a cada vez. Ambos os valores devem corresponder ao seu modelo base; a lista de modelos compatíveis do ms-swift fornece o par para cada família, e a mensagem de erro nomeia os candidatos entre os quais ele não conseguiu escolher.

train-and-publish.sh

set -euo pipefail

swift sft \
  --model meetkai/functionary \
  --model_type <model_type> \
  --template <template> \
  --dataset meetkai/functionary-train-data \
  --num_train_epochs 1 \
  --per_device_train_batch_size 1 \
  --lora_rank 8 \
  --output_dir /tmp/output

swift export \
  --adapters $(ls -d /tmp/output/*/checkpoint-* | sort -V | tail -1) \
  --merge_lora true \
  --output_dir /tmp/merged

python -c "
from huggingface_hub import HfApi
api = HfApi()
api.create_repo('meetkai/functionary', exist_ok=True)
api.upload_folder(repo_id='meetkai/functionary', folder_path='/tmp/merged')
"

Codifique-o com base64 < train-and-publish.sh e faça referência ao segredo no corpo de criação:

{
  "container": {
    "image": "modelscope-registry.us-west-1.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda12.9.1-py312-torch2.10.0-vllm0.19.1-modelscope1.35.4-swift4.1.3",
    "script_b64": "<base64 of train-and-publish.sh>",
    "env": {
      "USE_HF": "1",
      "HF_ENDPOINT": "https://hf.mka1.com",
      "HF_HUB_DISABLE_XET": "1"
    },
    "secret_env": {
      "HF_TOKEN": {"secret_id": "sec_Vb3nRk8sQw1xYz2M", "key": "HF_TOKEN"}
    }
  }
}

Quando o trabalho for concluído com sucesso, os pesos mesclados poderão ser baixados de meetkai/functionary por qualquer pessoa na sua organização, e um serviço Compute poderá servi-los diretamente — consulte Implantar um servidor de modelos.

Uma terminação no meio da execução destrói qualquer trabalho que ainda não tenha sido publicado. Publicar de dentro da carga de trabalho, como acima, é o mecanismo de checkpoint compatível nesta versão.

Acompanhe os custos

Toda resposta de trabalho contém accrued_usd, e o endpoint de uso agrega os custos entre recursos para uma janela de tempo:

const usage = await sdk.computeUsage.getComputeUsage({ resourceType: 'job' });
console.log(usage.summary);

curl "https://apigw.mka1.com/api/v1/compute/usage?resource_type=job" \
  --header 'Authorization: Bearer <mka1-api-key>'

{
  "window": {"from": "2026-06-29T12:10:00Z", "to": "2026-07-29T12:10:00Z"},
  "summary": {"total_usd": 12.41, "job_usd": 4.12, "service_usd": 8.29},
  "data": [
    {
      "resource_type": "job",
      "resource_id": "job_9f2kQxWv3bT8mLpZ",
      "name": "qwen-fine-tune",
      "billable_seconds": 1560,
      "accrued_usd": 0.19
    }
  ],
  "next_cursor": null,
  "total": 6
}

A cobrança é medida em minutos inteiros por recurso, e os custos do Compute são descontados dos mesmos orçamentos da organização que todos os outros serviços MKA1.

Referência da API

Para os esquemas completos de solicitação e resposta, abra os grupos Compute na Referência da API.

Veja também

Implantar um servidor de modelos - sirva os pesos produzidos por este trabalho atrás de um endpoint autenticado.
Gerenciar repositórios - crie e gerencie os repositórios dos quais este trabalho lê e nos quais publica.
Gerenciar repositórios - crie um repositório e coloque conjuntos de dados e pesos nele inicialmente.
Ajustar um modelo - a API gerenciada de ajuste fino para modelos da plataforma.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Executar um trabalho de ajuste fino

Antes de começar

Etapa 1 - Escolha um acelerador

Etapa 2 - Verifique preço e disponibilidade

Etapa 3 - Crie o trabalho

Etapa 4 - Consulte até terminar

Etapa 5 - Leia logs e eventos

Etapa 6 - Interrompa um trabalho antecipadamente

Use mka1-repos para conjuntos de dados e pesos

Acompanhe os custos

Referência da API

Veja também

​Antes de começar

​Etapa 1 - Escolha um acelerador

​Etapa 2 - Verifique preço e disponibilidade

​Etapa 3 - Crie o trabalho

​Etapa 4 - Consulte até terminar

​Etapa 5 - Leia logs e eventos

​Etapa 6 - Interrompa um trabalho antecipadamente

​Use mka1-repos para conjuntos de dados e pesos

​Acompanhe os custos

​Referência da API

​Veja também

Antes de começar

Etapa 1 - Escolha um acelerador

Etapa 2 - Verifique preço e disponibilidade

Etapa 3 - Crie o trabalho

Etapa 4 - Consulte até terminar

Etapa 5 - Leia logs e eventos

Etapa 6 - Interrompa um trabalho antecipadamente

Use mka1-repos para conjuntos de dados e pesos

Acompanhe os custos

Referência da API

Veja também