Desplegar un servidor de modelos

Utiliza un servicio de Compute cuando necesites GPUs para una carga de trabajo persistente, como servir modelos. Un servicio es la misma ejecución genérica de contenedor que un trabajo, más puertos con nombre, una sonda de preparación (readiness) opcional y un endpoint público — Compute no tiene un esquema de despliegue ni de modelo, así que esta guía sirve con vLLM puramente como carga útil de la carga de trabajo. Los servicios con GPU se ejecutan en proveedores externos de GPU, y los servicios con CPU, en el clúster de MKA1. El ejemplo de esta guía solicita una GPU, así que se ejecuta en un proveedor externo de GPU. Las dos ubicaciones protegen los endpoints de forma distinta; consulta Acceso al endpoint. Un servicio se ejecuta hasta que lo terminas, y tú eres dueño del ciclo de vida de principio a fin: Compute nunca reinicia, reescala ni cambia revisiones a tus espaldas, así que lo que desplegaste es exactamente lo que está en ejecución. Esa previsibilidad viene con dos reglas: mantén el proceso del servidor en primer plano durante toda la vida del servicio — una carga de trabajo que sale, incluso con código 0, termina el servicio como failed — y reemplaza un servicio fallido u obsoleto creando uno nuevo.

Antes de comenzar

Necesitas:

Requisito	Notas
Clave de API	Envíala como `Authorization: Bearer <mka1-api-key>` en cada solicitud.
Compute habilitado para tu organización	Compute es una lista de permitidos que falla en cerrado (fail-closed). Si las solicitudes devuelven `403 tenant_disabled`, pide a un administrador del clúster que habilite tu organización.
Una imagen para servir	Cualquier imagen Linux con GPU que el proveedor pueda descargar sin autenticación interactiva, y que mantenga el proceso del servidor en primer plano.
Pesos que servir	Un identificador de modelo público, o un repositorio en mka1-repos — por ejemplo uno publicado por un trabajo de ajuste fino.
Una clave de API para la propia carga de trabajo	Solo para un servicio en un proveedor externo de GPU, cuyo servidor de modelos debe autenticar las solicitudes por sí mismo. Genera una cadena aleatoria fuerte para esto. Los endpoints del clúster de MKA1 no necesitan una clave propia; consulta Acceso al endpoint.

Los servicios pasan por requested → allocating → provisioning → ready, y permanecen ahí hasta que algo termina la ejecución:

Un fallo en cualquier fase, incluida la salida de la carga de trabajo después de ready, desmonta el servicio a través de terminating hasta failed.
Una terminación explícita, un límite alcanzado o un presupuesto de organización agotado terminan en terminated en su lugar.

Con una sonda de preparación, ready significa que la sonda pasó. Sin una, solo significa que la carga de trabajo se lanzó; no hace ninguna afirmación de salud a nivel de aplicación, así que declara una sonda siempre que la imagen ofrezca una ruta de salud.

La facturación comienza en la asignación, no en la disponibilidad.El gasto se acumula desde la asignación hasta que el servicio alcanza un estado terminal, incluyendo todo el tiempo de aprovisionamiento y de carga del modelo. Un servicio nunca se completa por sí solo — termínalo cuando acabes y establece limits como salvaguarda.

Acceso al endpoint

La ubicación de un servicio determina quién autentica las solicitudes a sus endpoints. Los endpoints del clúster de MKA1 siempre los autentica el gateway de API de MKA1. Envía una clave de API de MKA1 de la organización propietaria del servicio que tenga el scope read:compute, exclusivo de administradores. Una solicitud sin una clave válida recibe 401. Una clave sin read:compute, o de otra organización, recibe 403. El gateway de API elimina el encabezado Authorization y las cookies antes de reenviar la solicitud, así que tu contenedor nunca recibe la credencial de quien llama. No configures el servidor de modelos para que exija una clave propia. Los endpoints de proveedores externos de GPU son accesibles en la URL del proveedor, sin autenticación de MKA1 delante. Protégelos con la clave propia del servidor de modelos, como hace esta guía con VLLM_API_KEY.

Paso 1 - Guarda la clave del endpoint como un secreto

Pasa la clave de API de la carga de trabajo mediante secret_env, no en línea en el comando, para que nunca aparezca en las especificaciones de pod del proveedor. Omite este paso para un servicio con CPU: el gateway de API de MKA1 autentica su endpoint.

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>"}
  }'

