次の方法で共有


Azure OpenAI グローバル バッチ デプロイの概要

Azure OpenAI Batch API は、大規模で大量の処理タスクを効率的に処理するように設計されています。 個別のクォータ、24 時間のターゲット ターンアラウンド、グローバル スタンダードと比較した場合の 50% 低いコストで要求の非同期グループを処理します。 バッチ処理では、一度に 1 つの要求を送信するのではなく、1 つのファイル内で多数の要求を送信します。 グローバル バッチ要求には、オンライン ワークロードの中断を回避する個別のエンキュー トークン クォータがあります。

主なユース ケースは次のとおりです。

  • 大規模なデータ処理: 広範なデータセットを並列ですばやく分析します。

  • コンテンツ生成: 製品の説明や記事など、大量のテキストを作成します。

  • ドキュメントの校閲と要約: 長いドキュメントの校閲と要約を自動化します。

  • カスタマー サポートの自動化: 多数の問い合わせを同時に処理して迅速な対応を実現します。

  • データの抽出と分析: 膨大な量の非構造化データから情報を抽出して分析します。

  • 自然言語処理 (NLP) タスク: 大規模なデータセットに対して感情分析や翻訳などのタスクを実行します。

  • マーケティングとパーソナル化: パーソナル化されたコンテンツとレコメンデーションを大規模に生成します。

重要

Microsoft は 24 時間以内にバッチ要求を処理することを目指します。それ以上の時間がかかるジョブを期限切れにすることはありません。 ジョブはいつでもキャンセルできます。 ジョブをキャンセルすると、残りの作業はすべてキャンセルされ、既に完了した作業があればそれが戻されます。 完了した作業があればそれに対する課金が行われます。

保存されたデータは指定された Azure の地理的な場所に留まりますが、推論のためのデータ処理は任意の Azure OpenAI の場所で実行される可能性があります。 データ所在地の詳細を確認する。 

グローバル バッチのサポート

リージョンとモデルのサポート

グローバル バッチが現在サポートされているのは以下のリージョンです。

リージョン gpt-4o2024 年 5 月 13 日 gpt-4o2024-08-06 gpt-4o-mini2024-07-18 gpt-40613 gpt-4turbo-2024-04-09 gpt-35-turbo0613 gpt-35-turbo1106 gpt-35-turbo0125
australiaeast
brazilsouth
canadaeast
eastus
eastus2
francecentral
germanywestcentral
japaneast
koreacentral
northcentralus
norwayeast
polandcentral
southafricanorth
southcentralus
southindia
swedencentral
switzerlandnorth
uksouth
westeurope
westus
westus3

以下のモデルがグローバル バッチをサポートしています。

モデル バージョン 入力形式
gpt-4o 2024-08-06 テキストと画像
gpt-4o-mini 2024-07-18 テキストと画像
gpt-4o 2024-05-13 テキストと画像
gpt-4 turbo-2024-04-09 text
gpt-4 0613 text
gpt-35-turbo 0125 text
gpt-35-turbo 1106 text
gpt-35-turbo 0613 text

グローバル バッチが現在サポートされているリージョン/モデルに関する最新情報についてはモデルに関するページを参照してください。

API のサポート

API バージョン
最新の GA API リリース: 2024-10-21
最新のプレビュー API リリース: 2024-10-01-preview

サポートは最初に 2024-07-01-preview に追加されました

機能サポート

現在、以下はサポートされていません。

  • Assistants API との統合。
  • Azure OpenAI On Your Data 機能との統合。

Note

構造化出力がグローバル バッチでサポートされるようになりました。

グローバル バッチ デプロイ

Azure AI Foundry ポータルでは、デプロイの種類が Global-Batch として表示されます。

Global-Batch デプロイ タイプが強調表示されている Azure AI Foundry ポータルのモデル デプロイ ダイアログを示すスクリーンショット。

ヒント

