PythonとMarvin実践ガイド:AI Functionによる構造化データの自動抽出と分類

Artificial Intelligence tutorial - IT technology blog
Artificial Intelligence tutorial - IT technology blog

背景と実際の課題

ユーザーから送られてくる自由形式のテキストデータを処理するのは、決して容易な作業ではありません。クレームメール、カスタマーサポートの問い合わせ、OCRでスキャンした請求書、注文の備考欄などは常に乱雑です。これらの文字列を細かくパースし、PostgreSQLなどに保存できる標準フォーマットへ変換する必要があります。従来の手法では、正規表現や無数の複雑なif-else分岐に頼ることが一般的でした。しかし、ユーザーの誤字・脱字や表現の揺らぎが少しあるだけで、パーサーはあっけなく破綻してしまいます。

LLMが普及するにつれ、OpenAI APIを呼び出してJSON形式で出力させる手法が当たり前の選択肢となりました。とはいえ、生(Raw)のJSON Schemaを含むプロンプトを自前で構築すると、終わりなきデバッグに悩まされがちです。モデルがJSONの外側に勝手に挨拶文を付け足したり、必須フィールドを欠落させたり、整数の代わりに文字列を返したりすることが頻繁に起こります。一方で、単なるデータ抽出タスクに対してLangChainを導入するのは、抽象化レイヤーが多すぎて過剰(オーバーキル)に感じられます。

システムのトラフィックが1日3,000チケットを超えた際、私たちのチームはよりシンプルで無駄のないアプローチを模索する必要に迫られました。要件は明確でした。型安全(type-safe)であること、アプリケーション層で厳密なバリデーションができること、そして純粋なPythonらしい(Pythonicな)コードで書けることです。そこで私たちが選定し、過去6ヶ月間にわたり抽出サービスのコアライブラリとして運用してきたのがMarvinです。

MarvinはPrefectのチームによって開発されたライブラリです。大規模言語モデルを通常のPython関数(AI Functions)へと変換し、Pydanticとシームレスに統合します。長大なプロンプトテンプレートの作成に頭を悩ませる必要はありません。明確な型ヒント(type hint)を付けて関数を宣言するだけで、セマンティックな推論とスキーマバリデーションのすべてをMarvinがバックグラウンドで自動的に処理してくれます。

環境構築

MarvinはPython 3.10以降で最も快適に動作します。依存関係を分離するために仮想環境を作成することをおすすめします:

# 仮想環境の作成と有効化
python3 -m venv .venv
source .venv/bin/activate

# Marvin、Pydantic v2、python-dotenvのインストール
pip install marvin pydantic python-dotenv

デフォルトでは、MarvinはOpenAIに直接接続します。社内インフラの厳しいセキュリティ要件がある場合でも、Azure OpenAIやClaude、あるいはセルフホストされたOllama環境に接続先を切り替えることが可能です。

接続設定

プロジェクトのルートディレクトリに.envファイルを作成し、APIキーとデフォルトモデルを設定します:

OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
MARVIN_CHAT_COMPLETION_MODEL="gpt-4o-mini"

分類やエンティティ抽出のタスクにおいて、gpt-4o-miniは最もバランスの取れた選択肢です。平均レスポンスタイムはわずか250ms〜400msで、96%以上の精度を達成しつつ、コストはgpt-4oの15分の1程度に抑えられます。

1. marvin.classifyによる即時コンテンツ分類

緊急度に応じたカスタマーサポートチケットのルーティングを例に考えてみましょう。LLMに指示を与えるために2ページもの長文プロンプトを詰め込む代わりに、標準的なEnumを定義するだけで済みます:

from enum import Enum
from dotenv import load_dotenv
import marvin

load_dotenv()

class Priority(Enum):
    LOW = "一般的な問い合わせ、機能改善の要望、営業時間に関する質問"
    MEDIUM = "軽微な表示崩れ、決済フローに影響しない問題"
    HIGH = "アカウントの二重引き落とし、セキュリティインシデント、サービス停止"

customer_message = "アカウントから5,000円が2回引き落とされているのに、注文はキャンセルのままです。至急対応してください!"

# Enumへ直接分類
result = marvin.classify(customer_message, Priority)
print(f"優先度: {result.name} | 定義: {result.value}")
# Output: 優先度: HIGH | 定義: アカウントの二重引き落とし、セキュリティインシデント、サービス停止

MarvinはEnumのdocstringや値を自動的に読み取り、分類の基準として利用します。手動でのプロンプト作成は一切不要です。返却される結果は標準的なEnumインスタンスであるため、ルーターによる条件分岐処理へそのまま即座に渡すことができます。

2. marvin.extractによるPydanticスキーマに基づいたデータ抽出

次の課題:顧客から送られてくる自由形式のホテル予約メールを処理するケースです。氏名、電話番号、チェックイン日、追加の要望を抽出してデータベースに保存する必要があります。

