Guida introduttiva: Usare il rilevamento della terra (anteprima)
Questa guida illustra come usare l'API di rilevamento della fondatezza. Questa funzionalità rileva e corregge automaticamente il testo privo di fondatezza in base ai documenti di origine forniti, garantendo che il contenuto generato sia allineato ai riferimenti oggettivi o previsti. Di seguito vengono esaminati diversi scenari comuni per comprendere come e quando applicare queste funzionalità per ottenere i risultati migliori.
Prerequisiti
- Una sottoscrizione di Azure: creare un account gratuitamente
- Dopo aver creato la sottoscrizione di Azure, Creare una risorsa di Sicurezza dei contenuti nel portale di Azure per ottenere la chiave e l'endpoint. Immettere un nome univoco per la risorsa, selezionare la sottoscrizione, quindi selezionare un gruppo di risorse, un'area supportata e un piano tariffario supportato. Selezionare Crea.
- La distribuzione della risorsa richiede alcuni minuti. Al termine, passare alla nuova risorsa. Nel riquadro a sinistra selezionare Gestione delle risorse e quindi selezionare Chiavi API ed endpoint. Copiare uno dei valori della chiave della sottoscrizione e dell'endpoint in un percorso temporaneo per poterlo usare in un secondo momento.
- (Facoltativo) Per usare la funzionalità di ragionamento, creare una risorsa del servizio Azure OpenAI usando un modello GPT distribuito.
- cURL o Python installato.
Verificare la fondatezza senza ragionamento
Nel caso semplice, ovvero senza l’uso della funzionalità di ragionamento, l'API di Rilevamento della fondatezza classifica la non fondatezza del contenuto inviato come true o false.
La sezione seguente illustra una richiesta di esempio con cURL. Incollare il comando qui di seguito in un editor di testo e apportare le modifiche seguenti.
Sostituire
<endpoint>con l'URL dell'endpoint associato alla risorsa.Sostituire
<your_subscription_key>con una delle chiavi per la risorsa.Facoltativamente, sostituire i campi
"query"o"text"nel corpo con il testo personalizzato da analizzare.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 }'
Aprire una finestra del prompt dei comandi ed eseguire il comando cURL.
Per testare un'attività di riepilogo anziché un'attività di risposta alle domande (QnA), usare il corpo JSON di esempio seguente:
{
"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
}
Nell'URL devono essere inclusi i campi seguenti:
| Nome | Obbligatorio | Descrizione | Tipo |
|---|---|---|---|
| Versione dell'API | Richiesto | Questa è la versione dell'API da usare. La versione corrente è: api-version=2024-09-15-preview. Esempio: <endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-15-preview |
String |
I parametri nel corpo della richiesta sono definiti in questa tabella:
| Nome | Descrizione | Tipo |
|---|---|---|
| domain | (facoltativo) MEDICAL o GENERIC. Valore predefinito: GENERIC |
Enumerazione |
| task | (Facoltativo) Tipo di attività: QnA, Summarization. Valore predefinito: Summarization |
Enumerazione |
| qna | (Facoltativo) Contiene i dati QnA quando il tipo di attività è QnA. |
String |
- query |
(Facoltativo) Rappresenta la domanda in un'attività QnA. Limite di caratteri: 7.500. | String |
| Testo | (Obbligatorio) Testo di output del modello LLM da controllare. Limite di caratteri: 7.500. | String |
| groundingSources | (Obbligatorio) Usa una matrice di origini di fondatezza per convalidare il testo generato dall'intelligenza artificiale. Vedere Requisiti di input per i limiti. | Matrice di stringhe |
| reasoning | (Facoltativo) Specifica se utilizzare la funzionalità di ragionamento. Il valore predefinito è false. Se true, è necessario usare azure OpenAI GPT4o (versione 0513, 0806) per fornire una spiegazione. Prestare attenzione: l'uso del ragionamento aumenta il tempo di elaborazione. |
Booleano |
Interpretare la risposta dell'API
Dopo l’invio della richiesta, si riceverà una risposta JSON che indica l'analisi di fondatezza eseguita. Ecco come appare un output tipico:
{
"ungroundedDetected": true,
"ungroundedPercentage": 1,
"ungroundedDetails": [
{
"text": "12/hour."
}
]
}
Gli oggetti JSON nell'output sono definiti qui:
| Nome | Descrizione | Tipo |
|---|---|---|
| ungroundedDetected | Indica se il testo presenta elementi non fondati. | Booleano |
| ungroundedPercentage | Specifica la proporzione del testo identificato come non fondato, espressa come numero compreso tra 0 e 1, dove 0 indica che non è presente alcun contenuto non fondato e 1 indica contenuto completamente non fondato. | Float |
| ungroundedDetails | Fornisce informazioni dettagliate sul contenuto non fondato con esempi e percentuali specifici. | Matrice |
-text |
Testo specifico non fondato. | String |
Verificare la fondatezza con il ragionamento
L'API di Rilevamento della fondatezza permette di includere il ragionamento nella risposta dell'API. Se il ragionamento è abilitato, la risposta include un campo "reasoning" che descrive in dettaglio istanze specifiche e spiegazioni per qualsiasi elemento non fondato rilevato.
Connettere la propria distribuzione GPT
Suggerimento
Sono supportate solo le risorse **Azure OpenAI GPT4o (0513, versione 0806) ** e non supportano altri tipi GPT. È possibile distribuire le risorse di Azure OpenAI GPT4o (versione 0513, 0806) in qualsiasi area. Tuttavia, per ridurre al minimo la latenza potenziale ed evitare eventuali problemi di privacy e rischio per i dati derivanti dai limiti geografici, è consigliabile inserirli nella stessa area delle risorse di Sicurezza dei contenuti. Per informazioni dettagliate sulla privacy dei dati, vedere le Linee guida per i dati, la privacy e la sicurezza per Servizio OpenAI di Azure e Dati, privacy e sicurezza per Sicurezza dei contenuti di Azure AI.
Per usare la risorsa Azure OpenAI GPT4o (0513, 0806 versione) per abilitare la funzionalità di ragionamento, usare l'identità gestita per consentire alla risorsa Content Safety di accedere alla risorsa OpenAI di Azure:
Abilitare Identità gestita per Sicurezza dei contenuti di Azure AI.
Passare all'istanza di Sicurezza dei contenuti di Azure AI nel portale di Azure. Individuare la sezione Identità nella categoria Impostazioni. Abilitare l’identità gestita assegnata dal sistema. Questa azione concede all'istanza di Sicurezza dei contenuti di Azure AI un'identità che può essere riconosciuta e usata in Azure per l'accesso ad altre risorse.
Assegnare il ruolo a Identità gestita.
Passare all'istanza di Azure OpenAI, selezionare Aggiungi assegnazione di ruolo per avviare il processo di assegnazione di un ruolo Azure OpenAI all'identità Sicurezza dei contenuti di Azure AI.
Scegliere il ruolo Utente o Collaboratore.
Effettuare la richiesta API
Nella richiesta all'API di Rilevamento della fondatezza impostare il parametro del corpo "reasoning" su truee specificare gli altri parametri necessari:
{
"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>"
}
}
La sezione seguente illustra una richiesta di esempio con cURL. Incollare il comando qui di seguito in un editor di testo e apportare le modifiche seguenti.
Sostituire
<endpoint>con l'URL dell'endpoint associato alla risorsa di Sicurezza dei contenuti di Azure AI.Sostituire
<your_subscription_key>con una delle chiavi per la risorsa.Sostituire
<your_OpenAI_endpoint>con l'URL dell'endpoint associato alla risorsa di Azure OpenAI.Sostituire
<your_deployment_name>con il nome della distribuzione di Azure OpenAI.Facoltativamente, sostituire i campi
"query"o"text"nel corpo con il testo personalizzato da analizzare.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>" }'Aprire una finestra del prompt dei comandi ed eseguire il comando cURL.
I parametri nel corpo della richiesta sono definiti in questa tabella:
| Nome | Descrizione | Tipo |
|---|---|---|
| domain | (facoltativo) MEDICAL o GENERIC. Valore predefinito: GENERIC |
Enumerazione |
| task | (Facoltativo) Tipo di attività: QnA, Summarization. Valore predefinito: Summarization |
Enumerazione |
| qna | (Facoltativo) Contiene i dati QnA quando il tipo di attività è QnA. |
String |
- query |
(Facoltativo) Rappresenta la domanda in un'attività QnA. Limite di caratteri: 7.500. | String |
| Testo | (Obbligatorio) Testo di output del modello LLM da controllare. Limite di caratteri: 7.500. | String |
| groundingSources | (Obbligatorio) Usa una matrice di origini di fondatezza per convalidare il testo generato dall'intelligenza artificiale. Vedere Requisiti di input per i limiti, | Matrice di stringhe |
| reasoning | (Facoltativo) Impostare su true, il servizio usa le risorse di Azure OpenAI per fornire una spiegazione. Prestare attenzione: l'uso del ragionamento aumenta il tempo di elaborazione e comporta costi aggiuntivi. |
Booleano |
| llmResource | (Obbligatorio) Se si vuole usare la propria risorsa Azure OpenAI GPT4o (0513, versione 0806) per abilitare il ragionamento, aggiungere questo campo e includere i sottocampi per le risorse usate. | String |
- resourceType |
Specifica il tipo di risorsa usata. Attualmente consente solo AzureOpenAI. Sono supportate solo le risorse GPT4o (0513, versione 0806) di Azure OpenAI e non supportano altri tipi GPT. |
Enum |
- azureOpenAIEndpoint |
URL dell'endpoint per il servizio Azure OpenAI. | String |
- azureOpenAIDeploymentName |
Nome della distribuzione GPT specifica da usare. | String |
Interpretare la risposta dell'API
Dopo l’invio della richiesta, si riceverà una risposta JSON che indica l'analisi di fondatezza eseguita. Ecco come appare un output tipico:
{
"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. "
}
]
}
Gli oggetti JSON nell'output sono definiti qui:
| Nome | Descrizione | Tipo |
|---|---|---|
| ungroundedDetected | Indica se il testo presenta elementi non fondati. | Booleano |
| ungroundedPercentage | Specifica la proporzione del testo identificato come non fondato, espressa come numero compreso tra 0 e 1, dove 0 indica che non è presente alcun contenuto non fondato e 1 indica contenuto completamente non fondato. | Float |
| ungroundedDetails | Fornisce informazioni dettagliate sul contenuto non fondato con esempi e percentuali specifici. | Matrice |
-text |
Testo specifico non fondato. | String |
-offset |
Oggetto che descrive la posizione del testo non fondato in varie codifiche. | String |
- offset > utf8 |
Posizione di offset del testo non fondato nella codifica UTF-8. | Intero |
- offset > utf16 |
Posizione di offset del testo non fondato nella codifica UTF-16. | Intero |
- offset > codePoint |
Posizione di offset del testo non fondato in termini di punti di codice Unicode. | Intero |
-length |
Oggetto che descrive la lunghezza del testo non fondato in varie codifiche. (utf8, utf16, codePoint), simile all'offset. | Object |
- length > utf8 |
Lunghezza del testo non fondato nella codifica UTF-8. | Intero |
- length > utf16 |
Lunghezza del testo non fondato nella codifica UTF-16. | Intero |
- length > codePoint |
Lunghezza del testo non fondato in termini di punti di codice Unicode. | Intero |
-reason |
Offre spiegazioni per gli elementi non fondati rilevati. | String |
Verificare la fondatezza con la funzionalità di correzione
L'API di rilevamento della fondatezza include una funzionalità di correzione che corregge automaticamente eventuali mancanze di fondatezza rilevate nel testo in base alle origini di fondatezza fornite. Quando la funzionalità di correzione è abilitata, la risposta include un campo "correction Text" che presenta il testo corretto allineato alle origini di fondatezza.
Connettere la propria distribuzione GPT
Suggerimento
Attualmente, la funzionalità di correzione supporta solo le risorse **Azure OpenAI GPT4o (0513, versione 0806) ** . Per ridurre al minimo la latenza e rispettare le linee guida sulla privacy dei dati, è consigliabile distribuire Azure OpenAI GPT4o (0513, versione 0806) nella stessa area delle risorse di sicurezza dei contenuti. Per altri dettagli sulla privacy dei dati, vedere le Linee guida per i dati, la privacy e la sicurezza per Servizio OpenAI di Azure e Dati, privacy e sicurezza per Sicurezza dei contenuti di Azure AI.
Per usare la risorsa Azure OpenAI GPT4o (0513, 0806 versione) per abilitare la funzionalità di correzione, usare Identità gestita per consentire alla risorsa Content Safety di accedere alla risorsa OpenAI di Azure. Seguire la procedura descritta nella sezione precedente per configurare l'identità gestita.
Effettuare la richiesta API
Nella richiesta all'API di rilevamento della fondatezza impostare il parametro del corpo "correction" su true e specificare gli altri parametri necessari:
{
"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>"
}
}
Questa sezione illustra una richiesta di esempio usando cURL. Sostituire i segnaposto in base alle esigenze:
- Sostituire
<endpoint>con l'URL dell'endpoint della risorsa. - Sostituire
<your_subscription_key>con la chiave di sottoscrizione. - Facoltativamente, sostituire il campo "text" con il testo da analizzare.
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>"
}
}'
I parametri nel corpo della richiesta sono definiti in questa tabella:
| Nome | Descrizione | Tipo |
|---|---|---|
| domain | (facoltativo) MEDICAL o GENERIC. Valore predefinito: GENERIC |
Enumerazione |
| task | (Facoltativo) Tipo di attività: QnA, Summarization. Valore predefinito: Summarization |
Enumerazione |
| qna | (Facoltativo) Contiene i dati QnA quando il tipo di attività è QnA. |
String |
- query |
(Facoltativo) Rappresenta la domanda in un'attività QnA. Limite di caratteri: 7.500. | String |
| Testo | (Obbligatorio) Testo di output del modello LLM da controllare. Limite di caratteri: 7.500. | String |
| groundingSources | (Obbligatorio) Usa una matrice di origini di fondatezza per convalidare il testo generato dall'intelligenza artificiale. Vedere Requisiti di input per i limiti. | String Array |
| correction | (Facoltativo) Se è impostato su true, il servizio usa le risorse di Azure OpenAI per fornire il testo corretto, garantendo la coerenza con le origini di fondatezza. Prestare attenzione: l'uso della correzione aumenta il tempo di elaborazione e comporta costi aggiuntivi. |
Booleano |
| llmResource | (Obbligatorio) Se si vuole usare la propria risorsa Azure OpenAI GPT4o (0513, versione 0806) per abilitare il ragionamento, aggiungere questo campo e includere i sottocampi per le risorse usate. | String |
- resourceType |
Specifica il tipo di risorsa usata. Attualmente consente solo AzureOpenAI. Sono supportate solo le risorse GPT4o (0513, versione 0806) di Azure OpenAI e non supportano altri tipi GPT. |
Enum |
- azureOpenAIEndpoint |
URL dell'endpoint per il servizio Azure OpenAI. | String |
- azureOpenAIDeploymentName |
Nome della distribuzione GPT specifica da usare. | String |
Interpretare la risposta dell'API
La risposta include un campo "correction Text" contenente il testo corretto, in modo da garantire la coerenza con le origini di fondatezza fornite.
La funzionalità di correzione rileva che Kevin è privo di fondatezza perché è in conflitto con l'origine di fondatezza Jane. L'API restituisce il testo corretto: "The patient name is Jane."
{
"ungroundedDetected": true,
"ungroundedPercentage": 1,
"ungroundedDetails": [
{
"text": "The patient name is Kevin"
}
],
"correction Text": "The patient name is Jane"
}
Gli oggetti JSON nell'output sono definiti qui:
| Nome | Descrizione | Tipo |
|---|---|---|
| ungroundedDetected | Indica se è stato rilevato contenuto privo di fondatezza. | Booleano |
| ungroundedPercentage | Percentuale di contenuto privo di fondatezza nel testo. | Float |
| ungroundedDetails | Dettagli del contenuto privo di fondatezza, inclusi segmenti di testo specifici. | Array |
-text |
Testo specifico non fondato. | String |
-offset |
Oggetto che descrive la posizione del testo non fondato in varie codifiche. | String |
- offset > utf8 |
Posizione di offset del testo non fondato nella codifica UTF-8. | Intero |
- offset > utf16 |
Posizione di offset del testo non fondato nella codifica UTF-16. | Intero |
-length |
Oggetto che descrive la lunghezza del testo non fondato in varie codifiche. (utf8, utf16, codePoint), simile all'offset. | Object |
- length > utf8 |
Lunghezza del testo non fondato nella codifica UTF-8. | Intero |
- length > utf16 |
Lunghezza del testo non fondato nella codifica UTF-16. | Intero |
- length > codePoint |
Lunghezza del testo non fondato in termini di punti di codice Unicode. | Intero |
-correction Text |
Testo corretto, in modo da garantire la coerenza con le origini di fondatezza. | String |
Pulire le risorse
Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.
Contenuto correlato
- Concetti di rilevamento della fondatezza
- Combinare Rilevamento della fondatezza con altre funzionalità di sicurezza dei modelli LLM, ad esempio Prompt Shields.