# Chẩn đoán PyTorch Kernodeck — phiên bản 1.0.0

Script này kiểm tra rằng một phép tính PyTorch nhỏ và gradient của nó chạy được trên thiết bị yêu cầu. Nó tạo ra một báo cáo JSON chỉ giới hạn ở các trường kỹ thuật hữu ích. Mặc định, nó yêu cầu GPU; muốn kiểm tra CPU thì phải yêu cầu rõ ràng.

Nó không chạy huấn luyện, không đo thông lượng và không chứng nhận bất kỳ ưu đãi thương mại, khả năng huấn luyện hay độ ổn định của máy theo thời gian. Mã gốc của nó được cung cấp theo [giấy phép MIT](kernodeck-diagnostic-v1-LICENSE.md).

## Chuẩn bị và chạy

Tải [script](kernodeck-diagnostic-v1.py), rồi mở terminal trong thư mục chứa nó. Dùng Python của môi trường làm việc bạn, với PyTorch đã được cài sẵn. Script sử dụng thư viện chuẩn của Python 3.10 trở lên; các môi trường thực sự được kiểm soát sẽ được trình bày chi tiết bên dưới. Không có cài đặt hay sửa đổi trình điều khiển nào được thực hiện.

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

Lệnh này chọn GPU đầu tiên mà PyTorch nhìn thấy. Nó thất bại với mã thoát khác không nếu thiếu PyTorch, backend GPU hoặc thiết bị khả dụng. Nó không tự chuyển sang CPU.

Để chỉ kiểm tra phép tính trên CPU:

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

Để chọn một GPU nhìn thấy được và lưu báo cáo vào một tệp mới:

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

Đường dẫn đầu ra do bạn chọn và không xuất hiện trong báo cáo. Tệp đã tồn tại sẽ không bao giờ bị ghi đè. Nếu không có `--output`, script không tạo tệp nào. Bạn có thể đọc mã thoát bằng `$LASTEXITCODE` trong PowerShell hoặc `echo $?` trong shell POSIX.

Nếu việc import PyTorch mất nhiều thời gian hơn, hãy tăng thời gian chờ, trong giới hạn cho phép:

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

| Tùy chọn công khai | Giá trị và tác dụng |
| --- | --- |
| `--device gpu` | Giá trị mặc định; yêu cầu GPU CUDA hoặc ROCm khả dụng. |
| `--device cpu` | Phép tính CPU rõ ràng; không kiểm tra khả năng hiển thị của trình điều khiển GPU. |
| `--device-index N` | Chỉ số PyTorch nhìn thấy được, từ 0 đến 63; mặc định 0. Không có tác dụng với phép tính CPU. |
| `--timeout N` | Thời gian chờ của tiến trình con tính toán, từ 5 đến 120 giây; mặc định 30. |
| `--host-check` | Đọc NVIDIA tùy chọn, giới hạn thêm 3 giây. |
| `--output FICHIER` | Cũng ghi JSON vào một tệp UTF-8 mới. |
| `--help` | Hiển thị trợ giúp, không import PyTorch. |

