Azure OpenAIの404エラーを解決：'DeploymentNotFound'エラーの対処法

問題：Azure OpenAI と標準 OpenAI の命名規則の違い

OpenAI の直接 API から Azure OpenAI への移行は、通常はスムーズなはずですが、特定の命名規則が多くの人を混乱させます。API キーを準備し、エンドポイントも確認済みで、eastus や swedencentral といったリージョンで GPT-4o が有効であることも分かっているとします。しかし、スクリプトを実行すると、SDK が 404 エラーを返します。

openai.NotFoundError: Error code: 404 - {'error': {'code': 'DeploymentNotFound', 'message': 'The model deployment at ID gpt-4o does not exist.'}}

問題の本質は、Azure がモデルを識別する方法にあります。OpenAI の直接 API では、model パラメーターは gpt-4o のようなベースエンジンを指します。しかし Azure は異なります。Azure のコードでは、model パラメーターは Azure AI Studio で作成した**デプロイ名（Deployment Name）**と一致している必要があります。基盤となるモデルが何であるかは関係ありません。SDK はその特定のラベルのみを参照します。

デバッグのプロセス

私は環境変数を再確認するのに 20 分ほど費やしましたが、結局問題は認証情報ではありませんでした。ポータルでデプロイ名を gpt-4o-prod-01 と名付けていたのに、コードでは依然として gpt-4o を探していたのです。単純な不一致ですが、これだけで接続は切れてしまいます。

openai-python ライブラリ (v1.0.0 以降) は、model 引数を特定のデプロイ ID へのポインターとして扱います。これらの文字列が一文字でも異なれば、Azure ゲートウェイはリクエストをルーティングできません。その名前のコンピューティングインスタンスが文字通り見つからないため、404 を返します。

このエラーの主な原因：

Azure AI Studio のデプロイ名が、Python スクリプト内の文字列と異なっている。
デプロイが、エンドポイントが指しているリソースとは別の Azure リソースに存在している。
モデルがまだ「プロビジョニング中」の状態で、トラフィックを受け入れる準備ができていない。

解決策：デプロイ名を一致させる

これを修正するには、Azure ポータルで識別子を同期させる必要があります。

1. Azure AI Studio で名前を確認する

Azure AI Studio にログインし、**デプロイ（Deployments）**タブをクリックします。**デプロイ名（Deployment name）**の列を注意深く確認してください。ハイフンやアンダースコアを含むこの正確な文字列が、コードに記述すべき内容です。

例えば、デプロイ名を marketing-gpt4-v1 とした場合は、スクリプト内でもその特定の文字列を使用する必要があります。

2. Python コードを更新する

AzureOpenAI クライアントの初期化を確認してください。create メソッドの呼び出しで、ポータルにあるデプロイ名が使用されていることを確認します。以下に、正常に動作するクリーンな例を示します：

import os
from openai import AzureOpenAI

# リソースの詳細を使用してクライアントを初期化
client = AzureOpenAI(
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), 
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview" # 現在の安定した API バージョンを使用
)

# 誤り: model="gpt-4o"
# 正解: model="実際のデプロイ名"

response = client.chat.completions.create(
    model="gpt-4o-prod-01", # これは Azure のデプロイ名と一致している必要があります
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Test connection."}
    ]
)

print(response.choices[0].message.content)

3. API バージョンの互換性を確認する

古い api_version を使用すると、GPT-4o のような新しいモデルでルーティングに失敗することがあります。依然としてエラーが発生する場合は、Azure OpenAI のドキュメントで最新のバージョン文字列を確認してください。2024-02-01 や 2024-08-01-preview といった値が、現在のデプロイでは一般的です。

検証：プログラムでデプロイ一覧を取得する

推測に頼るのをやめたい場合は、小さなヘルパースクリプトを使用して、Azure が実際に認識している内容を確認してください。これにより、API キーが機能していることを確認し、リソースで現在アクティブなすべてのデプロイ ID を一覧表示できます。

import os
import requests

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
api_key = os.getenv("AZURE_OPENAI_API_KEY")
url = f"{endpoint}/openai/deployments?api-version=2024-02-01"

headers = {"api-key": api_key}

response = requests.get(url, headers=headers)
if response.status_code == 200:
    data = response.json()["data"]
    for deployment in data:
        print(f"Valid Deployment ID: {deployment['id']} | Base Model: {deployment['model']}")
else:
    print(f"Failed to fetch: {response.status_code}")

ベストプラクティスのまとめ

Azure OpenAI は、標準の OpenAI API とは少し異なる考え方が必要です。将来の 404 エラーを避けるために、以下のルールを覚えておいてください：

モデル名 vs デプロイ ID: model パラメーターは常に deployment_id として扱ってください。
環境変数を使用する: デプロイ名をハードコードしないでください。AZURE_DEPLOYMENT_ID のような変数に保存することで、「開発（dev）」環境と「本番（prod）」環境を簡単に切り替えられるようになります。
リージョンの可用性を確認する: リソースのリージョン（例：uksouth）が、デプロイしたい特定のモデルバージョンを実際にサポートしているか確認してください。