> 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/maiagent-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 モニタリング画面**: 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 の自動リフレッシュ機構](/tech/maiagent-tech-ja/advanced-genai-tech/oauth-integration.md) - OAuth Token のリフレッシュロジックの詳細
* [デプロイアーキテクチャ](/tech/maiagent-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/maiagent-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.