Bản tải xuống không chứa PyTorch, CUDA, ROCm hay trình điều khiển của chúng. Để chọn bản cài đặt phù hợp với hệ thống của bạn, hãy bắt đầu từ [bộ chọn chính thức PyTorch](https://docs.pytorch.org/get-started/locally/). Một bản cài đặt hợp lệ trên máy khác không chứng minh được GPU của bạn tương thích.

## CUDA, ROCm và kiểm tra máy chủ

Script kiểm tra `torch.version.hip` trước `torch.version.cuda`. Một gói ROCm được nhận diện là `rocm`, ngay cả khi giá trị CUDA của nó là `null`. PyTorch cũng dùng `torch.cuda` và tên thiết bị `cuda` trên ROCm: do đó, một báo cáo `execution.device: "cuda:0"` tự nó không ngụ ý một card NVIDIA. Hãy xem cả `execution.backend`. [Tài liệu HIP của PyTorch](https://docs.pytorch.org/docs/2.14/notes/hip.html)

`torch.cuda.is_available()` cho biết CUDA hiện có khả dụng với PyTorch hay không. Script bổ sung quan sát này bằng một phép tính, gradient của nó và một lần đồng bộ thiết bị yêu cầu. Nó không suy ra rằng một mô hình thực tế sẽ vừa bộ nhớ. [Khả dụng](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.is_available.html) · [Đồng bộ](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.synchronize.html)

Với `--host-check`, một lệnh NVIDIA riêng chỉ hỏi phiên bản trình điều khiển và tổng bộ nhớ tính bằng MiB. Đầu ra của nó phải tuân theo một định dạng số nghiêm ngặt. Việc thiếu `nvidia-smi`, quá thời gian chờ hay đầu ra không nhận dạng được không hủy bỏ một phép tính thành công. Việc đọc này không cấu thành chẩn đoán máy chủ AMD và không cần thiết cho kiểm tra CPU. Nó có thể thấy những card mà tiến trình PyTorch không thấy; danh sách máy chủ không được ghép cặp với các chỉ số PyTorch. [Truy vấn chọn lọc NVIDIA](https://docs.nvidia.com/deploy/nvidia-smi/index.html)

Đối với AMD, phiên bản GPU, hệ thống, trình điều khiển và thư viện phải tạo thành một tổ hợp được hỗ trợ. Script này không thay thế [ma trận tương thích ROCm chính thức](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Đọc JSON

Cấu trúc ổn định cho phiên bản 1:

| Trường | Ý nghĩa |
| --- | --- |
| `schema`, `script_version` | Định dạng và phiên bản của script. |
| `requested_device` | `gpu` hoặc `cpu` ; `unspecified` nếu các đối số không hợp lệ hoặc quá trình thực thi bị gián đoạn. |
| `status`, `code`, `exit_code`, `message` | Kết quả tổng thể, mã ổn định, mã tiến trình và giải thích cố định. |
| `stage` | Bước cuối cùng đã đạt được: import, phát hiện, khả năng hiển thị, cấp phát, tính toán, gradient, đồng bộ hóa, xác thực, v.v. |
| `runtime` | Phiên bản số của Python được sử dụng và họ hệ điều hành; không có mã định danh máy. |
| `pytorch` | Phiên bản gói đã lọc, phiên bản biên dịch CUDA/HIP, backend được khai báo và khả năng hiển thị GPU khi được truy vấn. `null` nếu PyTorch không thể import. |
| `execution` | Thiết bị thực sự được chọn, mô hình GPU đã lọc, tổng bộ nhớ do PyTorch báo cáo, kiểu, hình dạng của ma trận và kết quả các kiểm tra. `null` nếu phép tính chưa được chuẩn bị. |
| `host_check` | Chỉ xuất hiện khi được yêu cầu: trạng thái đọc NVIDIA và hai trường số cho mỗi card. |

Ở chế độ CPU, `pytorch.backend` có thể là `cuda` vì nó mô tả gói đã cài đặt. `execution.backend` vẫn là `cpu` và mô tả phép tính đã thực thi. Khả năng hiển thị GPU, số lượng GPU, mô hình và bộ nhớ GPU khi đó là `null`: chúng chưa được đo.

Bài kiểm tra nhân hai ma trận 2×2 ở kiểu `float32`, xác minh tích `[[4, 4], [10, 8]]`, rồi đến gradient `[[16, 24], [40, 52]]`. Tổng bình phương mong đợi là `196.0`. Các số nguyên nhỏ này cho phép so sánh chính xác ở đây; tính chất này không hứa hẹn khả năng tái lập từng bit của bất kỳ mô hình nào. Việc xác minh sử dụng [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Việc tạo một ngữ cảnh GPU có thể tiêu tốn nhiều bộ nhớ hơn chỉ riêng các ma trận.

`total_memory_bytes` là dung lượng được báo cáo, không phải bộ nhớ trống hoặc khả dụng cho mô hình tương lai của bạn. Script không đo bộ nhớ tối đa của một quá trình huấn luyện, cũng không đo kết nối liên thông, tốc độ hay đa GPU.

## Hiểu một lỗi

| Đầu ra | Mã JSON | Cách đọc và kiểm tra tiếp theo |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Phép tính nhỏ và gradient của nó đều đúng trên thiết bị được chỉ định. |
| 2 | `CLI_ARGUMENTS_INVALID` | Đọc lại `--help` ; giá trị không hợp lệ không được sao chép lại. |
| 3 | `TORCH_MISSING` | Thiếu PyTorch trong Python này. Kiểm tra xem bạn đã chọn đúng môi trường chưa. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch tồn tại nhưng import thất bại; kiểm tra gói và các phụ thuộc của nó. |
| 5 | `GPU_BACKEND_ABSENT` | Gói không khai báo CUDA hay HIP. Hãy chọn một bản phân phối phù hợp, hoặc yêu cầu rõ ràng CPU. |
| 6 | `GPU_UNAVAILABLE` | Gói khai báo một backend GPU, nhưng không có GPU nào khả dụng được hiển thị trong tiến trình này. Kiểm tra quyền truy cập thiết bị và tính tương thích của môi trường. |
| 7 | `DEVICE_INDEX_INVALID` | Chỉ số được yêu cầu không có trong danh sách mà PyTorch hiển thị. |
| 8 | `CHECK_FAILED` | Phép tính hoặc gradient khác với kết quả cố định mong đợi. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Không thể cấp phát hoặc lỗi backend; `stage` chỉ rõ bước, mà không xuất ngoại lệ thô. |
| 10 | `TIMEOUT` | Tiến trình con đã vượt quá thời gian chờ và bị dừng. |
| 11 | `WORKER_FAILED` | Tiến trình con không cung cấp báo cáo hợp lệ. |
| 12 | `OUTPUT_WRITE_FAILED` | Tệp đã tồn tại hoặc không thể truy cập; hãy chọn một tên mới. Trạng thái tổng thể thất bại ngay cả khi phép tính trước đó đã thành công. |
| 130 | `INTERRUPTED` | Bài kiểm tra đã bị gián đoạn. |

Đừng gửi toàn bộ bản dump môi trường của bạn để giải thích một lỗi. Mã và bước trong báo cáo tạo thành nhận định ban đầu; nếu cần điều tra chính xác hơn, hãy xem xét nó trong môi trường của bạn trước khi chia sẻ dữ liệu.

## Dữ liệu và giới hạn

Le script n’effectue aucune requête réseau et ne transmet rien à Kernodeck. Il ne lit pas vos notebooks, jeux de données, comptes, paiements ou checkpoints. Il ne collecte pas de variables d’environnement, de liste de paquets, de nom d’hôte, de nom d’utilisateur, de chemin personnel, de numéro de série, de UUID, de processus GPU ou de jeton.

La version Python, la famille du système, les versions techniques, le modèle GPU filtré et la capacité mémoire peuvent révéler une partie de votre environnement matériel. Examinez le rapport avant de le partager. Les messages bruts de PyTorch et du pilote ne sont pas recopiés ; une version ou un modèle non reconnu devient une valeur neutre. Le rapport peut donc omettre un libellé légitime.

Le délai borne le sous-processus de contrôle, pas le fonctionnement du système ou du pilote. Le script ne répare pas un environnement, ne valide pas un noyau spécialisé et ne remplace pas un essai de votre charge de travail. Aucun logiciel tiers malveillant ou modifié n’a été évalué.

## Contrôles réellement effectués le 24 septembre 2026

Les exemples suivants sont les rapports minimisés réellement produits par le script, sans exception brute ni identifiant de machine. Ils concernent l’environnement de contrôle et ne décrivent aucune offre du catalogue Kernodeck.

| Cas exécuté | Environnement | Résultat |
| --- | --- | --- |
| CPU explicite | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Produit et gradient vérifiés ; perte `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU par défaut | Même environnement, compilation CUDA 12.8, NVIDIA GeForce RTX 5070 | Produit et gradient vérifiés sur `cuda:0` ; perte `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch absent | Windows, Python 3.12.14, sans PyTorch | `TORCH_MISSING`, sortie 3. [JSON d’échec](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU rendu invisible au seul processus de test | Python 3.14.6 et paquet CUDA ci-dessus | `GPU_UNAVAILABLE`, sortie 6. |
| Index absent, arguments invalides, fichier existant | Processus de contrôle séparés | Sorties 7, 2 et 12 ; fichier existant conservé. |

La recette compte 44 contrôles, mêlant ces exécutions réelles et des tests unitaires isolés. Les tests unitaires couvrent notamment un paquet sans backend GPU, la détection HIP, une erreur du backend, un délai dépassé et le filtrage des champs. Ils ne constituent pas des exécutions matérielles ROCm. **Aucun GPU AMD/ROCm n’a été exécuté dans cette recette.** NumPy 2.4.4 était importable dans l’environnement de contrôle, mais le script ne l’importe pas directement.

Les [sources consultées et leur rôle](kernodeck-diagnostic-v1-SOURCES.md) distinguent les versions de documentation des versions réellement utilisées. Le [manifeste SHA-256](kernodeck-diagnostic-v1-manifest.json) décrit les fichiers de cette livraison. Les empreintes détectent une différence de fichier ; elles ne sont pas une signature d’auteur.


## Présentation Kernodeck et compatibilité des rapports

La présentation, le nom du fichier et l’aide de commande portent la marque Kernodeck depuis le 25 septembre 2026. Les identifiants techniques du schéma JSON restent stables pour les lecteurs existants. Les trois rapports d’exemple ci-dessus sont conservés à l’octet comme résultats de l’exécution du 24 septembre 2026. Leur présence ne constitue pas une nouvelle exécution de cette présentation. Le manifeste distingue cette réédition des contrôles historiques.