クイックスタート: 根拠性検出 (プレビュー)

[アーティクル]
04/12/2024

こちらのガイドに従って Azure AI Content Safety 根拠性検出を使用し、大規模言語モデル (LLM) のテキスト応答が、ユーザーが提供するソース資料を根拠としているかどうかを確認してください。

前提条件

Azure サブスクリプション - 無料アカウントを作成します
Azure サブスクリプションを入手したら、Azure portal で Content Safety リソースを作成し、キーとエンドポイントを取得します。リソースの一意の名前を入力し、サブスクリプションを選択して、リソースグループ、サポートされているリージョン (米国東部 2、米国西部、スウェーデン中部)、サポートされている価格レベルを選択します。 [作成] を選択します。
- リソースのデプロイには数分かかります。完了したら、新しいリソースに移動します。左ペインの [リソース管理] で、[API キーとエンドポイント] を選択します。後で使用するために、サブスクリプションキーの値の 1 つとエンドポイントを一時的な場所にコピーします。
(省略可能) "推論" 機能を使用する場合は、GPT モデルがデプロイされた Azure OpenAI Service リソースを作成します。
cURL または Python がインストールされていること。

推論なしで根拠性をチェックする

"推論" 機能がない場合はシンプルで、Groundedness detection API により、送信されたコンテンツの非根拠性が true または false として分類されます。

cURL
Python

このセクションでは、cURL を使ったサンプル要求について説明します。以下のコマンドをテキストエディターに貼り付け、次の変更を加えます。

<endpoint> を、リソースに関連付けられたエンドポイント URL に置き換えます。
<your_subscription_key> をお使いのリソースのいずれかのキーで置き換えます。

必要に応じて、本文の "query" または "text" フィールドを、分析する独自のテキストに置き換えます。

curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "domain": "Generic",
  "task": "QnA",
  "qna": {
       "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": False
}'

コマンドプロンプトを開き、cURL コマンドを実行します。

quickstart.py という名前の新しい Python ファイルを作成します。好みのエディターまたは IDE で新しいファイルを開きます。

quickstart.py の内容を次のコードで置き換えます。エンドポイント URL とキーを適切なフィールドに入力します。必要に応じて、本文の "query" または "text" フィールドを、分析する独自のテキストに置き換えます。

import http.client
import json