エンキューされたトークン クォータ が不足することによるジョブの失敗を回避するために、すべてのグローバル バッチ モデル デプロイに対して動的クォータを有効 にすることをお勧めします。 動的クォータを使用すると、余剰容量がある場合には、デプロイがより多くのクォータを臨機応変に活用することができます。 動的クォータがオフに設定されている場合、デプロイは、デプロイの作成時に定義されたエンキューされたトークン制限までの要求のみを処理できます。

前提条件

バッチ ファイルの準備

ファインチューニングと同様に、グローバル バッチは JSON 行 (.jsonl) 形式のファイルを使用します。 さまざまな種類のサポートされるコンテンツのファイル例を以下に示します。

入力形式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id は、個々のバッチ要求の内どれが特定の応答に対応するのかを識別できるようにするために必要です。 応答は、.jsonl バッチ ファイル内で定義されている順序と同じ順序では返されません。

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。

重要

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。 バッチ ファイルの各行に存在するグローバル バッチ モデル デプロイ名はいずれも同じである必要があります。別のデプロイをターゲットにする場合は、別のバッチ ファイルまたはジョブでそれを行う必要があります。

パフォーマンスを最大限に高めるには、各ファイルに数行しかない多数の小さなファイルではなく、バッチ処理用に大きなファイルを送信することをお勧めします。

入力ファイルを作成する

この記事では、test.jsonl という名前のファイルを作成し、上記の標準入力コード ブロックからファイルに内容をコピーします。 グローバル バッチ デプロイ名を変更してファイルの各行に追加する必要があります。

バッチ ファイルをアップロードする

入力ファイルが準備できたら、まずファイルをアップロードして、バッチ ジョブを開始できるようにする必要があります。 ファイル アップロードは、プログラム的にも Studio 経由でも実行できます。

  1. Azure AI Foundry ポータルにサインインします。

  2. グローバル バッチ モデル デプロイを利用できる Azure OpenAI リソースを選択します。

  3. [バッチ ジョブ]>[+ バッチ ジョブの作成] を選択します。

    Azure AI Foundry ポータルのバッチ ジョブ作成エクスペリエンスを示すスクリーンショット。

  4. [バッチ データ]>[ファイルのアップロード] の下のドロップダウンから >[ファイルのアップロード] を選択して前の手順で作成した test.jsonl ファイルのパスを指定 >[次へ]

    ファイルのアップロード エクスペリエンスを示すスクリーンショット。

バッチ ジョブを作成する

[作成] を選択してバッチ ジョブを開始します。

Azure AI Foundry ポータル エクスペリエンスの [バッチ ジョブの作成] のスクリーンショット。

バッチ ジョブの進行状況を追跡する

ジョブが作成されたら、最後に作成されたジョブのジョブ ID を選択することで、ジョブの進行状況を監視できます。 既定では、最後に作成したバッチ ジョブの状態ページが表示されます。

現在検証中のジョブのバッチ ジョブ ID を示すスクリーンショット。

以下のように右側のペインで、ジョブのジョブ状態を追跡できます。

Azure AI Foundry ポータルのバッチ ジョブ状態エクスペリエンスを示すスクリーンショット。

バッチ ジョブ出力ファイルを取得する

ジョブが完了するか、終了状態に達すると、エラー ファイルと出力ファイルが生成されます。このファイルは、下矢印アイコンが付いたそれぞれのボタンを選択して、ダウンロードして確認できます。

ダウンロード可能なバッチ ジョブの出力ファイルとエラー ファイルを示すスクリーンショット。

バッチをキャンセルする

進行中のバッチをキャンセルします。 バッチは、最大 10 分間状態 cancelling に留まった後 cancelled に変化し、出力ファイルには部分的な結果 (存在する場合) が出力されます。

Azure AI Foundry ポータルのバッチ ジョブ [キャンセル] ボタンを示すスクリーンショット。

前提条件

この記事の手順は、Jupyter Notebook で順番に実行することを意図したものです。 このため、Azure OpenAI クライアントは、例の最初に 1 回だけインスタンス化します。 順番を守らずに手順を実行したい場合は、多くの場合、その呼び出しの一環として Azure OpenAI クライアントを設定する必要が生じます。

OpenAI Python ライブラリが既にインストールされている場合でも、以下のようにインストールを最新バージョンにアップグレードする必要があるかもしれません。

