Phase 10 - Lesson 13

Construindo um Pipeline Completo de LLM

Tudo das Lições 01 a 12 é uma etapa de um pipeline. Esta lição é o arcabouço que transforma essas etapas em uma única execução ponta a ponta: tokenizar, pré-treinar, escalar, SFT, alinhar, avaliar, quantizar, servir. Você não treinará um modelo de 70B em um laptop. Você produzirá a camada de orquestração, o manifesto, o portal de avaliação e o plano de rollback que uma equipe de fronteira em 2026 usa para decidir o que será implantado. Este é o projeto final.

Tipo: Build Idiomas: Python (stdlib) Pré-requisitos: Todas as lições de 01 a 12 da Fase 10 Tempo: ~120 minutos

Objetivos de Aprendizado

• Compor as onze lições anteriores (tokenizador, dados, pré-treinamento, escala, SFT, RLHF, DPO, CAI, avaliação, quantização, inferência) em uma única especificação de pipeline reproduzível
• Definir o contrato de artefato entre as etapas: o que cada etapa consome, o que produz e como a etapa seguinte verifica a entrada
• Construir um orquestrador que rastreia experimentos, gera hashes de artefatos e condiciona decisões de implantação a limites de avaliação
• Projetar o plano de rollback: quais artefatos são baratos para reexecutar, quais são caros e quanto custa um checkpoint corrompido

O Problema

As lições anteriores funcionam individualmente. Tokenizador treinado. Tiny GPT pré-treinado. Conjunto de dados SFT montado. Modelo de recompensa treinado. Execução de DPO realizada. Avaliações medidas. Pesos quantizados exportados. Servidor de inferência iniciado. Cada um é um notebook. Cada um tem suas próprias convenções, seus próprios caminhos de saída, sua própria semente (seed).

Uma execução de treinamento de fronteira não é um notebook. O Llama 3 405B levou 30 milhões de horas de H100 ao longo de aproximadamente 54 dias. DeepSeek-V3 usou cerca de 2,8 milhões de horas de H800. Durante esse tempo, um checkpoint corrompido, uma contaminação de dados ou uma regressão de avaliação pode custar a uma equipe uma semana de tempo real e um mês do orçamento de GPU. A maneira como as equipes sobrevivem a isso é por meio da higiene do pipeline: cada etapa tem uma entrada determinística, uma saída determinística, um manifesto, um hash e um portal.

Este é o projeto final. Você não executará o pipeline de ponta a ponta em um laptop. Você escreverá o orquestrador que coordena as etapas, o manifesto que descreve a execução, o verificador que condiciona as decisões de implantação e o plano de replicação que permite a terceiros reexecutar seu trabalho a partir de um único arquivo. O código é pequeno; a disciplina é grande.

O padrão escala de 100M a 1T de parâmetros sem alterações. Os mesmos quatro componentes — manifesto, orquestrador, portal de avaliação, armazenamento de artefatos — executam o Llama 3 e também o seu GPT de hobby. A diferença está no tamanho dos números dentro da configuração de cada etapa, não no formato do pipeline.

O Conceito

As Doze Etapas

Cada lição da Fase 10 é uma etapa. Aqui está o grafo de dependências completo.

graph TD
    S1["01 Tokenizer vocab"] --> S2["02 Trained tokenizer"]
    S2 --> S3["03 Sharded dataset"]
    S3 --> S4["04 Base model checkpoint"]
    S4 --> S5["05 Scaled training recipe"]
    S5 --> S6["06 SFT checkpoint"]
    S6 --> S7["07 Reward model + PPO policy"]
    S6 --> S8["08 DPO policy"]
    S7 --> S9["09 CAI / GRPO refined policy"]
    S8 --> S9
    S9 --> S10["10 Eval report"]
    S9 --> S11["11 Quantized weights"]
    S11 --> S12["12 Inference server"]
    S10 --> GATE["Ship gate"]
    S12 --> GATE

    style S1 fill:#1a1a2e,stroke:#e94560,color:#fff
    style S4 fill:#1a1a2e,stroke:#0f3460,color:#fff
    style S9 fill:#1a1a2e,stroke:#0f3460,color:#fff
    style GATE fill:#1a1a2e,stroke:#51cf66,color:#fff

