Desagregação de Prefill e Decode do SGLang: Guia de Arquitetura e Implantação

Desagregação de Prefill e Decode do SGLang: Guia de Arquitetura e Implantação

Última verificação: 16 de outubro de 2026. As flags do SGLang e as combinações de recursos compatíveis mudam rapidamente; fixe uma imagem ou commit testado do SGLang antes de aplicar este guia em produção.

A desagregação de prefill e decode do SGLang separa as duas tarefas muito diferentes dentro do serving de LLM: o processamento de prompts é executado em um pool de prefill, enquanto a geração de tokens é executada em um pool de decode. Os pools trocam o cache KV da solicitação, e um roteador apresenta um único endpoint de inferência ao cliente.

Essa separação pode proteger a latência entre tokens quando chegam prompts longos e permite escalar a capacidade de prefill, intensiva em computação, de modo diferente da capacidade de decode, limitada por memória. Ela também adiciona um caminho de transferência, outro limite de agendamento e uma superfície de compatibilidade maior. Trate-a como uma arquitetura de serving medida — não como uma opção que automaticamente torna toda carga de trabalho mais rápida.

Este guia explica a arquitetura de desagregação de prefill e decode do SGLang, uma topologia mínima de implantação, o que medir e as condições que devem interromper uma implementação.

A resposta rápida: quando a desagregação de PD justifica sua complexidade

A documentação upstream do SGLang descreve o prefill como intensivo em computação e o decode como intensivo em cache KV e memória. Em um agendador unificado, o trabalho de prefill recebido pode interromper o trabalho de decode; com atenção paralela a dados, diferentes workers também podem ficar desequilibrados entre as duas fases. A desagregação de PD separa essas fases para que cada uma possa ser agendada e provisionada de forma independente. A documentação de PD do SGLang é a fonte de verdade para as combinações atualmente compatíveis.

A decisão não é “prefill rápido, decode lento”. Trata-se de saber se isolar suas filas e limites de hardware melhora o objetivo visível ao usuário com que você se importa — geralmente o tempo até o primeiro token (TTFT), a latência entre tokens (ITL), a latência de cauda ou as solicitações concluídas dentro de um orçamento de capacidade fixo.

Como funciona a desagregação de prefill e decode no SGLang

A topologia de PD do SGLang tem três funções lógicas:

1. Roteador: recebe a solicitação do cliente, seleciona um caminho de prefill e decode e transmite a resposta mesclada de volta ao cliente.
2. Workers de prefill: tokenizam e processam o prompt completo e, em seguida, produzem o estado do cache KV necessário para continuar a geração.
3. Workers de decode: recebem esse estado de KV e geram tokens de saída até que a solicitação seja concluída.

A transferência é a parte importante. O worker de prefill não envia texto a um decodificador novo e o faz repetir o prompt. Ele transfere o estado do cache KV para que o decode possa continuar a partir do mesmo contexto de atenção. Atualmente, o SGLang documenta Mooncake e NIXL como mecanismos de transferência de PD; escolha o transporte e o caminho de rede que sua versão fixada e seu hardware realmente suportam.

client
  │
  ▼
PD router ──► prefill pool ──► KV-cache transfer ──► decode pool ──► streamed tokens
                 compute-heavy          fabric            memory-sensitive

Em um cluster multinó, cada função pode ter sua própria contagem de réplicas, configuração de GPU, limite de fila, política de escalonamento automático e orçamento de falhas. Isso só é útil se o roteador e a malha de transferência de KV forem tratados como dependências de produção, e não como uma cola invisível.

Antes de implantar: as cinco verificações que evitam resultados enganosos

1. Fixe a versão exata do SGLang e a configuração do modelo

Execute a mesma imagem ou commit testado do SGLang no roteador, nos workers de prefill e nos workers de decode. Mantenha explícitos em seus manifestos a revisão do modelo, o tokenizer, a quantização, o backend de atenção, a estratégia de paralelismo e as flags específicas do modelo. Um comando que funcionou em uma versão pode ser inválido ou ter semântica diferente em outra.

2. Comprove o caminho de transferência de KV antes de escalar o tráfego

PD é uma arquitetura de plano de dados. Valide o mapeamento da NIC ou da interconexão, a exposição de dispositivos do contêiner, os limites do host e o backend de transferência antes de interpretar a latência do modelo. As implantações específicas do Mooncake podem exigir configuração de InfiniBand/RDMA; a documentação do SGLang também descreve a seleção do backend NIXL para infraestrutura compatível. Não infira que um caminho rápido de comunicação coletiva prova automaticamente que o caminho de transferência de KV está saudável.

3. Estabeleça uma linha de base de servidor unificado

Use o mesmo modelo, prompts, comprimentos de geração, combinação de concorrência, configurações de amostragem e orçamento de hardware para a linha de base e o teste de PD. Meça pelo menos TTFT p50/p95, ITL p50/p95, throughput de solicitações, comportamento de cancelamento e taxa de erro. Um número maior de utilização da GPU, por si só, não é um resultado de serving.

4. Defina o limite de funções no seu agendador

Mantenha pods, serviços, logs e alertas de prefill e decode endereçáveis separadamente. Se você não conseguir identificar qual função está formando fila, sem capacidade de KV ou aguardando transferência, a arquitetura será mais difícil de operar do que uma frota unificada.

5. Leia as restrições atuais de compatibilidade — não apenas o bloco de início rápido

A documentação de desagregação de prefill e decode do SGLang inclui restrições para políticas específicas e fluxos de trabalho com estado. Por exemplo, a política documentada de alocação de decode prefill_complete tem um escopo de suporte mais restrito do que a política padrão. Valide cada combinação de recursos avançados em uma execução de staging antes de torná-la parte de uma promessa de disponibilidade.

Uma implantação mínima de desagregação de prefill e decode do SGLang

Comece com um worker de prefill, um worker de decode e um roteador em um host com duas GPUs. Este é um teste de aceitação funcional, não uma afirmação de que duas GPUs constituem uma configuração de produção. O exemplo NIXL a seguir segue o padrão upstream atual de nó único; use a sintaxe exata de comando da documentação correspondente à sua versão fixada do SGLang.

# GPU 0: função de prefill
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --disaggregation-mode prefill \
  --disaggregation-transfer-backend nixl \
  --port 30000

# GPU 1: função de decode
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --disaggregation-mode decode \
  --disaggregation-transfer-backend nixl \
  --base-gpu-id 1 \
  --port 30001

# Roteador de PD voltado ao cliente
python -m sglang_router.launch_router \
  --pd-disaggregation \
  --prefill http://127.0.0.1:30000 \
  --decode http://127.0.0.1:30001 \
  --host 0.0.0.0 \
  --port 8000

Envie uma solicitação curta pelo roteador, em vez de diretamente para qualquer um dos workers:

curl http://127.0.0.1:8000/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Explique em uma frase por que a transferência do cache KV é importante.",
    "max_tokens": 64
  }'

Sucesso significa mais do que receber texto. Confirme que o roteador selecionou ambas as funções, que a transferência de KV foi concluída, que o comportamento de streaming permanece intacto e que cada processo informa as configurações esperadas de modelo e compatibilidade. Mantenha esta pequena implantação de desagregação de prefill e decode do SGLang em CI ou em um ambiente de pré-produção para que uma atualização não interrompa silenciosamente o caminho de PD.

Para uma implantação Mooncake, use o guia de PD do SGLang atual para a instalação necessária do mecanismo de transferência e a configuração do dispositivo IB. Não copie variáveis de ambiente do Mooncake de um transporte, nuvem ou versão do SGLang diferente.

Passando de um par para uma topologia de produção

Quando o par básico estiver saudável, escale cada função com base nos dados de fila e recursos, em vez de assumir uma proporção de 1:1.

Para padrões multinó, o SGLang publica exemplos separados de inicialização de prefill e decode para implantações da classe DeepSeek, incluindo argumentos de inicialização distribuída e paralelismo específicos de cada função. Esses exemplos são um modelo útil, mas o modelo, o hardware e a versão do SGLang ainda precisam de seu próprio teste de aceitação. Consulte os exemplos upstream de PD multinó antes de adaptar um manifesto de cluster.

Se o Kubernetes gerencia o ciclo de vida, atribua ao prefill e ao decode rótulos, serviços, orçamentos de interrupção, painéis e sondas de prontidão separados. Os pré-requisitos mais amplos do cluster — exposição de GPU, enfileiramento, armazenamento, rede e observabilidade — são abordados em nosso guia de cluster Kubernetes com GPU.

Métricas para a desagregação de prefill e decode do SGLang

A desagregação de prefill e decode do SGLang deve melhorar um resultado escolhido da carga de trabalho, e não apenas produzir um gráfico de recursos diferente. Instrumente a linha do tempo da solicitação com intervalos distintos de prefill, transferência, admissão no decode e geração.

