ShadowPEFT no PEFT: o mapa de decisão de exportação de adaptadores

Mesma API get_peft_model, contrato de implantação diferente

O treinamento ainda começa com get_peft_model. Essa familiaridade ajuda, mas também pode ocultar a pergunta de implantação mais importante: o que exatamente você vai entregar?

Com ShadowPEFT, a resposta não é um modelo de base mesclado. A inferência anexada mantém o modelo de base no fluxo. A inferência separada de modelo de linguagem usa um cálculo diferente. Ambas podem ser escolhas legítimas, mas precisam de empacotamento diferente, testes diferentes e evidências de aceitação diferentes.

O que a integração de 15 de setembro muda

O anúncio de integração de 15 de setembro de 2026 dos autores informa que o ShadowPEFT foi mesclado ao ramo principal do PEFT. O artigo de abril oferece contexto útil, mas não é um novo artigo de setembro. Na data do anúncio, experimentar a integração significa instalar o PEFT a partir do código-fonte; a documentação principal separa esse caminho do pacote estável. A data do anúncio não é evidência independente da data exata da mesclagem.

Fixe as revisões do PEFT e do Transformers que você testou. Fixe também as revisões do modelo de base e do modelo shadow. Uma instalação do ramo principal sem versões fixadas não é um plano de lançamento reprodutível.

O anúncio explica o método e relata experimentos. A referência da API documenta as operações. Este artigo conecta essas partes a uma decisão de implantação: qual artefato existe, quais dependências precisam estar presentes e que evidência prova que o artefato está pronto para entrega. É um guia de planejamento, não uma reprodução da Optijara dos resultados dos autores.

Por que uma trajetória shadow não pode ser mesclada aos pesos de base

A documentação do ShadowPEFT descreve uma pequena backbone que produz um estado shadow inicial. Ao longo de blocos decodificadores contíguos, a discrepância h-s passa por uma correção de baixo rank para a entrada da base. Atualizações com portas então avançam o estado shadow usando as saídas dos blocos. Apenas uma trajetória de adaptador pode estar ativa por vez.

Esse é um comportamento dependente da entrada. Não é um delta fixo que possa ser incorporado aos pesos de base. Como resultado, merge, merge_adapter e merge_and_unload geram erros. Métodos familiares de salvar e carregar do PEFT não removem essa restrição.

Mantenha três inventários separados: o adaptador salvo, a configuração de inferência anexada base mais shadow e o checkpoint completo do modelo de linguagem separado. Eles não são três nomes de arquivo para a mesma coisa. São produtos diferentes.

O mapa de decisão de exportação de adaptadores: escolha o artefato antes do treinamento

Quatro rotas de implantação e suas evidências de aceitação

O mapa de decisão de exportação de adaptadores da Optijara é um auxílio de planejamento original para este artigo, não um padrão de fornecedor. Comece pela rota de que você precisa em produção, depois escolha etapas de treinamento, exportação e validação que possam realmente produzi-la.

A rota separada merece inspeção cuidadosa. Um pequeno arquivo de adaptador não é o mesmo que um checkpoint com uma tabela de embeddings, projeção, backbone, cabeça de saída, tokenizador e configuração. Registre quais componentes a configuração escolhida compartilha, treina e salva. Esse inventário também é útil ao revisar detalhes do artefato em vez de nomes de arquivo, embora este artigo não reivindique suporte de conversão GGUF para ShadowPEFT.

Para Diffusers, a documentação separa o backend da arquitetura Flux2 registrada de um alternativa MLP residual por token para arquiteturas compatíveis. Nenhum dos caminhos oferece suporte ao descarregamento autônomo. Essa limitação se aplica a modelos Diffusers de forma ampla, não apenas a arquiteturas sem um backend registrado.

Treinamento, inferência anexada e exportação separada são ramificações diferentes

As ramificações abaixo mostram decisões de ShadowPEFT e as verificações associadas a elas. A ramificação Diffusers é explicitamente sem suporte. Elas não descrevem um roteador de borda-nuvem implementado.

Este resumo compacto é JSON descritivo. Não é uma configuração PEFT e não realiza verificações de compatibilidade.

{
  "framework": "Adapter Export Decision Map",
  "shadow_merge_supported": false,
  "attached_requires_base": true,
  "detached_lm_requires_separate_evaluation": true,
  "independent_export_copy": true,
  "diffusers_standalone_supported": false
}