As etapas 07 e 08 podem ser executadas em paralelo. Todo o restante é uma dependência rígida. Uma alteração na etapa 02 (tokenizador) invalida todos os artefatos a jusante. Uma alteração na etapa 10 (avaliação) invalida apenas a decisão de implantação.

O Manifesto

Um manifesto é um arquivo único que descreve uma execução de forma completa o suficiente para replicá-la. Nada que o pipeline produz deve depender de um estado que não esteja no manifesto. Os campos são simples e obrigatórios.

pipeline_version: 1.2.3
seed: 42
git_commit: a1b2c3d4
stages:
  01_tokenizer:
    recipe: bpe_32k
    input_hash: sha256:...
    output_hash: sha256:...
    wall_clock_sec: 3600
    cost_usd: 12

O hash de saída da etapa N é o hash de entrada da etapa N+1. Qualquer desvio e o pipeline é interrompido. É assim que você detecta a corrupção de dados precocemente. Também é assim que um colega de equipe em outro continente verifica se a replicação dele produziu o mesmo artefato que o seu.

Na prática, as equipes usam um esquema YAML pequeno combinado com um verificador de manifesto que compara com a execução bem-sucedida anterior. Qualquer diferença fora dos campos esperados (custo, tempo real) é um sinal de alerta.

Tipagem de Artefatos

A saída de cada etapa é um artefato tipado. Não um diretório genérico, não um arquivo pickle, mas um tipo nomeado com um esquema conhecido.

A tipagem evita o modo de falha mais comum: usar a saída da etapa 08 como entrada da etapa 06, enviando um modelo treinado por DPO pelo caminho de SFT. Artefatos tipados e assinaturas de etapa tipadas transformam esses erros em falhas de compilação, e não em falhas no quinto dia.

O Portal de Avaliação

A implantação não é apenas o "treinamento concluído". A implantação é o "treinamento concluído e aprovação no portal de avaliação". O portal é definido antes do início da execução.

gates:
  mmlu:      >= baseline + 0.5   # no regression
  humaneval: >= baseline + 1.0
  truthfulqa: >= baseline         # no drop
  safety_refusal_rate: <= 0.05
  kl_from_reference: <= 25.0
  cost_total_usd: <= 50000

Todo portal é um limite numérico. Sem portais baseados em "parece bom". Sem aprovações subjetivas. Se todos os portais passarem, o artefato é marcado como implantável. Se qualquer portal falhar, a execução é retida aguardando uma substituição explícita (override) por um revisor nomeado, o que é registrado no próprio manifesto.

Dois portais evitam a maioria dos desastres. Um portal de regressão (o novo modelo deve ser pelo menos tão bom quanto o anterior nos benchmarks principais) detecta bugs de treinamento. Um portal de orçamento de KL (a política alinhada não deve ter se desviado mais do que X de sua referência) detecta o excesso de alinhamento (alignment overcooking). Todo pipeline de produção possui ambos.

O Orquestrador

Um pequeno pedaço de código que lê o manifesto, despacha as etapas, rastreia artefatos e interrompe em qualquer violação de contrato. Isso não é o Airflow. Isso não é o Kubeflow. Para a higiene do pipeline, você deseja algo simples e previsível que você mesmo escreveu.

O trabalho do orquestrador é limitado:

1. Resolver o DAG a partir do manifesto.
2. Para cada etapa, verificar se a saída esperada já existe no hash correto (ignorar se sim).
3. Executar a etapa, capturar stdout/stderr, medir o tempo real e o custo.
4. Verificar o hash de saída em relação ao hash de entrada esperado da etapa a jusante.
5. Em caso de falha, gravar um manifesto parcial com a etapa exata da falha e sair com código diferente de zero.

