Schnellstart: Groundedness-Erkennung (Vorschau)

Artikel
04/15/2024

Befolgen Sie dieses Handbuch, um die Azure KI Inhaltssicherheit Groundedness-Erkennung zu verwenden, um zu überprüfen, ob sich die Textantworten großer Sprachmodelle (LLMs) auf die von den Benutzern bereitgestellten Quellmaterialien stützen.

Voraussetzungen

Azure-Abonnement: Kostenloses Azure-Konto
Sobald Sie über ein Azure-Abonnement verfügen, können Sie im Azure-Portal eine Content Safety-Ressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Geben Sie für Ihre Ressource einen eindeutigen Namen ein. Wählen Sie Ihr Abonnement aus, und wählen Sie dann eine Ressourcengruppe, eine unterstützte Region (East US2, West US, Schweden, Mitte) und einen unterstützten Tarif. Klicken Sie anschließend auf Erstellen.
- Die Bereitstellung der Ressource dauert einige Minuten. Navigieren Sie danach zur neuen Ressource. Wählen Sie im linken Bereich unter Ressourcenverwaltung die Option API-Schlüssel und Endpunkte aus. Kopieren Sie einen der Abonnementschlüsselwerte und den Endpunkt an einen temporären Speicherort für die spätere Verwendung.
(Optional) Wenn Sie das Begründungsfeature verwenden möchten, erstellen Sie eine Azure OpenAI Service-Ressource mit einem bereitgestellten GPT-Modell.
cURL oder Python installiert.

Überprüfen der Groundedness ohne Begründung

Im einfachen Fall ohne die Begründungsfunktion klassifiziert die Groundedness-Erkennungs-API die Unbegründetheit des übermittelten Inhalts als true oder false.

cURL
Python

In diesem Abschnitt wird eine Beispielanforderung mit cURL erläutert. Fügen Sie den nachstehenden Befehl in einen Text-Editor ein, und nehmen Sie folgende Änderungen vor:

Ersetzen Sie <endpoint> durch die Endpunkt-URL, die Ihrer Ressource zugeordnet ist.
Ersetzen Sie <your_subscription_key> durch einen der Schlüssel für Ihre Ressource.

Ersetzen Sie optional Felder "query" oder "text" im Text durch Ihren eigenen Text für die Analyse.

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
}'

Öffnen Sie eine Eingabeaufforderung, und führen Sie den cURL-Befehl aus.

Erstellen Sie eine neue Python-Datei namens quickstart.py. Öffnen Sie die Datei in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE.

Ersetzen Sie den Inhalt von quickstart.py durch den folgenden Code. Geben Sie Ihre Endpunkt-URL und ihren Schlüssel in die entsprechenden Felder ein. Ersetzen Sie optional Felder "query" oder "text" im Text durch Ihren eigenen Text für die Analyse.

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

Wichtig

Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. In der Produktionsumgebung sollten Sie eine sichere Methode zum Speichern Ihrer Anmeldeinformationen sowie zum Zugriff darauf verwenden. Weitere Informationen finden Sie unter Azure Key Vault.

Führen Sie die Anwendung mit Befehl python aus:
```
python quickstart.py
```
Die Ausgabe der Ergebnisse dauert einen Moment.

Um eine Zusammenfassungsaufgabe anstelle einer Fragebeantwortungsaufgabe (QnA) zu testen, verwenden Sie den folgenden JSON-Beispieltext:

{
    "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
}

Die folgenden Felder müssen in der URL enthalten sein:

Name	Erforderlich	BESCHREIBUNG	type
API-Version	Erforderlich	Die zu benutzende API-Version. Aktuelle Version: api-version=2024-02-15-preview. Beispiel: `<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview`	String

Die Parameter im Anforderungstext sind in der folgenden Tabelle definiert:

Name	Description	type
domain	(Optional) `MEDICAL` oder `GENERIC`. Standardwert. `GENERIC`.	Enumeration
Aufgabe	(Optional) Typ des Vorgangs: `QnA`, `Summarization`. Standardwert. `Summarization`.	Enumeration
qna	(Optional) Enthält QnA-Daten, wenn der Aufgabentyp `QnA` ist.	String
- `query`	(Optional) Dies stellt die Frage in einer QnA-Aufgabe dar. Zeichengrenzwert: 7500.	String
text	(Erforderlich) Der zu überprüfende LLM-Ausgabetext. Zeichengrenzwert: 7500.	String
groundingSources	(Erforderlich) Verwendet ein Array von Grounding-Quellen, um KI-generierten Text zu überprüfen. Bis zu 55.000 Zeichen von Grounding-Quellen können in einer einzigen Anforderung analysiert werden.	Zeichenfolgenarray
Begründung	(Optional) Gibt an, ob das Begründungsfeature verwendet werden soll. Der Standardwert ist `false`. Bei `true` müssen Sie Ihre eigenen Azure OpenAI GPT-4 Turbo-Ressourcen mitbringen, um eine Erläuterung bereitzustellen. Seien Sie vorsichtig: Die Verwendung der Begründung erhöht die Verarbeitungszeit.	Boolean

