Início Rápido: Detecção de fundamentação (versão prévia)

Artigo
06/04/2024

Siga este guia para usar a detecção de Fundamentação da Segurança de Conteúdo de IA do Azure para verificar se as respostas de texto de LLMs (modelos de linguagem grandes) estão fundamentadas nos materiais de origem fornecidos pelos usuários.

Pré-requisitos

Uma assinatura do Azure – crie uma gratuitamente
Depois de ter uma assinatura do Azure, crie um recurso de Segurança do Conteúdo no portal do Azure para obter uma chave e um ponto de extremidade. Insira um nome exclusivo para o recurso, selecione sua assinatura e selecione um grupo de recursos, região com suporte e o tipo de preço com suporte. Em seguida, selecione Criar.
O recurso demora alguns minutos para implantar. Depois disso, acesse o novo recurso. No painel esquerdo, em Gerenciamento de Recursos, selecione Chaves de API e Pontos de Extremidade. Copie um dos valores de chave de assinatura e o ponto de extremidade para um local temporário para uso posterior.
(Opcional) Se você quiser usar o recurso de raciocínio, crie um recurso do Serviço OpenAI do Azure com um modelo GPT implantado.
O cURL ou o Python instalado.

Verificar a fundamentação sem raciocínio

No caso simples sem o recurso de raciocínio, a API de detecção de aterramento classifica a desproteção do conteúdo enviado como true ou false.

Curl
Python

Esta seção mostra como funciona uma solicitação de exemplo com o cURL. Cole o comando abaixo em um editor de texto e faça as seguintes alterações.

substitua <endpoint> pela URL do ponto de extremidade associada ao recurso.
Substitua <your_subscription_key> por uma das chaves para o recurso.

Opcionalmente, substitua os campos "query" ou "text" no corpo por um texto próprio que você deseja analisar.

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

Abra um prompt de comando e execute o comando do cURL.

Crie um novo arquivo Python denominado quickstart.py. Abra o novo arquivo em seu IDE ou editor preferido.

Substitua o conteúdo do quickstart.py pelo código a seguir. Insira a URL do ponto de extremidade e a chave nos campos apropriados. Opcionalmente, substitua os campos "query" ou "text" no corpo por um texto próprio que você deseja analisar.

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

Importante

Lembre-se de remover a chave do código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Para saber mais, veja Azure Key Vault

Execute o aplicativo com o comando python:
```
python quickstart.py
```
Leva alguns minutos para obter a resposta.

Para testar uma tarefa de resumo em vez de uma tarefa de pergunta e resposta (resposta às perguntas), use o seguinte exemplo de corpo 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
}

Os seguintes campos precisam ser incluídos na URL:

Nome	Obrigatória	Descrição	Type
Versão da API	Obrigatório	Esta é a versão de API a ser usada. A versão atual é: api-version=2024-02-15-preview. Exemplo: `<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview`	String

Os parâmetros no corpo da solicitação são definidos nesta tabela:

Nome	Descrição	Type
domain	(Opcional) `MEDICAL` ou `GENERIC`. Valor padrão: `GENERIC`.	Enum
task	(Opcional) Tipo de tarefa: `QnA`, `Summarization`. Valor padrão: `Summarization`.	Enum
qna	(Opcional) Armazena os dados de pergunta e resposta quando o tipo de tarefa é `QnA`.	String
- `query`	(Opcional) Isso representa a pergunta em uma tarefa de pergunta e resposta. Limite de caracteres: 7.500.	String
text	(Obrigatório) O texto de saída do LLM a ser verificado. Limite de caracteres: 7.500.	String
groundingSources	(Obrigatório) Usa uma matriz de fontes de fundamentação para validar o texto gerado por IA. Confira os Requisitos de entrada para conhecer os limites.	Matriz de cadeia de caracteres
reasoning	(Opcional) Especifica se o recurso de raciocínio deve ser usado. O valor padrão é `false`. Se for `true`, é necessário trazer os próprios recursos GPT-4 Turbo do OpenAI do Azure (1106-preview) para fornecer uma explicação. Tenha cuidado: o uso do raciocínio aumenta o tempo de processamento.	Booliano