from typing import List, Optional
from datetime import date
from pydantic import BaseModel, Field
import marvin

class BookingRequest(BaseModel):
    customer_name: str = Field(description="顧客名")
    phone_number: Optional[str] = Field(None, description="10桁の電話番号")
    checkin_date: Optional[date] = Field(None, description="チェックイン日")
    room_count: int = Field(default=1, description="予約部屋数")
    special_notes: List[str] = Field(default_factory=list, description="追加の要望")

raw_email = """
こんにちは、Minh Tuan(0912345678)と申します。
2026年11月25日に3部屋予約したいです。
高層階でオーシャンビューの部屋を希望します。作業用のデスクも準備をお願いします。
"""

# Pydanticスキーマに厳密に一致するデータを抽出
bookings = marvin.extract(raw_email, target=BookingRequest)

for booking in bookings:
    print(booking.model_dump_json(indent=2))

出力データは純粋なPydanticインスタンスです。checkin_dateフィールドは自動的にdatetime.date型にキャストされ、部屋数はint型として取得されます。このオブジェクトは型の不一致(type mismatch)を心配することなく、そのままSQLAlchemyセッションへ渡して保存できます。

3. @marvin.fnでPython関数をAI Function化する

これは本ライブラリの最も強力な機能です。@marvin.fnデコレータは、関数のシグネチャとdocstringをモデルの実行ロジックへと変換します:

from pydantic import BaseModel
import marvin

class NormalizedAddress(BaseModel):
    street: str
    ward: str
    district: str
    province: str

@marvin.fn
def parse_vietnamese_address(raw_text: str) -> NormalizedAddress:
    """
    ベトナムにおける略記や非標準の配送先住所文字列を解析し、
    番地/通り、坊/社、郡/区、省/市の4段階の行政区分に正規化する。
    """

address_input = "sn 45 ngõ 120 trần duy hưng, trung hoà, cầu giấy hn"
parsed = parse_vietnamese_address(address_input)

print(f"{parsed.street} | {parsed.ward} | {parsed.district} | {parsed.province}")
# Output: Số 45 ngõ 120 Trần Duy Hưng | Phường Trung Hoà | Quận Cầu Giấy | Hà Nội

この関数は、コードベース内のネイティブな関数とまったく同様に振る舞います。サービス層からは背後でどのモデルが動作しているかを意識することなく呼び出すことができます。

本番運用の実践知見

LLMをシステムのコアフローに組み込むには、堅牢な防御策が欠かせません。外部ネットワークの安定性にシステムの可用性を丸投げするわけにはいかないからです。

1. タイムアウト管理とフォールバックの実装

OpenAI APIはネットワーク遅延や過負荷が発生することがあります。タイムアウトを明示的に設定し、例外をキャッチして安全なデフォルト値を返す設計にしておきましょう:

import logging
import marvin

marvin.settings.openai.chat.completions.timeout = 5.0

def safe_classify_ticket(ticket_content: str) -> Priority:
    try:
        return marvin.classify(ticket_content, Priority)
    except Exception as exc:
        logging.error(f"LLM classification failed: {exc}")
        # 処理フローが中断しないようデフォルトの優先度にフォールバック
        return Priority.MEDIUM

2. キャッシュ活用によるコスト45%削減

実際の現場では、リクエストの約30%〜40%が類似した内容です。入力のハッシュ値をキーにしてRedisキャッシュやfunctools.lru_cacheを導入することで、APIコストを大幅に削減できます:

from functools import lru_cache

@lru_cache(maxsize=4096)
@marvin.fn
def standardize_brand_name(raw_name: str) -> str:
    """ファッションブランド名を正式名称に正規化する(例: nk -> Nike)。"""

私たちのチームでは、頻繁に検索される4,096件のアイテムをキャッシュしたことで、月間のOpenAI請求額を420ドルから230ドルへと削減できました。

3. AI Functionに対する自動ユニットテストの作成

検証テストのないAI Functionを本番環境へデプロイしてはなりません。出力の信頼性を担保するために、pytestと集合(set)形式のアサーションを組み合わせてテストを記述しましょう:

# tests/test_address_parser.py
def test_parse_vietnamese_address():
    raw = "1 Đại Cồ Việt, Bách Khoa, Hai Bà Trưng, Hà Nội"
    res = parse_vietnamese_address(raw)
    
    assert res.province in ["Hà Nội", "Thành phố Hà Nội"]
    assert res.district in ["Hai Bà Trưng", "Quận Hai Bà Trưng"]
    assert "1 Đại Cồ Việt" in res.street

Marvinは非常に直感的で自然な開発体験を提供してくれます。壊れやすいプロンプト文字列を継ぎ接ぎする代わりに、型ヒントと型安全なオブジェクトを直接扱うことができます。これこそが、現代のバックエンドシステムにAIを導入するための最も実践的なアプローチと言えるでしょう。

Share: