Partilha de notebooks Jupyter: resultados guardados, estado do kernel e novas execuções

Imagine que recebe um notebook Jupyter com um gráfico convincente. A célula de parâmetros acima dele foi alterada depois de o gráfico ter sido gerado. Esta partilha é hipotética, mas a pergunta é prática: o que comprova realmente o ficheiro?

O gráfico pode ser útil. Apenas não permite determinar qual foi o código-fonte guardado que o produziu. Antes de carregar em Executar todas, decida o que o seu colega precisa de saber. Talvez precise de uma nova execução sequencial. Talvez precise apenas do notebook original, com uma explicação clara de que os seus resultados não foram gerados novamente.

Este guia utiliza a Partilha em Três Estados para tornar essa escolha explícita. Trata-se de uma lista de verificação editorial, não de uma funcionalidade ou certificação do Jupyter.

Distinga o ficheiro do notebook, o kernel ativo e as evidências de reexecução

O que um ficheiro .ipynb preserva

A especificação do formato de notebook descreve células de código que contêm código-fonte, resultados e um execution_count que é um número inteiro ou null. Guardar estes campos preserva um documento. Não cria um histórico de auditoria que associe cada resultado visível ao código-fonte atual.

Esta distinção é o ponto de partida da Partilha em Três Estados da Optijara. Trate o documento guardado como um elemento de evidência. Investigue o kernel em execução separadamente e registe depois se foi tentada uma nova execução sequencial. Enquanto não souber como foi gerado um gráfico, este informa sobre o documento guardado, em vez de comprovar uma reexecução verificada.

O que pertence ao kernel em execução

O JupyterLab documenta a ligação de uma consola de código ao kernel de um notebook. A memória do kernel pode, por isso, incluir trabalho interativo realizado fora da sequência visível do notebook. Essas dependências merecem atenção antes de outra pessoa tentar executar o ficheiro.

Fechar o separador não as resolve. A documentação do painel de processos em execução do JupyterLab indica que o kernel subjacente continua em execução depois de o notebook ser fechado. Registe o kernel selecionado e qualquer contexto interativo relevante, em vez de tratar o fecho de um documento como uma reposição do estado.

O que uma nova execução sequencial pode comprovar

Uma execução sequencial com um kernel novo, concluída e revista, sustenta uma afirmação delimitada: as células de código incluídas no âmbito declarado foram executadas por ordem, no contexto registado e com o resultado comunicado. Registe as omissões, em vez de dar a entender que todas as células foram executadas. As orientações da PLOS sobre a partilha de notebooks recomendam reiniciar e voltar a executar as células para verificar se foram omitidos passos por acidente, não como certificação da análise.

Mantenha essa afirmação restrita. Um kernel novo pode continuar a utilizar o mesmo ambiente e os mesmos ficheiros. Os serviços externos também permanecem fora do notebook. Mesmo uma execução bem-sucedida deixa a questão analítica em aberto: um cálculo pode ser executado sem produzir uma resposta correta ou significativa.

Percorra um notebook hipotético executado fora de ordem

Um parâmetro editado ao lado de um gráfico anterior

Neste exemplo não executado, um analista executa uma célula de parâmetros e utiliza-a para preparar dados para um gráfico. Mais tarde, edita o texto do código-fonte do parâmetro e guarda o notebook sem voltar a executar as células dependentes.

O destinatário vê o novo parâmetro ao lado do gráfico anterior. Nada neste exemplo fornece valores de saída observados, contagens de execução ou erros. O exemplo ilustra uma lacuna de evidência: o gráfico, por si só, não permite determinar se foi produzido pelo parâmetro guardado.

Questões a resolver antes de aceitar a partilha

Comece por identificar a versão do código-fonte guardado e os dados de entrada que o remetente consegue indicar. Pergunte se alguma célula dependia do estado da consola. Mais diretamente, os resultados foram gerados novamente após a última alteração relevante?

As contagens de execução podem dar-lhe um motivo para investigar. Por si só, não respondem a essas perguntas. Se uma reexecução for autorizada e viável, documente a tentativa. Caso contrário, preserve o ficheiro fornecido e indique que os seus resultados não foram gerados novamente.

Uma reexecução falhada com um registo claro proporciona uma partilha melhor do que um notebook bem apresentado com um histórico de execução desconhecido. O destinatário precisa de informação suficiente para decidir em que confiar, incluindo onde essa confiança deve terminar.

Escolha a ação adequada no JupyterLab antes de partilhar

Limpar resultados, reiniciar ou executar todas as células?

O registo de comandos do JupyterLab apresenta operações distintas. A limpeza utiliza notebook:clear-all-cell-outputs; o reinício utiliza notebook:restart-kernel. Executar todas utiliza notebook:run-all-cells, enquanto reiniciar e executar utiliza notebook:restart-run-all.

Adeque a ação à evidência de que precisa

O mesmo registo de comandos também apresenta a ação combinada de reinício e limpeza, notebook:restart-clear-output. Um reinício não significa automaticamente que os resultados foram limpos. O nome de um comando também não lhe diz que a execução foi bem-sucedida.

Para uma verificação sequencial com um kernel novo, escolha deliberadamente Reiniciar o kernel e executar todas as células. Aguarde que a execução termine e depois examine as exceções e os resultados relevantes antes de guardar. Se a execução falhar ou parar antes do fim, comunique esse resultado. Os erros guardados podem ajudar um colega a diagnosticar um problema; não podem servir de evidência de uma execução bem-sucedida.

Utilize o procedimento de Partilha em Três Estados

Examine e autorize a reexecução

Preserve o notebook recebido antes de o editar. Reveja as células à procura de operações que afetem ficheiros ou bases de dados e verifique os pedidos de rede, os dados de entrada sensíveis e as chamadas a serviços pagos. As orientações de segurança do Jupyter Server deixam clara a capacidade subjacente: o Jupyter permite executar código arbitrário. Abrir um notebook não constitui autorização para executar tudo o que contém.

Escolha dados de entrada isolados, fora de produção, e evite segredos ativos. Se faltarem dependências ou uma escrita externa não estiver aprovada, mantenha a reexecução bloqueada e explique porquê. Não flexibilize os limites de execução apenas para obter um resultado aprovado.

Registe o contexto e execute de forma deliberada

Registe a identidade do notebook e o kernel selecionado. Inclua o diretório de trabalho e as versões das dependências, ou uma especificação do ambiente, quando disponível. Identifique os dados de entrada e as versões relevantes dos modelos ou serviços. Assinale como desconhecidos os detalhes que não conhece; um nome de ficheiro e um nome de kernel são apenas uma pequena parte do contexto.

Para um notebook que utiliza Polars, a escolha entre collect e sink_parquet no Polars aborda uma decisão relacionada com os artefactos. Um resultado em memória e um conjunto de dados gravado são entregáveis diferentes. Indique de qual deles este notebook precisa, sem tratar o guia relacionado como validação da sua execução.

As células que escrevem em bases de dados precisam de uma revisão separada das transações. O guia sobre Guardar e Commit no DBeaver explica a distinção num cliente de bases de dados. Leve essa questão para a revisão do notebook: guardar o notebook não comprova que uma transação da base de dados tenha sido confirmada ou revertida em segurança.

O fluxo seguinte é um auxílio ao planeamento. Não regista uma execução observada.

Reveja, guarde separadamente e indique os limites

Guarde a cópia executada e revista num destino distinto e mantenha o original. Verifique se a cópia guardada é o artefacto que pretende entregar. O facto de um comando de execução terminar não é suficiente, e uma falha ao guardar precisa de um estado próprio, mesmo que a execução tenha sido concluída.

O plano de medição abaixo regista evidências em vez de pontuações. Pergunta o que aconteceu e o que o destinatário pode examinar, sem inventar resultados de desempenho.

Um resumo legível por máquina pode manter o registo consistente. Este modelo é ilustrativo; os seus marcadores de posição não constituem evidência de execução.

{
  "framework": "three-state-handoff",
  "example_only": true,
  "source_artifact": "not-recorded",
  "execution_context": "not-recorded",
  "rerun_status": "not-recorded",
  "saved_artifact": "not-recorded",
  "limitations": ["no-execution-evidence"]
}

Substitua um marcador de posição apenas quando tiver observado ou fornecido evidências que o sustentem. Inclua o âmbito da reexecução juntamente com o resultado real. Se não tiver sido guardado nenhum artefacto executado, torne essa ausência explícita, em vez de deixar o destinatário deduzir que deve existir um ficheiro.

