# Diagnostic PyTorch Kernodeck — version 1.0.0

Ce script vérifie qu’un petit calcul PyTorch et son gradient s’exécutent sur le périphérique demandé. Il produit un rapport JSON limité à des champs techniques utiles. Par défaut, il exige un GPU ; un contrôle CPU doit être demandé explicitement.

Il ne lance aucun entraînement, ne mesure aucun débit et ne certifie ni une offre commerciale, ni une capacité d’entraînement, ni la stabilité d’une machine sur la durée. Son code original est fourni sous [licence MIT](kernodeck-diagnostic-v1-LICENSE.md).

## Préparer et lancer

Téléchargez [le script](kernodeck-diagnostic-v1.py), puis ouvrez un terminal dans son dossier. Utilisez le Python de votre environnement de travail, avec PyTorch déjà installé. Le script emploie la bibliothèque standard de Python 3.10 ou ultérieur ; les environnements réellement contrôlés sont détaillés plus bas. Aucune installation ou modification de pilote n’est effectuée.

```sh
python kernodeck-diagnostic-v1.py
```

Cette commande sélectionne le premier GPU visible par PyTorch. Elle échoue avec un code de sortie non nul si PyTorch, le backend GPU ou le périphérique utilisable manque. Elle ne se rabat pas sur CPU.

Pour vérifier uniquement le calcul sur CPU :

```sh
python kernodeck-diagnostic-v1.py --device cpu
```

Pour choisir un GPU visible et conserver un rapport dans un nouveau fichier :

```sh
python kernodeck-diagnostic-v1.py --device-index 0 --output diagnostic.json
```

Le chemin de sortie est choisi par vous et n’apparaît pas dans le rapport. Un fichier existant n’est jamais écrasé. Sans `--output`, le script ne crée aucun fichier. Vous pouvez lire le code de sortie avec `$LASTEXITCODE` dans PowerShell ou `echo $?` dans un shell POSIX.

Si l’import de PyTorch demande plus de temps, augmentez le délai, dans la limite prévue :

```sh
python kernodeck-diagnostic-v1.py --timeout 60
```

| Option publique | Valeur et effet |
| --- | --- |
| `--device gpu` | Valeur par défaut ; exige un GPU CUDA ou ROCm utilisable. |
| `--device cpu` | Calcul CPU explicite ; ne vérifie pas la visibilité du pilote GPU. |
| `--device-index N` | Index PyTorch visible, entre 0 et 63 ; défaut 0. Sans effet sur le calcul CPU. |
| `--timeout N` | Délai du sous-processus de calcul, entre 5 et 120 secondes ; défaut 30. |
| `--host-check` | Lecture NVIDIA facultative, limitée à 3 secondes supplémentaires. |
| `--output FICHIER` | Écrit aussi le JSON dans un nouveau fichier UTF-8. |
| `--help` | Affiche l’aide, sans importer PyTorch. |