Los valores de los secretos son de solo escritura. Guarda el id sec_... devuelto para el cuerpo de creación, y el valor de la clave en sí para tus clientes.

Paso 2 - Crea el servicio

Crea el servicio con el encabezado obligatorio Idempotency-Key, exactamente igual que con los trabajos. Este ejemplo sirve Qwen2.5-0.5B-Instruct con el servidor compatible con OpenAI de vLLM, replicando la prueba de humo de la 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
      }
    }
  }'

Notas sobre los campos:

Campo	Notas
`container.ports`	Cada puerto necesita un nombre único, un puerto de contenedor y un protocolo `http` o `tcp`. Cada puerto con nombre se expone en el endpoint público del servicio.
`service.readiness`	Referencia un puerto declarado por su nombre, nunca por su número. Una sonda `http` requiere que el protocolo de ese puerto sea `http`; una sonda `tcp` toma solo el nombre del puerto.
`secret_env.VLLM_API_KEY`	vLLM lee `VLLM_API_KEY` de forma nativa y luego la exige como token bearer en cada solicitud. Configúrala solo en un proveedor externo de GPU.
`--enable-auto-tool-choice --tool-call-parser hermes`	Obligatorios si el gateway LLM va a llamar a este endpoint: el gateway envía `tool_choice: "auto"` por defecto, y un vLLM sin estos flags lo rechaza con un `400`.

Como con los trabajos, 201 significa que la solicitud fue aceptada; los problemas de capacidad y aprovisionamiento aparecen después a través de state, reason, los registros y los eventos.

Paso 3 - Espera a que esté listo

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

La descarga y la carga del modelo ocurren dentro de la carga de trabajo, así que espera minutos de provisioning antes de que la sonda de preparación pase. Un servicio listo incluye sus 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
}

Si en cambio el servicio aterriza en failed, lee reason, y luego GET .../logs?source=user para la salida del propio servidor y source=system para problemas de asignación y arranque — la misma superficie de registros y eventos que los trabajos.

Paso 4 - Llama a tu endpoint

El endpoint es vLLM puro: una API compatible con OpenAI. Este ejemplo se ejecuta en un proveedor externo de GPU, así que se autentica con la clave que guardaste en el Paso 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": "Say hello."}]
  }'

En un proveedor externo de GPU, el propio vLLM rechaza una solicitud sin la clave: MKA1 no se interpone delante de ese endpoint. Para un endpoint del clúster de MKA1, envía en su lugar una clave de API de MKA1 con read:compute.

Comprueba el esquema de la url del endpoint antes de enviar cualquier cosa sensible. Los endpoints del clúster de MKA1 siempre usan https, pero un proveedor externo de GPU puede servir un endpoint sobre http plano, en cuyo caso los tokens bearer y las cargas útiles cruzan internet sin cifrar.

Paso 5 - Regístralo en el gateway LLM

Opcionalmente, registra el endpoint como un modelo propio (bring-your-own) en el gateway LLM de MKA1, para que se pueda llamar a través de la API /responses de la plataforma con claves normales de la plataforma. Agrega el endpoint a tu catálogo de modelos con una clave de un administrador o propietario de la organización. El id del catálogo nombra tu modelo de MKA1; modelId debe coincidir con el nombre del modelo que sirve vLLM. auth.value es la credencial que el gateway LLM envía a tu endpoint, así que depende de la ubicación:

Proveedor externo de GPU: la clave propia del servidor de modelos. El ejemplo siguiente registra el endpoint de esta guía con la clave del Paso 1.
Clúster de MKA1: una clave de API de MKA1 de la organización propietaria del servicio que tenga read:compute. Es preferible una clave dedicada que solo tenga ese scope. El gateway de API de MKA1 rechaza la clave propia del servidor con 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>"}
  }'

Luego activa el modelo del catálogo con su model_id (el id que indicaste arriba):

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"
  }'

Los modelos con formato completions se aceptan en /responses; el gateway maneja por ti el upstream de chat-completions. Por eso el cuerpo de creación del Paso 2 pasó los flags de tool-choice a vLLM.

Paso 6 - Termina el servicio

Un servicio se ejecuta, y factura, hasta que lo detienes.

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