Planeie a execução com nbclient sem exagerar o alcance da automação

Contexto de execução e política de erros

Esta secção descreve uma proposta de automação baseada na documentação. Não é uma implementação executável. Não foi executado nenhum notebook nem instalada qualquer dependência para este guia. Não foram efetuadas chamadas a APIs de IA.

O guia de execução do nbclient mostra como configurar NotebookClient com um kernel selecionado e um diretório de execução antes de chamar execute(). Leia atentamente as suas definições. O exemplo timeout=600 aplica-se à execução das células, não à tarefa inteira. Nem kernel_name='python3' nem o diretório notebooks/ constituem recomendações universais.

O guia de tratamento de erros do nbclient documenta allow_errors=False como predefinição. Com allow_errors=True, a execução pode continuar apesar das exceções nas células. Decida quais os erros que tornam uma partilha inaceitável antes de agendar a automação. Chegar à última célula não constitui, por si só, uma aprovação.

Uma decisão de aceitação deve distinguir uma exceção esperada de uma falha inesperada. Se a sua política permitir um erro, registe essa política e reveja o notebook resultante à luz dela. Não altere a política silenciosamente depois de uma execução falhar. A partilha deve permitir que outra pessoa compreenda a decisão sem ter de a reconstruir a partir dos registos.

Guardar os resultados é uma responsabilidade separada

No fluxo de trabalho programático documentado, nbformat.write guarda o notebook separadamente da execução. Planeie um destino que preserve o original e comunique as falhas de persistência de forma independente. Se pretender afirmar que a execução utilizou um kernel novo, exija um kernel explicitamente novo e sob o seu controlo, em vez de presumir essa condição.

As orientações do nbclient sobre widgets estabelecem outro limite útil: a execução não apresenta os widgets num navegador. Por isso, o estado guardado dos widgets não comprova que um resultado interativo funcione no visualizador pretendido. Verifique esses resultados nesse visualizador ou indique que não foram testados.

Evite os erros que uma reexecução sem falhas não consegue corrigir

Erros comuns na partilha

É fácil confundir um gráfico guardado com uma execução atual. Uma variável da consola não documentada é mais difícil de detetar, mas cria o mesmo problema prático: o destinatário tem de adivinhar como foi produzido o resultado. Tratar Executar todas como uma reposição do estado acrescenta outra suposição sem fundamento.

Substituir o notebook recebido elimina o ponto de comparação. Omitir as células que falharam esconde evidências de que a próxima pessoa precisa. Preserve tanto o código-fonte como um relato honesto da tentativa, mesmo quando o resultado estiver desorganizado.

A confiança num notebook responde a uma pergunta diferente. A documentação do JupyterLab sobre confiança trata da sanitização de HTML e da apresentação de resultados interativos. Lida em conjunto com o modelo de segurança do servidor, explica por que razão confiar num notebook não isola o seu código nem valida a sua análise. Fazer aparecer resultados ricos bloqueados não é motivo para confiar num notebook desconhecido sem revisão.

Limites da reprodutibilidade, da confiança e dos serviços externos

O artigo da PLOS de 2019 Dez regras simples para escrever e partilhar análises computacionais em Jupyter Notebooks oferece uma base metodológica para documentar dependências, dados e passos de análise. Utilize-o nesse papel. Não constitui evidência de uma versão atual de um produto nem de uma implementação da Optijara.

As referências de investigação têm o seu próprio lugar na partilha. Preservar referências de investigação com o Zotero pode ajudar na rastreabilidade bibliográfica, mantendo os cálculos e a execução sujeitos a verificação separada.

Uma execução posterior pode utilizar dependências ou dados de entrada diferentes. O estado do gerador de números aleatórios e os serviços externos também fazem parte da discussão sobre reprodutibilidade, especialmente quando um identificador de modelo não garante respostas futuras idênticas. Documente o que sabe, em vez de prometer que o notebook produzirá os mesmos resultados em qualquer ambiente.

Voltar a executar também tem um custo operacional. Reveja os custos dos serviços e a privacidade antes da execução e mantenha os dados de entrada privados ou as credenciais fora do registo de partilha. Partilhe o contexto restrito através de controlos de acesso aprovados. O entregável útil é um relato preciso do que foi tentado, com contexto suficiente para avaliar o resultado e limites claros sobre o que continua por testar.