Azure OpenAI Service の REST API リファレンス

  • [アーティクル]

この記事では、Azure OpenAI の推論 REST API エンドポイントについて詳しく説明します。

認証

Azure OpenAI には、2 つの認証方法が用意されています。 API キーまたは Azure Active Directory のいずれかを使用できます。

  • API キー認証: この種類の認証の場合、すべての API 要求で、api-key HTTP ヘッダーに API キーを含める必要があります。 クイック スタートに、この種類の認証を使用して呼び出しを行う方法に関するガイダンスが用意されています。

  • Azure Active Directory 認証: Azure Active Directory トークンを使用して API 呼び出しを認証できます。 認証トークンは、Authorization ヘッダーとして要求に含まれます。 指定するトークンの前に Bearer を付ける必要があります (例: Bearer YOUR_AUTH_TOKEN)。 Azure Active Directory での認証に関する攻略ガイドをお読みください。

REST API のバージョン管理

サービス API は、api-version クエリ パラメーターを使用してバージョン管理されます。 すべてのバージョンは、YYYY-MM-DD 日付構造に従います。 たとえば、次のように入力します。

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2022-12-01

入力候補

入力候補操作では、指定したプロンプトに基づいて、モデルによって 1 つ以上の予測入力候補が生成されます。 サービスでは、それぞれの位置で代替トークンの確率を返すこともできます。

入力候補の作成

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

パス パラメーター

パラメーター Type 必須 説明
your-resource-name string 必須 Azure OpenAI リソースの名前。
deployment-id string 必須 モデルのデプロイ時に選択したデプロイ名。
api-version string 必須 この操作に使用する API バージョン。 これは、YYYY-MM-DD 形式に従います。

サポートされているバージョン

要求本文

パラメーター Type 必須 Default 説明
prompt 文字列または配列 オプション <\|endoftext\|> 文字列、文字列の一覧、またはトークン リストの一覧としてエンコードされた、入力候補の生成対象となるプロンプト。 <\|endoftext\|> はトレーニング中にモデルが確認するドキュメント区切り記号であるため、プロンプトを指定しない場合、モデルは新しいドキュメントの先頭からのように生成します。
max_tokens 整数 (integer) 省略可能 16 入力候補に生成するトークンの最大数。 プロンプトのトークン数と max_tokens の合計は、モデルのコンテキスト長を超えることはできません。 ほとんどのモデルのコンテキスト長は 2048 トークンです (4096 をサポートする最新のモデルを除く)。
temperature number オプション 1 使用するサンプリング温度。 値が大きいほど、モデルはより多くのリスクを負います。 よりクリエイティブなアプリケーションの場合は 0.9、明確に定義された回答の場合は 0 (argmax sampling) をお試しください。 一般的に、これと top_p の両方ではなく、いずれかを変更することをお勧めします。
top_p number オプション 1 核サンプリングと呼ばれる、温度によるサンプリングの代替で、モデルはで top_p 確率質量を持つトークンの結果が考慮されます。 したがって、0.1 は、上位 10% の確率質量を含むトークンのみが考慮されることを意味します。 一般的に、これと temperature の両方ではなく、いずれかを変更することをお勧めします。
logit_bias map オプション null 指定したトークンが入力候補に表示される可能性を変更します。 トークン (GPT トークナイザーのトークン ID で指定) を関連付けられたバイアス値 (-100 から 100) にマップする json オブジェクトを受け入れます。 このトークナイザー ツール (GPT-2 と GPT-3 の両方で機能) を使用して、テキストをトークン ID に変換できます。 数学的には、サンプリングの前にモデルによって生成されたロジットにバイアスが追加されます。 正確な効果はモデルごとに異なりますが、-1 から 1 の値では選択の可能性が低下または増加し、-100 や 100 などの値では、関連するトークンの禁止または排他的な選択になります。 たとえば、{"50256": -100} を渡して、<|endoftext|> トークンが生成されないようにすることができます。
user string 省略可能 エンド ユーザーを表す一意の識別子。不正使用の監視と検出に役立ちます
n 整数 (integer) 省略可能 1 プロンプトごとに生成する入力候補の数。 注: このパラメーターにより多くの入力候補が生成されるため、トークン クォータがすぐに消費される可能性があります。 慎重に使用し、max_tokens と stop の設定が合理的であることを確認してください。
stream boolean 省略可能 False 部分的な進行状況をストリーム バックするかどうか。 設定した場合、トークンは、使用可能になると data-only server-sent イベントとして送信され、ストリームはデータ [DONE] メッセージで終了します。
logprobs 整数 (integer) 省略可能 null logprobs の最も可能性の高いトークンと、選択したトークンのログ確率を含めます。 たとえば、logprobs が 10 の場合、API は可能性が最も高い 10 個のトークンの一覧を返します。 API は常にサンプリングされたトークンの logprob を返します。そのため、応答には最大 logprobs+1 の要素が含まれる可能性があります。 このパラメーターは gpt-35-turbo では使用できません。
suffix string 省略可能 null 挿入されたテキストが完了した後に配置されるサフィックス。
echo boolean 省略可能 False 入力候補に加えてプロンプトをエコーバックします。 このパラメーターは gpt-35-turbo では使用できません。
stop 文字列または配列 オプション null API がそれ以上のトークンの生成を停止する、最大 4 つのシーケンス。 返されるテキストに停止シーケンスは含まれません。
presence_penalty number オプション 0 -2.0 から 2.0 の数値。 正の値を指定すると、これまでのテキストに出現するかどうかに基づいて新しいトークンにペナルティが課せられ、モデルが新しいトピックを扱う可能性が高まります。
frequency_penalty number オプション 0 -2.0 から 2.0 の数値。 値を正にすると、これまでのテキストに存在する頻度に基づいて新しいトークンにペナルティが課せられ、モデルが同じ行を逐語的に繰り返す可能性が低下します。
best_of 整数 (integer) 省略可能 1 サーバー側 best_of 入力候補を生成し、"best" (トークンあたりのログ確率が最低のもの) を返します。 結果をストリーミングすることはできません。 n と共に使用する場合、best_of は入力候補の数を制御し、n は返す数を指定します。best_of は n より大きくする必要があります。 注: このパラメーターにより多くの入力候補が生成されるため、トークン クォータがすぐに消費される可能性があります。 慎重に使用し、max_tokens と stop の設定が合理的であることを確認してください。 このパラメーターは gpt-35-turbo では使用できません。