Exporte um modelo de linguagem separado sem perder o contrato do artefato

Treine o caminho autônomo deliberadamente

O cálculo Transformers separado documentado é head(projection(backbone(x))). Ele não é o estado shadow final entre camadas sL, porque sL depende de interações com o decodificador de base. Portanto, resultados anexados fortes não provam qualidade de tarefa separada.

Trate a qualidade do preditor como uma pergunta de aceitação separada. Uma exportação pode ser tecnicamente válida e ainda ser o preditor errado para a tarefa. Um salvamento bem-sucedido não resolve essa pergunta.

A perda da tarefa auxiliar supervisiona o estado shadow inicial s0, o caminho disponível sem essas interações com a base. A configuração documenta auxiliary_loss_weight=0.05 como padrão, com a perda adicionada quando rótulos são fornecidos. Verifique se a execução de treinamento fornece rótulos e lida com a cabeça da tarefa como pretendido. Definir um valor na configuração não é o mesmo que verificar o caminho da perda.

Para modelagem de linguagem causal, a cabeça de saída da base é reutilizada. Inclua modules_to_save=['lm_head'] quando essa cabeça precisar ser treinada e salva pelo PEFT. Não transforme o treinamento da cabeça em um reflexo. Registre o tamanho do vocabulário da cabeça e sua relação com o tokenizador e a tabela de embeddings.

Use unload_shadow(copy=True) para exportação independente

O trecho a seguir segue a interface de exportação documentada. Ele é ilustrativo e não foi executado aqui. peft_model significa um modelo PEFT Transformers compatível e já treinado, não um pipeline Diffusers arbitrário.

# Apenas ilustrativo: não executado para este artigo.
detached_model = peft_model.base_model.unload_shadow(copy=True)
detached_model.save_pretrained("standalone-shadow")

Por padrão, copy=False compartilha módulos com o modelo PEFT. Se o shadow usa embeddings de entrada congelados da base por meio de uma referência fora de sua árvore de submódulos registrada, salvar esse objeto separado pode omitir a tabela de embeddings. A documentação recomenda copy=True ao salvar ou enviar um modelo independente porque isso anexa uma cópia privada dos embeddings. A compensação é memória extra durante a exportação.

Esse sinalizador resolve uma dependência de serialização. Ele não prova que o tokenizador foi salvo, que o carregador é compatível ou que a qualidade separada atende ao requisito da tarefa. Use a interface de carregamento da implementação fixada. Não infira a classe de recarregamento a partir de um nome conveniente.

Lista de verificação de recarregamento a frio, explicitamente não executado aqui

Use esta lista de verificação prospectivo antes de chamar uma exportação de implantável. A Optijara não treinou, exportou, recarregou nem avaliou o modelo para este artigo. Documentação e inspeção de código-fonte não substituem evidência local de teste de serialização.

Mantenha o artefato anexado enquanto testa a exportação. Um carregamento limpo não deve substituir automaticamente o candidato de implantação anexada. Ele apenas aprova a verificação de serialização. Rejeite artefatos incompletos antes de interpretar diferenças de qualidade, especialmente quando configurações de tokenizador ou pesos ausentes podem explicar o comportamento.

Meça inferência anexada e separada como produtos distintos

Quatro linhas de base na mesma carga de trabalho reservada

Planeje uma comparação entre somente base, LoRA, Shadow anexado e Shadow separado. Use as mesmas tarefas reservadas, prompts, regras de pontuação e configurações de geração quando fizer sentido. Registre diferenças de tokenizador, tamanhos de modelo e orçamentos de treinamento. Uma arquitetura separada menor não é idêntica à base, e a avaliação não deve fingir que é.

Defina limites de aceitação antes de olhar os resultados. Uma tarefa hipotética de rotulagem de documentos pode se importar mais com a correção dos rótulos e com uma saída estruturada estável. Um assistente interativo também precisa de verificações de latência. Estas são escolhas de avaliação propostas, não resultados relatados do ShadowPEFT.

Tamanho do adaptador não é memória de serviço

A geração anexada usa caches KV pareados de base e shadow. A referência da API descreve ShadowCache como intencionalmente não compilável; a conversão para tupla legada não é compatível. Não prometa suporte a torch.compile ou compatibilidade com mecanismo de inferência apenas porque generate() parece familiar. A implementação do modelo define separadamente o caminho de exportação autônoma e sua restrição de Diffusers.