!pip install openai --upgrade

バッチ ファイルの準備

ファインチューニングと同様に、グローバル バッチは JSON 行 (.jsonl) 形式のファイルを使用します。 さまざまな種類のサポートされるコンテンツのファイル例を以下に示します。

入力形式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id は、個々のバッチ要求の内どれが特定の応答に対応するのかを識別できるようにするために必要です。 応答は、.jsonl バッチ ファイル内で定義されている順序と同じ順序では返されません。

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。

重要

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。 バッチ ファイルの各行に存在するグローバル バッチ モデル デプロイ名はいずれも同じである必要があります。別のデプロイをターゲットにする場合は、別のバッチ ファイルまたはジョブでそれを行う必要があります。

パフォーマンスを最大限に高めるには、各ファイルに数行しかない多数の小さなファイルではなく、バッチ処理用に大きなファイルを送信することをお勧めします。

入力ファイルを作成する

この記事では、test.jsonl という名前のファイルを作成し、上記の標準入力コード ブロックからそのファイルに内容をコピーします。 グローバル バッチ デプロイ名を変更してファイルの各行に追加する必要があります。 このファイルは、Jupyter Notebook を実行しているのと同じディレクトリに保存します。

バッチ ファイルをアップロードする

入力ファイルが準備できたら、まずファイルをアップロードして、バッチ ジョブを開始できるようにする必要があります。 ファイル アップロードは、プログラム的にも Studio 経由でも実行できます。 この例では、キーとエンドポイントの値の代わりに環境変数を使用します。 Python で環境変数を使用する方法に慣れていない場合は、ステップバイステップで環境変数を設定するプロセスが説明されているクイックスタートのいずれかを参照してください。

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
  azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
  azure_ad_token_provider=token_provider,
  api_version="2024-10-21"
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch"
)

print(file.model_dump_json(indent=2))
file_id = file.id

出力:

{
  "id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "bytes": 815,
  "created_at": 1722476551,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": null,
  "status_details": null
}

バッチ ジョブを作成する

ファイルが正常にアップロードされたら、バッチ処理のためにファイルを送信できます。

# Submit a batch job with the file
batch_response = client.batches.create(
    input_file_id=file_id,
    endpoint="/chat/completions",
    completion_window="24h",
)

# Save batch ID for later use
batch_id = batch_response.id

print(batch_response.model_dump_json(indent=2))

Note

現状、完了期間は 24 時間に設定する必要があります。 24 時間以外の値を設定すると、ジョブは失敗します。 24 時間を超えるジョブは、キャンセルされるまで実行が継続されます。

出力:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": null,
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": null,
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

バッチ ジョブの進行状況を追跡する

バッチ ジョブを正常に作成したら、Studio 内またはプログラム的に進行状況を監視できます。 バッチ ジョブの進行状況を確認するときは、各状態呼び出しの間に少なくとも 60 秒待機することをお勧めします。

import time
import datetime 

status = "validating"
while status not in ("completed", "failed", "canceled"):
    time.sleep(60)
    batch_response = client.batches.retrieve(batch_id)
    status = batch_response.status
    print(f"{datetime.datetime.now()} Batch Id: {batch_id},  Status: {status}")

if batch_response.status == "failed":
    for error in batch_response.errors.data:  
        print(f"Error code {error.code} Message {error.message}")

出力:

2024-07-31 21:48:32.556488 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: validating
2024-07-31 21:49:39.221560 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:50:53.383138 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:52:07.274570 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:53:21.149501 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:54:34.572508 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:55:35.304713 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:56:36.531816 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:57:37.414105 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: completed

以下の状態の値があり得ます。

Status 説明
validating バッチ処理を開始する前に、入力ファイルの検証が行われています。
failed 入力ファイルが検証プロセスに失敗しました。
in_progress 入力ファイルの検証が成功し、バッチが現在実行中です。
finalizing バッチが完了し、結果が準備されています。
completed バッチが完了し、結果の準備が整いました。
expired バッチを 24 時間の時間枠内で完了できませんでした。
cancelling バッチは cancelled の最中です (これが有効になるには最大で 10 分かかる場合があります。)
cancelled バッチが cancelled されました。

