Implantar um servidor de modelo

Use um serviço Compute quando precisar de GPUs para uma carga de trabalho persistente, como servir modelos. Um serviço é a mesma execução de contêiner genérica que um job, além de portas nomeadas, uma sonda de prontidão opcional e um endpoint público — o Compute não tem esquema de implantação ou modelo, portanto este guia utiliza o vLLM puramente como carga de trabalho. Os serviços com GPU são executados em provedores externos de GPU, e os serviços com CPU, no cluster da MKA1. O exemplo deste guia solicita uma GPU, portanto é executado em um provedor externo de GPU. Os dois locais de execução protegem os endpoints de forma diferente; consulte Acesso ao endpoint. Um serviço é executado até que você o encerre, e você é responsável pelo ciclo de vida de ponta a ponta: o Compute nunca reinicia, redimensiona ou troca revisões sem sua intervenção, portanto o que você implantou é exatamente o que está em execução. Essa previsibilidade vem com duas regras: mantenha o processo do servidor em primeiro plano durante toda a vida do serviço — uma carga de trabalho que encerra, mesmo com código 0, encerra o serviço como failed — e substitua um serviço com falha ou desatualizado criando um novo.

Antes de começar

Você precisa de:

Requisito	Observações
Chave de API	Envie-a como `Authorization: Bearer <mka1-api-key>` em cada solicitação.
Compute habilitado para sua organização	O Compute é uma lista de permissões com falha fechada. Se as solicitações retornarem `403 tenant_disabled`, peça a um administrador do cluster para habilitar sua organização.
Uma imagem de serving	Qualquer imagem Linux com GPU que o provedor possa obter sem autenticação interativa, mantendo o processo do servidor em primeiro plano.
Pesos para servir	Um identificador de modelo público ou um repositório em mka1-repos — por exemplo, um publicado por um job de fine-tune.
Uma chave de API para a própria carga de trabalho	Somente para um serviço em um provedor externo de GPU, cujo servidor de modelo deve autenticar as solicitações por conta própria. Gere uma string aleatória forte para isso. Endpoints do cluster da MKA1 não precisam de chave própria; consulte Acesso ao endpoint.

Os serviços passam por requested → allocating → provisioning → ready e permanecem nesse estado até que algo encerre a execução:

Uma falha em qualquer fase, incluindo a carga de trabalho sendo encerrada após ready, desmonta o serviço passando por terminating até failed.
O encerramento explícito, um limite de vinculação ou um orçamento da organização esgotado encerram em terminated.

Com uma sonda de prontidão, ready significa que a sonda foi aprovada. Sem uma, significa apenas que a carga de trabalho foi iniciada; não faz nenhuma afirmação de integridade no nível da aplicação, portanto declare uma sonda sempre que a imagem oferecer uma rota de integridade.

A cobrança começa na alocação, não na prontidão.Os gastos são acumulados desde a alocação até o serviço alcançar um estado terminal, incluindo todo o tempo de provisionamento e carregamento do modelo. Um serviço nunca é concluído por conta própria — encerre-o quando terminar e defina limits como proteção adicional.

Acesso ao endpoint

O local de execução de um serviço determina quem autentica as solicitações aos seus endpoints. Endpoints do cluster da MKA1 são sempre autenticados pelo gateway de API da MKA1. Envie uma chave de API MKA1 da organização proprietária do serviço que tenha o escopo read:compute, exclusivo de administradores. Uma solicitação sem uma chave válida recebe 401. Uma chave sem read:compute, ou de outra organização, recebe 403. O gateway de API remove o cabeçalho Authorization e os cookies antes de encaminhar a solicitação, portanto seu contêiner nunca recebe a credencial de quem chama. Não configure o servidor de modelo para exigir uma chave própria. Endpoints de provedores externos de GPU são acessíveis na URL do provedor, sem autenticação da MKA1 à frente deles. Proteja-os com a chave própria do servidor de modelo, como este guia faz com VLLM_API_KEY.

Etapa 1 - Armazene a chave do endpoint como um segredo

