Compartilhar via

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

  • Artigo

Este guia mostra como usar a API de detecção de fundamentação. Esse recurso detecta e corrige automaticamente textos sem fundamento com base nos documentos de origem fornecidos, garantindo que o conteúdo gerado esteja alinhado com referências factuais ou intencionais. Abaixo, exploramos vários cenários comuns para ajudar você a entender como e quando aplicar esses recursos para obter os melhores resultados.

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

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.

  1. substitua <endpoint> pela URL do ponto de extremidade associada ao recurso.

  2. Substitua <your_subscription_key> por uma das chaves para o recurso.

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

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

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-09-15-preview. Exemplo: <endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-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 ele for true, você precisará trazer seu próprio GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure para oferecer 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.

Conectar sua implantação de GPT

Dica

Só damos suporte a recursos **GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure** e não oferecemos suporte a outros tipos de GPT. Existe a flexibilidade de implantar os recursos GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure 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 de Conteúdo de IA do Azure.

Para usar o recurso GPT4o do OpenAI do Azure (0513, versão 0806) para habilitar o recurso de raciocínio, use a identidade gerenciada para permitir que o seu recurso de Segurança de Conteúdo acesse o recurso do OpenAI do Azure:

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

    Captura de tela de um recurso de identidade da Segurança de Conteúdo no portal do Azure.

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

    Captura de tela da adição da atribuição de função no portal do Azure.

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

    Captura de tela do portal do Azure com as funções Colaborador e Usuário exibidas em uma lista.

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:


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

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.

  1. Substitua <endpoint> pelo URL do ponto de extremidade associado ao recurso de Segurança de Conteúdo de IA do Azure.

  2. Substitua <your_subscription_key> por uma das chaves para o recurso.

  3. Substitua <your_OpenAI_endpoint> pelo URL do ponto de extremidade associado ao recurso do OpenAI do Azure.

  4. Substitua <your_deployment_name> pelo nome da implantação do OpenAI do Azure.

  5. 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-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. Abra um prompt de comando e execute o comando do cURL.

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 você quiser usar seu próprio recurso GPT4o do OpenAI do Azure (0513, versão 0806) 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ó damos suporte a recursos GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure 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

Verificar a fundamentação com o recurso de correção

A API de detecção de fundamentação possui um recurso de correção que ajusta automaticamente a ausência de fundamento detectada no texto, com base nas fontes de fundamentação fornecidas. Quando esse recurso está habilitado, a resposta inclui um campo "correction Text" que apresenta o texto corrigido de acordo com essas mesmas fontes.

Conectar sua implantação de GPT

Dica

Atualmente, o recurso de correção dá suporte apenas a recursos **GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure**. Para minimizar a latência e seguir as diretrizes de privacidade de dados, é recomendável implantar seus recursos GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure na mesma região que seus recursos de segurança de conteúdo. Para obter mais detalhes sobre a privacidade de dados, consulte as Diretrizes de dados, privacidade e segurança do Serviço OpenAI do Azure e Dados, privacidade e segurança da Segurança de Conteúdo de IA do Azure.

Para usar o recurso GPT4o do OpenAI do Azure (0513, versão 0806) para habilitar o recurso de correção, use a Identidade Gerenciada para permitir que o recurso de Segurança de Conteúdo acesse o recurso do OpenAI do Azure. Siga as etapas na seção anterior para configurar a Identidade Gerenciada.

Fazer a solicitação de API

Em sua solicitação para a API de detecção de fundamentação, defina o parâmetro do corpo "correction" como true e forneça os outros parâmetros necessários:

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

Essa seção demonstra uma solicitação de exemplo usando cURL. Substitua os espaços reservados conforme necessário:

  • Substitua <endpoint> pelo URL do ponto de extremidade do recurso.
  • Substitua <your_subscription_key> por sua chave de assinatura.
  • Opcionalmente, substitua o campo "texto" pelo texto que você quer analisar.
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>"
  }
}'

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
correção (Opcional) Definido como true, o serviço usa os recursos do OpenAI do Azure para fornecer o texto corrigido, garantindo consistência com as fontes de fundamentação. Tenha cuidado: o uso da correção aumenta o tempo de processamento e incorre em taxas extras. Booliano
llmResource (Obrigatório) Se você quiser usar seu próprio recurso GPT4o do OpenAI do Azure (0513, versão 0806) 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ó damos suporte a recursos GPT4o (versão 0513, 0806) do Serviço OpenAI do Azure 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

A resposta inclui um campo "correction Text" que contém o texto corrigido, garantindo consistência com as fontes de fundamentação fornecidas.

O recurso de correção detecta que o Kevin está infundado porque conflita com a fonte de fundamentação Jane. A API retorna o texto corrigido: "The patient name is Jane."

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

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

Nome Descrição Type
ungroundedDetected Indica se o conteúdo infundado foi detectado. Booliano
ungroundedPercentage A proporção de conteúdo infundado no texto. Float
ungroundedDetails Detalhes de conteúdo infundado, incluindo segmentos de texto 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
-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
-correction Text O texto corrigido, garantindo a consistência com as fontes fundamentadas. 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.

Conteúdo relacionado