要求の例

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2022-12-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

応答の例

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

応答の例では、finish_reason と stop は等しくなります。 finish_reason と content_filter が等しい場合は、コンテンツのフィルター処理のガイドを参照して、これが発生している理由を理解してください。

埋め込み

機械学習モデルやその他のアルゴリズムで簡単に使用できる、特定の入力のベクター表現を取得します。

埋め込みの作成

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

パス パラメーター

パラメーター Type 必須 説明
your-resource-name string 必須 Azure OpenAI リソースの名前。
deployment-id string 必須 モデル デプロイの名前。 モデルをデプロイしてから呼び出しを実行する必要があります。
api-version string 必須 この操作に使用する API バージョン。 これは、YYYY-MM-DD 形式に従います。

サポートされているバージョン

要求本文

パラメーター Type 必須 Default 説明
input 文字列または配列 はい 該当なし 埋め込みを取得する入力テキスト。トークンの文字列または配列としてエンコードします。 1 回の要求で複数の入力の埋め込みを取得するには、文字列の配列またはトークン配列の配列を渡します。 各入力の長さは 2048 トークンを超えてはなりません。 現在、最大 1 の配列が受け入れられます。
改行が存在すると想定どおりの結果が得られないことが確認されているため、コードを埋め込む場合を除き、入力の改行文字 (\n) を 1 つのスペースに置き換えることをお勧めします。
user string No [Null] エンド ユーザーを表す一意の識別子。 Azure OpenAI による不正使用の監視と検出に役立ちます。 PII 識別子を渡さないでください。代わりに GUID などの仮名化された値を使用してください

要求の例

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2022-12-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

応答の例

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

チャット入力候補

ChatGPT (プレビュー) モデルと GPT-4 (プレビュー) モデルを使用して、チャット メッセージの入力候補を作成します。 現在、チャット入力候補は api-version=2023-03-15-preview でのみ使用できます。