Passe a chave de API da carga de trabalho por secret_env, não embutida no comando, para que ela nunca apareça nas especificações de pods do provedor. Pule esta etapa para um serviço com CPU: o gateway de API da MKA1 autentica o endpoint dele.

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

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

const secret = await sdk.computeSecrets.createComputeSecret({
  computeSecretCreate: {
    name: 'inference-endpoint-key',
    data: { VLLM_API_KEY: '<generated-endpoint-key>' },
  },
});
console.log(secret.id);

mka1 compute-secrets create \
  --body '{
    "name": "inference-endpoint-key",
    "data": {"VLLM_API_KEY": "<generated-endpoint-key>"}
  }'

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

Os valores dos segredos são somente para gravação. Guarde o id sec_... retornado para o corpo de criação e o próprio valor da chave para seus clientes.

Etapa 2 - Crie o serviço

Crie o serviço com um cabeçalho Idempotency-Key obrigatório, exatamente como para jobs. Este exemplo serve Qwen2.5-0.5B-Instruct com o servidor compatível com OpenAI do vLLM, correspondente ao teste de fumaça da plataforma:

const service = await sdk.computeServices.createService({
  idempotencyKey: '<unique-request-id>',
  computeResourceCreate: {
    name: 'qwen-inference',
    compute: {
      accelerator: 'nvidia-rtx-4090-24gb',
      gpuCount: 1,
      ephemeralDiskGb: 60,
    },
    container: {
      image: 'vllm/vllm-openai:v0.26.0-cu129',
      command: [
        'vllm', 'serve', 'Qwen/Qwen2.5-0.5B-Instruct',
        '--host', '0.0.0.0', '--port', '8000',
        '--max-model-len', '4096', '--gpu-memory-utilization', '0.85',
        '--enable-auto-tool-choice', '--tool-call-parser', 'hermes',
      ],
      secretEnv: {
        VLLM_API_KEY: { secretId: 'sec_Qw8pLm2vTn5xRc7J', key: 'VLLM_API_KEY' },
      },
      ports: [{ name: 'api', containerPort: 8000, protocol: 'http' }],
    },
    service: {
      readiness: { type: 'http', port: 'api', path: '/health', successStatus: 200 },
    },
  },
});
console.log(service.id, service.state);

curl https://apigw.mka1.com/api/v1/compute/services \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'Idempotency-Key: <unique-request-id>' \
  --data '{
    "name": "qwen-inference",
    "compute": {
      "accelerator": "nvidia-rtx-4090-24gb",
      "gpu_count": 1,
      "ephemeral_disk_gb": 60
    },
    "container": {
      "image": "vllm/vllm-openai:v0.26.0-cu129",
      "command": ["vllm", "serve", "Qwen/Qwen2.5-0.5B-Instruct", "--host", "0.0.0.0", "--port", "8000", "--max-model-len", "4096", "--gpu-memory-utilization", "0.85", "--enable-auto-tool-choice", "--tool-call-parser", "hermes"],
      "secret_env": {
        "VLLM_API_KEY": {"secret_id": "sec_Qw8pLm2vTn5xRc7J", "key": "VLLM_API_KEY"}
      },
      "ports": [
        {"name": "api", "container_port": 8000, "protocol": "http"}
      ]
    },
    "service": {
      "readiness": {
        "type": "http",
        "port": "api",
        "path": "/health",
        "success_status": 200
      }
    }
  }'

Observações sobre os campos:

Campo	Observações
`container.ports`	Cada porta precisa de um nome exclusivo, uma porta de contêiner e um protocolo `http` ou `tcp`. Toda porta nomeada é exposta no endpoint público do serviço.
`service.readiness`	Referencia uma porta declarada pelo nome, nunca pelo número. Uma sonda `http` exige que o protocolo dessa porta seja `http`; uma sonda `tcp` aceita apenas o nome da porta.
`secret_env.VLLM_API_KEY`	O vLLM lê `VLLM_API_KEY` nativamente e então a exige como token bearer em cada solicitação. Defina-a somente em um provedor externo de GPU.
`--enable-auto-tool-choice --tool-call-parser hermes`	Obrigatório se o gateway de LLM chamar este endpoint: o gateway envia `tool_choice: "auto"` por padrão, e um vLLM sem essas flags rejeita isso com um `400`.

