次の方法で共有


独自のデータに基づく Azure OpenAI の API リファレンス

この記事では、新しい Azure OpenAI On Your Data API の Python と REST 用のリファレンス ドキュメントを提供します。 最新の API バージョンは 2024-05-01-previewSwagger の仕様です。

API バージョン 2024-02-15-preview 以降、以前の API バージョンと比較して、次の破壊的変更が導入されました。

  • API パスが /extensions/chat/completions から /chat/completions に変更されます。
  • プロパティ キーと列挙値の名前付け規則は、キャメル ケースからスネーク ケースの大文字と小文字表現に変更されます。 例: deploymentNamedeployment_name に変更されます。
  • データ ソースの種類 AzureCognitiveSearchazure_search に変更されます。
  • 引用とインテントは、アシスタント メッセージのコンテキスト ツール メッセージからアシスタント メッセージのコンテキスト ルート レベルに移動され、明示的なスキーマが定義されます。
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

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

PineconeElasticsearch は、プレビューとしてのみサポートされます。

URI パラメーター

名前 タイプ 必須 説明
deployment-id パス 文字列 正しい この要求に使用するチャット完了モデルのデプロイ名を指定します。
endpoint パス 文字列 正しい Azure OpenAI エンドポイント。 例: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version クエリ 文字列 正しい この操作に使用する API バージョン。

リクエストの本文

要求本文は、チャット完了 API 要求と同じスキーマを継承します。 次の表に、Azure OpenAI On Your Data に固有のパラメーターを示します。

名前 タイプ 必須 説明
data_sources データソース[] 正しい Azure OpenAI On Your Data の構成エントリ。 配列には 1 つの要素が必要です。 指定されていない場合、data_sources サービスはチャット入力候補モデルを直接使用し、Azure OpenAI On Your Data を使用しません。 data_sources パラメーターを指定すると、logprobsまたはtop_logprobsパラメーターを使用できなくなります。

応答内容

応答本文は、チャット完了 API 応答と同じスキーマを継承します。 応答チャット メッセージ には context プロパティがあります。これは、Azure OpenAI On Your Data 用に追加されます。

チャット メッセージ

応答アシスタント メッセージ スキーマはチャット入力候補アシスタントのチャット メッセージから継承され、プロパティ context で拡張されます。

名前 タイプ 必須 説明
context コンテキスト いいえ 取得したドキュメントなど、要求の処理中に Azure OpenAI On Your Data によって実行される増分ステップを表します。

コンテキスト

名前 タイプ 必須 説明
citations 引用[] いいえ 応答でアシスタント メッセージを生成するために使用されるデータ ソースの取得結果。 クライアントでは、引用文献からの参照をレンダリングできます。
intent 文字列 いいえ チャット履歴から検出された意図。 前の意図を戻す必要はなくなりました。 このプロパティは無視します。
all_retrieved_documents 取得したドキュメント[] いいえ すべての取得したドキュメント。

引用

名前 タイプ 必須 説明
content 文字列 正しい 引用の内容。
title 文字列 いいえ 引用のタイトル。
url 文字列 いいえ 引用の URL。
filepath 文字列 いいえ 引用のファイル パス。
chunk_id 文字列 いいえ 引用のチャンク ID。

取得したドキュメント

名前 タイプ 必須 説明
search_queries 文字列[] 正しい ドキュメント取得に使用した検索クエリ。
data_source_index 整数 正しい データ ソースのインデックス。
original_search_score ダブル 正しい 取得したドキュメントの元の検索スコア。
rerank_score ダブル いいえ 取得したドキュメントの再ランク付けスコア。
filter_reason 文字列 いいえ ドキュメントをフィルター処理するための根拠を表します。 ドキュメントがフィルター処理されない場合は、このフィールドは設定されないままになります。 ドキュメントが score で定義された元の検索スコアのしきい値でフィルター処理されている場合、strictness になります。 ドキュメントが、元の検索スコアのしきい値でフィルター処理されずに再ランク付けスコアと rerank でフィルター処理されている場合、top_n_documents になります。

データ ソース

この一覧には、サポートされているデータ ソースが表示されます。

例示

この例では、より良い結果を得るために会話履歴を渡す方法を示します。

前提条件:

  • Azure OpenAI システム割り当てマネージド ID から Azure Search サービスへのロールの割り当てを構成します。 必要なロール: Search Index Data ReaderSearch Service Contributor
  • ユーザーから Azure OpenAI リソースへのロールの割り当てを構成します。 必要なロール: Cognitive Services OpenAI User
  • Az CLI をインストールし、az login を実行します。
  • 環境変数 AzureOpenAIEndpointChatCompletionsDeploymentNameSearchEndpointSearchIndex を定義します。
export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

最新の pip パッケージ openaiazure-identity をインストールします。

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

endpoint = os.environ.get("AzureOpenAIEndpoint")
deployment = os.environ.get("ChatCompletionsDeploymentName")
search_endpoint = os.environ.get("SearchEndpoint")
search_index = os.environ.get("SearchIndex")

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

client = AzureOpenAI(
    azure_endpoint=endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-05-01-preview",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ],
    extra_body={
        "data_sources": [
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": search_endpoint,
                    "index_name": search_index,
                    "authentication": {
                        "type": "system_assigned_managed_identity"
                    }
                }
            }
        ]
    }
)

print(completion.model_dump_json(indent=2))

# render the citations

content = completion.choices[0].message.content
context = completion.choices[0].message.context
for citation_index, citation in enumerate(context["citations"]):
    citation_reference = f"[doc{citation_index + 1}]"
    url = "https://example.com/?redirect=" + citation["url"] # replace with actual host and encode the URL
    filepath = citation["filepath"]
    title = citation["title"]
    snippet = citation["content"]
    chunk_id = citation["chunk_id"]
    replaced_html = f"<a href='{url}' title='{title}\n{snippet}''>(See from file {filepath}, Part {chunk_id})</a>"
    content = content.replace(citation_reference, replaced_html)
print(content)