ジョブ状態の詳細を確認するには、次を実行します。

print(batch_response.model_dump_json(indent=2))

出力:

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "completed",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": 1722477429,
  "error_file_id": "file-c795ae52-3ba7-417d-86ec-07eebca57d0b",
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": 1722477177,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "file-3304e310-3b39-4e34-9f1c-e1c1504b2b2a",
  "request_counts": {
    "completed": 3,
    "failed": 0,
    "total": 3
  }
}

error_file_id と個別の output_file_id の両方があることを確認します。 error_file_id を使用して、バッチ ジョブで発生する問題のデバッグを支援します。

バッチ ジョブ出力ファイルを取得する

import json

output_file_id = batch_response.output_file_id

if not output_file_id:
    output_file_id = batch_response.error_file_id

if output_file_id:
    file_response = client.files.content(output_file_id)
    raw_responses = file_response.text.strip().split('\n')  

    for raw_response in raw_responses:  
        json_response = json.loads(raw_response)  
        formatted_json = json.dumps(json_response, indent=2)  
        print(formatted_json)

出力:

簡潔にするために、ここでは出力のチャット補完応答の内 1 つだけを含めています。 この記事の手順に従うと、以下に類似する応答が 3 つ得られるはずです。

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "choices": [
        {
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          },
          "finish_reason": "stop",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": "Microsoft was founded on April 4, 1975, by Bill Gates and Paul Allen in Albuquerque, New Mexico.",
            "role": "assistant"
          }
        }
      ],
      "created": 1722477079,
      "id": "chatcmpl-9rFGJ9dh08Tw9WRKqaEHwrkqRa4DJ",
      "model": "gpt-4o-2024-05-13",
      "object": "chat.completion",
      "prompt_filter_results": [
        {
          "prompt_index": 0,
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "jailbreak": {
              "filtered": false,
              "detected": false
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          }
        }
      ],
      "system_fingerprint": "fp_a9bfe9d51d",
      "usage": {
        "completion_tokens": 24,
        "prompt_tokens": 27,
        "total_tokens": 51
      }
    },
    "request_id": "660b7424-b648-4b67-addc-862ba067d442",
    "status_code": 200
  },
  "error": null
}

その他のバッチ コマンド

バッチをキャンセルする

進行中のバッチをキャンセルします。 バッチは、最大 10 分間状態 cancelling に留まった後 cancelled に変化し、出力ファイルには部分的な結果 (存在する場合) が出力されます。

client.batches.cancel("batch_abc123") # set to your batch_id for the job you want to cancel

バッチを一覧表示する

特定の Azure OpenAI リソースのバッチ ジョブを一覧表示します。

client.batches.list()

Python ライブラリのリスト メソッドでは、改ページされます。

すべてのジョブを一覧表示するには:

all_jobs = []
# Automatically fetches more pages as needed.
for job in client.batches.list(
    limit=20,
):
    # Do something with job here
    all_jobs.append(job)
print(all_jobs)

バッチの一覧表示 (プレビュー)

REST API を使用して、追加の並べ替え/フィルター処理オプションとともにすべてのバッチ ジョブを一覧表示します。

以下の例では、フィルターの構築を容易にする generate_time_filter 関数を提供しています。 この関数を使用しない場合、フィルター文字列の形式は created_at gt 1728860560 and status eq 'Completed' のようになります。

import requests
import json
from datetime import datetime, timedelta
from azure.identity import DefaultAzureCredential

token_credential = DefaultAzureCredential()
token = token_credential.get_token('https://cognitiveservices.azure.com/.default')

endpoint = "https://{YOUR_RESOURCE_NAME}.openai.azure.com/"
api_version = "2024-10-01-preview"
url = f"{endpoint}openai/batches"
order = "created_at asc"
time_filter =  lambda: generate_time_filter("past 8 hours")

# Additional filter examples:
#time_filter =  lambda: generate_time_filter("past 1 day")
#time_filter =  lambda: generate_time_filter("past 3 days", status="Completed")