Meça o crescimento do cache na carga de trabalho que você pretende servir. Separe bytes do adaptador, bytes da exportação, picos de carregamento e memória de serviço em estado estável. Siga a mesma disciplina usada para testar o artefato exato no ambiente de execução e no dispositivo de destino. Um download menor não estabelece um tempo de execução anexado menor.

Leia o benchmark dos autores sem um atalho de custo

O benchmark de integração dos autores relata os seguintes resultados de treinamento MetaMathQA e avaliação GSM8K para Llama 3.2 3B em uma NVIDIA A100 80GB. A tabela deles rotula a coluna de armazenamento como "Checkpoint"; estes são artefatos de experimento relatados, não exportações autônomas verificadas.

Nesse experimento, ShadowPEFT tem pontuação maior e checkpoint menor, com memória de pico maior e treinamento mais longo. Inspecione a configuração Shadow e a configuração LoRA vinculadas. O anúncio chama as configurações de padrões, mas o arquivo Shadow especifica auxiliary_loss_weight=0.01 e shadow_alpha=0.5, em vez dos padrões da API de 0.05 e 0.1. Use os arquivos vinculados para entender o experimento; não presuma uma busca de hiperparâmetros igual. Um resultado relatado sem incerteza não estabelece superioridade ampla. Ele também não diz nada, por si só, sobre memória de serviço separada, latência ou acurácia de inferência separada.

O que evitar na implantação do ShadowPEFT

Tratar todo adaptador PEFT como mesclável

A seguir estão erros de implementação previstos, não incidentes de trabalho de cliente da Optijara. Um script de implantação que chama merge_and_unload para todo tipo de adaptador precisa de uma ramificação específica ao método. Substituir essa chamada pelo descarregamento shadow também altera o preditor que está sendo entregue, portanto o relatório de aceitação antigo não pode simplesmente ser transferido.

Possíveis modos de falha incluem tratar tamanho de checkpoint como memória de pico, atribuir pontuações de benchmark anexado a um modelo separado e validar serialização em um processo no qual a base original continua disponível. Módulos compartilhados podem fazer um experimento em memória parecer completo enquanto deixam uma exportação independente sem teste.

Confundir treinamento auxiliar de imagem com um denoiser destacável

Um caminho de treinamento auxiliar de denoising não cria um produto Diffusers autônomo compatível. O suporte ao backend Flux2 diz respeito a como o cálculo shadow é construído. Ele não remove o NotImplementedError no descarregamento autônomo.

Os autores também relatam uma comparação de geração de imagem usando um pequeno conjunto de dados DreamBooth de um único gato. Esse experimento específico de modelo não prova generalização para todos os sujeitos, qualidade universal de imagem ou qualidade de denoiser autônomo. Mantenha essas alegações fora de uma proposta de implantação.

Para equipes que transitam entre ferramentas de imagem, controles familiares não provam paridade de execução. A mesma lógica se aplica aqui. Nomes de API compartilhados são ergonomia útil, não evidência de que dois métodos exportam modelos equivalentes.

Ressalvas antes de adotar a integração do ramo principal

Compatibilidade, custo de implementação e limites de avaliação

O comportamento do ramo principal depende da revisão. Registre a arquitetura, o carregador, as versões de dependências e as restrições de tempo de execução cobertas por seus testes. A descrição de suporte da documentação é onde o trabalho começa. Não é certificação para todo mecanismo de serviço.

Inclua no orçamento verificação de exportação, avaliação, armazenamento e manutenção além do treinamento. Hardware, preços de provedores, comprimento de contexto, concorrência e escolha de modelo afetam o resultado medido. Um adaptador menor não pode sustentar sozinho uma alegação de economia. Mantenha a incerteza visível nas comparações e execute novamente as verificações relevantes após mudanças de dependência.

Verificações de privacidade e licença continuam específicas ao artefato

Revise os termos do modelo de base, checkpoint shadow, conjunto de dados, tokenizador e head da tarefa antes da distribuição. O checkpoint shadow Qwen projetado é uma configuração concreta a inspecionar, não uma permissão geral para toda implantação derivada. A separação não concede direitos de redistribuição nem remove preocupações de privacidade dos dados de treinamento.

Escolha uma rota compatível, mantenha seu inventário de dependências e avalie o artefato que realmente chegará ao ambiente-alvo. Deixe a exportação autônoma Diffusers sem suporte fora do plano de lançamento até que a implementação ofereça suporte explicitamente.