1. Definir a referência e o resultado esperado
Comece pelo que você quer refazer: produzir as mesmas categorias, obter valores próximos ou retomar uma trajetória de treinamento. Guarde um pequeno conjunto de entradas que percorra as etapas importantes e um exemplo de saída válida. Uma instalação que termina sem erro ainda não responde a essa pergunta.
Vamos usar um caso didático: sua aplicação produz embeddings para uma amostra identificada. No ambiente de referência, você deve registrar a forma das saídas, seu tipo, a ausência de valores não finitos e o critério de negócio útil. Se comparar valores, escolha uma tolerância justificada pelo seu uso. Nenhum limiar numérico universal é fornecido aqui.
Atribua uma revisão ao código, aos dados e aos pesos. Um nome como « último-modelo » pode mudar sem que o programa mostre isso. Associe também os parâmetros e o pré-processamento à referência. Esse dossiê permite saber se uma diferença vem do software, das entradas ou das condições de execução.
Role a tabela para ler todas as colunas.| Elemento | A manter | Controle após reconstrução |
|---|---|---|
| Código e parâmetros | Revisão, eventuais modificações, configuração | Mesmo ponto de entrada e mesmas opções. |
| Dados e pesos | Versão ou impressão digital, procedência e direitos de acesso | Mesma amostra e mesmo conteúdo esperado. |
| Python e pacotes | Versões, procedimento e fontes de instalação | Interpretador correto e dependências coerentes. |
| Sistema e backend | SO, arquitetura, driver, CUDA ou ROCm | Dispositivo visível e cálculo mínimo bem-sucedido. |
| Resultado | Formato e critérios de aceitação | Estrutura e depois qualidade ou tolerância prevista. |
2. Separar a cadeia do sistema dos pacotes Python
Verifique em conjunto a placa, o sistema, o driver, o Python e as bibliotecas. Um ambiente virtual organiza os pacotes Python; ele não substitui o driver do sistema. Da mesma forma, a referência de uma imagem não basta para descrever o acesso real à GPU a partir do seu host. Para uma extensão compilada, registre as ferramentas e bibliotecas de compilação necessárias.
Escolha a distribuição PyTorch a partir da plataforma de cálculo do seu projeto. No ROCm, o PyTorch reutiliza as chamadas torch.cuda e os dispositivos nomeados cuda: o nome da interface não permite identificar NVIDIA. Registre separadamente torch.version.cuda e torch.version.hip. Uma extensão escrita para uma determinada cadeia merece seu próprio controle.
Conserve o procedimento que efetivamente permitiu a instalação, com a origem dos pacotes. Evite misturar um comando recente encontrado online com um arquivo de dependências antigo sem examinar a compatibilidade. A documentação consultada pode evoluir; registre as versões usadas no seu próprio dossiê.
3. Escrever uma reconstrução em vez de copiar o dossiê instalado
Crie um novo ambiente com o Python escolhido. Em seguida, use explicitamente o interpretador dele para instalar e executar o projeto. No Linux, será por exemplo .venv-rebuild/bin/python; no Windows, .venv-rebuild\Scripts\python.exe. Você não precisa depender de uma ativação anterior. A documentação do Python esclarece que um ambiente virtual deve ser recriado quando muda de localização.
pip freeze fornece um inventário dos pacotes instalados, não um arquivo de lock calculado. Conserve-o como observação. O arquivo de reconstrução também deve explicitar os índices ou arquivos necessários à sua variante de PyTorch e as versões compatíveis. Revise os caminhos ou URLs que um inventário possa conter antes de compartilhá-lo.
Os comandos abaixo ilustram uma reconstrução Linux a adaptar; eles não constituem um teste executado do seu projeto. O arquivo requirements-rebuild.txt já deve descrever seu ambiente, incluindo a escolha correta do PyTorch. Não o substitua por uma lista de versões supostamente universais.
python -m venv .venv-rebuild
.venv-rebuild/bin/python -m pip --version
.venv-rebuild/bin/python -m pip install -r requirements-rebuild.txt
.venv-rebuild/bin/python -m pip check
.venv-rebuild/bin/python -m pip freeze --all > installed-after.txt4. Verificar o contrato das dependências antes do cálculo
python -m pip check, executado com o interpretador correto, procura dependências instaladas ausentes ou incompatíveis segundo seus metadados. Um resultado sem conflitos não é uma validação do driver, das extensões nativas ou da qualidade da aplicação. Mantenha, portanto, essa etapa curta e prossiga para um controle de cálculo.
Para tornar a reconstrução mais estrita, você pode fixar as versões e conservar as impressões digitais das distribuições autorizadas. Essa decisão exige manter a lista completa que corresponde à sua plataforma. Um arquivo de wheels compilados pode depender do SO e da arquitetura; ele não é uma garantia de portabilidade entre duas máquinas diferentes.
No nosso exemplo de embeddings, compare o inventário reconstruído com a referência antes de modificar o modelo ou seus parâmetros. Se uma diferença for intencional, registre-a e trate a nova execução como uma variante. Caso contrário, corrija a reconstrução; alterar várias camadas ao mesmo tempo tornará o diagnóstico menos preciso.
5. Passar do controle mínimo à aplicação
No interpretador do projeto, registre Python, PyTorch e o backend, depois verifique o dispositivo e um pequeno cálculo. Interrompa essa etapa se a GPU esperada não estiver acessível; uma execução de CPU como fallback embaralharia a comparação. O diagnóstico do Kernodeck fornece um relatório interpretável e distingue as etapas realmente concluídas.
Uma vez bem-sucedido esse controle, use sua pequena amostra da aplicação. Para os embeddings, verifique o número de saídas, suas dimensões, sua correspondência com os identificadores e o critério escolhido. Recarregue os arquivos a partir da pasta de saída. Um cálculo matricial bem-sucedido não demonstra que o pré-processamento ou uma extensão do projeto funciona.
Se o teste falhar na leitura dos dados, na transferência ou durante uma operação específica, guarde a etapa e o primeiro erro. A reconstrução geral pode estar correta; o bloqueio pode pertencer ao carregador de dados ou a um operador específico. Direcione então o diagnóstico para essa camada.
6. Distinguir reconstrução e identidade numérica
Recuperar as mesmas dependências não garante resultados idênticos entre hardwares, plataformas ou versões do PyTorch. Fixar uma seed não cobre todas as fontes de variação. Documente os geradores utilizados, as transformações dos dados e os ajustes de precisão ou determinismo pertinentes.
Defina o critério de comparação antes de olhar a diferença: estrutura exata, tolerância numérica ou estabilidade de uma métrica. Alguns ajustes determinísticos podem recusar operações ou alterar o custo de cálculo. O resultado buscado é uma conclusão compreensível nas condições anunciadas, não uma promessa de identidade em qualquer máquina.
Para retomar um treinamento, as versões não bastam: é preciso também restaurar o estado de cálculo e o progresso. A pasta de retomada verifica essa questão separadamente. Seu exercício de CPU e sua tolerância não se tornam automaticamente as condições do seu modelo.
7. Terminar com uma pasta que outro lançamento possa usar
A pasta final reúne o procedimento, o inventário observado, a configuração, as referências dos dados e os resultados do controle. Adicione a sequência exata: reconstruir, diagnosticar, executar a amostra, reler a saída. Mantenha os acessos em separado e especifique apenas como fornecê-los.
Repita essa sequência em uma pasta limpa antes de considerar o ambiente como transmissível. O controle deve ser bem-sucedido sem recuperar uma variável de um notebook antigo nem buscar um arquivo esquecido. Se uma mudança for necessária, corrija o procedimento e dê uma nova identidade à referência. Você obtém uma base utilizável para seu próximo período de cálculo.