def generate_time_filter(time_range, status=None):
    now = datetime.now()
    
    if 'day' in time_range:
        days = int(time_range.split()[1])
        start_time = now - timedelta(days=days)
    elif 'hour' in time_range:
        hours = int(time_range.split()[1])
        start_time = now - timedelta(hours=hours)
    else:
        raise ValueError("Invalid time range format. Use 'past X day(s)' or 'past X hour(s)'")
    
    start_timestamp = int(start_time.timestamp())
    
    filter_string = f"created_at gt {start_timestamp}"
    
    if status:
        filter_string += f" and status eq '{status}'"
    
    return filter_string

filter = time_filter()

headers = {'Authorization': 'Bearer ' + token.token}

params = {
    "api-version": api_version,
    "$filter": filter,
    "$orderby": order
}

response = requests.get(url, headers=headers, params=params)

json_data = response.json()

if response.status_code == 200:
    print(json.dumps(json_data, indent=2))
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)  

出力:

{
  "data": [
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729011896,
      "completion_window": "24h",
      "created_at": 1729011128,
      "error_file_id": "file-472c0626-4561-4327-9e4e-f41afbfb30e6",
      "expired_at": null,
      "expires_at": 1729097528,
      "failed_at": null,
      "finalizing_at": 1729011805,
      "id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
      "in_progress_at": 1729011493,
      "input_file_id": "file-f89384af0082485da43cb26b49dc25ce",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-62bebde8-e767-4cd3-a0a1-28b214dc8974",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    },
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729016366,
      "completion_window": "24h",
      "created_at": 1729015829,
      "error_file_id": "file-85ae1971-9957-4511-9eb4-4cc9f708b904",
      "expired_at": null,
      "expires_at": 1729102229,
      "failed_at": null,
      "finalizing_at": 1729016272,
      "id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43",
      "in_progress_at": 1729016126,
      "input_file_id": "file-686746fcb6bc47f495250191ffa8a28e",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-04399828-ae0b-4825-9b49-8976778918cb",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    }
  ],
  "first_id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
  "has_more": false,
  "last_id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43"
}

前提条件

バッチ ファイルの準備

ファインチューニングと同様に、グローバル バッチは JSON 行 (.jsonl) 形式のファイルを使用します。 さまざまな種類のサポートされるコンテンツのファイル例を以下に示します。

入力形式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id は、個々のバッチ要求の内どれが特定の応答に対応するのかを識別できるようにするために必要です。 応答は、.jsonl バッチ ファイル内で定義されている順序と同じ順序では返されません。

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。

重要

model 属性は、推論応答のターゲットにしたいグローバル バッチ デプロイの名前と一致するように設定する必要があります。 バッチ ファイルの各行に存在するグローバル バッチ モデル デプロイ名はいずれも同じである必要があります。別のデプロイをターゲットにする場合は、別のバッチ ファイルまたはジョブでそれを行う必要があります。

パフォーマンスを最大限に高めるには、各ファイルに数行しかない多数の小さなファイルではなく、バッチ処理用に大きなファイルを送信することをお勧めします。

入力ファイルを作成する

この記事では、test.jsonl という名前のファイルを作成し、上記の標準入力コード ブロックからそのファイルに内容をコピーします。 グローバル バッチ デプロイ名を変更してファイルの各行に追加する必要があります。

バッチ ファイルをアップロードする

入力ファイルが準備できたら、まずファイルをアップロードして、バッチ ジョブを開始できるようにする必要があります。 ファイル アップロードは、プログラム的にも Studio 経由でも実行できます。 この例では、キーとエンドポイントの値の代わりに環境変数を使用します。 Python で環境変数を使用する方法に慣れていない場合は、ステップバイステップで環境変数を設定するプロセスが説明されているクイックスタートのいずれかを参照してください。

重要

API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。

AI サービスのセキュリティの詳細については、「Azure AI サービスに対する要求の認証」を参照してください。

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files?api-version=2024-10-21 \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -F "purpose=batch" \
  -F "file=@C:\\batch\\test.jsonl;type=application/json"

