Pi Agent: Troubleshooting & AI Providers
最終更新：2026-08-31
--- title: "トラブルシューティングとAIプロバイダー" description: "Pi Agentのよくある問題のトラブルシューティングガイドとAIプロバイダーの詳細設定リファレンス。" order: 20 lang: ja
トラブルが起きてもパニックにならないで——問題の90%はこのページで解決できる。
1. よくあるトラブルシューティング
(1) インストール問題
| 問題 | 原因 | 解決策 |
|---|---|---|
| pip installが失敗 | pipバージョンが古い | pip install --upgrade pip |
| ネットワークタイムアウト | ネットワーク問題 | ミラーを使用：-i https://pypi.tuna.tsinghua.edu.cn/simple |
| コンパイルエラー | ビルドツール不足 | build-essential（Linux）またはVS Build Tools（Windows）をインストール |
| 権限エラー | グローバルインストールにrootが必要 | --user または virtualenvを使用 |
(2) API呼び出し問題
| エラーコード | 意味 | 解決策 |
|---|---|---|
| 401 | 認証失敗 | APIキーを確認 |
| 429 | レート制限 | リクエスト頻度を下げるかプランをアップグレード |
| 500 | サーバーエラー | 後で再試行 |
| 503 | サービス利用不可 | プロバイダーのステータスページを確認 |
(3) ツール呼び出し問題
| 問題 | 原因 | 解決策 |
|---|---|---|
| ツールが応答しない | 権限不足 | 信頼レベルとツール権限を確認 |
| ツールがタイムアウト | 実行時間が長すぎる | max_execution_time を増やす |
| 空の結果 | 入力パラメータが不正 | パラメータの型と形式を確認 |
| ファイルが見つからない | パスが間違っている | 絶対パスを使用 |
2. デバッグのヒント
(1) デバッグモードの有効化
BASH
pi-agent chat --debug
PYTHON
agent = Agent(name="debug", debug=True)
(2) 詳細ログ
PYTHON
import logging
logging.basicConfig(level=logging.DEBUG)
agent = Agent(name="debug")
agent.chat("Test message")
(3) イベントトレース
PYTHON
@agent.on("*")
def trace(event):
print(f"[{event.timestamp}] {event.name}: {event.data}")
3. AIプロバイダーリファレンス
(1) DeepSeek
YAML
providers:
deepseek:
api_key: "sk-xxxxxxxx"
base_url: "https://api.deepseek.com"
models:
- name: deepseek-chat
context: 64000
input_price: 1.0
output_price: 2.0
- name: deepseek-reasoner
context: 64000
input_price: 4.0
output_price: 16.0
(2) OpenAI
YAML
providers:
openai:
api_key: "sk-xxxxxxxx"
base_url: "https://api.openai.com/v1"
models:
- name: gpt-4o
context: 128000
input_price: 2.5
output_price: 10.0
- name: gpt-4o-mini
context: 128000
input_price: 0.15
output_price: 0.6
(3) Anthropic
YAML
providers:
anthropic:
api_key: "sk-ant-xxxxxxxx"
base_url: "https://api.anthropic.com"
models:
- name: claude-sonnet-4-20250514
context: 200000
input_price: 3.0
output_price: 15.0
- name: claude-3-5-haiku-20241022
context: 200000
input_price: 0.8
output_price: 4.0
(4) Google Gemini
YAML
providers:
gemini:
api_key: "AIzaxxxxxxxx"
base_url: "https://generativelanguage.googleapis.com/v1beta"
models:
- name: gemini-2.0-flash
context: 1048576
input_price: 0.1
output_price: 0.4
(5) llama.cpp
YAML
providers:
local:
type: llama_cpp
model_path: "./models/qwen2.5-7b-instruct-q4_k_m.gguf"
n_gpu_layers: -1
n_ctx: 4096
(6) Ollama
YAML
providers:
ollama:
type: ollama
base_url: "http://localhost:11434"
model: "qwen2.5:7b"
4. パフォーマンス最適化
PYTHON
agent = Agent(
max_tokens=2048,
temperature=0.3,
context_window=4096,
provider="deepseek",
auto_summarize=True
)
5. ヘルスチェック
例1：診断スクリプト（難易度：⭐）
PYTHON
from pi_agent import Config, Agent
print("=== Pi Agent Diagnostics ===")
config = Config.load()
print(f"Config: {'OK' if config else 'Not found'}")
for name, provider in config.providers.items():
try:
agent = Agent(provider=name)
agent.chat("ping")
print(f"Provider {name}: OK")
except Exception as e:
print(f"Provider {name}: FAIL ({e})")
print("=== Diagnostics Complete ===")
❓ よくある質問
Q Agentが応答しない？
A ネットワーク、APIキーの有効性、プロバイダーのサービス状況を確認してください。詳細なリクエストログにはデバッグモードを有効にしてください。
Q ツール呼び出しの権限が拒否された？
A プロジェクトの信頼レベルを確認してください。shellとfile_writeにはtrustedまたはrestrictedレベルが必要です。
Q より安いモデルに切り替えたい？
A インタラクティブ：
/model gpt-4o-mini。コード：Agent(model="deepseek-chat")。設定：default_modelを変更。📖 まとめ
- 3つの問題カテゴリ：インストール、API、ツール——それぞれにトラブルシューティング方法がある
- デバッグツールキット：--debug、logging、イベントトレース
- 6つのAIプロバイダーの完全な設定リファレンス
- パフォーマンス最適化：レイテンシ削減、コスト削減、同時実行制御
- ヘルスチェックスクリプトで迅速な問題診断
📝 練習問題
- 基礎（難易度：⭐）: ヘルスチェックスクリプトを実行し、環境が正しく設定されていることを確認してください。
- 中級（難易度：⭐⭐）: 2つのプロバイダーを設定し、バックアッププロバイダーに自動フェイルオーバーするコードを書いてください。
- 上級（難易度：⭐⭐⭐）: 完全な監視ソリューションを実装してください：定期的なプロバイダーチェック、レスポンスレイテンシ追跡、トークン使用量トレンド、異常時のアラート。
