# AI-For-Beginners トラブルシューティングガイド

このガイドは、[AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) リポジトリを使用または貢献する際に遭遇する一般的な問題を解決する方法を説明します。各問題には背景、症状、説明、そしてステップバイステップの解決策が含まれています。

---

## 目次

- [一般的な問題](../..)
- [インストールの問題](../..)
- [設定の問題](../..)
- [ノートブックの実行](../..)
- [パフォーマンスの問題](../..)
- [教科書ウェブサイトの問題](../..)
- [貢献に関する問題](../..)
- [FAQ](../..)
- [ヘルプの取得](../..)

---

## 一般的な問題

### 1. リポジトリが正しくクローンできない

**背景:** クローン操作はリポジトリを自分のマシンにコピーするためのものです。

**症状:**
- エラー: `fatal: repository not found`
- エラー: `Permission denied (publickey)`

**考えられる原因:**
- リポジトリ URL が間違っている
- 権限が不足している
- SSH キーが設定されていない

**解決策:**
1. **リポジトリ URL を確認する。**  
   HTTPS URL を使用してください:  
   ```
   git clone https://github.com/microsoft/AI-For-Beginners.git
   ```
2. **SSH が失敗した場合は HTTPS に切り替える。**  
   `Permission denied (publickey)` が表示された場合は、SSH の代わりに上記の HTTPS リンクを使用してください。
3. **SSH キーを設定する（オプション）。**  
   SSH を使用したい場合は、[GitHub の SSH ガイド](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) を参照してください。

---

## インストールの問題

### 2. Python 環境の問題

**背景:** このリポジトリは Python とさまざまなライブラリに依存しています。

**症状:**
- エラー: `ModuleNotFoundError: No module named '<package>'`
- スクリプトやノートブックを実行する際のインポートエラー

**考えられる原因:**
- 依存関係がインストールされていない
- Python のバージョンが間違っている

**解決策:**
1. **仮想環境をセットアップする。**  
   ```bash
   python -m venv venv
   source venv/bin/activate   # On Windows: venv\Scripts\activate
   ```
2. **依存関係をインストールする。**  
   ```bash
   pip install -r requirements.txt
   ```
3. **Python のバージョンを確認する。**  
   Python 3.7 以上を使用してください。  
   ```bash
   python --version
   ```

### 3. Jupyter がインストールされていない

**背景:** ノートブックは学習の主要なリソースです。

**症状:**
- エラー: `jupyter: command not found`
- ノートブックが起動しない

**考えられる原因:**
- Jupyter がインストールされていない

**解決策:**
1. **Jupyter Notebook をインストールする。**  
   ```bash
   pip install notebook
   ```
   または、Anaconda を使用している場合:
   ```bash
   conda install notebook
   ```
2. **Jupyter Notebook を起動する。**  
   ```bash
   jupyter notebook
   ```

### 4. 依存関係のバージョンの競合

**背景:** パッケージのバージョンが一致しないとプロジェクトが壊れる可能性があります。

**症状:**
- 不適合なバージョンに関するエラーや警告

**考えられる原因:**
- 古いまたは競合する Python パッケージ

**解決策:**
1. **クリーンな環境でインストールする。**  
   古い venv/conda 環境を削除し、新しい環境を作成してください。
2. **正確なバージョンを使用する。**  
   常に以下を実行してください:
   ```bash
   pip install -r requirements.txt
   ```
   これが失敗した場合は、README に記載されている手順に従って不足しているパッケージを手動でインストールしてください。

---

## 設定の問題

### 5. 環境変数が設定されていない

**背景:** 一部のモジュールはキー、トークン、または設定が必要です。

**症状:**
- エラー: `KeyError` または設定が不足しているという警告

**考えられる原因:**
- 必要な環境変数が設定されていない

**解決策:**
1. **`.env.example` または類似ファイルを確認する。**
2. **`.env` ファイルを作成し、必要な値を入力する。**
3. **環境変数を設定した後にターミナルや IDE を再読み込みする。**

---

## ノートブックの実行

### 6. ノートブックが開かない、または実行できない

**背景:** Jupyter ノートブックは適切なセットアップが必要です。

**症状:**
- ノートブックが起動しない
- ブラウザが自動的に開かない

**考えられる原因:**
- Jupyter がインストールされていない
- ブラウザの設定に問題がある