上記のコードでは、test.jsonl ファイルの特定のファイル パスを想定しています。 ローカル システムでの必要性に応じて、このファイル パスを調整してください。

出力:

{
  "status": "pending",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "id": "file-21006e70789246658b86a1fc205899a4",
  "created_at": 1721408291,
  "object": "file"
}

ファイル アップロード状態を追跡する

アップロード ファイルのサイズによっては、完全にアップロードされて処理されるのに時間がかかる場合があります。 ファイル アップロード状態を確認するには、次を実行します。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{file-id}?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY"

出力:

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "id": "file-21006e70789246658b86a1fc205899a4",
  "created_at": 1721408291,
  "object": "file"
}

バッチ ジョブを作成する

ファイルが正常にアップロードされたら、バッチ処理のためにファイルを送信できます。

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h"
  }'

Note

現状、完了期間は 24 時間に設定する必要があります。 24 時間以外の値を設定すると、ジョブは失敗します。 24 時間を超えるジョブは、キャンセルされるまで実行が継続されます。

出力:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:13:57.2491382+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:13:57.1918498+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_fe3f047a-de39-4068-9008-346795bfc1db",
  "in_progress_at": null,
  "input_file_id": "file-21006e70789246658b86a1fc205899a4",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

バッチ ジョブの進行状況を追跡する

バッチ ジョブを正常に作成したら、Studio 内またはプログラム的に進行状況を監視できます。 バッチ ジョブの進行状況を確認するときは、各状態呼び出しの間に少なくとも 60 秒待機することをお勧めします。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" 

出力:

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:33:29.1619286+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:33:29.1578141+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_e0a7ee28-82c4-46a2-a3a0-c13b3c4e390b",
  "in_progress_at": null,
  "input_file_id": "file-c55ec4e859d54738a313d767718a2ac5",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

以下の状態の値があり得ます。

Status 説明
validating バッチ処理を開始する前に、入力ファイルの検証が行われています。
failed 入力ファイルが検証プロセスに失敗しました。
in_progress 入力ファイルの検証が成功し、バッチが現在実行中です。
finalizing バッチが完了し、結果が準備されています。
completed バッチが完了し、結果の準備が整いました。
expired バッチを 24 時間の時間枠内で完了できませんでした。
cancelling バッチは cancelled の最中です (これが有効になるには最大で 10 分かかる場合があります。)
cancelled バッチが cancelled されました。

バッチ ジョブ出力ファイルを取得する

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{output_file_id}/content?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

その他のバッチ コマンド

バッチをキャンセルする

進行中のバッチをキャンセルします。 バッチは、最大 10 分間状態 cancelling に留まった後 cancelled に変化し、出力ファイルには部分的な結果 (存在する場合) が出力されます。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}/cancel?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" 

バッチを一覧表示する

特定の Azure OpenAI リソースの既存のバッチ ジョブを一覧表示します。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2024-10-21 \
  -H "api-key: $AZURE_OPENAI_API_KEY" 

リスト API 呼び出しでは、改ページされます。 応答には、反復処理する、より多くの結果があることを示すブール値 has_more が含まれます。

バッチの一覧表示 (プレビュー)

REST API を使用して、追加の並べ替え/フィルター処理オプションとともにすべてのバッチ ジョブを一覧表示します。

curl "YOUR_RESOURCE_NAME.openai.azure.com/batches?api-version=2024-10-01-preview&$filter=created_at%20gt%201728773533%20and%20created_at%20lt%201729032733%20and%20status%20eq%20'Completed'&$orderby=created_at%20asc" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

URL rejected: Malformed input to a URL function エラーを回避するために、スペースが %20 に置き換えられます。

グローバル バッチ制限

制限名 制限値
リソースあたりの最大ファイル数 500
最大入力ファイル サイズ 200 MB
ファイルあたりの最大要求数 100,000

グローバル バッチ クォータ

次の表はバッチのクォータ制限を示したものです。 グローバル バッチのクォータ値は、エンキューされたトークンの数で表されます。 バッチ処理用のファイルを送信すると、ファイル内に存在するトークンの数がカウントされます。 バッチ ジョブが終了状態になるまで、これらのトークンはエンキューされたトークンの合計の制限に対してカウントされます。

