> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/platform-development/celery-periodic-tasks.md).

# 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のアーキテクチャと設定

```mermaid
flowchart LR
    App["Djangoアプリケーション"]
    Beat["Celery Beat<br/>（スケジューラー）"]
    Broker["Message Broker<br/>（Redis/RabbitMQ）"]
    Worker1["Worker 1"]
    Worker2["Worker 2"]
    WorkerN["Worker N"]
    DB[("データベース")]
    
    App -- "タスクを送信" --> Broker
    Beat -- "定期的にトリガー" --> Broker
    Broker -- "タスクを振り分け" --> Worker1
    Broker -- "タスクを振り分け" --> Worker2
    Broker -- "タスクを振り分け" --> WorkerN
    Worker1 -- "データの読み書き" --> DB
    Worker2 -- "データの読み書き" --> DB
    WorkerN -- "データの読み書き" --> DB
```

### 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 タスクの実行フロー

```mermaid
sequenceDiagram
    participant Beat as Celery Beat
    participant Broker as Redis Queue
    participant Worker as Celery Worker
    participant DB as Database
    participant OAuth as OAuth Provider
    
    Note over Beat: 1時間ごとにトリガー
    Beat->>Broker: 更新タスクを送信
    Broker->>Worker: 利用可能なWorkerにタスクを振り分け
    
    Worker->>DB: まもなく期限切れになるTokenを照会<br/>（有効期限が1時間未満）
    DB-->>Worker: 更新対象のToken一覧を返す
    
    loop Tokenを1つずつ処理
        Worker->>DB: Tokenにクライアント認証情報があるか確認
        alt 完全な認証情報がある場合
            Worker->>OAuth: Refresh Tokenを使用して新しいTokenをリクエスト
            OAuth-->>Worker: 新しいAccess Tokenを返す
            Worker->>DB: Token情報を更新
        else 認証情報が不足している場合
            Worker->>DB: 旧形式のTokenとしてマークし、処理対象から除外
        end
    end
    
    Worker->>Broker: タスク完了を報告
```

### 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監視インターフェース**：タスクの実行ステータスやWorkerの稼働状態をリアルタイムで確認できるWebインターフェースです
* **ログ記録**：各タスクの実行時間、パラメータ、結果を詳細に記録します
* **メトリクス収集**：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の自動更新](/tech/ja/advanced-genai-tech/oauth-integration.md) - OAuth Token更新ロジックの詳細を確認できます
* [デプロイアーキテクチャ](/tech/ja/platform-development/architecture.md) - システム全体のアーキテクチャにおけるCeleryの位置付けを確認できます

### 参考リンク

* [Celery Documentation](https://docs.celeryq.dev/)
* [Django Celery Beat](https://django-celery-beat.readthedocs.io/)
* [Flower - Celery Monitoring Tool](https://flower.readthedocs.io/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/ja/platform-development/celery-periodic-tasks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.