ソフトウェアエンジニア必見！12-factor-agentsでLLMアプリの悪夢を打ち砕く方法

humanlayer/12-factor-agents

プロダクション環境で顧客に安心して使ってもらえるLLM（大規模言語モデル）搭載ソフトウェアを開発する…それは、まるで霧に包まれた夜の森を進むようなもの。一歩間違えれば、魑魅魍魎（ちみもうりょう）が跋扈するデバッグの沼に引きずり込まれ、悪夢のようなパフォーマンス問題に苛まれるだろう。しかし、恐れることはない。我々ソフトウェアエンジニアには、この暗闇を照らす灯台がある。それが「12-factor-agents」の原則だ！

この「12-factor-agents」は、一言で言えば、プロダクション環境で安定して動作するLLMアプリケーションを構築するための設計原則だ。元々はウェブアプリケーション開発で広く知られる「The Twelve-Factor App」の原則を、LLMの特性に合わせて再解釈・拡張したもの。LLM特有の気まぐれさや予測不能性、そしてパフォーマンスの問題といった「亡霊」のような課題に、どのように立ち向かうべきかを教えてくれる。

この原則は、まるで古文書に記された禁断の呪文のように、我々がLLMアプリケーション開発で直面する以下の恐ろしい問題に対処するためにある。

不安定な挙動: LLMは同じ入力でも異なる出力を返すことがある。まるで憑りつかれたかのように、突然おかしな回答を生成することも。

パフォーマンスの悪化: LLMの推論には時間がかかる。ユーザーを待たせれば、まるで永遠のような沈黙がアプリケーションを覆うだろう。

状態管理の複雑さ: 会話の履歴やユーザーの好みをLLMにどう「記憶」させるか？ これはまるで記憶をなくした幽霊のように、曖昧で掴みどころがない。

デプロイと運用地獄: 新しいモデルへの切り替えや機能追加で、プロダクション環境が崩壊する悪夢。

これらの問題は、まさに夜な夜な我々のコードに忍び寄る「恐怖のミステリーホラー」なのだ。

12-factor-agentsの原則に従うことで、我々ソフトウェアエンジニアは以下の「呪い」から解放される。

可観測性の向上: アプリケーションが「なぜ」異常な挙動をしているのか、まるで憑依された霊魂を特定するかのように、その原因を突き止める手がかりが得られる。ログやメトリクスが充実し、問題の切り分けが容易になる。

堅牢性の確保: LLMの応答が不安定でも、アプリケーション全体が道連れにならないよう、適切なエラーハンドリングやフォールバック戦略を立てられる。まるで結界を張るかのように、システム全体を守ることができる。

スケーラビリティの向上: ユーザーが増えても、まるで無限の魔力を持つかのように、アプリケーションが柔軟に対応できるよう設計できる。トラフィックの急増にも動じない。

デプロイと運用の簡素化: 新しいバージョンのデプロイやロールバックが、まるで魔法のようにスムーズになる。手作業によるミスやダウンタイムの恐怖から解放される。

チーム開発の効率化: 複数の開発者が関わる場合でも、コードベースの一貫性が保たれ、まるで魂を共有するかのように、互いの作業が衝突しない。

具体的な導入方法は、まるで悪霊を鎮めるための儀式のように、慎重かつ段階的に進める必要がある。

設定情報をコードから分離し、環境変数や設定ファイルで管理する。これにより、本番環境と開発環境で異なる設定を簡単に切り替えられる。

# settings.py (開発環境用)
OPENAI_API_KEY = "sk-development-key"
MODEL_NAME = "gpt-3.5-turbo"

# プロダクション環境では環境変数で設定
# export OPENAI_API_KEY="sk-production-key"
# export MODEL_NAME="gpt-4o"

import os

# 環境変数から取得、なければデフォルト値を使用
api_key = os.getenv("OPENAI_API_KEY", "your_default_dev_key")
model_name = os.getenv("MODEL_NAME", "gpt-3.5-turbo")

print(f"Using API Key: {api_key}")
print(f"Using Model: {model_name}")

各リクエストは独立して処理され、エージェント自身はセッションの状態を持たないようにする。セッション情報はデータベースや外部のキャッシュに保存し、必要に応じて取得する。

# 悪い例: エージェントが状態を持つ
class StatefulAgent:
    def __init__(self):
        self.history = []

    def process_query(self, query):
        self.history.append(query)
        # LLM呼び出し
        response = call_llm(self.history)
        return response

# 良い例: エージェントはステートレス
def process_query_stateless(user_id, session_id, query, message_history):
    # 外部から取得した履歴を使ってLLMを呼び出す
    current_history = message_history + [{"role": "user", "content": query}]
    response = call_llm(current_history)
    # 新しい履歴を外部に保存する
    save_history_to_db(user_id, session_id, current_history + [{"role": "assistant", "content": response}])
    return response

# 実際の呼び出し例
# ユーザーのリクエストごとに履歴をDBなどから取得し、渡す
user_id = "user123"
session_id = "session456"
# DBから前回の会話履歴を取得
previous_history = get_history_from_db(user_id, session_id)
response = process_query_stateless(user_id, session_id, "今日の天気は？", previous_history)

# 会話履歴を扱うAPI層やサービス
# FastAPIの例
from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Dict

app = FastAPI()

# データベースのモック
conversation_db = {}

class Message(BaseModel):
    role: str
    content: str

class ConversationRequest(BaseModel):
    user_id: str
    session_id: str
    messages: List[Message]

@app.post("/save_