Assim como com jobs, 201 significa que a solicitação foi aceita; problemas de capacidade e provisionamento surgem depois por meio de state, reason, logs e eventos.

Etapa 3 - Aguarde a prontidão

const service = await sdk.computeServices.getService({ id: 'service_2mVx7cKq9dRw4bTn' });
console.log(service.state, service.ready, service.endpoints);

mka1 compute-services get-service \
  --id service_2mVx7cKq9dRw4bTn

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

O download e o carregamento do modelo ocorrem dentro da carga de trabalho, portanto espere minutos de provisioning antes que a sonda de prontidão seja aprovada. Um serviço pronto contém seus endpoints públicos:

{
  "id": "service_2mVx7cKq9dRw4bTn",
  "name": "qwen-inference",
  "state": "ready",
  "ready": true,
  "reason": null,
  "compute": {"accelerator": "nvidia-rtx-4090-24gb", "gpu_count": 1, "ephemeral_disk_gb": 60},
  "hardware": {"accelerator": "nvidia-rtx-4090-24gb", "gpu_count": 1, "gpu_memory_gb": 24},
  "price_usd_hr": 0.46,
  "accrued_usd": 0.12,
  "allocated_at": "2026-07-29T13:02:41Z",
  "limits": {},
  "endpoints": [
    {
      "name": "api",
      "protocol": "http",
      "host": "svc-2mvx7ckq.endpoints.example.net",
      "port": 443,
      "url": "https://svc-2mvx7ckq.endpoints.example.net"
    }
  ],
  "created_at": "2026-07-29T13:01:12Z",
  "started_at": "2026-07-29T13:06:30Z",
  "terminal_at": null
}

Se o serviço entrar em failed, leia reason e então execute GET .../logs?source=user para a saída do próprio servidor e source=system para problemas de alocação e inicialização — os mesmos logs e eventos são exibidos para jobs.

Etapa 4 - Chame seu endpoint

O endpoint é vLLM puro: uma API compatível com OpenAI. Este exemplo é executado em um provedor externo de GPU, portanto se autentica com a chave que você armazenou na Etapa 1.

Bash

curl https://svc-2mvx7ckq.endpoints.example.net/v1/chat/completions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <generated-endpoint-key>' \
  --data '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [{"role": "user", "content": "Diga olá."}]
  }'

Em um provedor externo de GPU, o próprio vLLM rejeita uma solicitação sem a chave: a MKA1 não fica à frente desse endpoint. Para um endpoint do cluster da MKA1, envie em vez disso uma chave de API MKA1 com read:compute.

Verifique o esquema da url do endpoint antes de enviar qualquer informação sensível. Endpoints do cluster da MKA1 sempre usam https, mas um provedor externo de GPU pode servir um endpoint por http simples, caso em que tokens bearer e cargas úteis atravessam a internet sem criptografia.

Etapa 5 - Registre no gateway de LLM

Opcionalmente, registre o endpoint como um modelo traga-o-seu no gateway de LLM da MKA1, para que ele possa ser chamado pela API /responses da plataforma com chaves normais da plataforma. Adicione o endpoint ao seu catálogo de modelos usando uma chave de administrador ou proprietário da organização. O id do catálogo nomeia seu modelo MKA1; modelId deve corresponder ao nome do modelo servido pelo vLLM. auth.value é a credencial que o gateway de LLM envia ao seu endpoint, portanto depende do local de execução:

Provedor externo de GPU: a chave própria do servidor de modelo. O exemplo a seguir registra o endpoint deste guia com a chave da Etapa 1.
Cluster da MKA1: uma chave de API MKA1 da organização proprietária do serviço que tenha read:compute. Prefira uma chave dedicada somente com esse escopo. O gateway de API da MKA1 rejeita a chave própria do servidor com 401.

Bash

curl https://apigw.mka1.com/api/v1/llm/models/catalog \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "id": "qwen-compute-demo",
    "provider": "openai-compatible",
    "modelId": "Qwen/Qwen2.5-0.5B-Instruct",
    "displayName": "Qwen Compute demo",
    "created": 1789488000,
    "capabilities": {"modalities": {"input": ["text"], "output": ["text"]}, "reasoning": false},
    "apiFormat": "completions",
    "apiProviderType": "openai",
    "baseUrl": "https://svc-2mvx7ckq.endpoints.example.net/v1",
    "auth": {"type": "api-key", "value": "<generated-endpoint-key>"}
  }'

Em seguida, ative o modelo do catálogo usando seu model_id (o id que você definiu acima):

Bash

curl https://apigw.mka1.com/api/v1/llm/models/registry \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "source": "byo",
    "model_id": "qwen-compute-demo"
  }'

Modelos no formato completions são aceitos em /responses; o gateway gerencia o upstream de conclusões de chat para você. É por isso que o corpo de criação na Etapa 2 passou as flags de escolha de ferramenta ao vLLM.

Etapa 6 - Encerre

Um serviço é executado e é cobrado até que você o interrompa.

const service = await sdk.computeServices.terminateService({ id: 'service_2mVx7cKq9dRw4bTn' });
console.log(service.state);

mka1 compute-services terminate-service \
  --id service_2mVx7cKq9dRw4bTn

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

O encerramento é idempotente, desaloca o recurso do provedor e interrompe os gastos; o registro permanece legível para auditoria e uso. Encerrar o serviço não remove a entrada de catálogo que você adicionou na Etapa 5. O modelo continua ativo e as solicitações a ele retornam 404; remova-o na Etapa 7.

Etapa 7 - Remova o modelo do gateway de LLM

Se você registrou o endpoint na Etapa 5, desative o modelo e exclua sua entrada de catálogo usando a mesma chave de administrador ou proprietário da organização:

const deactivation = await sdk.llm.models.deactivateRegistryEntry({
  "id": "qwen-compute-demo"
});
console.log(deactivation.deactivated);

const deletion = await sdk.llm.models.deleteCatalogEntry({
  "id": "qwen-compute-demo"
});
console.log(deletion.deleted);

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

deactivation = sdk.llm.models.deactivate_registry_entry(
    id="qwen-compute-demo",
)
print(deactivation.deactivated)

deletion = sdk.llm.models.delete_catalog_entry(
    id="qwen-compute-demo",
)
print(deletion.deleted)

using MeetKai.MKA1;
using Newtonsoft.Json;

var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

var deactivateResponse = await sdk.Llm.Models.DeactivateRegistryEntryAsync(id: "qwen-compute-demo");
var deactivation = deactivateResponse.DeactivateRegistryEntryResponse
    ?? throw new InvalidOperationException(JsonConvert.SerializeObject(deactivateResponse));
Console.WriteLine(JsonConvert.SerializeObject(deactivation.Deactivated));

var deleteResponse = await sdk.Llm.Models.DeleteCatalogEntryAsync(id: "qwen-compute-demo");
var deletion = deleteResponse.DeleteCatalogModelResponse
    ?? throw new InvalidOperationException(JsonConvert.SerializeObject(deleteResponse));
Console.WriteLine(JsonConvert.SerializeObject(deletion.Deleted));

mka1 llm models deactivate-registry-entry \
  --id qwen-compute-demo

mka1 llm models delete-catalog-entry \
  --id qwen-compute-demo

curl 'https://apigw.mka1.com/api/v1/llm/models/registry?id=qwen-compute-demo' \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

curl 'https://apigw.mka1.com/api/v1/llm/models/catalog?id=qwen-compute-demo' \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Desativar libera o nome do modelo, portanto as solicitações para qwen-compute-demo deixam de ser resolvidas; excluir retira a definição do catálogo.

Sirva um modelo de mka1-repos

Para servir pesos de mka1-repos — como a saída mesclada de um job de fine-tune, ou pesos que você enviou por git — altere apenas o identificador do modelo e as credenciais. Defina HF_ENDPOINT no serviço, apontando para o endpoint de artefatos do seu cluster, e o vLLM resolverá os identificadores de modelo nele — o mesmo acesso Hugging Face descrito em Gerenciar repositórios, portanto servir um repositório requer apenas um identificador de modelo e duas variáveis de ambiente. O console preenche HF_ENDPOINT automaticamente quando você cria uma carga de trabalho; defina-o manualmente ao chamar a API diretamente. O mka1-repos autentica com sua chave de API MKA1, injetada como HF_TOKEN por meio de secret_env:

{
  "container": {
    "image": "vllm/vllm-openai:v0.26.0-cu129",
    "command": ["vllm", "serve", "meetkai/functionary", "--host", "0.0.0.0", "--port", "8000", "--max-model-len", "4096", "--gpu-memory-utilization", "0.85", "--enable-auto-tool-choice", "--tool-call-parser", "hermes"],
    "env": {
      "HF_ENDPOINT": "https://hf.mka1.com"
    },
    "secret_env": {
      "VLLM_API_KEY": {"secret_id": "sec_Qw8pLm2vTn5xRc7J", "key": "VLLM_API_KEY"},
      "HF_TOKEN": {"secret_id": "sec_Vb3nRk8sQw1xYz2M", "key": "HF_TOKEN"}
    },
    "ports": [
      {"name": "api", "container_port": 8000, "protocol": "http"}
    ]
  }
}

O serviço baixa os pesos do repositório da sua organização na inicialização e os serve com o mesmo identificador, completando o ciclo: faça fine-tune como um job, publique em mka1-repos e sirva como um serviço.

Acompanhe os gastos

Os gastos do serviço são acumulados por minuto inteiro a partir da alocação e aparecem ao lado dos jobs no endpoint de uso:

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

mka1 compute-usage get \
  --resource-type service

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

Os gastos do Compute consomem os mesmos orçamentos da organização que todos os outros serviços MKA1, e um serviço que atinge um orçamento da organização ou seus próprios limits é encerrado sem período de carência.

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

Executar um job de fine-tune - produza os pesos que este serviço serve.
Gerenciar repositórios - crie e gerencie os repositórios dos quais este serviço obtém pesos.
Gerenciar repositórios - crie um repositório e coloque pesos nele inicialmente.
Gerar uma resposta - chame seu modelo registrado por meio da API /responses da plataforma.

Primeiros passos

SDKs e CLI

Respostas

APIs independentes

Agentes

Avaliações

Computação

Produção

Implantar um servidor de modelo

Antes de começar

Acesso ao endpoint

Etapa 1 - Armazene a chave do endpoint como um segredo

Etapa 2 - Crie o serviço

Etapa 3 - Aguarde a prontidão

Etapa 4 - Chame seu endpoint

Etapa 5 - Registre no gateway de LLM

Etapa 6 - Encerre

Etapa 7 - Remova o modelo do gateway de LLM

Sirva um modelo de mka1-repos

Acompanhe os gastos

Referência da API

Veja também

​Antes de começar

​Acesso ao endpoint

​Etapa 1 - Armazene a chave do endpoint como um segredo

​Etapa 2 - Crie o serviço

​Etapa 3 - Aguarde a prontidão

​Etapa 4 - Chame seu endpoint

​Etapa 5 - Registre no gateway de LLM

​Etapa 6 - Encerre

​Etapa 7 - Remova o modelo do gateway de LLM

​Sirva um modelo de mka1-repos

​Acompanhe os gastos

​Referência da API

​Veja também

Antes de começar

Acesso ao endpoint

Etapa 1 - Armazene a chave do endpoint como um segredo

Etapa 2 - Crie o serviço

Etapa 3 - Aguarde a prontidão

Etapa 4 - Chame seu endpoint

Etapa 5 - Registre no gateway de LLM

Etapa 6 - Encerre

Etapa 7 - Remova o modelo do gateway de LLM

Sirva um modelo de mka1-repos

Acompanhe os gastos

Referência da API

Veja também