La terminación es idempotente, libera el recurso del proveedor y detiene el gasto; el registro sigue siendo legible para auditoría y uso. Terminar el servicio no elimina la entrada de catálogo que agregaste en el Paso 5. El modelo sigue activo y las solicitudes a él devuelven 404; elimínalo en el Paso 7.

Paso 7 - Elimina el modelo del gateway LLM

Si registraste el endpoint en el Paso 5, desactiva el modelo y elimina su entrada de catálogo con la misma clave de administrador o propietario de la organización:

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

Desactivar libera el nombre del modelo, así que las solicitudes a qwen-compute-demo dejan de resolverse; eliminarlo retira su definición del catálogo.

Servir un modelo desde mka1-repos

Para servir pesos desde mka1-repos — como la salida fusionada de un trabajo de ajuste fino, o pesos que subiste por git — cambia solo el identificador del modelo y las credenciales. Compute siempre inyecta HF_ENDPOINT en cada carga de trabajo, apuntando al endpoint de artefactos configurado para tu clúster, y vLLM resuelve los identificadores de modelo contra él. mka1-repos autentica con tu clave de API de MKA1, inyectada como HF_TOKEN mediante secret_env:

{
  "container": {
    "image": "vllm/vllm-openai:v0.26.0-cu129",
    "command": ["vllm", "serve", "acme/qwen2.5-0.5b-support", "--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"},
      "HF_TOKEN": {"secret_id": "sec_Vb3nRk8sQw1xYz2M", "key": "HF_TOKEN"}
    },
    "ports": [
      {"name": "api", "container_port": 8000, "protocol": "http"}
    ]
  }
}

El servicio descarga los pesos desde el repositorio de tu organización al arrancar y los sirve bajo el mismo identificador, cerrando el ciclo: ajusta finamente como trabajo, publica en mka1-repos y sirve como servicio.

Supervisar el gasto

El gasto de los servicios se acumula por minuto completo desde la asignación y aparece junto a los trabajos en el 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>'

El gasto de Compute se descuenta de los mismos presupuestos de organización que cualquier otro servicio de MKA1, y un servicio que alcanza un presupuesto de la organización o sus propios limits se termina sin periodo de gracia.

Referencia de API

Para ver el esquema completo de solicitud y respuesta, abre los grupos de Compute en la Referencia de API.

Ver también

Ejecutar un trabajo de ajuste fino - produce los pesos que este servicio sirve.
Gestionar repositorios - crea y gestiona los repositorios de los que este servicio obtiene los pesos.
Usar repositorios con Compute - sube pesos por git y sírvelos por referencia.
Generar una respuesta - llama a tu modelo registrado a través de la API /responses de la plataforma.

Comenzar

SDKs y CLI

Respuestas

APIs independientes

Agentes

Compute

Producción

Desplegar un servidor de modelos

Antes de comenzar

Acceso al endpoint

Paso 1 - Guarda la clave del endpoint como un secreto

Paso 2 - Crea el servicio

Paso 3 - Espera a que esté listo

Paso 4 - Llama a tu endpoint

Paso 5 - Regístralo en el gateway LLM

Paso 6 - Termina el servicio

Paso 7 - Elimina el modelo del gateway LLM

Servir un modelo desde mka1-repos

Supervisar el gasto

Referencia de API

Ver también

​Antes de comenzar

​Acceso al endpoint

​Paso 1 - Guarda la clave del endpoint como un secreto

​Paso 2 - Crea el servicio

​Paso 3 - Espera a que esté listo

​Paso 4 - Llama a tu endpoint

​Paso 5 - Regístralo en el gateway LLM

​Paso 6 - Termina el servicio

​Paso 7 - Elimina el modelo del gateway LLM

​Servir un modelo desde mka1-repos

​Supervisar el gasto

​Referencia de API

​Ver también

Antes de comenzar

Acceso al endpoint

Paso 1 - Guarda la clave del endpoint como un secreto

Paso 2 - Crea el servicio

Paso 3 - Espera a que esté listo

Paso 4 - Llama a tu endpoint

Paso 5 - Regístralo en el gateway LLM

Paso 6 - Termina el servicio

Paso 7 - Elimina el modelo del gateway LLM

Servir un modelo desde mka1-repos

Supervisar el gasto

Referencia de API

Ver también