Interpretieren der API-Antwort

Nachdem Sie Ihre Anforderung übermittelt haben, erhalten Sie eine JSON-Antwort, die die durchgeführte Groundedness-Analyse widerspiegelt. So sieht eine typische Ausgabe aus:

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

Die JSON-Objekte in der Ausgabe werden hier definiert:

Name	Description	type
ungroundedDetected	Gibt an, ob der Text nicht begründet ist.	Boolean
ungroundedPercentage	Gibt den Anteil des als nicht begründet gekennzeichneten Texts an, ausgedrückt als Zahl zwischen 0 und 1, wobei 0 keinen unbegründeten Inhalt angibt und 1 den vollständig unbegründeten Inhalt angibt.	Gleitkomma
ungroundedDetails	Bietet Einblicke in unbegründeten Inhalt mit bestimmten Beispielen und Prozentsätzen.	Array
-`text`	Der spezifische Text, der unbegründet ist.	String

Überprüfen von Groundedness mit Begründung

Die Groundedness-Erkennungs-API bietet die Möglichkeit, Begründungen in die API-Antwort einzuschließen. Wenn die Begründung aktiviert ist, enthält die Antwort ein "reasoning" Feld, das bestimmte Instanzen und Erklärungen für alle erkannten Unbegründetheiten enthält. Seien Sie vorsichtig: Die Verwendung der Begründung erhöht die Verarbeitungszeit und verursacht zusätzliche Gebühren.

Sorgen Sie für Ihre eigene GPT-Bereitstellung

Tipp

Derzeit unterstützen wir nur Azure OpenAI GPT-4 Turbo-Ressourcen und keine anderen GPT-Typen. Ihre GPT-4 Turbo-Ressourcen können in jeder Region bereitgestellt werden. Wir empfehlen jedoch, sie in derselben Region zu platzieren wie die Inhaltssicherheitsressourcen, um potenzielle Wartezeiten zu minimieren.

Um Ihre Azure OpenAI GPT4-Turbo-Ressource zum Aktivieren der Begründungsfunktion zu verwenden, verwenden Sie eine verwaltete Identität, um Ihrer Inhaltssicherheitsressource den Zugriff auf die Azure OpenAI-Ressource zu ermöglichen:

Aktivieren sie verwaltete Identität für Azure KI Inhaltssicherheit.

Navigieren Sie im Azure-Portal zu Ihrer Azure KI Inhaltssicherheits-Instanz. Suchen Sie den Abschnitt Identität unter der Kategorie Einstellungen. Aktivieren der systemseitig zugewiesenen verwalteten Identität. Diese Aktion gewährt Ihrer Azure KI Inhaltssicherheits-Instanz eine Identität, die in Azure für den Zugriff auf andere Ressourcen erkannt und verwendet werden kann.
Zuweisen einer Rolle zur verwalteten Identität.

Navigieren Sie zu Ihrer Azure OpenAI-Instanz, wählen Sie Rollenzuweisung hinzufügen aus, um den Prozess der Zuweisung einer Azure OpenAI-Rolle zur Azure KI Inhaltssicherheits-Identität zu starten.

Wählen Sie die Rolle Benutzer oder Mitwirkender aus.

API-Anforderung stellen

Legen Sie in Ihrer Anforderung an die Groundedness-Erkennungs-API den "reasoning" Textparameter auf true, und geben Sie die anderen erforderlichen Parameter an:

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

cURL
Python

In diesem Abschnitt wird eine Beispielanforderung mit cURL erläutert. Fügen Sie den nachstehenden Befehl in einen Text-Editor ein, und nehmen Sie folgende Änderungen vor:

Ersetzen Sie <endpoint> durch die Endpunkt-URL, die Ihrer Ressource zugeordnet ist.
Ersetzen Sie <your_subscription_key> durch einen der Schlüssel für Ihre Ressource.

Ersetzen Sie optional Felder "query" oder "text" im Text durch Ihren eigenen Text für die Analyse.

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>"
}'

Öffnen Sie eine Eingabeaufforderung, und führen Sie den cURL-Befehl aus.

Erstellen Sie eine neue Python-Datei namens quickstart.py. Öffnen Sie die Datei in Ihrem bevorzugten Editor oder Ihrer bevorzugten 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"))

Führen Sie die Anwendung mit Befehl python aus:
```
python quickstart.py
```
Die Ausgabe der Ergebnisse dauert einen Moment.

Die Parameter im Anforderungstext sind in der folgenden Tabelle definiert:

Name	Description	type
domain	(Optional) `MEDICAL` oder `GENERIC`. Standardwert. `GENERIC`.	Enumeration
Aufgabe	(Optional) Typ des Vorgangs: `QnA`, `Summarization`. Standardwert. `Summarization`.	Enumeration
qna	(Optional) Enthält QnA-Daten, wenn der Aufgabentyp `QnA` ist.	String
- `query`	(Optional) Dies stellt die Frage in einer QnA-Aufgabe dar. Zeichengrenzwert: 7500.	String
text	(Erforderlich) Der zu überprüfende LLM-Ausgabetext. Zeichengrenzwert: 7500.	String
groundingSources	(Erforderlich) Verwendet ein Array von Grounding-Quellen, um KI-generierten Text zu überprüfen. Bis zu 55.000 Zeichen von Grounding-Quellen können in einer einzigen Anforderung analysiert werden.	Zeichenfolgenarray
Begründung	(Optional) Wenn auf `true` gesetzt, verwendet der Dienst Azure OpenAI-Ressourcen, um eine Erläuterung bereitzustellen. Seien Sie vorsichtig: Die Verwendung der Begründung erhöht die Verarbeitungszeit und verursacht zusätzliche Gebühren.	Boolean
llmResource	(Erforderlich) Wenn Sie Ihre eigenen Azure OpenAI GPT4-Turbo-Ressourcen zum Aktivieren der Begründung verwenden möchten, fügen Sie dieses Feld sowie die Unterfelder für die verwendeten Ressourcen hinzu.	String
- `resourceType`	Gibt den Typ der verwendeten Ressource an. Derzeit ist nur `AzureOpenAI` zulässig. Derzeit unterstützen wir nur Azure OpenAI GPT-4 Turbo-Ressourcen und keine anderen GPT-Typen. Ihre GPT-4 Turbo-Ressourcen können in jeder Region bereitgestellt werden. Wir empfehlen jedoch, sie in derselben Region zu platzieren wie die Inhaltssicherheitsressourcen, um potenzielle Wartezeiten zu minimieren.	Enumeration
- `azureOpenAIEndpoint`	Ihre Endpunkt-URL für den Azure OpenAI-Dienst.	String
- `azureOpenAIDeploymentName`	Der Name der zu verwendenden GPT-Bereitstellung.	String

Interpretieren der API-Antwort

Nachdem Sie Ihre Anforderung übermittelt haben, erhalten Sie eine JSON-Antwort, die die durchgeführte Groundedness-Analyse widerspiegelt. So sieht eine typische Ausgabe aus:

{
    "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. "
        }
    ]
}

Die JSON-Objekte in der Ausgabe werden hier definiert:

Name	Description	type
ungroundedDetected	Gibt an, ob der Text nicht begründet ist.	Boolean
ungroundedPercentage	Gibt den Anteil des als nicht begründet gekennzeichneten Texts an, ausgedrückt als Zahl zwischen 0 und 1, wobei 0 keinen unbegründeten Inhalt angibt und 1 den vollständig unbegründeten Inhalt angibt.	Gleitkomma
ungroundedDetails	Bietet Einblicke in unbegründeten Inhalt mit bestimmten Beispielen und Prozentsätzen.	Array
-`text`	Der spezifische Text, der unbegründet ist.	String
-`offset`	Ein Objekt, das die Position des unbegründeten Texts in verschiedener Codierung beschreibt.	String
- `offset > utf8`	Die Offsetposition des unbegründeten Texts in UTF-8-Codierung.	Ganzzahl
- `offset > utf16`	Die Offsetposition des unbegründeten Texts in UTF-16-Codierung.	Ganzzahl
- `offset > codePoint`	Die Offsetposition des unbegründeten Texts in Bezug auf Unicode-Codepunkte.	Ganzzahl
-`length`	Ein Objekt, das die Länge des unbegründeten Texts in verschiedener Codierung beschreibt. (utf8, utf16, codePoint), ähnlich dem Offset.	Objekt
- `length > utf8`	Die Länge des unbegründeten Texts in UTF-8-Codierung.	Ganzzahl
- `length > utf16`	Die Länge des unbegründeten Texts in UTF-16-Codierung.	Ganzzahl
- `length > codePoint`	Die Länge des unbegründeten Texts in Bezug auf Unicode-Codepunkte.	Ganzzahl
-`reason`	Bietet Erklärungen für erkannte Unbegründetheit.	String

Bereinigen von Ressourcen

Wenn Sie ein Azure KI Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Nächste Schritte

Kombinieren Sie die Groundedness-Erkennung mit anderen LLM-Sicherheitsfeatures wie Prompt Shields.

Schnellstart für Prompt Shields

Schnellstart: Groundedness-Erkennung (Vorschau)

Voraussetzungen

Überprüfen der Groundedness ohne Begründung

Interpretieren der API-Antwort

Überprüfen von Groundedness mit Begründung

Sorgen Sie für Ihre eigene GPT-Bereitstellung

API-Anforderung stellen

Interpretieren der API-Antwort

Bereinigen von Ressourcen

Nächste Schritte

Zusätzliche Ressourcen