conn = http.client.HTTPSConnection("<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview")
payload = json.dumps({
  "domain": "Generic",
  "task": "QnA",
  "qna": {
    "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": False
})
headers = {
  'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、資格情報を安全に保存してアクセスできる方法を使用してください。詳しくは、Azure Key Vault に関する記事をご覧ください。

python コマンドを使用してアプリケーションを実行します。
```
python quickstart.py
```
応答が返されるまで少し時間がかかります。

質問応答 (QnA) タスクの代わりに要約タスクをテストするには、次のサンプル JSON 本文を使用します。

{
    "domain": "Medical",
    "task": "Summarization",
    "text": "Ms Johnson has been in the hospital after experiencing a stroke.",
    "groundingSources": ["Our patient, Ms. Johnson, presented with persistent fatigue, unexplained weight loss, and frequent night sweats. After a series of tests, she was diagnosed with Hodgkin’s lymphoma, a type of cancer that affects the lymphatic system. The diagnosis was confirmed through a lymph node biopsy revealing the presence of Reed-Sternberg cells, a characteristic of this disease. She was further staged using PET-CT scans. Her treatment plan includes chemotherapy and possibly radiation therapy, depending on her response to treatment. The medical team remains optimistic about her prognosis given the high cure rate of Hodgkin’s lymphoma."],
    "reasoning": false
}

URL には次のフィールドを含める必要があります。

名前	必須	説明	種類
API バージョン	必須	これが使用される API のバージョンです。現在のバージョンは api-version=2024-02-15-preview です。例: `<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview`	String

要求本文のパラメーターは、次の表のように定義されています。

名前	Description	Type
domain	(省略可能) `MEDICAL` または `GENERIC`。既定値: `GENERIC`。	列挙型
タスク	(省略可能) タスクの種類: `QnA`、`Summarization`。既定値: `Summarization`。	列挙型
qna	(省略可能) タスクの種類が `QnA` の場合は QnA データを保持します。	String
- `query`	(省略可能) これは QnA タスクの質問を表します。文字数制限: 7,500 文字。	String
text	(必須) チェックする LLM 出力テキスト。文字数制限: 7,500 文字。	String
groundingSources	(必須) 根拠となるソースの配列を使用して、AI によって生成されたテキストを検証します。 1 回の要求で最大 55,000 文字の根拠となるソースを分析できます。	文字列配列
reasoning	(省略可能) 推論機能を使用するかどうかを指定します。既定値は `false` です。 `true` の場合、説明を提供するには独自の Azure OpenAI GPT-4 Turbo リソースを用意する必要があります。推論を使用すると処理時間が長くなることにご注意ください。	Boolean

API 応答を解釈する

要求を送信後、実行された根拠性分析が反映された JSON 応答を受け取ります。一般的な出力は次のようになります。

{
    "ungroundedDetected": true,
    "ungroundedPercentage": 1,
    "ungroundedDetails": [
        {
            "text": "12/hour."
        }
    ]
}

出力の JSON オブジェクトは次のように定義されています。

名前	Description	Type
ungroundedDetected	テキストが非根拠性を示しているかどうかを示します。	Boolean
ungroundedPercentage	根拠なしとして識別されるテキストの比率を 0 から 1 の間の数値で表します。0 は根拠なしのコンテンツはないことを示し、1 は完全に根拠なしのコンテンツであることを示します。	Float
ungroundedDetails	具体的な例と割合を使用して、根拠なしのコンテンツに関する分析情報を提供します。	Array
-`text`	根拠なしの具体的なテキスト。	String

推論を使用して根拠性をチェックする

根拠性検出 API には、API 応答に "推論" を含めるオプションが備わっています。推論が有効になっていると、応答には、検出された非根拠性の具体的なインスタンスと説明の詳細を示す "reasoning" フィールドが含まれます。ただし、推論を使用すると処理時間が長くなり、追加の費用が発生することにご注意ください。

独自の GPT デプロイを持ち込む

ヒント

現時点では、Azure OpenAI GPT-4 Turbo リソースのみがサポートされており、他の GPT の種類はサポートされていません。 GPT-4 Turbo リソースは、任意のリージョンにデプロイできます。ただし、潜在的な待ち時間を最小限に抑えるために、Content Safety リソースと同じリージョンに配置することをお勧めします。

自分の Azure OpenAI GPT4-Turbo リソースを使用して推論機能を有効にするには、マネージド ID を使用して Content Safety リソースから Azure OpenAI リソースへのアクセスを許可にします。

Azure AI Content Safety のマネージド ID を有効にします。

Azure portal で Azure AI Content Safety インスタンスに移動します。 [設定] カテゴリで [ID] セクションを見つけます。システム割り当てのマネージド ID を有効にします。このアクションにより、Azure AI Content Safety インスタンスに、他のリソースにアクセスするために Azure 内で認識されて使用できる ID が付与されます。
マネージド ID にロールを割り当てます。

Azure OpenAI インスタンスに移動し、[ロールの割り当てを追加] を選択して、Azure AI Content Safety の ID に Azure OpenAI のロールを割り当てるプロセスを開始します。

ユーザー ロールまたは共同作成者ロールを選択します。

API 要求を行う

根拠性検出 API への要求で、本文パラメーター "reasoning" を true に設定し、他の必要なパラメーターを指定します。

 {
  "reasoning": true,
  "llmResource": {
    "resourceType": "AzureOpenAI",
    "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
    "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
}

cURL
Python

このセクションでは、cURL を使ったサンプル要求について説明します。以下のコマンドをテキストエディターに貼り付け、次の変更を加えます。

<endpoint> を、リソースに関連付けられたエンドポイント URL に置き換えます。
<your_subscription_key> をお使いのリソースのいずれかのキーで置き換えます。

必要に応じて、本文の "query" または "text" フィールドを、分析する独自のテキストに置き換えます。

curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "domain": "Generic",
  "task": "QnA",
  "qna": {
       "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": true,
  "llmResource": {
        "resourceType": "AzureOpenAI",
        "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
        "azureOpenAIDeploymentName": "<your_deployment_name>"
}'

コマンドプロンプトを開き、cURL コマンドを実行します。

quickstart.py という名前の新しい Python ファイルを作成します。好みのエディターまたは IDE で新しいファイルを開きます。

import http.client
import json

conn = http.client.HTTPSConnection("<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview")
payload = json.dumps({
  "domain": "Generic",
  "task": "QnA",
  "qna": {
    "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": True
  "llmResource": {
   "resourceType": "AzureOpenAI",
   "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
   "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
})
headers = {
  'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

python コマンドを使用してアプリケーションを実行します。
```
python quickstart.py
```
応答が返されるまで少し時間がかかります。

要求本文のパラメーターは、次の表のように定義されています。

名前	Description	Type
domain	(省略可能) `MEDICAL` または `GENERIC`。既定値: `GENERIC`。	列挙型
タスク	(省略可能) タスクの種類: `QnA`、`Summarization`。既定値: `Summarization`。	列挙型
qna	(省略可能) タスクの種類が `QnA` の場合は QnA データを保持します。	String
- `query`	(省略可能) これは QnA タスクの質問を表します。文字数制限: 7,500 文字。	String
text	(必須) チェックする LLM 出力テキスト。文字数制限: 7,500 文字。	String
groundingSources	(必須) 根拠となるソースの配列を使用して、AI によって生成されたテキストを検証します。 1 回の要求で最大 55,000 文字の根拠となるソースを分析できます。	文字列配列
reasoning	(省略可能) `true` に設定すると、サービスで Azure OpenAI リソースを使用して説明が提供されます。ただし、推論を使用すると処理時間が長くなり、追加の費用が発生することにご注意ください。	Boolean
llmResource	(省略可能) 独自の Azure OpenAI GPT4-Turbo リソースを使用して推論を有効にする場合は、このフィールドを追加し、使用するリソースのサブフィールドを含めます。	String
- `resourceType`	使用されるリソースの種類を指定します。現時点では、`AzureOpenAI` のみを指定できます。 Azure OpenAI GPT-4 Turbo リソースのみがサポートされており、他の GPT の種類はサポートされていません。 GPT-4 Turbo リソースは、任意のリージョンにデプロイできます。ただし、潜在的な待ち時間を最小限に抑えるために、Content Safety リソースと同じリージョンに配置することをお勧めします。	列挙型
- `azureOpenAIEndpoint`	Azure OpenAI Service のエンドポイント URL。	String
- `azureOpenAIDeploymentName`	使用する具体的な GPT デプロイの名前。	String

API 応答を解釈する

要求を送信後、実行された根拠性分析が反映された JSON 応答を受け取ります。一般的な出力は次のようになります。

{
    "ungroundedDetected": true,
    "ungroundedPercentage": 1,
    "ungroundedDetails": [
        {
            "text": "12/hour.",
            "offset": {
                "utF8": 0,
                "utF16": 0,
                "codePoint": 0
            },
            "length": {
                "utF8": 8,
                "utF16": 8,
                "codePoint": 8
            },
            "reason": "None. The premise mentions a pay of \"10/hour\" but does not mention \"12/hour.\" It's neutral. "
        }
    ]
}

出力の JSON オブジェクトは次のように定義されています。

名前	Description	Type
ungroundedDetected	テキストが非根拠性を示しているかどうかを示します。	Boolean
ungroundedPercentage	根拠なしとして識別されるテキストの比率を 0 から 1 の間の数値で表します。0 は根拠なしのコンテンツはないことを示し、1 は完全に根拠なしのコンテンツであることを示します。	Float
ungroundedDetails	具体的な例と割合を使用して、根拠なしのコンテンツに関する分析情報を提供します。	Array
-`text`	根拠なしの具体的なテキスト。	String
-`offset`	さまざまなエンコードでの根拠なしのテキストの位置を示すオブジェクト。	String
- `offset > utf8`	UTF-8 エンコードでの根拠なしのテキストのオフセット位置。	Integer
- `offset > utf16`	UTF-16 エンコードでの根拠なしのテキストのオフセット位置。	Integer
- `offset > codePoint`	Unicode コードポイントを単位とする根拠なしのテキストのオフセット位置。	Integer
-`length`	さまざまなエンコードでの根拠なしのテキストの長さを示すオブジェクト。 (utf8、utf16、codePoint)、オフセットに類似。	Object
- `length > utf8`	UTF-8 エンコードでの根拠なしのテキストの長さ。	Integer
- `length > utf16`	UTF-16 エンコードでの根拠なしのテキストの長さ。	Integer
- `length > codePoint`	Unicode コードポイントを単位とする根拠なしのテキストの長さ。	Integer
-`reason`	検出された非根拠性の説明を提供します。	String

リソースをクリーンアップする

Azure AI サービスサブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除することができます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。

次のステップ

根拠性検出を、プロンプトシールドなどの他の LLM の安全を確保する機能と組み合わせます。

プロンプトシールドのクイックスタート

クイックスタート: 根拠性検出 (プレビュー)

前提条件

推論なしで根拠性をチェックする

API 応答を解釈する

推論を使用して根拠性をチェックする

独自の GPT デプロイを持ち込む

API 要求を行う

API 応答を解釈する

リソースをクリーンアップする

次のステップ

その他のリソース