チャット入力候補を作成する

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

パス パラメーター

パラメーター Type 必須 説明
your-resource-name string 必須 Azure OpenAI リソースの名前。
deployment-id string 必須 モデル デプロイの名前。 モデルをデプロイしてから呼び出しを実行する必要があります。
api-version string 必須 この操作に使用する API バージョン。 これは、YYYY-MM-DD 形式に従います。

サポートされているバージョン

要求の例

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-03-15-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure Cognitive Services support this too?"}]}'

応答の例

{"id":"chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
"object":"chat.completion","created":1679072642,
"model":"gpt-35-turbo",
"usage":{"prompt_tokens":58,
"completion_tokens":68,
"total_tokens":126},
"choices":[{"message":{"role":"assistant",
"content":"Yes, other Azure Cognitive Services also support customer managed keys. Azure Cognitive Services offer multiple options for customers to manage keys, such as using Azure Key Vault, customer-managed keys in Azure Key Vault or customer-managed keys through Azure Storage service. This helps customers ensure that their data is secure and access to their services is controlled."},"finish_reason":"stop","index":0}]}

応答の例では、finish_reason と stop は等しくなります。 finish_reason と content_filter が等しい場合は、コンテンツのフィルター処理のガイドを参照して、これが発生している理由を理解してください。

読みやすいように出力形式が調整されています。実際の出力は改行のない単一のテキスト ブロックです。

パラメーター Type 必須 Default 説明
messages array 必須 チャット形式でチャット入力候補を生成するメッセージ。
temperature number オプション 1 使用するサンプリング温度 (0 から 2)。 0.8 のような大きい値にすると、出力はよりランダムになり、0.2 のような小さい値にすると、出力はより集中的および確定的になります。\n一般に、これと top_p のいずれかを変更し、両方は変更しないことをお勧めします。
n 整数 (integer) 省略可能 1 入力メッセージごとに生成するチャット入力候補の選択肢の数。
stream boolean 省略可能 false 設定すると、ChatGPT と同様に部分的なメッセージ デルタが送信されます。 トークンは、使用可能になると data-only server-sent イベントとして送信され、ストリームは data: [DONE] メッセージで終了します。
stop 文字列または配列 オプション null API がそれ以上のトークンの生成を停止する、最大 4 つのシーケンス。
max_tokens 整数 (integer) 省略可能 inf 生成された回答に許可されるトークンの最大数。 既定では、モデルが返すことができるトークンの数は (4096 - プロンプト トークン) になります。
presence_penalty number オプション 0 -2.0 から 2.0 の数値。 正の値を指定すると、これまでのテキストに出現するかどうかに基づいて新しいトークンにペナルティが課せられ、モデルが新しいトピックを扱う可能性が高まります。
frequency_penalty number オプション 0 -2.0 から 2.0 の数値。 値を正にすると、これまでのテキストに存在する頻度に基づいて新しいトークンにペナルティが課せられ、モデルが同じ行を逐語的に繰り返す可能性が低下します。
logit_bias object 省略可能 null 指定したトークンが入力候補に表示される可能性を変更します。 トークン (トークナイザーのトークン ID で指定) を関連付けられたバイアス値 (-100 から 100) にマップする json オブジェクトを受け入れます。 数学的には、サンプリングの前にモデルによって生成されたロジットにバイアスが追加されます。 正確な効果はモデルごとに異なりますが、-1 から 1 の値では選択の可能性が低下または増加し、-100 や 100 などの値では、関連するトークンの禁止または排他的な選択になります。
user string 省略可能 エンド ユーザーを表す一意の識別子。これは、Azure OpenAI が不正使用を監視および検出するのに役立ちます。

管理 API

Azure OpenAI は、Azure Cognitive Services の一部としてデプロイされます。 すべての Cognitive Services は、作成、更新、削除の操作で同じ一連の管理 API に依存します。 管理 API は、OpenAI リソース内にモデルをデプロイするためにも使用されます。

管理 API リファレンス ドキュメント

次の手順

REST API を使用したデプロイ、モデルの管理、および微調整に関する記事を確認します。 Azure OpenAI をサポートする基となるモデルに関する記事を確認します。