Quickstart: Groundedness detection (preview)
Volg deze handleiding om azure AI Content Safety Groundedness-detectie te gebruiken om te controleren of de tekstreacties van grote taalmodellen (LLM's) zijn geaard in de bronmaterialen die door de gebruikers worden geleverd.
Zie de conceptpagina groundednessdetectie voor meer informatie over groundednessdetectie. Zie de sectie Invoervereisten van het overzicht voor API-invoerlimieten.
Vereisten
- Een Azure-abonnement - Een gratis abonnement maken
- Zodra u uw Azure-abonnement hebt, maakt u een Content Safety-resource in Azure Portal om uw sleutel en eindpunt op te halen. Voer een unieke naam in voor uw resource, selecteer uw abonnement en selecteer een resourcegroep, ondersteunde regio en ondersteunde prijscategorie. Selecteer vervolgens Maken.
- Het implementeren van de resource duurt enkele minuten. Zodra dit is gebeurd, gaat u naar de nieuwe resource. Selecteer api-sleutels en eindpunten in het linkerdeelvenster onder ResourceBeheer. Kopieer een van de abonnementssleutelwaarden en het eindpunt naar een tijdelijke locatie voor later gebruik.
- (Optioneel) Als u de redeneringsfunctie wilt gebruiken, maakt u een Azure OpenAI-serviceresource met een GPT-model dat is geïmplementeerd.
- cURL of Python geïnstalleerd.
Geaardheid controleren zonder redenering
In het eenvoudige geval zonder de redeneringsfunctie classificeert de Groundedness detection-API de onaardigheid van de ingediende inhoud als true
of false
.
In deze sectie wordt een voorbeeldaanvraag met cURL beschreven. Plak de onderstaande opdracht in een teksteditor en breng de volgende wijzigingen aan.
Vervang door
<endpoint>
de eindpunt-URL die is gekoppeld aan uw resource.Vervang door
<your_subscription_key>
een van de sleutels voor uw resource.Vervang desgewenst de
"query"
of"text"
velden in de hoofdtekst door uw eigen tekst die u wilt analyseren.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 }'
Open een opdrachtprompt en voer de cURL-opdracht uit.
Als u een samenvattingstaak wilt testen in plaats van een vraagantwoordtaak (QnA), gebruikt u de volgende voorbeeld-JSON-hoofdtekst:
{
"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
}
De volgende velden moeten worden opgenomen in de URL:
Naam | Vereist | Beschrijving | Type |
---|---|---|---|
API-versie | Vereist | Dit is de API-versie die moet worden gebruikt. De huidige versie is: api-version=2024-02-15-preview. Voorbeeld: <endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview |
String |
De parameters in de aanvraagbody worden gedefinieerd in deze tabel:
Name | Omschrijving | Type |
---|---|---|
domein | (Optioneel) MEDICAL of GENERIC . Standaardwaarde: GENERIC . |
Enum |
taak | (Optioneel) Type taak: QnA , Summarization . Standaardwaarde: Summarization . |
Enum |
qna | (Optioneel) Bevat QnA-gegevens wanneer het taaktype is QnA . |
String |
- query |
(Optioneel) Dit vertegenwoordigt de vraag in een QnA-taak. Tekenlimiet: 7.500. | String |
tekst | (Vereist) De LLM-uitvoertekst die moet worden gecontroleerd. Tekenlimiet: 7.500. | String |
groundingSources | (Vereist) Maakt gebruik van een matrix met grondbronnen om door AI gegenereerde tekst te valideren. Zie de invoervereisten voor limieten. | Tekenreeksmatrix |
redenering | (Optioneel) Hiermee geeft u op of de redeneringsfunctie moet worden gebruikt. De standaardwaarde is false . Als true u uw eigen Azure OpenAI GPT-4 Turbo-resources (1106-preview) moet meenemen om een uitleg te geven. Wees voorzichtig: het gebruik van redenering verhoogt de verwerkingstijd. |
Booleaanse waarde |
Het API-antwoord interpreteren
Nadat u uw aanvraag hebt ingediend, ontvangt u een JSON-antwoord dat de uitgevoerde Groundedness-analyse weergeeft. Hier ziet u hoe een typische uitvoer eruitziet:
{
"ungroundedDetected": true,
"ungroundedPercentage": 1,
"ungroundedDetails": [
{
"text": "12/hour."
}
]
}
De JSON-objecten in de uitvoer worden hier gedefinieerd:
Name | Omschrijving | Type |
---|---|---|
ungroundedDetected | Geeft aan of de tekst onaardigheid vertoont. | Booleaanse waarde |
ungroundedPercentage | Hiermee geeft u het aandeel van de tekst aan die is geïdentificeerd als niet-geaard, uitgedrukt als een getal tussen 0 en 1, waarbij 0 geen niet-geaarde inhoud aangeeft en 1 geheel niet-geaarde inhoud aangeeft. | Float |
ungroundedDetails | Biedt inzicht in niet-geaarde inhoud met specifieke voorbeelden en percentages. | Matrix |
-text |
De specifieke tekst die niet is geaard. | String |
Geaardheid controleren met redenering
De Groundedness detection-API biedt de mogelijkheid om redenering op te nemen in het API-antwoord. Als redenering is ingeschakeld, bevat het antwoord een "reasoning"
veld waarin specifieke exemplaren en uitleg worden weergegeven voor gedetecteerde niet-geaardheid.
Uw eigen GPT-implementatie gebruiken
Tip
Op dit moment ondersteunen we alleen Azure OpenAI GPT-4 Turbo-resources (1106-preview) en bieden we geen ondersteuning voor andere GPT-typen. U hebt de flexibiliteit om uw GPT-4 Turbo-resources (1106-preview) in elke regio te implementeren. Als u echter potentiële latentie wilt minimaliseren en eventuele privacy- en risicoproblemen van geografische grensgegevens wilt voorkomen, raden we u aan ze in dezelfde regio te plaatsen als uw bronnen voor inhoudsveiligheid. Raadpleeg de richtlijnen voor gegevens, privacy en beveiliging voor Azure OpenAI-service en -gegevens, privacy en beveiliging voor Azure AI Content Safety voor uitgebreide informatie over gegevensprivacy.
Als u uw Azure OpenAI GPT4-Turbo-resource (1106-preview) wilt gebruiken om de redeneringsfunctie in te schakelen, gebruikt u Beheerde identiteit om uw Content Safety-resource toegang te geven tot de Azure OpenAI-resource:
Beheerde identiteit inschakelen voor Azure AI Content Safety.
Navigeer naar uw Azure AI Content Safety-exemplaar in Azure Portal. Zoek de sectie Identiteit onder de categorie Instellingen . Schakel de door het systeem toegewezen beheerde identiteit in. Met deze actie verleent u uw Azure AI Content Safety-exemplaar een identiteit die kan worden herkend en gebruikt in Azure voor toegang tot andere resources.
Rol toewijzen aan beheerde identiteit.
Navigeer naar uw Azure OpenAI-exemplaar, selecteer Roltoewijzing toevoegen om het proces voor het toewijzen van een Azure OpenAI-rol aan de Azure AI Content Safety-identiteit te starten.
Kies de rol Gebruiker of Inzender .
De API-aanvraag maken
Stel in uw aanvraag voor de Groundedness detection-API de "reasoning"
hoofdtekstparameter true
in op en geef de andere vereiste parameters op:
{
"reasoning": true,
"llmResource": {
"resourceType": "AzureOpenAI",
"azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
"azureOpenAIDeploymentName": "<your_deployment_name>"
}
}
In deze sectie wordt een voorbeeldaanvraag met cURL beschreven. Plak de onderstaande opdracht in een teksteditor en breng de volgende wijzigingen aan.
Vervang door
<endpoint>
de eindpunt-URL die is gekoppeld aan uw resource.Vervang door
<your_subscription_key>
een van de sleutels voor uw resource.Vervang desgewenst de
"query"
of"text"
velden in de hoofdtekst door uw eigen tekst die u wilt analyseren.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>" }'
Open een opdrachtprompt en voer de cURL-opdracht uit.
De parameters in de aanvraagbody worden gedefinieerd in deze tabel:
Name | Omschrijving | Type |
---|---|---|
domein | (Optioneel) MEDICAL of GENERIC . Standaardwaarde: GENERIC . |
Enum |
taak | (Optioneel) Type taak: QnA , Summarization . Standaardwaarde: Summarization . |
Enum |
qna | (Optioneel) Bevat QnA-gegevens wanneer het taaktype is QnA . |
String |
- query |
(Optioneel) Dit vertegenwoordigt de vraag in een QnA-taak. Tekenlimiet: 7.500. | String |
tekst | (Vereist) De LLM-uitvoertekst die moet worden gecontroleerd. Tekenlimiet: 7.500. | String |
groundingSources | (Vereist) Maakt gebruik van een matrix met grondbronnen om door AI gegenereerde tekst te valideren. Zie invoervereisten voor limieten, | Tekenreeksmatrix |
redenering | (Optioneel) Ingesteld op true : de service maakt gebruik van Azure OpenAI-resources om een uitleg te geven. Wees voorzichtig: het gebruik van redenering verhoogt de verwerkingstijd en er worden extra kosten in rekening gebracht. |
Booleaanse waarde |
llmResource | (Vereist) Als u uw eigen Azure OpenAI GPT4-Turbo-resource (1106-preview) wilt gebruiken om redenering mogelijk te maken, voegt u dit veld toe en neemt u de subvelden op voor de gebruikte resources. | String |
- resourceType |
Hiermee geeft u het type resource dat wordt gebruikt. Op dit moment is het alleen toegestaan AzureOpenAI . We ondersteunen alleen Azure OpenAI GPT-4 Turbo-resources (1106-preview) en bieden geen ondersteuning voor andere GPT-typen. |
Enum |
- azureOpenAIEndpoint |
Uw eindpunt-URL voor de Azure OpenAI-service. | String |
- azureOpenAIDeploymentName |
De naam van de specifieke GPT-implementatie die moet worden gebruikt. | String |
Het API-antwoord interpreteren
Nadat u uw aanvraag hebt ingediend, ontvangt u een JSON-antwoord dat de uitgevoerde Groundedness-analyse weergeeft. Hier ziet u hoe een typische uitvoer eruitziet:
{
"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. "
}
]
}
De JSON-objecten in de uitvoer worden hier gedefinieerd:
Name | Omschrijving | Type |
---|---|---|
ungroundedDetected | Geeft aan of de tekst onaardigheid vertoont. | Booleaanse waarde |
ungroundedPercentage | Hiermee geeft u het aandeel van de tekst aan die is geïdentificeerd als niet-geaard, uitgedrukt als een getal tussen 0 en 1, waarbij 0 geen niet-geaarde inhoud aangeeft en 1 geheel niet-geaarde inhoud aangeeft. | Float |
ungroundedDetails | Biedt inzicht in niet-geaarde inhoud met specifieke voorbeelden en percentages. | Matrix |
-text |
De specifieke tekst die niet is geaard. | String |
-offset |
Een object met een beschrijving van de positie van de niet-geaarde tekst in verschillende coderingen. | String |
- offset > utf8 |
De verschuivingspositie van de niet-geaarde tekst in UTF-8-codering. | Geheel getal |
- offset > utf16 |
De verschuivingspositie van de niet-geaarde tekst in UTF-16-codering. | Geheel getal |
- offset > codePoint |
De verschuivingspositie van de niet-geaarde tekst in termen van Unicode-codepunten. | Geheel getal |
-length |
Een object met een beschrijving van de lengte van de niet-geaarde tekst in verschillende coderingen. (utf8, utf16, codePoint), vergelijkbaar met de offset. | Object |
- length > utf8 |
De lengte van de niet-geaarde tekst in UTF-8-codering. | Geheel getal |
- length > utf16 |
De lengte van de niet-geaarde tekst in UTF-16-codering. | Geheel getal |
- length > codePoint |
De lengte van de niet-geaarde tekst in termen van Unicode-codepunten. | Geheel getal |
-reason |
Biedt uitleg over gedetecteerde niet-geaardheid. | String |
Resources opschonen
Als u een Azure AI-servicesabonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle bijbehorende resources verwijderd.
Gerelateerde inhoud
- Basisdetectieconcepten
- Combineer Groundedness-detectie met andere LLM-veiligheidsfuncties, zoals Prompt Shields.