Celery 定期タスク設定と OAuth Token のリフレッシュ

本ドキュメントでは、MaiAgent プラットフォームが Celery Beat スケジューラーを使用して定期タスクを実行する方法、特に OAuth Token を自動的にリフレッシュする実装方式について説明します。

1. MaiAgent における Celery の役割

Celery は分散型のタスクキューシステムであり、MaiAgent プラットフォームにおいて重要な役割を担っています。

タスク種別	説明	実行方式
非同期タスク	文書解析やベクトル化など、時間のかかるバックグラウンド処理	Celery Worker がタスクを受け取って実行します
定期タスク	Token のリフレッシュやデータクリーンアップなど、定時実行するメンテナンス作業	Celery Beat がスケジュールに従ってタスクをトリガーします
遅延タスク	通知の定時送信など、特定の時刻に実行する必要があるタスク	countdown または eta パラメータを設定して遅延実行します
タスクチェーン	複数のステップを順番に実行する必要がある複雑なフロー	Celery Chain を使用して複数のタスクを組み合わせます

主な利用シーン:

• ナレッジベース処理: ファイルアップロード後の解析、チャンク分割、ベクトル化などの時間のかかる処理

• 定期メンテナンス: OAuth Token のリフレッシュ、期限切れデータのクリーンアップ、システムのヘルスチェック

• レポート生成: 利用量統計や対話品質分析などのレポートを定期的に生成

• 通知送信: メール通知や Webhook コールバックのバッチ送信

---

2. Celery のアーキテクチャと構成

2.1 コアコンポーネントの説明

• Celery Beat (スケジューラー): 設定されたスケジュール表に従って定期タスクをトリガーします

• Message Broker (メッセージブローカー): Redis または RabbitMQ をタスクキューとして使用します

• Celery Workers (ワーカープロセス): 実際にタスクを実行するワーカープロセスであり、水平スケールが可能です

• Result Backend (結果ストレージ): タスクの実行結果を保存し、通常は Redis またはデータベースを使用します

2.2 定期タスクの構成

MaiAgent は Django Celery Beat を使用して定期タスクを管理しています。

タスク名	スケジュール	説明
OAuth Token のリフレッシュ	1 時間ごと	間もなく期限切れになる OAuth Token を自動的にリフレッシュします
Session のクリーンアップ	毎日深夜	期限切れのユーザー Session を削除します

スケジュール式の種類:

• crontab: Unix の cron に似た時刻式で、分、時、曜日、月などをサポートします

• timedelta: 固定間隔で実行します。例えば 30 分ごとなど

• solar: 日の出・日の入りの時刻に基づくスケジュール

---

3. OAuth Token の自動リフレッシュタスク

3.1 タスクの実行フロー

3.2 クエリ最適化戦略

MaiAgent は複数のクエリ最適化を実装しており、Token リフレッシュの効率を高めています。

• 旧版 Token のフィルタリング: client_id と client_secret を持たない旧版 Token を除外します

• タイムウィンドウクエリ: 今後 1 時間以内に期限切れになる Token のみを照会します

• バッチ処理: リフレッシュ対象の複数の Token を一度に照会し、データベースへの問い合わせ回数を削減します

• エラーハンドリング: リフレッシュに失敗した Token については詳細なエラー情報を記録し、問題の追跡を容易にします

3.3 エラーハンドリングの仕組み

Token のリフレッシュ処理では、以下のようなエラーが発生する可能性があります。

エラー種別	考えられる原因	処理方法
Refresh Token が無効	ユーザーが認可を取り消した、または Token が期限切れになっている	再認可が必要であるとマークし、ユーザーに通知します
ネットワークタイムアウト	OAuth サービスプロバイダーに一時的に接続できない	自動的に 3 回リトライし、指数バックオフ戦略を使用します
レート制限	OAuth サービスのリクエスト頻度の制限を超過した	遅延リトライを行い、ブロックを回避します
クライアント認証情報の誤り	client_id または client_secret が正しくない	エラーを記録し、管理者に構成の確認を通知します

---

4. タスクのモニタリングとデバッグ

4.1 タスク状態のモニタリング

MaiAgent では、Celery タスクの状態を監視するための複数の方法を提供しています。

• Flower モニタリング画面: Web 画面でタスクの実行状態や Worker の健全性をリアルタイムに確認できます

• ログ記録: 各タスクの実行時刻、パラメータ、結果を詳細に記録します

• メトリクス収集: Prometheus と統合し、成功率や実行時間などのタスク実行メトリクスを収集します

• アラート機構: タスクが連続して失敗した場合や実行時間が異常な場合に、自動的にアラートを送信します

4.2 パフォーマンス最適化の推奨事項

Worker プールの構成:

• 並行数の調整: CPU コア数とタスク種別に応じて Worker の並行数を調整します

• キューの分離: 緊急タスクと非緊急タスクを異なるキューに割り当てます

• タスクの優先度: 重要なタスクにはより高い優先度を設定します

タスク設計の原則:

• 冪等性: タスクを安全にリトライでき、副作用が発生しないようにします

• 時効性: 妥当なタスクの有効期限を設定し、期限切れのタスクを実行しないようにします

• 分割処理: 大量のデータ処理では分割戦略を採用し、メモリオーバーフローを回避します

---

5. MaiAgent の Celery 構成における技術的優位性

5.1 信頼性と安定性

• タスクの永続化: タスク情報は Message Broker に保存されるため、システムを再起動しても失われません

• 自動リトライ: タスク失敗後の自動リトライ機構をサポートします

• グレースフルシャットダウン: Worker はシャットダウン前に実行中のタスクを完了させます

• ヘルスチェック: Worker と Beat の稼働状態を定期的にチェックします

5.2 拡張性とパフォーマンス

• 水平スケール: Worker の数を容易に増やしてトラフィックの増加に対応できます

• タスクルーティング: 異なる種別のタスクを専用の Worker プールに割り当てます

• 非同期実行: メインアプリケーションをブロックせず、システムの応答速度を向上させます

• バッチ最適化: スマートなバッチ処理によりデータベースへの問い合わせ回数を削減します

5.3 運用のしやすさ

• 可視化されたモニタリング: Flower が直感的なモニタリング画面を提供します

• 詳細なログ: タスクの実行過程を完全に記録し、問題の調査を容易にします

• 動的な構成: システムを再起動することなくスケジュール表を調整できます

• アラート統合: 企業のモニタリングシステムと統合し、異常を迅速に検知します

---

6. 関連技術ドキュメント

• OAuth 2.0 統合と Token の自動リフレッシュ機構 - OAuth Token のリフレッシュロジックの詳細

• デプロイアーキテクチャ - システム全体のアーキテクチャにおける Celery の位置づけ

参考リンク

• Celery Documentation

• Django Celery Beat

• Flower - Celery Monitoring Tool