Python Pydantic + InstructorでAI応答を自在に操る：構造化出力の完全ガイド

AIアプリを作りたい。でも「JSONの形式で返して」とお願いしても、思った通りにならない。そんな悩みを解決するのがPydanticとInstructorです。

今回はHolySheep AIのAPIを使って、PythonでAIの返答を完全にコントロールする方法をゼロから解説します。

そもそも「構造化出力」って何？

通常のAI会話では、こんな風に曖昧な返答が返ってきます：

質問: 「田中さんの情報を教えて」
AI: 「田中さんは32歳で、東京に住んでいて、
     ソフトウェアエンジニアとして働いています。
     好きな色は青で、休日はカフェ巡りを楽しんでいます。」

これを「名前」「年齢」「職業」などのように整理されたデータとして取得できたら、プログラムで扱いやすくなりますよね？

準備するもの

• Python 3.8以上
• HolySheep AIのAPIキー（登録だけで無料クレジットGET！）

まずは必要なライブラリをインストールしましょう。ターミナルで以下を実行します：

# ターミナルでの実行
pip install instructor pydantic openai

Pydanticでデータ模型を作る

Pydanticは、Pythonでデータの「型」を定義するためのライブラリです。Excelの表 заголовок（列名）を決めるようなものと考えてください。

from pydantic import BaseModel
from typing import Optional

class 人物情報(BaseModel):
    """人物情報を整理するための模型"""
    名前: str                    # 必ず必要な文字列
    年齢: int                    # 必ず必要な整数
    職業: Optional[str] = None   # なくても良い文字列
    都市: Optional[str] = None   # なくても良い文字列

💡ポイント：「Optional」付きの項目は、AIが情報を思い出せない場合でもエラーになりません。

InstructorでAI接続を簡単にする

Instructorは、AIの返答を自動的にPydantic模型に変換してくれるライブラリです。HolySheep AIのAPIに接続してみましょう：

import instructor
from openai import OpenAI

HolySheep AIに接続（api.holysheep.aiを使用）
client = instructor.from_openai(
    OpenAI(
        base_url="https://api.holysheep.ai/v1",
        api_key="YOUR_HOLYSHEEP_API_KEY"  # 自分のAPIキーに置き換えてね
    )
)

Pydantic模型にAI応答を自動変換
人物 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "あなたは情報を整理するアシスタントです"},
        {"role": "user", "content": "私の名前は田中太郎、28歳で東京に住んでいて、ウェブデザイナーとして働いています"}
    ],
    response_model=人物情報  # ← ここでPydantic模型を指定
)

print(f"名前: {人物.名前}")
print(f"年齢: {人物.年齢}")
print(f"職業: {人物.職業}")
print(f"都市: {人物.都市}")

✅ 実行結果の例：

名前: 田中太郎
年齢: 28
職業: ウェブデザイナー
都市: 東京

実践編：複数の人物情報を一度に取得

リストを使って、複数の人物情報を同時に取得することもできます：

from typing import List

class 製品情報(BaseModel):
    """製品情報を整理するための模型"""
    製品名: str
    価格: float
    在庫状況: str

class 製品リスト(BaseModel):
    """製品リストの模型"""
    製品: List[製品情報]
    合計金額: float

結果 = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": """次の3つの製品の情報を整理してください：
        1. iPhone - 12万円 - 在庫あり
        2. MacBook Pro - 25万円 - 残りわずか
        3. AirPods - 3万円 - 在庫あり"""}
    ],
    response_model=製品リスト
)

for p in 結果.製品:
    print(f"📦 {p.製品名}: ¥{p.価格:,} ({p.在庫状況})")

print(f"\n💰 合計金額: ¥{結果.合計金額:,}")

✅ 実行結果の例：

📦 iPhone: ¥120,000 (在庫あり)
📦 MacBook Pro: ¥250,000 (残りわずか)
📦 AirPods: ¥30,000 (在庫あり)

💰 合計金額: ¥400,000

なぜHolySheep AIなのか？

この教程でHolySheep AIを選んだ理由は3つあります：

• 成本的メリット：レートが¥1=$1で提供されており公式サイト比85%節約可能
• 高速応答：レイテンシーが50ms未満で、リアルタイムアプリでもストレスフリー
• 支払いが便利：WeChat PayやAlipayに対応しており、日本語ユーザーはもちろん中国系ユーザーにも優しい

特にDeepSeek V3.2モデルは出力$0.42/MTokという破格の安さで、個人開発や小規模プロジェクトに最適です！

よくあるエラーと対処法

エラー1：APIキーが無効です

# ❌ よくある間違い
api_key="YOUR_HOLYSHEEP_API_KEY"  # そのまま忘れていた

✅ 正しい書き方
api_key="sk-holysheep-xxxxxxxxxxxx"  # 自分の実際のキーに変更

解決方法：HolySheep AIのダッシュボードからAPIキーをコピーして、actualなキーに置き換えてください。キーは「sk-」から始まる英数字です。

エラー2：モデルが構造化出力に対応していない

# ❌ 対応していない古いモデル
model="gpt-3.5-turbo"

✅ 構造化出力対応のモデル
model="gpt-4o-mini"  # または "gpt-4o", "claude-3-5-sonnet"

解決方法：Instructorの構造化出力機能を使う場合は、gpt-4o-mini以上のモデルを指定してください。HolySheep AIでは最新モデルが 저렴な価格で使えます。

エラー3：必須項目のデータが不足している

# ❌ Pydantic定義で全項目を必須にしていた
class 製品情報(BaseModel):
    製品名: str
    価格: float
    在庫状況: str      # 必須 = AIが知らないとエラー

✅ 解決：Optionalで必須項目を減らす
class 製品情報(BaseModel):
    製品名: str
    価格: float
    在庫状況: Optional[str] = "不明"  # デフォルト値を設定

解決方法：AIが必ず返せる項目だけ「必須（必須項目なし）」にして、「なくても良い」項目にはOptional型和デフォルト値を設定しましょう。

エラー4：base_urlのタイプミス

# ❌ 間違い例
base_url="https://api.openai.com/v1"  # 第三方APIは使用禁止

✅ 正しい書き方
base_url="https://api.holysheep.ai/v1"

解決方法：必ず「api.holysheep.ai/v1」を使ってください。openai.comやanthropic.comは прямой接続では使用できません。

まとめ

本次の教程を通じて、以下を学びました：

• Pydanticでデータの「型」を定義する方法
• Instructorを使ってAI返答を自動変換する方法
• HolySheep AIのAPI接続方法
• よくあるエラーの対処法

Pydantic + Instructorの組み合わせは、AIアプリを開発する際の最強ツールセットです。HolySheep AIなら、85%節約で最新AIモデルを気軽にお試しできます！

👉 HolySheep AI に登録して無料クレジットを獲得