Executar um job de ajuste fino

Use um job do Compute quando precisar de GPUs para uma carga de trabalho finita, como ajuste fino. Você traz 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 tem esquema de ajuste fino. Um job é uma execução genérica de contêiner, então este guia faz o ajuste fino com ms-swift puramente como payload da carga 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, veja Ajuste fino de um modelo.

Antes de começar

Você precisa de:

Requisito	Observações
Chave de API	Envie-a como `Authorization: Bearer <mka1-api-key>` em toda requisição.
Compute habilitado para sua organização	O Compute usa uma lista de permissões que nega por padrão (fail-closed), porque há dinheiro real em jogo. Se as requisiçõ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 consiga baixar sem autenticação interativa. Ela deve executar 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 na criação se quiser depurar a execução interativamente. O Compute nunca gera nem guarda chaves privadas.

Os jobs passam por requested → allocating → provisioning → running → finalizing e então chegam a um estado terminal:

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

A cobrança começa na alocação, não na prontidão.Os gastos acumulam a partir do momento em que o hardware é alocado, então o tempo de provisionamento e as inicializações que falham custam dinheiro. Defina limits.max_runtime_hours e limits.max_cost_usd em todo job; um job que atinge um limite é encerrado e desalocado imediatamente.

Passo 1 - Escolha um acelerador

Liste o catálogo curado 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 quantidades de GPU que você pode solicitar e as interconexões que ele suporta:

{
  "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"]
}

Passo 2 - Verifique preço e disponibilidade

Opcionalmente, solicite uma cotação antes de criar qualquer coisa. Uma cotação é uma observação do mercado em tempo real: ela retorna se a configuração pode ser obtida no momento e a faixa de preço por hora, e 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.

Passo 3 - Crie o job

Crie o job com um cabeçalho Idempotency-Key obrigatório. Repetir com a mesma chave e o mesmo corpo retorna o mesmo job com 200 em vez de criar uma duplicata; a mesma chave com um corpo diferente retorna 409 idempotency_conflict. Este exemplo executa um pequeno ajuste fino LoRA do Qwen2.5-0.5B-Instruct e mescla o adapter, reproduzindo o smoke test 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-* | 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-* | 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 do ms-swift acima sozinha ocupa quase 60 GB.
`container.command` ou `container.script_b64`	Exatamente um é obrigatório. `command` é um argv; `script_b64` é um script bash codificado em base64, mais fácil para cargas de trabalho com várias etapas.
`container.env`	Variáveis de ambiente comuns. Nomes `MKA1_*` são reservados e `HF_ENDPOINT` pertence à plataforma, então ambos são rejeitados.
`container.secret_env`	Variáveis de ambiente resolvidas a partir de segredos armazenados no lançamento. Use-o para tokens, para que nunca apareçam nas especificações de pod do provedor — veja a seção do mka1-repos.
`limits`	Opcional, mas recomendado. Os tetos de tempo de execução e de custo são independentes, e qualquer um deles encerra o job quando atingido.

A resposta é 201 com o job persistido 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
}

A criação bem-sucedida significa que a requisição foi aceita, não que exista capacidade. Esgotamento de capacidade, erros do provedor e falhas de bootstrap aparecem depois através de state, reason, logs e eventos — nunca como um erro HTTP em uma criação que já retornou 201.

Passo 4 - Consulte até a conclusão

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 job reporta o hardware que realmente obteve, o preço por hora capturado na alocação, os gastos até o momento e um comando SSH pronto para uso, se você forneceu 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 job passa por finalizing até succeeded, o exit_code é registrado, o recurso do provedor é desalocado automaticamente e os gastos param de acumular. Uma saída diferente de zero termina em failed com um reason explicando o motivo. Jobs em estado terminal permanecem legíveis para auditoria e uso.

Passo 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 a 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>'

Passo 6 - Interrompa um job antecipadamente

O encerramento é explícito, 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 é retido para auditoria, uso e reconciliação. Um job que atinge limits.max_runtime_hours, limits.max_cost_usd ou um orçamento da organização é encerrado da mesma forma, sem período de carência e sem garantia de resultados parciais, então publique os artefatos de dentro da carga de trabalho antes que ela termine.

Use o mka1-repos para datasets e pesos

O Compute não armazena artefatos de carga de trabalho. O caminho recomendado é o mka1-repos, o serviço de repositórios da plataforma compatível com Hugging Face para modelos e datasets: seu job baixa o dataset dele e publica os pesos mesclados de volta nele, tudo de dentro da carga de trabalho. Duas convenções da plataforma fazem isso funcionar:

O Compute sempre injeta HF_ENDPOINT em toda carga de trabalho, apontando para o endpoint de artefatos configurado para o seu cluster. Ferramentas compatíveis com Hugging Face — huggingface_hub, ms-swift com USE_HF=1, vLLM — resolvem identificadores <org>/<name> contra ele, então as cargas de trabalho alcançam o mka1-repos sem nenhuma mudança de código. Você não pode sobrescrever HF_ENDPOINT por conta própria.
O mka1-repos autentica com sua chave de API MKA1. Armazene a chave como um segredo do Compute e injete-a como HF_TOKEN através de secret_env, para que ela nunca apareça inline na especificação do job.

Crie o segredo uma única 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 de segredos são somente escrita; 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"
}

Depois escreva a carga de trabalho como um script que treina a partir do seu repositório de dataset e publica os pesos mesclados:

train-and-publish.sh

set -euo pipefail

swift sft \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --dataset acme/support-conversations \
  --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-* | tail -1) \
  --merge_lora true \
  --output_dir /tmp/merged

python -c "
from huggingface_hub import HfApi
api = HfApi()
api.create_repo('acme/qwen2.5-0.5b-support', exist_ok=True)
api.upload_folder(repo_id='acme/qwen2.5-0.5b-support', folder_path='/tmp/merged')
"

Codifique-o com base64 < train-and-publish.sh e referencie o 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"},
    "secret_env": {
      "HF_TOKEN": {"secret_id": "sec_Vb3nRk8sQw1xYz2M", "key": "HF_TOKEN"}
    }
  }
}

Quando o job é concluído com sucesso, os pesos mesclados ficam disponíveis para download em acme/qwen2.5-0.5b-support por qualquer pessoa da sua organização, e um serviço do Compute pode servi-los diretamente — veja Implantar um servidor de modelos.

Um encerramento no meio da execução destrói qualquer trabalho ainda não publicado. Publicar de dentro da carga de trabalho, como acima, é o mecanismo de checkpoint suportado nesta versão.

Acompanhe os gastos

Toda resposta de job carrega accrued_usd, e o endpoint de uso agrega os gastos 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 gastos do Compute saem dos mesmos orçamentos da organização que qualquer outro serviço MKA1.

Referência da API

Para o esquema completo de requisição e resposta, abra os grupos do Compute na Referência de API.

Veja também

Implantar um servidor de modelos - sirva os pesos que este job produziu atrás de um endpoint autenticado.
Gerenciar repositórios - crie e gerencie os repositórios que este job lê e nos quais publica.
Usar repositórios com o Compute - envie datasets e pesos via git e conecte-os às cargas de trabalho.
Ajuste fino de um modelo - a API gerenciada de ajuste fino para modelos da plataforma.

Primeiros passos

Respostas

Recursos

Compute

CLI

Receitas

Benchmarks

Infraestrutura

Executar um job de ajuste fino

Antes de começar

Passo 1 - Escolha um acelerador

Passo 2 - Verifique preço e disponibilidade

Passo 3 - Crie o job

Passo 4 - Consulte até a conclusão

Passo 5 - Leia logs e eventos

Passo 6 - Interrompa um job antecipadamente

Use o mka1-repos para datasets e pesos

Acompanhe os gastos

Referência da API

Veja também

​Antes de começar

​Passo 1 - Escolha um acelerador

​Passo 2 - Verifique preço e disponibilidade

​Passo 3 - Crie o job

​Passo 4 - Consulte até a conclusão

​Passo 5 - Leia logs e eventos

​Passo 6 - Interrompa um job antecipadamente

​Use o mka1-repos para datasets e pesos

​Acompanhe os gastos

​Referência da API

​Veja também

Antes de começar

Passo 1 - Escolha um acelerador

Passo 2 - Verifique preço e disponibilidade

Passo 3 - Crie o job

Passo 4 - Consulte até a conclusão

Passo 5 - Leia logs e eventos

Passo 6 - Interrompa um job antecipadamente

Use o mka1-repos para datasets e pesos

Acompanhe os gastos

Referência da API

Veja também