**解決策:**
1. **Jupyter をインストールする（上記のインストールの問題を参照）。**
2. **ノートブックを手動で開く。**
   - ターミナルから URL（例: `http://localhost:8888/?token=...`）をコピーしてブラウザに貼り付けてください。

### 7. カーネルがクラッシュする、またはフリーズする

**背景:** ノートブックのカーネルはリソース制限やコードエラーでクラッシュすることがあります。

**症状:**
- カーネルが繰り返し死ぬ、または再起動する
- メモリ不足エラー

**考えられる原因:**
- 大規模なデータセット
- 不適合なコードやパッケージ

**解決策:**
1. **カーネルを再起動する。**  
   Jupyter の「Restart Kernel」ボタンを使用してください。
2. **メモリ使用量を確認する。**  
   使用していないアプリケーションを閉じてください。
3. **クラウドプラットフォームでノートブックを実行する。**  
   [Google Colab](https://colab.research.google.com/) や [Azure Notebooks](https://notebooks.azure.com/) を使用してください。

---

## パフォーマンスの問題

### 8. ノートブックの実行が遅い

**背景:** 一部の AI タスクは大量のメモリや CPU を必要とします。

**症状:**
- 実行が遅い
- ノートパソコンのファンがうるさい

**考えられる原因:**
- 大規模なデータセットやモデル
- システムリソースが限られている

**解決策:**
1. **クラウドプラットフォームを使用する。**
   - ノートブックを Colab や Azure Notebooks にアップロードしてください。
2. **データセットのサイズを縮小する。**
   - 練習用にサンプルデータを使用してください。
3. **不要なプログラムを閉じる。**
   - システム RAM を解放してください。

---

## 教科書ウェブサイトの問題

### 9. チャプターが読み込まれない

**背景:** オンライン教科書はレッスンやチャプターを表示します。

**症状:**
- チャプター（例: Transformers/BERT）が欠落している、または開かない

**既知の問題:**  
- [Issue #303](https://github.com/microsoft/AI-For-Beginners/issues/303): 「18 Transformers. BERT. が教科書ウェブサイトで開けない。」ファイル名のエラーが原因（`READMEtransformers.md` ではなく `README.md`）。

**解決策:**
1. **ファイル名の変更エラーを確認する。**  
   貢献者の場合、チャプターファイルが `README.md` という名前になっていることを確認してください。
2. **欠落しているファイルを報告する。**  
   チャプター名とエラーの詳細を記載して GitHub Issue を開いてください。

---

## 貢献に関する問題

### 10. PR が受け入れられない、またはビルドが失敗する

**背景:** 貢献はテストに合格し、ガイドラインに従う必要があります。

**症状:**
- プルリクエストが拒否される
- CI/CD パイプラインエラー

**考えられる原因:**
- テストが失敗している
- コーディング標準に従っていない

**解決策:**
1. **貢献ガイドラインを読む。**
   - リポジトリの [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) に従ってください。
2. **プッシュする前にローカルでテストを実行する。**
3. **リンティングルールやフォーマット要件を確認する。**

---

## FAQ

### 特定のモジュールに関するヘルプはどこで見つけられますか？
- 各モジュールには通常独自の README が付属しています。セットアップや使用方法のヒントはそこから始めてください。

### バグを報告したり機能をリクエストするにはどうすればいいですか？
- [GitHub Issue を開く](https://github.com/microsoft/AI-For-Beginners/issues/new) ことで、明確な説明と再現手順を記載してください。

### このリストにない問題についてヘルプを求めることはできますか？
- もちろんです！既存の Issue を検索し、問題が見つからない場合は新しい Issue を作成してください。

---

## ヘルプの取得

- **Issue を確認する:** [GitHub Issues](https://github.com/microsoft/AI-For-Beginners/issues)
- **質問する:** GitHub Discussions を利用するか、Issue を開いてください。
- **コミュニティ:** チャットやフォーラムのオプションについてはリポジトリリンクを参照してください。

---

_最終更新日: 2025-09-20_

---

**免責事項**:  
この文書は、AI翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を追求しておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があります。元の言語で記載された文書を正式な情報源としてお考えください。重要な情報については、専門の人間による翻訳を推奨します。この翻訳の使用に起因する誤解や誤解釈について、当方は一切の責任を負いません。