作成ファイル: PRODUCTION_OPERATIONS_MANUAL.md
週次回帰テスト → 精度確認
↓
正解率 < 90% ？
↓ YES
アラートメール送信
↓
カテゴリ別分析
↓
FAQ追加 / プロンプト強化 / パラメータ調整
↓
再テスト
↓
正解率 ≥ 95% → 本番反映✅ マニュアルの構成（全9章）
1. 概要
- PoC01-08機能一覧と精度への影響
| PoC | 機能 | 目的 | 精度への影響 |
|---|---|---|---|
| PoC01 | ベースライン評価 | 現状把握 | 正解率 66.7%（9問中6問） |
| PoC02 | FAQ決め打ちルーター | FAQ質問の100%正答化 | 0% → 100%（9問） |
| PoC03 | プロンプト強化 | 想像回答の抑制 | 不正確なURL回答の抑止 |
| PoC04 | Personaフィルタ | RAG精度向上 | カテゴリ絞込によるノイズ削減 |
| PoC05 | Rerank + SelfCheck | 回答品質向上 | 誤答防止（2段階検証） |
| PoC06 | 自動チューニング | パラメータ最適化 | top_k 等の自動探索 |
| PoC07 | 回帰テスト + ダッシュボード | 品質監視 | 自動メトリクス可視化 |
| PoC08 | Guardrails + アラート | 本番保護・異常検知 | CircuitBreaker・RateLimiter実装 |
- システム構成図（FAQ Router → RAG Pipeline → Guardrails → Alert）
ChatBot2025
├── FAQ Router (PoC02)
├── RAG Pipeline
│ ├── Persona Filter (PoC04)
│ ├── Reranker + SelfCheck (PoC05)
│ └── Auto Tuning (PoC06)
├── Production Guardrails (PoC08)
│ ├── Circuit Breaker / Rate Limiter
│ ├── Graceful Degradation
│ └── Production Monitor
└── Alert System (PoC08)
├── メール通知（実装途中）
└── Slack通知
Monitoring
├── Regression Test (PoC07)
└── Dashboard / HTML Reports
2. 日次運用（毎日5-15分）
- 朝の点検: サービス稼働確認、アラートメール確認、簡易動作テスト
- 夜のメトリクス確認: Production Monitor、エラーログ確認
3. 週次運用（毎週15-35分）
- 回帰テスト実行: Golden Test Suite、HTMLダッシュボード確認
- パフォーマンス分析: レイテンシ、コスト分析
4. 月次運用（毎月30-90分）
- 総合レビュー: 月次メトリクス集計、品質傾向分析
- FAQ更新: 新規FAQ追加、既存FAQ見直し
5. アラート対応（4種類）
- 📉 正解率低下: カテゴリ別分析 → プロンプト調整
- ⏱️ レイテンシ増加: API遅延確認 → Graceful Degradation
- ❌ エラー率上昇: Circuit Breaker確認 → API障害対応
- 💰 コスト超過: Rate Limiter強化 → ボット攻撃調査
6. トラブルシューティング（4パターン）
- 🔴 サービス起動失敗 → ポート競合、環境変数エラー
- ⚠️ API障害 → Circuit Breaker動作、フォールバック
- 💥 システムエラー → Python例外、設定ファイル検証
- 📊 精度劣化 → 変更履歴確認、ロールバック
7. 精度改善プロセス（5手法）
- FAQ精度改善: 新規FAQ追加、テストケース作成
- プロンプト強化: PoC03テンプレート適用
- RAGデータ拡充: Persona Filter用タグ付与
- 自動チューニング: PoC06による全パラメータ探索
- 手動パラメータ調整: パフォーマンス重視/精度重視/バランス重視
8. 運用コマンド集（7カテゴリ）
# サービス管理
sudo systemctl status piano-chatbot.service
# テスト・評価
PYTHONPATH=. python3 tools/run_qa_regression_full.py
# ログ確認
tail -100 /var/log/piano-chatbot/error.log
# メトリクス確認
cat uploads/qa_reports/production_metrics_$(date +%Y%m%d).json
# 設定変更
nano .env
sudo systemctl restart piano-chatbot.service
# バックアップ・リストア
tar -czf config_backup_$(date +%Y%m%d).tar.gz app/data/person*.txt
# Git操作
git tag -a v1.0.1 -m "Release v1.0.1"9. 付録
- 重要な閾値・目標値表（正解率95%、レイテンシ2000ms、コスト$5など）
- 連絡先・エスカレーション基準（障害レベル1-4）
- 参考資料リンク
📊 主要な運用ポイント
| 運用頻度 | 主な作業 | 所要時間 | 重要度 |
|---|---|---|---|
| 日次 | アラート確認、簡易テスト | 5-15分 | ⭐⭐⭐ |
| 週次 | 回帰テスト、パフォーマンス分析 | 15-35分 | ⭐⭐⭐ |
| 月次 | 総合レビュー、FAQ更新 | 30-90分 | ⭐⭐ |
| 随時 | アラート対応、トラブルシューティング | 変動 | ⭐⭐⭐ |
🎯 精度維持・改善の流れ
週次回帰テスト → 精度確認
↓
正解率 < 90% ？
↓ YES
アラートメール送信
↓
カテゴリ別分析
↓
FAQ追加 / プロンプト強化 / パラメータ調整
↓
再テスト
↓
正解率 ≥ 95% → 本番反映📈 期待される運用効果
- 継続的な高精度維持: 週次テストで95%以上の正解率を維持
- 迅速な障害対応: アラート通知により1時間以内に検知・対応
- 計画的な改善: 月次レビューで戦略的な機能強化
- コスト管理: 日次$5、月次$150以内の予算遵守
- ユーザー満足度向上: レイテンシ2秒以下の高速応答
🔧 次のアクション
このマニュアルに基づいて、以下を実施することを推奨します：
- 運用担当者へのトレーニング – 第8章のコマンド集で実習
- 初回の週次運用実施 – 回帰テスト実行とレポート確認
- アラート設定の有効化 – .envでSMTP設定を完了
- 月次レビュー会議の設定 – 第4章の手順でKPI確認
マニュアルは PRODUCTION_OPERATIONS_MANUAL.md に保存されています。必要に応じて組織の運用ルールに合わせてカスタマイズしてください！
付録：運用マニュアル（原文）
ピアノチャットボット 実運用マニュアル全文
Version: 1.0
対象システム: ChatBot2025（PoC01–08 実装完了版）
最終更新: 2025-11-05
📋 目次
1. 概要
1.1 本マニュアルの目的
本マニュアルは、PoC01〜08で実装された機能群を活用し、
ピアノチャットボットの精度・安定性・信頼性を継続的に維持・改善するための実運用手順を定めるものです。
1.2 実装済みPoC機能一覧
| PoC | 機能 | 目的 | 精度への影響 |
|---|---|---|---|
| PoC01 | ベースライン評価 | 現状把握 | 正解率 66.7%（9問中6問） |
| PoC02 | FAQ決め打ちルーター | FAQ質問の100%正答化 | 0% → 100%（9問） |
| PoC03 | プロンプト強化 | 想像回答の抑制 | 不正確なURL回答の抑止 |
| PoC04 | Personaフィルタ | RAG精度向上 | カテゴリ絞込によるノイズ削減 |
| PoC05 | Rerank + SelfCheck | 回答品質向上 | 誤答防止（2段階検証） |
| PoC06 | 自動チューニング | パラメータ最適化 | top_k 等の自動探索 |
| PoC07 | 回帰テスト + ダッシュボード | 品質監視 | 自動メトリクス可視化 |
| PoC08 | Guardrails + アラート | 本番保護・異常検知 | CircuitBreaker・RateLimiter実装 |
1.3 システム構成
ChatBot2025
├── FAQ Router (PoC02)
├── RAG Pipeline
│ ├── Persona Filter (PoC04)
│ ├── Reranker + SelfCheck (PoC05)
│ └── Auto Tuning (PoC06)
├── Production Guardrails (PoC08)
│ ├── Circuit Breaker / Rate Limiter
│ ├── Graceful Degradation
│ └── Production Monitor
└── Alert System (PoC08)
├── メール通知
└── Slack通知
Monitoring
├── Regression Test (PoC07)
└── Dashboard / HTML Reports
2. 日次運用（毎日実施）
2.1 朝の点検（5〜10分）
2.1.1 サービス稼働確認
sudo systemctl status piano-chatbot.service
# → Active: active (running) が正常
2.1.2 アラートメール確認
- 📧 「🚨 ChatBot Alert」件名のメールを確認
- 📊 Slackチャンネルで通知を確認
異常がある場合 → 5. アラート対応 を参照。
2.1.3 動作テスト（手動）
- 「体験レッスンの流れを教えてください」（FAQ）
- 「ハノンって何ですか？」（音楽理論）
- 「スタッカートの練習方法」（テクニック）
期待結果：
- 3秒以内で応答
- FAQ質問は即答
- その他は適切な生成回答
2.2 夜のメトリクス確認（3〜5分）
cat uploads/qa_reports/production_metrics_$(date +%Y%m%d).json
確認基準：
- error_rate < 0.10
- avg_latency_ms < 3000
- total_cost < $10
- cache_hit_rate > 0.5
3. 週次運用（毎週実施）
3.1 回帰テスト実行（15〜20分）
PYTHONPATH=. python3 tools/run_qa_regression_full.py
確認項目：
- 総合正解率 > 90%
- FAQ Router：100%
- 平均レイテンシ < 3000ms
- エラー率 < 10%
3.2 アラート送信確認
回帰テスト時に自動で発火。メールまたはSlackで閾値超過を報告。
4. 月次運用（毎月実施）
4.1 月次レビュー（30〜60分）
PYTHONPATH=. python3 tools/generate_monthly_report.py
分析観点：
- 精度推移（週次グラフ）
- レイテンシ傾向
- CircuitBreaker・RateLimit発動回数
4.2 FAQ更新
nano app/services/faq_definitions.py
追加・更新後は回帰テストで検証。
5. アラート対応
5.1 主なアラート種別と対応
| 種別 | 判定条件 | 主な対応 |
|---|---|---|
| 正解率低下 | < 90% | 回帰テスト結果分析・カテゴリ特定 |
| レイテンシ増加 | > 3000ms | Graceful Degradation確認 |
| エラー率上昇 | > 10% | API障害／システムログ調査 |
| コスト超過 | > $10 | RateLimiter制限強化 |
各種手順は「メール件名」別に詳細記載（例：🚨 ChatBot Alert: 正解率低下）。
6. トラブルシューティング
| 症状 | 主な原因 | 対処 |
|---|---|---|
| サービス起動失敗 | ポート競合／依存関係エラー | journalctl -u piano-chatbot.service |
| API障害 | OpenAI Timeout／Rate Limit | CircuitBreaker自動復帰を待機 |
| Python例外 | 設定ファイル／KeyError | error.log でトレース確認 |
| 精度低下 | パラメータ・プロンプト変更 | 回帰テストで原因特定 |
7. 精度改善プロセス
改善は以下のサイクルを遵守します：
検知 → 原因分析 → 仮説立案 → 修正 → 回帰テスト → 効果測定 → 反映
主な改善手法
| 手法 | PoC | 効果 |
|---|---|---|
| FAQ追加 | PoC02 | 定型質問の精度向上 |
| プロンプト強化 | PoC03 | 想像回答抑制 |
| RAGデータ拡充 | PoC04 | 情報欠落防止 |
| 自動チューニング | PoC06 | パラメータ最適化 |
| 回帰テスト | PoC07 | 改善効果の定量化 |
A/B比較は compare_reports.py で実施。
8. 運用コマンド集
8.1 基本操作
sudo systemctl restart piano-chatbot.service
sudo systemctl status piano-chatbot.service
sudo journalctl -u piano-chatbot.service -n 100 -f
8.2 テスト系
PYTHONPATH=. python3 tools/run_qa_regression_full.py
PYTHONPATH=. python3 tools/test_alert_service.py
PYTHONPATH=. python3 tools/run_guardrails_demo.py
8.3 ログ・メトリクス確認
tail -100 /var/log/piano-chatbot/error.log
cat uploads/qa_reports/production_metrics_$(date +%Y%m%d).json
9. 付録
9.1 閾値・目標値
| メトリクス | 目標値 | アラート閾値 |
|---|---|---|
| 総合正解率 | 95%以上 | 90%未満 |
| FAQ正解率 | 100% | 未達時アラート |
| 平均レイテンシ | < 2000ms | > 3000ms |
| エラー率 | < 5% | > 10% |
| 日次コスト | < $5 | > $10 |
| Cache Hit Rate | > 60% | < 40% |
| Circuit Breaker | 月10回以下 | 週5回以上 |
| Rate Limit | 月20回以下 | 週10回以上 |
9.2 エスカレーション体制
| 障害レベル | 対応者 | 連絡方法 | 目標対応時間 |
|---|---|---|---|
| Lv1（軽微） | 運用担当 | メール | 営業時間内 |
| Lv2（中度） | 管理者 | メール | 4時間以内 |
| Lv3（重大） | 開発チーム | Slack／電話 | 1時間以内 |
| Lv4（緊急） | 全員 | 緊急連絡網 | 即時 |
9.3 参考資料
- PoC01–08 技術レポート:
uploads/qa_reports/PoC0*_analysis_summary.txt - 設計書:
app/data/poc0*_plan.md - デプロイ手順:
DEPLOYMENT_UBUNTU.md - プロジェクト概要:
README.md
改版履歴
- v1.0（2025-11-05）初版作成 – PoC01〜08対応版
作成者: ChatBot2025 開発チーム
承認者: システム管理者
次回見直し予定: 2025-12-05
このマニュアルは、ピアノチャットボットの本番運用を支えるための「日次〜月次点検・異常検知・改善ループ」を体系化した正式ドキュメントです。
特に PoC08で導入した Guardrails／Alert 機構 を中心に、安定稼働を持続させるための基盤運用を明確に定義しています。
コメント