この記事では、新しい Azure OpenAI On Your Data API の Python と REST 用のリファレンス ドキュメントを提供します。 最新の API バージョンは 2024-05-01-preview
Swagger の仕様です。
注
API バージョン 2024-02-15-preview
以降、以前の API バージョンと比較して、次の破壊的変更が導入されました。
- API パスが
/extensions/chat/completions
から/chat/completions
に変更されます。 - プロパティ キーと列挙値の名前付け規則は、キャメル ケースからスネーク ケースの大文字と小文字表現に変更されます。 例:
deploymentName
がdeployment_name
に変更されます。 - データ ソースの種類
AzureCognitiveSearch
がazure_search
に変更されます。 - 引用とインテントは、アシスタント メッセージのコンテキスト ツール メッセージからアシスタント メッセージのコンテキスト ルート レベルに移動され、明示的なスキーマが定義されます。
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}
サポートされているバージョン
-
2024-02-15-preview
Swagger の仕様。 -
2024-02-01
Swagger の仕様。 -
2024-05-01-preview
Swagger の仕様
注
Pinecone と Elasticsearch は、プレビューとしてのみサポートされます。
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 Reader
、Search Service Contributor
。 - ユーザーから Azure OpenAI リソースへのロールの割り当てを構成します。 必要なロール:
Cognitive Services OpenAI User
。 -
Az CLI をインストールし、
az login
を実行します。 - 環境変数
AzureOpenAIEndpoint
、ChatCompletionsDeploymentName
、SearchEndpoint
、SearchIndex
を定義します。
export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index
最新の pip パッケージ openai
、azure-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)