モデル エンタープライズ契約 既定値 月単位のクレジット カード ベースのサブスクリプション MSDN サブスクリプション Microsoft Azure for Students、無料試用版
gpt-4o 5 B 200 M 50 M 90 K 該当なし
gpt-4o-mini 15 B 1 B 50 M 90 K 該当なし
gpt-4-turbo 300 M 80 M 40 M 90 K 該当なし
gpt-4 150 M 30 M 5 M 100 K 該当なし
gpt-35-turbo 10 B 1 B 100 M 2 M 50 K

B = 10 億 | M = 100万 | K = 1,000

バッチ オブジェクト

プロパティ Type Definition
id string
object string batch
endpoint string バッチによって使用される API エンドポイント
errors オブジェクト
input_file_id string バッチの入力ファイルの ID
completion_window string バッチを処理する時間枠
status string バッチの現在の状態。 指定できる値: validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelled
output_file_id string 正常に実行された要求の出力を含むファイルの ID。
error_file_id string エラーが発生した要求の出力を含むファイルの ID。
created_at integer このバッチが作成された時点のタイムスタンプ (unix エポック)。
in_progress_at integer このバッチが進行状態になった時点のタイムスタンプ (unix エポック)。
expires_at integer このバッチの有効期限が切れる時点のタイムスタンプ (unix エポック)。
finalizing_at integer このバッチが終了処理を開始した時点のタイムスタンプ (unix エポック)。
completed_at integer このバッチが終了処理を開始した時点のタイムスタンプ (unix エポック)。
failed_at integer このバッチが失敗した時点のタイムスタンプ (unix エポック)
expired_at integer このバッチの有効期限が切れた時点のタイムスタンプ (unix エポック)。
cancelling_at integer このバッチが cancelling を開始した時点のタイムスタンプ (unix エポック)。
cancelled_at integer このバッチが cancelled された時点のタイムスタンプ (unix エポック)。
request_counts オブジェクト オブジェクト構造:

total integer
バッチ内の要求の合計数。
completed integer
バッチ内で正常に完了した要求の数。
failed integer
バッチ内の失敗した要求の数。
metadata map バッチにアタッチできるキーと値のペアのセット。 これは、バッチに関する追加情報を構造化された形式で保存する上で役立ちます。

よく寄せられる質問 (FAQ)

バッチ API では画像を使用できますか?

この機能は、一部のマルチモーダル モデルに限定されます。 現在、バッチ要求の一部として画像をサポートしているのは GPT-4o だけです。 画像は、画像 URL または画像の base64 エンコード表現のどちらかを介して入力として指定できます。 バッチでの画像は、GPT-4 Turbo では現在サポートされていません。

ファインチューニングされたモデルでバッチ API を使用できますか?

現在これはサポートされていません。

埋め込みモデルに対してバッチ API を使用できますか?

現在これはサポートされていません。

コンテンツ フィルタリングはグローバル バッチ デプロイで機能しますか?

はい。 他のデプロイ タイプと同様に、コンテンツ フィルターを作成し、それらをグローバル バッチ デプロイ タイプに関連付けることができます。

追加のクォータを要求できますか?

はい。Azure AI Foundry ポータルのクォータ ページから行うことができます。 既定のクォータ割り当ては、クォータと制限に関する記事で確認できます。

API が 24 時間の時間枠内に要求を完了しなかった場合は何が起きますか?

Microsoft はこれらの要求を 24 時間以内に処理することを目指します。それ以上の時間がかかるジョブを期限切れにすることはありません。 ジョブはいつでもキャンセルできます。 ジョブをキャンセルすると、残りの作業はすべてキャンセルされ、既に完了した作業があればそれが戻されます。 完了した作業があればそれに対する課金が行われます。

バッチを使用してエンキューできる要求の数はいくつですか?

バッチ処理できる要求の数には固定の制限はなく、この数はエンキューされたトークン クォータによって決まります。 エンキューされたトークン クォータには、一度にエンキューできる入力トークンの最大数が含まれます。