Le téléchargement ne contient pas PyTorch, CUDA, ROCm ou leurs pilotes. Pour choisir une installation adaptée à votre système, partez du [sélecteur officiel PyTorch](https://docs.pytorch.org/get-started/locally/). Une installation valide sur une autre machine ne prouve pas la compatibilité de votre GPU.

## CUDA, ROCm et contrôle hôte

Le script examine `torch.version.hip` avant `torch.version.cuda`. Un paquet ROCm est identifié comme `rocm`, même si sa valeur CUDA est `null`. PyTorch utilise aussi `torch.cuda` et le nom de périphérique `cuda` sur ROCm : un rapport `execution.device: "cuda:0"` n’implique donc pas à lui seul une carte NVIDIA. Consultez aussi `execution.backend`. [Documentation HIP de PyTorch](https://docs.pytorch.org/docs/2.14/notes/hip.html)

`torch.cuda.is_available()` indique si CUDA est actuellement disponible pour PyTorch. Le script complète cette observation par un calcul, son gradient et une synchronisation du périphérique demandé. Il ne déduit pas qu’un modèle réel tiendra en mémoire. [Disponibilité](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.is_available.html) · [Synchronisation](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.synchronize.html)

Avec `--host-check`, une commande NVIDIA distincte demande seulement la version du pilote et la mémoire totale en MiB. Sa sortie doit respecter un format numérique strict. L’absence de `nvidia-smi`, un délai dépassé ou une sortie inconnue n’annule pas un calcul réussi. Cette lecture ne constitue pas un diagnostic hôte AMD et n’est pas nécessaire au contrôle CPU. Elle peut voir des cartes que le processus PyTorch ne voit pas ; la liste hôte n’est pas appariée aux index PyTorch. [Requêtes sélectives NVIDIA](https://docs.nvidia.com/deploy/nvidia-smi/index.html)

Para AMD, as versões da GPU, do sistema, do driver e das bibliotecas devem formar uma combinação suportada. Este script não substitui a [matriz oficial de compatibilidade ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Ler o JSON

A estrutura é estável para a versão 1:

| Campo | Significado |
| --- | --- |
| `schema`, `script_version` | Formato e versão do script. |
| `requested_device` | `gpu` ou `cpu`; `unspecified` se os argumentos forem inválidos ou a execução for interrompida. |
| `status`, `code`, `exit_code`, `message` | Resultado global, código estável, código do processo e explicação fixa. |
| `stage` | Última etapa alcançada: import, detecção, visibilidade, alocação, cálculo, gradiente, sincronização, validação, etc. |
| `runtime` | Versão numérica do Python utilizado e família de sistema; nenhum identificador de máquina. |
| `pytorch` | Versão filtrada do pacote, versões de compilação CUDA/HIP, backend declarado e visibilidade da GPU quando consultada. `null` se o PyTorch não pôde ser importado. |
| `execution` | Dispositivo realmente selecionado, modelo de GPU filtrado, memória total informada pelo PyTorch, tipo, forma das matrizes e resultado das verificações. `null` se o cálculo não foi preparado. |
| `host_check` | Presente apenas sob demanda: estado da leitura NVIDIA e dois campos numéricos por placa. |

No modo CPU, `pytorch.backend` pode ser `cuda` porque descreve o pacote instalado. `execution.backend` permanece `cpu` e descreve o cálculo executado. A disponibilidade da GPU, o número de GPUs, o modelo e a memória da GPU são então `null`: eles não foram medidos.

O controle multiplica duas matrizes 2×2 em `float32`, verifica o produto `[[4, 4], [10, 8]]`, depois o gradiente `[[16, 24], [40, 52]]`. A soma dos quadrados esperada é `196.0`. Esses pequenos inteiros permitem aqui uma comparação exata; essa propriedade não promete a reprodutibilidade bit a bit de qualquer modelo. A verificação usa [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). A criação de um contexto de GPU pode consumir mais memória do que apenas as matrizes.

`total_memory_bytes` é uma capacidade informada, não a memória livre ou utilizável pelo seu futuro modelo. O script não mede a memória máxima de um treinamento, nem a interconexão, nem a velocidade, nem o multi-GPU.

## Entender uma falha

| Saída | Código JSON | Leitura e próxima verificação |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | O pequeno cálculo e seu gradiente estão corretos no dispositivo indicado. |
| 2 | `CLI_ARGUMENTS_INVALID` | Reveja `--help`; o valor inválido não é copiado. |
| 3 | `TORCH_MISSING` | O PyTorch está ausente neste Python. Verifique se você escolheu o ambiente correto. |
| 4 | `TORCH_IMPORT_FAILED` | O PyTorch existe, mas sua importação falha; verifique o pacote e suas dependências. |
| 5 | `GPU_BACKEND_ABSENT` | O pacote não declara nem CUDA nem HIP. Escolha uma distribuição adequada, ou solicite explicitamente CPU. |
| 6 | `GPU_UNAVAILABLE` | O pacote declara um backend de GPU, mas nenhuma GPU utilizável está visível neste processo. Verifique o acesso ao dispositivo e a compatibilidade do ambiente. |
| 7 | `DEVICE_INDEX_INVALID` | O índice solicitado não está presente na lista visível pelo PyTorch. |
| 8 | `CHECK_FAILED` | O cálculo ou o gradiente difere do resultado fixo esperado. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Alocação impossível ou erro do backend; `stage` especifica a etapa, sem exportar a exceção bruta. |
| 10 | `TIMEOUT` | O subprocesso excedeu o tempo limite e foi interrompido. |
| 11 | `WORKER_FAILED` | O subprocesso não forneceu um relatório válido. |
| 12 | `OUTPUT_WRITE_FAILED` | O arquivo já existe ou não está acessível; escolha um novo nome. O status global falha mesmo se o cálculo anterior tiver sido bem-sucedido. |
| 130 | `INTERRUPTED` | O controle foi interrompido. |

Não forneça um dump completo do seu ambiente para explicar uma falha. O código e a etapa do relatório constituem uma primeira constatação; se uma investigação mais precisa for necessária, examine-a no seu ambiente antes de compartilhar dados.

## Dados e limites

O script não faz nenhuma requisição de rede e não transmite nada ao Kernodeck. Ele não lê seus notebooks, conjuntos de dados, contas, pagamentos ou checkpoints. Ele não coleta variáveis de ambiente, lista de pacotes, nome de host, nome de usuário, caminho pessoal, número de série, UUID, processos de GPU ou token.

A versão do Python, a família do sistema, as versões técnicas, o modelo de GPU filtrado e a capacidade de memória podem revelar parte do seu ambiente de hardware. Examine o relatório antes de compartilhá-lo. As mensagens brutas do PyTorch e do driver não são copiadas; uma versão ou um modelo não reconhecido se torna um valor neutro. O relatório pode, portanto, omitir um rótulo legítimo.

O tempo limite limita o subprocesso de verificação, não o funcionamento do sistema ou do driver. O script não repara um ambiente, não valida um kernel especializado e não substitui um teste da sua carga de trabalho. Nenhum software de terceiros malicioso ou modificado foi avaliado.

## Verificações realmente efetuadas em 24 de setembro de 2026

Os exemplos a seguir são os relatórios minimizados realmente produzidos pelo script, sem exceção bruta nem identificador de máquina. Eles se referem ao ambiente de verificação e não descrevem nenhuma oferta do catálogo Kernodeck.

| Caso executado | Ambiente | Resultado |
| --- | --- | --- |
| CPU explícita | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Produto e gradiente verificados; perda `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU padrão | Mesmo ambiente, compilação CUDA 12.8, NVIDIA GeForce RTX 5070 | Produto e gradiente verificados em `cuda:0`; perda `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch ausente | Windows, Python 3.12.14, sem PyTorch | `TORCH_MISSING`, saída 3. [JSON de falha](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU tornada invisível apenas para o processo de teste | Python 3.14.6 e pacote CUDA acima | `GPU_UNAVAILABLE`, saída 6. |
| Índice ausente, argumentos inválidos, arquivo existente | Processos de verificação separados | Saídas 7, 2 e 12; arquivo existente preservado. |

A receita conta com 44 verificações, combinando essas execuções reais e testes unitários isolados. Os testes unitários cobrem, entre outros, um pacote sem backend de GPU, a detecção de HIP, um erro do backend, um tempo limite excedido e a filtragem de campos. Eles não constituem execuções de hardware ROCm. **Nenhuma GPU AMD/ROCm foi executada nesta receita.** O NumPy 2.4.4 estava importável no ambiente de verificação, mas o script não o importa diretamente.

As [fontes consultadas e seu papel](kernodeck-diagnostic-v1-SOURCES.md) distinguem as versões da documentação das versões realmente utilizadas. O [manifesto SHA-256](kernodeck-diagnostic-v1-manifest.json) descreve os arquivos desta entrega. As impressões digitais detectam uma diferença de arquivo; elas não são uma assinatura de autor.


## Apresentação Kernodeck e compatibilidade dos relatórios

A apresentação, o nome do arquivo e a ajuda de comando trazem a marca Kernodeck desde 25 de setembro de 2026. Os identificadores técnicos do esquema JSON permanecem estáveis para os leitores existentes. Os três relatórios de exemplo acima são preservados byte a byte como resultados da execução de 24 de setembro de 2026. Sua presença não constitui uma nova execução desta apresentação. O manifesto distingue esta reedição das verificações históricas.