Mistral AI 422 Unprocessable Entityを修正：不正なAPIパラメータによるMistralAPIStatusException

TL;DR

HTTP 422 を伴う mistralai.exceptions.MistralAPIStatusException は、ネットワークや認証の問題ではなく、パラメータのバリデーションエラーです。Mistral API は JSON の解析自体は成功しましたが、その内容を拒否しました。よくある原因としては、モデル名の誤り、1.0 を超える temperature、無効なメッセージロール、または Mistral がサポートしていない frequency_penalty などのフィールドが挙げられます。detail フィールドで問題のあるパラメータを特定し、修正してください。

エラーの見た目

mistralai.exceptions.MistralAPIStatusException: Status: 422. Message: {"message": "Invalid request", "detail": [{"loc": ["body", "temperature"], "msg": "value is not a valid float", "type": "value_error.number.not_lt"}]}

mistralai SDK は、2xx 以外のすべての HTTP レスポンスを MistralAPIStatusException でラップします。HTTP 422 は Unprocessable Entity（処理不可能なエンティティ）を意味し、サーバーがリクエストの解析には成功したものの、その内容がバリデーションに失敗したことを示します。これは常にコード側のバグです。ネットワークの問題でも、障害でも、認証の問題でもありません。レスポンスボディに何が問題だったかが正確に記載されています。

原因

モデル名のタイポまたは未サポートのモデル — 例："mistral-gpt-4" や "mistral-large"（-latest などのバージョンサフィックスが必要）
temperature の範囲外 — Mistral は 0.0〜1.0 を受け付けます。1.5 や 2 を渡すと 422 が発生します
無効なメッセージロール — 有効なのは "user"、"assistant"、"system"、"tool" のみです
パラメータの型の誤り — 例：max_tokens を整数 500 ではなく文字列 "500" で渡す
サポートされていない追加フィールド — frequency_penalty や presence_penalty など OpenAI 固有のパラメータは Mistral の API に存在しません
空または不正な形式のメッセージリスト — メッセージが全くない、または content キーが欠けているメッセージがある

ステップ 1 — detail フィールドを読む

推測する前に、エラーを読んでください。すべての 422 レスポンスには、問題のあるフィールドを特定してその理由を説明する detail 配列が含まれています。例外をキャッチして出力してみましょう：

import mistralai

try:
    response = client.chat.complete(model=model, messages=messages, temperature=temp)
except mistralai.exceptions.MistralAPIStatusException as e:
    print("Status:", e.http_status)
    print("Body:", e.message)   # 生の JSON detail が含まれています
    raise

出力の中で、loc が問題のフィールドを示します — 例：["body", "temperature"] — そして msg がどのルールに違反したかを教えてくれます。まずここから始めましょう。推測は禁物です。

ステップ 2 — モデル名を検証する

モデル ID は大文字・小文字を区別し、正確なバージョンサフィックスが必要です。"mistral-large" は失敗しますが、"mistral-large-latest" は動作します。API から現在のリストを取得して、自分のアカウントで実際に使用できるモデルを確認しましょう：

from mistralai import Mistral

client = Mistral(api_key="your-api-key")
models = client.models.list()
for m in models.data:
    print(m.id)

返ってきた ID の中から選んでください — mistral-large-latest、mistral-small-latest、open-mistral-7b など。名前を作り上げないでください。

ステップ 3 — パラメータの範囲を修正する

Mistral は厳密な型と値の範囲を強制します。各パラメータが受け付ける値は以下のとおりです：

temperature：0.0 から 1.0 までの浮動小数点数（両端を含む）
top_p：0.0 から 1.0 までの浮動小数点数
max_tokens：正の整数、モデルのコンテキストウィンドウを超えないこと
random_seed：整数（浮動小数点数は不可）

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    temperature=0.7,      # float 0.0–1.0、1.5 や 2 は不可
    top_p=0.9,
    max_tokens=512,       # int、"512" は不可
    random_seed=42,       # 設定する場合は int
)

ステップ 4 — messages 配列を検証する

すべてのメッセージには role と content の 2 つのキーが必要です。ロールは厳密に 4 つの値のいずれかでなければならず、それ以外は 422 を引き起こします。

# 誤り — 422 が発生します
messages = [
    {"role": "human", "content": "Hi"},   # 無効なロール
    {"role": "ai", "text": "Hello"},       # キーの誤り + ロールの誤り
    {"role": "user"},                       # content が欠けている
]

# 正しい
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"},
    {"role": "assistant", "content": "4"},
    {"role": "user", "content": "And 3+3?"},
]

もう一点：空の messages=[] は常に失敗します。少なくとも 1 つのメッセージが必要です。

ステップ 5 — 未知のパラメータを削除する

OpenAI から移行していますか？いくつかの OpenAI パラメータは Mistral の API に存在しないため、渡すと 422 が発生します：

# OpenAI には存在するが Mistral には存在しないパラメータ（422 が発生します）
# frequency_penalty, presence_penalty, logit_bias, logprobs, n

# Mistral の安全な chat.complete() パラメータ（SDK v1.x 時点）
response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    temperature=0.7,
    top_p=1.0,
    max_tokens=1024,
    stream=False,
    safe_prompt=False,
    random_seed=None,
)

ステップ 6 — SDK バージョンの不一致

mistralai SDK は 0.x と 1.x の間で破壊的な API 変更がありました。旧来の呼び出しは client.chat() で、新しい呼び出しは client.chat.complete() です。誤ったパターンを使用すると AttributeError が発生します。古いスタイルのキーワード引数を新しいクライアントに渡すと 422 が発生します。

# インストール済みバージョンを確認する
pip show mistralai

# 最新の安定版にアップグレードする
pip install --upgrade mistralai

0.x に留まる必要がある場合は、0.x の呼び出しパターンを使用してください：

# mistralai 0.x
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage

client = MistralClient(api_key="your-api-key")
response = client.chat(
    model="mistral-small",
    messages=[ChatMessage(role="user", content="Hello")],
)

動作確認

修正を加えたら、この簡単なスモークテストを実行してください。例外が発生しなければ問題ありません：

from mistralai import Mistral

client = Mistral(api_key="your-api-key")
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Say OK"}],
    temperature=0.5,
    max_tokens=10,
)
print(response.choices[0].message.content)  # OK と出力されるはずです

クイックリファレンス — 有効 vs 無効

# 無効 → 422
client.chat.complete(
    model="mistral-large",          # -latest またはバージョンサフィックスが欠けている
    messages=[],                     # 空のリスト
    temperature=2.0,                 # 範囲外
    max_tokens="1000",               # int ではなく文字列
    frequency_penalty=0.5,           # サポートされていないパラメータ
)

# 有効
client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}],
    temperature=0.7,
    max_tokens=1000,
)

参考資料

Mistral AI API リファレンス — 完全なパラメータリストと制約
GitHub の mistralai Python SDK — 0.x と 1.x 間の変更履歴
Mistral のモデル ID — 現在有効なモデル名