Execute dois conjuntos de testes. Um deve usar a combinação de tráfego esperada hoje; o outro deve conter deliberadamente prompts longos, comprimentos de geração variáveis, cancelamentos e picos. O PD pode parecer excelente em um prompt sintético médio, mas falhar em seu propósito real sob uma combinação de produção enviesada.

Política de alocação de decode: um controle direcionado, não um truque de ajuste padrão

Por padrão, o SGLang documenta um comportamento de alocação de decode early: os slots de KV de destino são reservados antes de o prefill terminar. Portanto, prefills longos podem reter capacidade de decode enquanto o lado do decode aguarda os dados de KV.

A alternativa documentada é:

--disaggregation-decode-allocation-policy prefill_complete

Com prefill_complete, o SGLang adia a alocação de destino até que o prefill esteja pronto. Isso pode ajudar quando prompts longos competem com tráfego de decode ativo pela capacidade de KV de destino, mas também altera a sobreposição e o escopo de suporte. A documentação upstream informa que a política deve ser definida tanto no prefill quanto no decode e lista várias combinações incompatíveis. Trate-a como um experimento controlado com critérios de reversão, não como uma otimização universal.

Modos de falha comuns e a próxima verificação mais rápida

A implantação da desagregação de prefill e decode do SGLang deve ser reversível. Mantenha uma rota de serving unificada ou uma revisão de implantação comprovadamente funcional até que a configuração de PD atenda aos limiares definidos de latência e confiabilidade em toda a combinação de cargas de trabalho relevante.

Uma sequência de implantação segura

1. Linha de base: Capture um benchmark de SGLang unificado com prompts, saídas, concorrência e casos de falha semelhantes aos de produção.
2. Um par: Inicie um worker de prefill, um worker de decode e um roteador; conclua verificações funcionais, de streaming, cancelamento e reinicialização.
3. Visibilidade por função: Separe logs, painéis, alertas e limites de capacidade por roteador, prefill, transferência e decode.
4. Carga controlada: Compare o PD com a linha de base por faixa de comprimento de prompt e de saída, não apenas pela média.
5. Escale uma restrição por vez: Ajuste o tamanho do pool, a configuração de GPU, a concorrência ou a configuração de transferência em experimentos separados.
6. Canário e reversão: Direcione uma parcela limitada do tráfego, defina um limiar de reversão para latência/erros e preserve a última configuração saudável.

Esta sequência transforma a desagregação de prefill e decode do SGLang PD de um diagrama de arquitetura promissor em uma mudança operacionalmente testável.

Perguntas frequentes

A desagregação de PD sempre aumenta o throughput?

Não. Ela pode melhorar uma carga de trabalho em que a contenção entre prefill e decode é a restrição, mas também introduz transferência de KV, agendamento pelo roteador e sobrecarga operacional. Teste-a em comparação com uma linha de base unificada, usando a mesma combinação de tráfego e o mesmo orçamento de capacidade.

O prefill é executado em um modelo diferente do decode?

Não. As funções dão continuidade a uma única solicitação lógica. Mantenha o modelo, o tokenizador, a revisão, a quantização e a configuração de serving testados alinhados entre o par, a menos que a documentação upstream ofereça suporte explícito a uma configuração diferente.

Qual backend de transferência devo usar?

Use um backend compatível com a sua versão fixada do SGLang e validado para a sua infraestrutura real. A documentação atual do SGLang descreve Mooncake e NIXL, mas a escolha correta depende da plataforma, da imagem de contêiner, dos dispositivos e do suporte operacional que você verificou.

Posso combinar a desagregação de prefill e decode do SGLang com todos os recursos avançados?

Não. O suporte a PD é sensível a recursos e versões. Consulte as notas atuais de compatibilidade upstream antes de combiná-lo com respostas com estado, execução de ferramentas, recursos de cache, modos de especulação ou comportamento de função não padrão.

O próximo passo prático

Comece com um ambiente de aceitação de um par, documente os limites de TTFT/ITL/erros que justificam a arquitetura e promova somente depois que os caminhos de transferência e falha estiverem observáveis. Para decisões de serving relacionadas, compare vLLM vs. SGLang, analise a decodificação especulativa para inferência de LLM e planeje o cluster de GPU do Kubernetes subjacente separadamente da implementação de PD.