Isso são 200 linhas de Python. Ele se parecerá com o arquivo code/main.py nesta lição. Nos bastidores, o pipeline real usa torchrun ou ray para executar etapas individuais em clusters, mas o próprio orquestrador é executado em uma única máquina.

Rastreamento de Experimentos e Armazenamento de Artefatos

Dois sistemas externos ancoram o pipeline.

Rastreador de experimentos (wandb, neptune, mlflow). Registra curvas de perda, métricas de avaliação e telemetria do sistema por etapa. O rastreador é onde você vai quando precisa comparar a execução A com a execução B três semanas depois. As equipes quase sempre usam um rastreador hospedado para isso — escrever o seu próprio consome tempo que deveria ser dedicado ao treinamento.

Armazenamento de artefatos (S3, R2, GCS). Armazenamento de objetos imutável para checkpoints, conjuntos de dados, tokenizadores e relatórios de avaliação. Os artefatos são endereçados por hash, não por nome de arquivo. Um nome de arquivo como latest.pt é um perigo; ckpt-7b-step-20000-sha256:abc123.safetensors é um contrato.

O orquestrador grava em ambos. O rastreador é para humanos que analisam gráficos. O armazenamento de artefatos é para a próxima etapa consultar as entradas.

Cálculo de Custos

Uma execução de fronteira tem um valor em dólares associado. A disciplina orçamentária ocorre em dois lugares.

Estimativa pré-execução. A partir do manifesto, calcula-se os FLOPs esperados (para pré-treinamento: 6 x parâmetros x tokens), as horas de GPU esperadas (FLOPs / rendimento de pico / utilização) e o custo em dólares na taxa de aluguel atual. Se a estimativa exceder o limite do orçamento, o pipeline se recusa a iniciar.

Rastreamento durante a execução. O tempo real e o custo etapa por etapa são registrados no manifesto. Após cada etapa, o orçamento restante é verificado. Se uma etapa estourar o orçamento, o portal da próxima etapa é avaliado com o novo orçamento restante. Você não descobre que ficou sem dinheiro apenas quando o investidor liga.

O custo relatado do Llama 3 foi de US$ 61 milhões. O DeepSeek-V3 relatou US$ 5,6 milhões para a execução principal do pré-treinamento. A proporção deve-se principalmente à eficiência do hardware combinada com a mistura de especialistas (mixture-of-experts) — mas o custo específico é visível porque ambas as equipes o rastrearam por etapa, não por execução.

Reproduzibilidade vs Determinismo

Eles não são a mesma coisa. Reproduzível significa que o mesmo manifesto mais o mesmo código mais a mesma infraestrutura produzem um checkpoint com métricas equivalentes a jusante. Determinístico significa saída idêntica bit a bit.

O treinamento moderno de LLM é reproduzível, mas não determinístico. O reduce-order do treinamento distribuído, o não-determinismo de kernels de GPU (cuBLAS, flash-attn) e o arredondamento de precisão mista combinam-se para produzir floats que diferem no nível de 1e-5 entre as execuções. Isso é aceitável para as métricas finais, que não mudam. No entanto, é fatal se você estiver tentando depurar com diferenças no nível de bit. A solução é registrar o hash de entrada, o hash de saída e as métricas principais de cada etapa — se esses valores coincidirem, a execução é considerada "reproduzida", mesmo que os pesos não sejam idênticos bit a bit.

graph LR
    M["Manifesto v1.2.3"] --> O["Orchestrator"]
    O --> S["Stages 01 → 12"]
    S --> AS["Artifact Store\n(content-addressed)"]
    S --> ET["Experiment Tracker\n(metrics, curves)"]
    AS --> GATE["Eval Gate"]
    ET --> GATE
    GATE -->|pass| SHIP["Ship"]
    GATE -->|fail| ROLL["Rollback plan"]

    style M fill:#1a1a2e,stroke:#0f3460,color:#fff
    style GATE fill:#1a1a2e,stroke:#e94560,color:#fff
    style SHIP fill:#1a1a2e,stroke:#51cf66,color:#fff
    style ROLL fill:#1a1a2e,stroke:#c0392b,color:#fff