バッチ要求が完了すると、入力トークンがクリアされるため、バッチ レート制限がリセットされます。 この制限は、キュー内のグローバル要求の数によって決まります。 Batch API キューがバッチを迅速に処理する場合、バッチ レート制限はより迅速にリセットされます。

トラブルシューティング

statusCompleted である場合、ジョブは成功しています。 成功したジョブが error_file_id を生成することもありますが、これは 0 バイトの空ファイルに関連付けられます。

ジョブの失敗が発生した場合は、以下のように errors プロパティ内で失敗の詳細を確認できます。

"value": [
        {
          "id": "batch_80f5ad38-e05b-49bf-b2d6-a799db8466da",
          "completion_window": "24h",
          "created_at": 1725419394,
          "endpoint": "/chat/completions",
          "input_file_id": "file-c2d9a7881c8a466285e6f76f6321a681",
          "object": "batch",
          "status": "failed",
          "cancelled_at": null,
          "cancelling_at": null,
          "completed_at": 1725419955,
          "error_file_id": "file-3b0f9beb-11ce-4796-bc31-d54e675f28fb",
          "errors": {
                "object": “list”,
                "data": [
                {
               “code”: “empty_file”,
               “message”: “The input file is empty. Please ensure that the batch contains at least one   request.”
                    }
                ]
          },
          "expired_at": null,
          "expires_at": 1725505794,
          "failed_at": null,
          "finalizing_at": 1725419710,
          "in_progress_at": 1725419572,
          "metadata": null,
          "output_file_id": "file-ef12af98-dbbc-4d27-8309-2df57feed572",

            "request_counts": {
                "total": 10,
                "completed": null,
                "failed": null
            },
        }

エラー コード

エラー コード Definition
invalid_json_line 入力ファイル内の 1 つ (または複数) の行が有効な JSON として解析できませんでした。

JSON 標準に従って入力ミス、適切な開始角かっこ、終わり角かっこ、引用符がないことを確認し、要求を再送信してください。
too_many_tasks 入力ファイル内の要求の数が、許容される最大値である 100,000 を超えています。

要求の合計が 100,000 以下であることを確認し、ジョブを再送信してください。
url_mismatch 入力ファイル内に他の行と一致しない URL を持つ行が存在するか、入力ファイル内で指定された URL が想定されるエンドポイント URL と一致しません。

すべての要求 URL が同じであり、それが Azure OpenAI デプロイに関連付けられているエンドポイント URL と一致することを確認してください。
model_not_found 入力ファイルの model プロパティで指定された Azure OpenAI モデルのデプロイ名が見つかりませんでした。

この名前が有効な Azure OpenAI モデル デプロイを指していることを確認してください。
duplicate_custom_id この要求のカスタム ID は、別の要求のカスタム ID と重複しています。
empty_batch 入力ファイルをチェックして、バッチ内の各要求のカスタム ID パラメーターが一意であることを確認してください。
model_mismatch 入力ファイルのこの要求の model プロパティで指定された Azure OpenAI モデルのデプロイ名が、ファイルの残りの部分のものと一致しません。

バッチ内のすべての要求が、要求の model プロパティ内で同じ AOAI モデル デプロイを指していることを確認してください。
invalid_request 入力行のスキーマが無効であるか、デプロイ SKU が無効です。

入力ファイル内の要求のプロパティが想定される入力プロパティと一致していること、および Azure OpenAI デプロイ SKU がバッチ API 要求に対する globalbatch であることを確認してください。

既知の問題

  • Azure CLI を使用してデプロイされたリソースは、そのままでは Azure OpenAI グローバル バッチで機能しません。 この原因は、このメソッドを使用してデプロイされたリソースは https://your-resource-name.openai.azure.com パターンに従わないエンドポイント サブドメインを持つという問題にあります。 この問題の回避策は、デプロイ プロセスの一環としてサブドメインのセットアップを適切に処理する他の一般的なデプロイ方法のいずれかを使用して、新しい Azure OpenAI リソースをデプロイすることです。

関連項目