Modal

Visão Geral

Modal é uma plataforma em nuvem para executar código Python de forma serverless, com foco em cargas de trabalho de IA/ML. Principais capacidades:

• Computação com GPU sob demanda (incluindo H100, H200, B200 e B300)
• Funções serverless com escalonamento automático de zero a milhares de contêineres
• Imagens de contêiner personalizadas construídas inteiramente em código Python
• Armazenamento persistente via Volumes para pesos de modelos e conjuntos de dados
• Endpoints web para servir modelos e APIs
• Jobs agendados via cron ou intervalos fixos
• Reutilização de contêineres e pools aquecidos para reduzir cold starts (o carregamento do modelo ainda leva tempo)

Apps e Imagens do Modal são definidos em Python; Dockerfiles existentes também são suportados.

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Implantar ou servir modelos de IA/ML na nuvem
• Executar computações aceleradas por GPU (treinamento, inferência, fine-tuning)
• Criar APIs web serverless ou endpoints
• Escalar jobs de processamento em lote em paralelo
• Agendar tarefas recorrentes (pipelines de dados, retreinamento, scraping)
• Precisar de armazenamento em nuvem persistente para pesos de modelos ou conjuntos de dados
• Quiser executar código em ambientes de contêiner personalizados
• Construir filas de jobs ou sistemas de processamento de tarefas assíncronas

Instalação e Autenticação

Instalar

uv pip install "modal==1.6.0"

Revisado contra o SDK 1.6.0 e as notas de lançamento atuais. Construção local do SDK e manipuladores selecionados foram testados; builds remotos, implantações, inferência de GPU e limites de nuvem não foram executados. Snippets que usam placeholders de modelo/dados ou cargas de trabalho de terceiros são ilustrativos e requerem suas dependências declaradas.

Autenticar

Prefira credenciais existentes antes de criar novas. Apenas as duas variáveis específicas do Modal abaixo são relevantes — não leia, carregue ou exponha quaisquer outras variáveis de ambiente ou conteúdo do arquivo .env:

1. Reutilize um perfil Modal existente ou verifique se MODAL_TOKEN_ID e MODAL_TOKEN_SECRET estão definidos; reporte apenas a presença.
2. Se não, procure apenas essas duas chaves em um arquivo .env local (ignore todas as outras entradas) e carregue-as se apropriado para o fluxo de trabalho.
3. Caia para modal setup interativo apenas se nenhum perfil utilizável ou par de tokens existir. O SDK suporta perfis em .modal.toml; tokens de ambiente são opcionais quando um perfil autentica.

modal setup

Isso abre um navegador para autenticação. Para ambientes CI/CD ou headless, use variáveis de ambiente:

export MODAL_TOKEN_ID=<your-token-id>
export MODAL_TOKEN_SECRET=<your-token-secret>

Se nem um perfil existente nem um par de tokens estiver disponível, crie credenciais em https://modal.com/settings

Verifique o preço atual e as cotas do espaço de trabalho antes de dimensionar uma execução. O uso de GPU requer um método de pagamento mesmo quando os créditos permanecem.

Referência: Veja references/getting-started.md para configuração detalhada e o primeiro walkthrough de app.

Conceitos Principais

App e Funções

Um App do Modal agrupa funções relacionadas. Funções decoradas com @app.function() rodam remotamente na nuvem:

import modal

app = modal.App("my-app")

@app.function()
def square(x):
    return x ** 2

@app.local_entrypoint()
def main():
    # .remote() runs in the cloud
    print(square.remote(42))

Execute com modal run script.py. Implante com modal deploy script.py.

Referência: Veja references/functions.md para hooks de ciclo de vida, classes, .map(), .spawn() e mais.

Imagens de Contêiner

Modal constrói imagens de contêiner a partir de código Python. O instalador de pacotes recomendado é uv:

image = (
    modal.Image.debian_slim(python_version="3.11")
    .uv_pip_install("torch==2.12.0", "transformers==5.9.0", "accelerate==1.13.0")
    .apt_install("git")
)

@app.function(image=image, gpu="L40S")
def inference(prompt):
    from transformers import pipeline
    pipe = pipeline("text-generation", model="openai-community/gpt2", device=0)
    return pipe(prompt)

Métodos chave de imagem:

• .uv_pip_install() — Instala pacotes Python com uv (recomendado)
• .pip_install() — Instala com pip (fallback)
• .apt_install() — Instala pacotes do sistema
• .run_commands() — Executa comandos shell durante a construção
• .run_function() — Executa Python durante a construção (ex: baixar pesos de modelos)
• .add_local_python_source() — Adiciona módulos locais
• .env() — Define variáveis de ambiente

Referência: Veja references/images.md para Dockerfiles, micromamba, caching, passos de construção de GPU.

Computação com GPU

Solicite GPUs através do parâmetro gpu:

…