O Plano de Rollback

Antes de iniciar a execução, defina o que acontece em caso de falha de cada etapa. Três categorias.

• Barato para reexecutar (horas): tokenizador, avaliação, quantização, servidor de inferência. Apenas execute novamente.
• Médio (dias): SFT, DPO, CAI. Mantenha o modelo base; reexecute apenas as etapas de alinhamento.
• Caro (semanas e milhões de dólares): pré-treinamento. O plano de rollback aqui não é "reexecutar". É "usar o último checkpoint válido e reexecutar as etapas mais baratas a jusante com dados revisados".

Como as dependências de etapa são tipadas e hashed, o orquestrador pode calcular o conjunto de rollback automaticamente: invalidar a etapa que falhou mais cada descendente. Uma falha na etapa 06 (SFT) invalida as etapas 06, 07, 08, 09, 10, 11, 12. Uma falha na etapa 11 (quantização) invalida apenas as etapas 11 e 12. Definir isso antecipadamente evita improvisações enquanto a equipe está exausta às 4 horas da manhã.

Receitas de Produção Observadas em 2026

A maioria das equipes de fronteira convergiu para o mesmo esqueleto.

• Tokenizador: BPE de 128k com byte fallback. Treinado em uma fatia multilíngue pequena e equilibrada.
• Pré-treinamento: 10-20T tokens, principalmente da web, código e sintéticos. Otimizador Muon ou AdamW. FSDP2 ou DeepSpeed ZeRO-3. Checkpointing de gradiente. Pesos em BF16, mestre em FP32.
• SFT: 500k-2M pares de instruções, misturando dados humanos e sintéticos, com deduplicação rigorosa contra o conjunto de avaliação.
• Alinhamento: DPO ou CAI + GRPO. RLHF apenas onde o sinal de preferência é muito multidimensional para o DPO.
• Avaliação: MMLU-Pro, MATH, HumanEval+, GPQA, SWE-Bench Verified, LiveBench, além de um conjunto de dados privado retido que o público nunca vê.
• Quantização: GPTQ ou AWQ de 4 bits para servir, 8 bits para avaliações de segurança onde as diferenças de acurácia são importantes.
• Serviço: vLLM, TensorRT-LLM ou interno. Agrupamento contínuo (continuous batching). Decodificação especulativa. Remoção (eviction) de cache KV.

Os números mudam a cada seis meses. O esqueleto não.

Construa Você Mesmo

O código desta lição é um orquestrador e um verificador de manifesto, não doze scripts de treinamento. Cada etapa é simulada com um marcador de posição (placeholder) que produz um artefato de saída com formato e hash corretos. Executar o orquestrador de ponta a ponta comprova que a estrutura do pipeline funciona antes de você gastar dinheiro de GPU nas etapas reais.

Veja code/main.py para a implementação completa. As peças principais:

• Dataclass Manifest: versão do pipeline, semente (seed), commit do git, etapas, portais.
• Dataclass Stage: nome, tipo, entradas (hashes), saída (hash), tempo real, custo.
• Orchestrator.run(): resolve o DAG, despacha as etapas, verifica os hashes, atualiza o manifesto.
• EvalGate.check(): lê limites, compara com o relatório de avaliação mais recente, retorna aprovação/falha (pass/fail).
• ArtifactStore (stub em memória): armazena/recupera por hash, simulando o S3.
• CostTracker: custo por etapa e acumulado, interrompendo quando o limite é excedido.

O pipeline em main.py executa doze etapas simuladas, produz um manifesto e exercita um portal de avaliação com falha para mostrar como é uma execução retida. Substitua cada placeholder pelo script de treinamento real da lição correspondente e você terá o esqueleto que um pipeline de fronteira real utiliza.

Como Usar

O fluxo de trabalho canônico tem três comandos.

python code/main.py plan    # validate manifest, compute cost estimate, print DAG
python code/main.py run     # execute stages, writing to manifest.out.yaml
python code/main.py gate    # read manifest.out.yaml, apply eval gates, ship-or-hold

Sempre execute plan primeiro. A maioria dos bugs de pipeline aparece no momento do planejamento — limites de portais ausentes, hashes desatualizados, estouros de orçamento. Executar plan é grátis. Executar run é caro. Economize dinheiro detectando bugs no lado barato.

A saída de gate é SHIP ou HOLD: <reason>. Uma execução retida (held run) não é uma falha; é um ponto de decisão. Um revisor nomeado pode aplicar uma substituição (override, e isso é registrado) ou aprovar o rollback.

Implemente

Esta lição produz outputs/skill-llm-pipeline-reviewer.md. Forneça a ela uma proposta de manifesto de pipeline e ela verificará todos os contratos: tipagem de etapas, cadeia de hashes, portais, plano de rollback, estimativa de custo. Ela se recusa a aprovar um manifesto com um portal de avaliação ausente, um orçamento de KL sem limites ou uma execução que misture dados de avaliação e de treinamento.

Exercícios

1. Estenda o orquestrador para dar suporte à execução paralela das etapas 07 e 08. Use o módulo concurrent.futures da biblioteca padrão. Confirme se o manifesto final registra as saídas de ambas as etapas e se o hash de entrada da etapa 09 é uma combinação determinística de ambas.
2. Adicione um portal de "verificação de contaminação". Com base no hash do conjunto de dados de avaliação e nos fragmentos do conjunto de dados de treinamento, calcule a sobreposição (correspondência exata de string ou correspondência de 13-grams). O portal falha se a sobreposição exceder 0,1%. Forneça um conjunto de treinamento contaminado e confirme se o portal retém a execução.
3. Implemente um estimador de custo a partir de princípios básicos. Para a etapa 04 (pré-treinamento), estime os FLOPs como 6 x parâmetros x tokens, assuma 40% de MFU (utilização de FLOPs do modelo) em H100 a 989 TFLOPs BF16, a US$ 2,50/hora-GPU. Relate a estimativa para um modelo de 7B treinado em 2T de tokens. Compare com os números publicados do Llama 2.
4. Construa um rollback parcial. Simule uma falha na etapa 09 (CAI) e reexecute as etapas de 09 a 12, mantendo as etapas 01-08 em cache. O orquestrador deve detectar os artefatos em cache por hash e ignorá-los. Meça o tempo real economizado versus uma reexecução completa.
5. Adicione observabilidade. Emita spans do OpenTelemetry para cada etapa, com atributos para parâmetros, tokens vistos, perda e custo. Encaminhe os spans para um coletor local. O objetivo não são painéis (dashboards); o objetivo é que a saúde de cada etapa seja rastreável a partir de um único ID de rastreamento (trace ID).

Termos-Chave

Leitura Adicional

• Dubey et al., 2024 -- "The Llama 3 Herd of Models" — a descrição pública mais detalhada de um pipeline de fronteira, incluindo dados, treinamento, alinhamento e avaliação
• DeepSeek-AI, 2024 -- "DeepSeek-V3 Technical Report" — pipeline focado em eficiência com aproximadamente 1/10 do custo do treinamento da classe do Llama 3
• Kaplan et al., 2020 -- "Scaling Laws for Neural Language Models" — a relação original de escala de computação-dados-parâmetros
• Hoffmann et al., 2022 -- "Training Compute-Optimal Large Language Models (Chinchilla)" — a correção para Kaplan que recalibrou os orçamentos de dados modernos
• PyTorch FSDP2 documentation — a primitiva de treinamento distribuído que substitui o FSDP1 no PyTorch 2.4+
• Weights & Biases LLM Reports — manifestos reais e saídas de rastreadores de experimentos para execuções de LLM de código aberto, úteis como templates