次の方法で共有

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

  • [アーティクル]

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

Note

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}

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

Note

Azure Machine Learning インデックス、Pinecone、Elasticsearch は、プレビューとしてのみサポートされます。

URI パラメーター

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

要求本文

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

名前 タイプ Required 説明
data_sources DataSource[] True 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 で拡張されます。

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

Context

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

引用

名前 タイプ Required Description
content string True 引用の内容。
title string False 引用のタイトル。
url string False 引用の URL。
filepath string False 引用のファイル パス。
chunk_id string False 引用のチャンク ID。

取得したドキュメント

名前 タイプ Required 説明
search_queries string[] True ドキュメント取得に使用した検索クエリ。
data_source_index integer True データ ソースのインデックス。
original_search_score 倍精度浮動小数点 True 取得したドキュメントの元の検索スコア。
rerank_score 倍精度浮動小数点 False 取得したドキュメントの再ランク付けスコア。
filter_reason string False ドキュメントをフィルター処理するための根拠を表します。 ドキュメントがフィルター処理されない場合は、このフィールドは設定されないままになります。 ドキュメントが strictness で定義された元の検索スコアのしきい値でフィルター処理されている場合、score になります。 ドキュメントが、元の検索スコアのしきい値でフィルター処理されずに再ランク付けスコアと top_n_documents でフィルター処理されている場合、rerank になります。

データ ソース

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

例

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

前提条件:

  • 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)