Interpretar a resposta da API

Depois de enviar sua solicitação, você receberá uma resposta JSON que reflete a análise de fundamentação feita. Veja a aparência de uma saída típica:

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

Os objetos JSON na saída são definidos aqui:

Nome	Descrição	Type
ungroundedDetected	Indica se o texto exibe uma falta de fundamentação.	Booliano
ungroundedPercentage	Especifica a proporção do texto identificado como sem fundamentação, expresso como um número entre 0 e 1, sendo que 0 indica nenhum conteúdo sem fundamentação e 1 indica um conteúdo totalmente sem fundamentação.	Float
ungroundedDetails	Apresenta insights sobre o conteúdo sem fundamentação com exemplos e percentuais específicos.	Array
-`text`	O texto específico que não está fundamentado.	String

Verificar a fundamentação com raciocínio

A API de detecção de Fundamentação fornece a opção de incluir o raciocínio na resposta da API. Com o raciocínio habilitado, a resposta inclui um campo "reasoning" que apresenta detalhes de ocorrências específicas e explicações para qualquer falta de fundamentação detectada.

Trazer sua implantação de GPT

Dica

No momento, só damos suporte a recursos do GPT-4 Turbo do OpenAI do Azure (1106-preview) e não oferecemos suporte a outros tipos de GPT. Existe a flexibilidade de implantar os recursos GPT-4 Turbo (1106-preview) em qualquer região. No entanto, para minimizar a latência potencial e evitar todas as preocupações com risco e privacidade de dados de limite geográfico, é recomendável situá-los na mesma região que seus recursos de segurança de conteúdo. Para obter maiores detalhes sobre privacidade de dados, consulte as Diretrizes de dados, privacidade e segurança do Serviço OpenAI do Azure e os Dados, privacidade e segurança da Segurança e Conteúdo de IA do Azure.

Para usar o recurso GPT4-Turbo do OpenAI do Azure (1106-preview) para habilitar o recurso de raciocínio, use a identidade gerenciada para permitir que o recurso de Segurança de Conteúdo acesse o recurso do OpenAI do Azure:

Habilite a identidade gerenciada para a Segurança de Conteúdo de IA do Azure.

Navegue até a instância da Segurança de Conteúdo de IA do Azure no portal do Azure. Localize a seção Identidade na categoria Configurações. Habilite a identidade gerenciada atribuída pelo sistema. Essa ação concede à instância da Segurança de Conteúdo de IA do Azure uma identidade que pode ser reconhecida e usada no Azure para acessar outros recursos.
Atribua uma função à Identidade Gerenciada.

Navegue até a sua instância do OpenAI do Azure, selecione Adicionar atribuição de função para iniciar o processo de atribuição de uma função do OpenAI do Azure à identidade da Segurança de Conteúdo de IA do Azure.

Escolha a função Usuário ou Colaborador.

Fazer a solicitação de API

Na solicitação à API de detecção de Fundamentação, defina o parâmetro de corpo "reasoning" como true e informe os outros parâmetros necessários:

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

Curl
Python

Esta seção mostra como funciona uma solicitação de exemplo com o cURL. Cole o comando abaixo em um editor de texto e faça as seguintes alterações.

substitua <endpoint> pela URL do ponto de extremidade associada ao recurso.
Substitua <your_subscription_key> por uma das chaves para o recurso.

Opcionalmente, substitua os campos "query" ou "text" no corpo por um texto próprio que você deseja analisar.

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

Abra um prompt de comando e execute o comando do cURL.

Crie um novo arquivo Python denominado quickstart.py. Abra o novo arquivo em seu IDE ou editor preferido.

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

Execute o aplicativo com o comando python:
```
python quickstart.py
```
Leva alguns minutos para obter a resposta.

Os parâmetros no corpo da solicitação são definidos nesta tabela:

