Delen via

Quickstart: Groundedness detection (preview) gebruiken

  • Artikel

Deze handleiding laat zien hoe u de groundedness detection-API gebruikt. Deze functie detecteert en corrigeert automatisch niet-geaarde tekst op basis van de opgegeven brondocumenten, zodat de gegenereerde inhoud wordt afgestemd op feitelijke of beoogde verwijzingen. Hieronder verkennen we verschillende veelvoorkomende scenario's om inzicht te krijgen in hoe en wanneer u deze functies toepast om de beste resultaten te behalen.

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.

  1. Vervang door <endpoint> de eindpunt-URL die is gekoppeld aan uw resource.

  2. Vervang door <your_subscription_key> een van de sleutels voor uw resource.

  3. 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-09-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-09-15-preview. Voorbeeld: <endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-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 trueu uw eigen Azure OpenAI GPT4o (versie 0513, 0806) 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 verbinden

Tip

We ondersteunen alleen **Azure OpenAI GPT4o (versie 0513, 0806) ** en bieden geen ondersteuning voor andere GPT-typen. U hebt de flexibiliteit om uw Azure OpenAI GPT4o-resources (versie 0513, 0806) 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 GPT4o-resource (versie 0513, 0806) wilt gebruiken om de redeneringsfunctie in te schakelen, gebruikt u Managed Identity om uw Content Safety-resource toegang te geven tot de Azure OpenAI-resource:

  1. 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.

    Schermopname van een Content Safety-identiteitsresource in Azure Portal.

  2. 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.

    Schermopname van het toevoegen van roltoewijzing in Azure Portal.

    Kies de rol Gebruiker of Inzender .

    Schermopname van Azure Portal met de rol Inzender en Gebruiker weergegeven in een lijst.

De API-aanvraag maken

Stel in uw aanvraag voor de Groundedness detection-API de "reasoning" hoofdtekstparameter truein op en geef de andere vereiste parameters op:


{
  "domain": "Medical",
  "task": "Summarization",
  "text": "The patient name is Kevin.",
  "groundingSources": [
    "The patient name is Jane."
  ],
  "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.

  1. Vervang door <endpoint> de eindpunt-URL die is gekoppeld aan uw Azure AI Content Safety-resource.

  2. Vervang door <your_subscription_key> een van de sleutels voor uw resource.

  3. Vervang door <your_OpenAI_endpoint> de eindpunt-URL die is gekoppeld aan uw Azure OpenAI-resource.

  4. Vervang door <your_deployment_name> de naam van uw Azure OpenAI-implementatie.

  5. 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-09-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>"
}'

  6. 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 GPT4o-resource (versie 0513, 0806) 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 GPT4o-resources (0513, 0806-versie) 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

Geaardheid controleren met de correctiefunctie

De groundedness detection-API bevat een correctiefunctie waarmee alle gedetecteerde niet-geaardheid in de tekst automatisch wordt gecorrigeerd op basis van de opgegeven grondbronnen. Wanneer de correctiefunctie is ingeschakeld, bevat het antwoord een "correction Text" veld waarin de gecorrigeerde tekst wordt weergegeven die is uitgelijnd met de grondbronnen.

Uw eigen GPT-implementatie verbinden

Tip

Momenteel ondersteunt de correctiefunctie alleen **Azure OpenAI GPT4o (versie 0513, 0806) ** resources. Als u de latentie wilt minimaliseren en aan de privacyrichtlijnen voor gegevens wilt voldoen, is het raadzaam om uw Azure OpenAI GPT4o (versie 0513, 0806) in dezelfde regio te implementeren als uw resources 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 meer informatie over gegevensprivacy.

Als u uw Azure OpenAI GPT4o-resource (versie 0513, 0806) wilt gebruiken om de correctiefunctie in te schakelen, gebruikt u Managed Identity om uw Content Safety-resource toegang te geven tot de Azure OpenAI-resource. Volg de stappen in de vorige sectie om de beheerde identiteit in te stellen.

De API-aanvraag maken

Stel in uw aanvraag voor de geaardheidsdetectie-API de "correction" hoofdtekstparameter truein op en geef de andere vereiste parameters op:

{
  "domain": "Medical",
  "task": "Summarization",
  "text": "The patient name is Kevin.",
  "groundingSources": [
    "The patient name is Jane."
  ],
  "correction": true,
  "llmResource": {
    "resourceType": "AzureOpenAI",
    "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
    "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
}

In deze sectie ziet u een voorbeeldaanvraag met behulp van cURL. Vervang de tijdelijke aanduidingen indien nodig:

  • Vervang door <endpoint> de eindpunt-URL van uw resource.
  • Vervang <your_subscription_key> door uw abonnementssleutel.
  • Vervang desgewenst het veld 'tekst' door de tekst die u wilt analyseren.
curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "domain": "Generic",
  "task": "Summarization",
  "text": "The patient name is Kevin.",
  "groundingSources": [
    "The patient name is Jane."
  ],
  "correction": true,
  "llmResource": {
        "resourceType": "AzureOpenAI",
        "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
        "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
}'

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
correctie (Optioneel) Ingesteld op true, de service maakt gebruik van Azure OpenAI-resources om de gecorrigeerde tekst te bieden, waardoor consistentie met de grondbronnen wordt gegarandeerd. Wees voorzichtig: het gebruik van correctie verhoogt de verwerkingstijd en leidt tot extra kosten. Booleaanse waarde
llmResource (Vereist) Als u uw eigen Azure OpenAI GPT4o-resource (versie 0513, 0806) 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 GPT4o-resources (0513, 0806-versie) 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

Het antwoord bevat een "correction Text" veld met de gecorrigeerde tekst, waardoor consistentie met de opgegeven grondbronnen wordt gegarandeerd.

Met de correctiefunctie wordt gedetecteerd dat deze Kevin niet is geaard omdat deze conflicteert met de grondbron Jane. De API retourneert de gecorrigeerde tekst: "The patient name is Jane."

{
  "ungroundedDetected": true,
  "ungroundedPercentage": 1,
  "ungroundedDetails": [
    {
      "text": "The patient name is Kevin"
    }
  ],
  "correction Text": "The patient name is Jane"
}

De JSON-objecten in de uitvoer worden hier gedefinieerd:

Name Omschrijving Type
ungroundedDetected Geeft aan of er niet-geaarde inhoud is gedetecteerd. Booleaanse waarde
ungroundedPercentage Het aandeel van niet-geaarde inhoud in de tekst. Float
ungroundedDetails Details van niet-geaarde inhoud, inclusief specifieke tekstsegmenten. 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
-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
-correction Text De gecorrigeerde tekst zorgt voor consistentie met de grondbronnen. 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