はじめに
FastAPIのエンドポイントで時間のかかる処理をそのまま実行すると、レスポンスが遅くなる。
メール送信・PDF生成・データ集計・外部APIへの大量リクエストなど、「すぐに結果を返さなくていい処理」はバックグラウンドジョブに切り出すべき。LaravelのQueueが便利だったのと同じことをPythonでやりたかった。
調べるとCeleryというライブラリが定番で、ブローカー(メッセージキュー)にAWS SQSを使う構成にした。
全体構成
[FastAPI]
↓ タスクをキューに積む
[SQS(メッセージキュー)]
↓ メッセージを取り出す
[Celery Worker]
↓ 処理を実行
[DB / S3 / 外部API]
LaravelとPythonの対応:
Laravel Queue → Celery
Redis/SQS → SQS(ブローカー)
Queue Worker → Celery Worker
Job クラス → Celery Task(関数)
dispatch() → delay() / apply_async()
インストール
pip install celery
pip install celery[sqs] # SQSサポート
pip install boto3 # AWS SDK
pip install kombu # Celeryの依存(メッセージングライブラリ)
SQSキューの作成
# 標準キューの作成
aws sqs create-queue \
--queue-name my-app-jobs \
--region ap-northeast-1 \
--attributes '{
"VisibilityTimeout": "300",
"MessageRetentionPeriod": "86400",
"ReceiveMessageWaitTimeSeconds": "20"
}'
# デッドレターキューの作成(失敗したメッセージを保存)
aws sqs create-queue \
--queue-name my-app-jobs-dlq \
--region ap-northeast-1
# デッドレターキューのARNを取得
DLQ_ARN=$(aws sqs get-queue-attributes \
--queue-url https://sqs.ap-northeast-1.amazonaws.com/123456789012/my-app-jobs-dlq \
--attribute-names QueueArn \
--query 'Attributes.QueueArn' \
--output text)
# メインキューにDLQを設定(3回失敗したらDLQに移動)
aws sqs set-queue-attributes \
--queue-url https://sqs.ap-northeast-1.amazonaws.com/123456789012/my-app-jobs \
--attributes "{
\"RedrivePolicy\": \"{\\\"deadLetterTargetArn\\\":\\\"$DLQ_ARN\\\",\\\"maxReceiveCount\\\":\\\"3\\\"}\"
}"
SQSのパラメータ:
VisibilityTimeout — ワーカーが処理中にメッセージを他から隠す時間
MessageRetentionPeriod — メッセージの保持期間
ReceiveMessageWaitTimeSeconds — ロングポーリング(20秒待つ)
maxReceiveCount — 失敗してDLQに移動するまでの試行回数
Celeryの設定
# celery_app.py
import os
from celery import Celery
# SQSのブローカーURL
BROKER_URL = "sqs://" # boto3が自動でIAMロールから認証情報を取得
celery_app = Celery(
"myapp",
broker = BROKER_URL,
broker_transport = "sqs",
)
celery_app.config_from_object({
# SQSの設定
"broker_transport_options": {
"region": "ap-northeast-1",
"visibility_timeout": 300,
"polling_interval": 1,
"wait_time_seconds": 20, # ロングポーリング
"queue_name_prefix": "my-app-", # キュー名のプレフィックス
},
# タスクのデフォルト設定
"task_serializer": "json",
"result_serializer": "json",
"accept_content": ["json"],
"task_acks_late": True, # 処理完了後にackを送る
"task_reject_on_worker_lost": True, # ワーカーが死んだらメッセージを戻す
"task_default_queue": "jobs", # デフォルトキュー(my-app-jobsになる)
"worker_prefetch_multiplier": 1, # 一度に1つのタスクを処理
# タスクのリトライ設定
"task_max_retries": 3,
"task_default_retry_delay": 60, # 60秒後にリトライ
})
タスクの定義
# tasks/email_tasks.py
import logging
from celery_app import celery_app
from celery import Task
logger = logging.getLogger(__name__)
class BaseTask(Task):
"""共通の基底タスク"""
abstract = True
def on_failure(self, exc, task_id, args, kwargs, einfo):
logger.error(
f"タスク失敗: {self.name} (id={task_id})\n"
f"引数: {args}, {kwargs}\n"
f"エラー: {exc}"
)
def on_retry(self, exc, task_id, args, kwargs, einfo):
logger.warning(
f"タスクリトライ: {self.name} (id={task_id})\n"
f"エラー: {exc}"
)
def on_success(self, retval, task_id, args, kwargs):
logger.info(f"タスク成功: {self.name} (id={task_id})")
@celery_app.task(
base = BaseTask,
name = "tasks.send_welcome_email",
max_retries = 3,
default_retry_delay = 60,
bind = True, # selfを受け取る(リトライのため)
)
def send_welcome_email(self, user_id: int, email: str, name: str):
"""ウェルカムメールを送信する"""
try:
logger.info(f"ウェルカムメール送信開始: {email}")
# メール送信処理(SESなど)
import boto3
ses = boto3.client('ses', region_name='ap-northeast-1')
ses.send_email(
Source = "noreply@example.com",
Destination = {"ToAddresses": [email]},
Message = {
"Subject": {"Data": f"ようこそ、{name}さん!"},
"Body": {"Text": {"Data": "ご登録ありがとうございます。"}},
},
)
logger.info(f"ウェルカムメール送信完了: {email}")
return {"status": "sent", "email": email}
except Exception as exc:
logger.error(f"メール送信失敗: {exc}")
# 最大リトライ回数まで再試行
raise self.retry(exc=exc, countdown=60)
# tasks/report_tasks.py
import pandas as pd
import boto3
from celery_app import celery_app
from datetime import date
@celery_app.task(
name = "tasks.generate_monthly_report",
time_limit = 600, # 最大10分
soft_time_limit = 540, # 9分でSoftTimeLimitExceptionを発生
)
def generate_monthly_report(year: int, month: int, user_id: int):
"""月次レポートを生成してS3に保存する"""
import logging
logger = logging.getLogger(__name__)
logger.info(f"月次レポート生成開始: {year}年{month}月")
try:
# DBから集計(省略)
df = fetch_monthly_data(year, month)
# Excelに変換
import io
buffer = io.BytesIO()
df.to_excel(buffer, index=False, engine='openpyxl')
buffer.seek(0)
# S3に保存
s3 = boto3.client('s3', region_name='ap-northeast-1')
key = f"reports/{user_id}/{year}/{month:02d}/report.xlsx"
s3.put_object(
Bucket = "my-app-bucket",
Key = key,
Body = buffer.getvalue(),
ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
)
# 署名付きURLを生成(ダウンロードリンク)
url = s3.generate_presigned_url(
'get_object',
Params = {'Bucket': 'my-app-bucket', 'Key': key},
ExpiresIn = 86400, # 24時間有効
)
logger.info(f"月次レポート生成完了: {key}")
return {"status": "completed", "url": url, "key": key}
except Exception as exc:
logger.error(f"レポート生成失敗: {exc}")
raise
FastAPIからタスクを呼ぶ
# main.py
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
from celery_app import celery_app
from tasks.email_tasks import send_welcome_email
from tasks.report_tasks import generate_monthly_report
app = FastAPI()
class UserCreate(BaseModel):
name: str
email: str
@app.post("/users", status_code=201)
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
# DBにユーザーを保存
db_user = User(**user.model_dump())
db.add(db_user)
db.commit()
db.refresh(db_user)
# ウェルカムメール送信をキューに積む(非同期)
send_welcome_email.delay(
user_id = db_user.id,
email = db_user.email,
name = db_user.name,
)
# すぐにレスポンスを返す(メール送信を待たない)
return {"id": db_user.id, "name": db_user.name}
class ReportRequest(BaseModel):
year: int
month: int
@app.post("/reports/generate")
async def request_report(
req: ReportRequest,
current_user: User = Depends(get_current_user),
):
# レポート生成タスクをキューに積む
task = generate_monthly_report.apply_async(
args = [req.year, req.month, current_user.id],
countdown = 0, # すぐに実行
expires = 3600, # 1時間以内に処理されなければ破棄
)
return {
"task_id": task.id,
"status": "queued",
"message": "レポートの生成を開始しました。完了後にダウンロードリンクをお送りします。"
}
タスクの進捗を確認する
# FastAPIのエンドポイントでタスクの状態を返す
from celery.result import AsyncResult
@app.get("/tasks/{task_id}")
async def get_task_status(task_id: str):
result = AsyncResult(task_id, app=celery_app)
response = {
"task_id": task_id,
"status": result.status,
}
if result.status == "SUCCESS":
response["result"] = result.result
elif result.status == "FAILURE":
response["error"] = str(result.result)
elif result.status == "PENDING":
response["message"] = "タスクはキューで待機中です"
return response
タスクの状態を保存するには**バックエンド(Result Backend)**が必要。SQSはブローカーのみでResult Backendには使えないので、Redisやデータベースを使う。
# Result BackendにRedisを使う場合
celery_app = Celery(
"myapp",
broker = "sqs://",
backend = "redis://localhost:6379/0",
)
Celery Workerの起動
# 基本的な起動
celery -A celery_app worker --loglevel=info
# コンカレンシーを指定(並列処理数)
celery -A celery_app worker --loglevel=info --concurrency=4
# 特定のキューだけ処理する
celery -A celery_app worker --queues=jobs,reports
# デーモンとして起動
celery -A celery_app worker --loglevel=info --detach
Dockerでの構成
# Dockerfile.worker(ワーカー用)
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["celery", "-A", "celery_app", "worker",
"--loglevel=info",
"--concurrency=2"]
# compose.yaml
services:
api:
build: .
ports:
- "8000:8000"
env_file: .env
command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
worker:
build:
context: .
dockerfile: Dockerfile.worker
env_file: .env
deploy:
replicas: 2 # ワーカーを2台起動
depends_on:
- api
IAM権限の設定
Celery WorkerがSQSを操作するために必要な権限。
// celery-worker-policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sqs:SendMessage",
"sqs:ReceiveMessage",
"sqs:DeleteMessage",
"sqs:GetQueueUrl",
"sqs:GetQueueAttributes",
"sqs:ListQueues"
],
"Resource": [
"arn:aws:sqs:ap-northeast-1:123456789012:my-app-*"
]
}
]
}
モニタリング — Flower
CeleryのWebベースの監視ツール。
pip install flower
# Flowerを起動
celery -A celery_app flower --port=5555
http://localhost:5555でタスクの実行状況・成功率・ワーカーの状態を確認できる。LaravelのHorizonに相当する。
SQSの代替 — Redisとの比較
| 項目 | SQS | Redis |
|---|---|---|
| 管理 | フルマネージド | 自己管理 or ElastiCache |
| コスト | 従量課金(安い) | インスタンス代 |
| 可用性 | 高い(AWSが管理) | 設定による |
| Result Backend | 使えない | 使える |
| ローカル開発 | localstackが必要 | Docker起動でOK |
| 順序保証 | FIFOキューで可能 | LISTで可能 |
ローカル開発ではRedisを使ってSQSに近い動作を確認する。
# 開発環境ではRedisを使う
BROKER_URL = os.environ.get("CELERY_BROKER_URL", "redis://localhost:6379/0")
celery_app = Celery("myapp", broker=BROKER_URL)
LaravelのQueueとの比較
| 機能 | Laravel Queue | Celery + SQS |
|---|---|---|
| タスク定義 | Jobクラス | 関数(@task) |
| キューに積む | dispatch(new Job()) |
task.delay() |
| リトライ | $this->tries |
max_retries |
| 遅延実行 | ->delay(60) |
countdown=60 |
| 失敗処理 | failed()メソッド |
on_failure() |
| 監視 | Horizon | Flower |
| ブローカー | Redis/SQS/DB | Redis/SQS等 |
Laravel Queueより設定項目が多いが、柔軟性は高い。
まとめ
- Celeryはブローカー(SQS)を通じてタスクを非同期実行する
- タスクは
@celery_app.taskデコレータで定義する - FastAPIからは
task.delay()でキューに積む - タスクの状態確認にはResult Backend(Redis等)が必要
- DLQ(デッドレターキュー)で失敗したメッセージを回収する
- Workerは別コンテナとしてECSで動かす
- Flowerでタスクの実行状況をモニタリングする
LaravelのJobとQueueの仕組みをPythonで実現するにはCelery + SQSが現実的な選択肢だった。設定量はLaravelより多いが、柔軟性は高い。ローカル開発はRedisで代替してSQSとの差分を最小化するのが運用しやすい。