Nome	Descrição	Type
domain	(Opcional) `MEDICAL` ou `GENERIC`. Valor padrão: `GENERIC`.	Enum
task	(Opcional) Tipo de tarefa: `QnA`, `Summarization`. Valor padrão: `Summarization`.	Enum
qna	(Opcional) Armazena os dados de pergunta e resposta quando o tipo de tarefa é `QnA`.	String
- `query`	(Opcional) Isso representa a pergunta em uma tarefa de pergunta e resposta. Limite de caracteres: 7.500.	String
text	(Obrigatório) O texto de saída do LLM a ser verificado. Limite de caracteres: 7.500.	String
groundingSources	(Obrigatório) Usa uma matriz de fontes de fundamentação para validar o texto gerado por IA. Confira os Requisitos de entrada para conhecer os limites.	Matriz de cadeia de caracteres
reasoning	(Opcional) Se ele for definido como `true`, o serviço usará os recursos do OpenAI do Azure para oferecer uma explicação. Tenha cuidado: o uso do raciocínio aumenta o tempo de processamento e gera valores extras.	Booliano
llmResource	(Obrigatório) Se desejar usar o próprio recurso GPT4-Turbo do OpenAI do Azure (1106-preview) para habilitar o raciocínio, adicione este campo e inclua os subcampos para os recursos usados.	String
- `resourceType`	Especifica o tipo de recurso que está sendo usado. Atualmente, só permite `AzureOpenAI`. Só oferecemos suporte a recursos do GPT-4 Turbo do OpenAI do Azure (1106-preview) e não oferecemos suporte a outros tipos de GPT.	Enum
- `azureOpenAIEndpoint`	A URL do ponto de extremidade para o Serviço OpenAI do Azure.	String
- `azureOpenAIDeploymentName`	O nome da implantação específica de GPT a ser usada.	String

Interpretar a resposta da API

Depois de enviar sua solicitação, você receberá uma resposta JSON que reflete a análise de fundamentação feita. Veja a aparência de uma saída típica:

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

Os objetos JSON na saída são definidos aqui:

Nome	Descrição	Type
ungroundedDetected	Indica se o texto exibe uma falta de fundamentação.	Booliano
ungroundedPercentage	Especifica a proporção do texto identificado como sem fundamentação, expresso como um número entre 0 e 1, sendo que 0 indica nenhum conteúdo sem fundamentação e 1 indica um conteúdo totalmente sem fundamentação.	Float
ungroundedDetails	Apresenta insights sobre o conteúdo sem fundamentação com exemplos e percentuais específicos.	Array
-`text`	O texto específico que não está fundamentado.	String
-`offset`	Um objeto que descreve a posição do texto sem fundamentação em várias codificações.	String
- `offset > utf8`	A posição de deslocamento do texto sem fundamentação na codificação UTF-8.	Inteiro
- `offset > utf16`	A posição de deslocamento do texto sem fundamentação na codificação UTF-16.	Inteiro
- `offset > codePoint`	A posição de deslocamento do texto sem fundamentação em termos de pontos de código Unicode.	Inteiro
-`length`	Um objeto que descreve o comprimento do texto sem fundamentação em várias codificações. (utf8, utf16, codePoint), semelhante ao deslocamento.	Objeto
- `length > utf8`	O comprimento do texto sem fundamentação na codificação UTF-8.	Inteiro
- `length > utf16`	O comprimento do texto sem fundamentação na codificação UTF-16.	Inteiro
- `length > codePoint`	O comprimento do texto sem fundamentação em termos de pontos de código Unicode.	Inteiro
-`reason`	Oferece explicações para a falta de fundamentação detectada.	String

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de IA do Azure, você poderá excluir o recurso ou grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Combine a detecção de Fundamentação com outros recursos de segurança de LLM, como as Proteções de Solicitação.

Início rápido das Proteções de Solicitação

Compartilhar via

Início Rápido: Detecção de fundamentação (versão prévia)

Pré-requisitos

Verificar a fundamentação sem raciocínio

Interpretar a resposta da API

Verificar a fundamentação com raciocínio

Trazer sua implantação de GPT

Fazer a solicitação de API

Interpretar a resposta da API

Limpar os recursos

Próximas etapas

Comentários

Comentários

Recursos adicionais