Verificar o embasamento com RAG

Como parte da sua experiência de Geração Aumentada de Recuperação (RAG, na sigla em inglês) no Vertex AI Agent Builder, você pode verificar o embasamento para determinar o quanto um trecho de texto (chamado de candidato a resposta) está embasado em um determinado conjunto de textos de referência (chamados de fatos).

A API Check Grounding retorna uma pontuação de suporte geral de 0 a 1, que indica o quanto a resposta candidata concorda com os fatos fornecidos. A resposta também inclui citações dos fatos que comprovam cada afirmação na resposta candidata.

A fundamentação perfeita exige que cada declaração na resposta seja apoiada por um ou mais dos fatos fornecidos. Em outras palavras, a alegação é totalmente decorrente dos fatos. Se a reivindicação for apenas parcialmente envolvida, ela não será considerada fundamentada. Por exemplo, a afirmação "O Google foi fundado por Larry Page e Sergey Brin em 1975" está correta apenas parcialmente. Os nomes dos fundadores estão corretos, mas a data está errada. Por isso, a afirmação é considerada infundada. Nesta versão da API de verificação de fundamentação, uma sentença é considerada uma única declaração.

É possível usar a API check grounding para verificar qualquer parte do texto. Pode ser um texto de apresentação gerado por humanos ou uma resposta gerada por máquina. Um caso de uso típico é verificar uma resposta gerada por um LLM em relação a um determinado conjunto de fatos. A API de verificação de aterramento foi projetada para ser rápida, com latência inferior a 500ms. Essa velocidade permite que os bots de chat chamem a API de verificação de base durante cada inferência, sem incorrer em uma desaceleração significativa. A API de verificação de fundamentação também pode fornecer referências para apoiar as descobertas, para que os usuários possam dizer quais partes da resposta gerada são confiáveis. A API também fornece uma pontuação de suporte para indicar a precisão geral da resposta. Ao definir um limite de citações, os chatbots podem filtrar as respostas no momento da inferência que provavelmente contêm alegações falsas.

Esta página descreve como verificar a conexão à terra usando a API check grounding.

Recursos experimentais

Se você quiser testar os recursos experimentais abaixo que estão disponíveis para a API check grounding, entre em contato com a equipe de conta do Google e peça para ser adicionado à lista de permissões:

Termos definidos e explicados

Antes de usar a API check grounding, é importante entender as entradas e as saídas e como estruturar os fatos de fundamentação para obter os melhores resultados.

Dados de entrada

A API de verificação de aterramento exige as seguintes entradas na solicitação.

  • Candidato a resposta:pode ser qualquer parte do texto que você quer verificar. Por exemplo, no contexto da Vertex AI para Pesquisa, o candidato a resposta pode ser o resumo de pesquisa gerado que responde a uma consulta. A API determinaria a precisão do resumo nos fatos de entrada. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um ponto (um sinal de pontuação usado para encerrar a frase). Por exemplo, a frase "Eles usaram roupas de prateleira em 2024" tem sete tokens, incluindo seis palavras e um ponto.

  • Fatos:um conjunto de segmentos de texto usados como referências para a fundamentação. Um conjunto de atributos de metadados (pares de chave-valor) pode ser fornecido com cada segmento de texto. Por exemplo, "Autor" e "Título" são chaves de atributo típicas.

    O serviço aceita até 200 fatos, cada um com um máximo de 10 mil caracteres.

    O Google recomenda não fornecer um fato muito grande que contenha todas as informações. Em vez disso, você pode conseguir resultados melhores dividindo fatos grandes em fatos menores e fornecendo atributos adequados para os fatos menores. Por exemplo, é possível dividir um fato grande por título, autor ou URL e fornecer essas informações em atributos.

  • Limite de citação: um valor flutuante de 0 a 1 que controla a confiança das citações que apoiam a resposta candidata. Um limite mais alto impõe uma confiança mais rigorosa. Portanto, um limite mais alto gera menos, mas citações mais fortes.

Dados de saída

A API Check Grounding retorna o seguinte para um candidato a resposta:

  • Pontuação de suporte:é um número de 0 a 1 que indica o quanto uma resposta candidata está fundamentada no conjunto de fatos fornecido. Ele aproxima de forma aproximada a fração de reivindicações na resposta candidata que foram encontradas com base em um ou mais dos fatos fornecidos.

  • Trechos citados:são partes dos fatos de entrada que apoiam a resposta candidata.

  • Alegações e citações:as alegações e citações conectam uma alegação (geralmente uma frase) da resposta candidata a um ou mais dos fragmentos citados que comprovam a alegação.

    Quando a pontuação no nível da reivindicação está ativada, uma pontuação de suporte é retornada como um número de 0 a 1 que indica o quanto a reivindicação é fundamentada no conjunto de fatos fornecido. Para mais informações, consulte Receber pontuações no nível da reivindicação para um candidato a resposta.

  • Verificação de aterramento necessária: com cada declaração, um booleano "grounding-check-required" é retornado. Quando isso é retornado como False, significa que o sistema considera que a reivindicação não precisa de fundamentação e, portanto, as citações e as contracitações não são retornadas. Por exemplo, uma frase como "Aqui está o que encontrei" não é um fato por si só e, portanto, não requer uma verificação de informações empíricas.

    Quando a verificação de fundamentação obrigatória retorna como true, significa que uma verificação de fundamentação foi realizada e as pontuações de suporte, citações e contratações, se houver, são retornadas.

Receber uma pontuação de suporte para uma resposta candidata

Para descobrir se uma resposta é baseada em um conjunto de fatos, siga estas etapas:

  1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Definições e explicações dos termos.

  2. Chame o método check usando o seguinte código:

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
-d '{
  "answerCandidate": "CANDIDATE",
  "facts": [
  {
    "factText": "TEXT_0",
    "attributes": {"ATTRIBUTE_A": "VALUE_A0","ATTRIBUTE_B": "VALUE_B0"}
  },
  {
    "factText": "TEXT_1",
    "attributes": {"ATTRIBUTE_A": "VALUE_A1","ATTRIBUTE_B": "VALUE_B1"}
  },
  {
    "factText": "TEXT_2",
    "attributes": {"ATTRIBUTE_A": "VALUE_A2","ATTRIBUTE_B": "VALUE_B2"}
  }
  ],
  "groundingSpec": {
    "citationThreshold": "CITATION_THRESHOLD"
  }
}'

Substitua:

  • PROJECT_ID: o número ou ID do seu projeto do Google Cloud.

  • CANDIDATE: a string de candidato a resposta para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um ponto (um sinal de pontuação usado para encerrar a frase). Por exemplo, a frase "Eles usaram roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto.

  • TEXT: o segmento de texto a ser usado para fundamentação, por exemplo, Titanic is a 1997 American epic... Academy Awards.. Consulte o texto completo em Exemplos de fatos.

  • ATTRIBUTE: o nome de um atributo de metadados associado ao fato, por exemplo, author ou title. Esse é um rótulo definido pelo usuário para adicionar mais informações ao texto do fato. Por exemplo, se o texto do fato Toronto is the capital of Ontario tiver um atributo author com o valor Wikipedia, as seguintes declarações serão consideradas baseadas no fato:

    • Wikipedia cites that Toronto is the capital of Ontario

    • Toronto is the capital of Ontario

      No entanto, a afirmação de que Government of Ontario claims that Toronto is the capital of Ontario não é tão fundamentada quanto as duas primeiras.

  • VALUE: o valor do atributo, por exemplo, Simple Wikipedia ou Titanic (1997 film).

  • CITATION_THRESHOLD: um valor flutuante de 0 a 1 que determina se um fato precisa ser citado para uma declaração na resposta indicada. Um limite maior leva a menos citações, mas fortes, e um limite menor leva a mais citações, mas fracas. Se não for definido, o valor de limite padrão será 0.6.

Python

Para mais informações, consulte a documentação de referência da API Python do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"

client = discoveryengine.GroundedGenerationServiceClient()

# The full resource name of the grounding config.
# Format: projects/{project_id}/locations/{location}/groundingConfigs/default_grounding_config
grounding_config = client.grounding_config_path(
    project=project_id,
    location="global",
    grounding_config="default_grounding_config",
)

request = discoveryengine.CheckGroundingRequest(
    grounding_config=grounding_config,
    answer_candidate="Titanic was directed by James Cameron. It was released in 1997.",
    facts=[
        discoveryengine.GroundingFact(
            fact_text=(
                "Titanic is a 1997 American epic romantic disaster movie. It was directed, written,"
                " and co-produced by James Cameron. The movie is about the 1912 sinking of the"
                " RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released"
                " on December 19, 1997. It received positive critical reviews. The movie won 11 Academy"
                " Awards, and was nominated for fourteen total Academy Awards."
            ),
            attributes={"author": "Simple Wikipedia"},
        ),
        discoveryengine.GroundingFact(
            fact_text=(
                'James Cameron\'s "Titanic" is an epic, action-packed romance'
                "set against the ill-fated maiden voyage of the R.M.S. Titanic;"
                "the pride and joy of the White Star Line and, at the time,"
                "the largest moving object ever built. "
                'She was the most luxurious liner of her era -- the "ship of dreams" -- '
                "which ultimately carried over 1,500 people to their death in the "
                "ice cold waters of the North Atlantic in the early hours of April 15, 1912."
            ),
            attributes={"author": "Simple Wikipedia"},
        ),
    ],
    grounding_spec=discoveryengine.CheckGroundingSpec(citation_threshold=0.6),
)

response = client.check_grounding(request=request)

# Handle the response
print(response)

Exemplos de fatos

Confira a seguir alguns exemplos de fatos e atributos. Esses exemplos ajudam você a entender a resposta de aterramento e o formato do comando curl.

  • Fato 0

    • Texto: "Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. The movie is about the 1912 sinking of the RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards."

    • Atributos: {"Author": "Simple Wikipedia"}

  • Fato 1

    • Texto: "James Cameron's "Titanic" is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era -- the "ship of dreams" -- which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912."

    • Atributos: {"Author": "Rotten Tomatoes"}

Exemplo de solicitação

Depois de preparar os fatos, envie a solicitação a seguir, substituindo o campo CANDIDATE por diferentes strings com a base que você quer verificar.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
    -d '{
    "answerCandidate": "CANDIDATE",
    "facts": [
     {
      "factText": "Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. The movie is about the 1912 sinking of the RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.",
      "attributes": {"author":"Simple Wikipedia"}
     },
     {
      "factText": "James Cameron's \"Titanic\" is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era -- the \"ship of dreams\" -- which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912.",
      "attributes": {"author":"Simple Wikipedia"}
     }
    ],
    "groundingSpec": {
      "citationThreshold": "0.6"
    }
    }'

Exemplos de candidatos a resposta e respostas de fundamentação

A tabela a seguir mostra exemplos de diferentes candidatos a resposta e respostas quando você envia a solicitação de exemplo, com base nos exemplos de fatos.

Candidato a resposta Verificar a resposta de aterramento
Here is what I found. Titanic was directed by James Cameron. Pontuação de suporte: 0.99

Fragmentos citados:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
Afirmações e citações:
  • 0. Here is what I found.
    Verificação de aterramento necessária: false
  • 1. Titanic was directed by James Cameron.
    Citações: [0]
    Verificação de aterramento necessária: true
Titanic was directed by James Cameron. It was released in 1997. Pontuação de suporte: 0.99

Fragmentos citados:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
  2. [From FACT 1]...Titanic is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912....
Afirmações e citações:
  • 0. Titanic was directed by James Cameron.
    Citações: [0]
    Verificação de aterramento necessária: true
  • 1. It was released in 1997.
    Citações: [1]
    Verificação de aterramento necessária: true
Titanic was directed by James Cameron. It was based on the sinking of the RMS Titanic that led to the death of 1500 people. Pontuação de suporte: 0.95

Fragmentos citados:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
  2. [From FACT 1]...Titanic is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912....
Afirmações e citações:
  • 0. Cited chunks: Titanic was directed by James Cameron.
    Citações: [0]
    Verificação de aterramento necessária: true
  • 1. Cited chunks: It was based on the sinking of the RMS Titanic that led to the death of 1500 people.
    Citações: [1]
    Verificação de aterramento necessária: true
Titanic was directed by James Cameron. It starred Brad Pitt and Kate Winslet Pontuação de suporte: 0.54

Fragmentos citados:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
  2. [From FACT 1]...Titanic is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912....
Afirmações e citações:
  • 0. Titanic was directed by James Cameron.
    Citações: [0]
    Verificação de aterramento necessária: true
  • 1. It starred Brad Pitt and Kate Winslet
    Citações: []
    Verificação de aterramento necessária: true
Observação:embora Kate Winslet tenha estrelado o filme, como a alegação "It starred Brad Pitt and Kate Winslet" não é totalmente verdadeira, ela não recebe citações. Nesse caso, é possível chamar o método com as citações anti-spam ativadas para receber uma pontuação de contradição. Para mais informações, consulte Obter uma pontuação de contradição para uma resposta candidata.

Receber uma pontuação de contradição para uma resposta candidata

Além da pontuação de suporte, você também pode receber uma pontuação de contradição. O índice de contradição aproxima-se da fração de alegações que contradizem os fatos fornecidos.

Para testar esse recurso experimental, entre em contato com a Equipe de Contas do Google e peça para ser adicionado à lista de permissões.

Conferir uma pontuação de contradição

Para conferir a pontuação de contradição, siga estas etapas:

  1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Definições e explicações dos termos.

  2. Chame o método check usando o seguinte comando curl:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
-d '{
"answerCandidate": "CANDIDATE",
"facts": [
 {
  "factText": "TEXT_0",
  "attributes": {"ATTRIBUTE_A": "VALUE_A0","ATTRIBUTE_B": "VALUE_B0"}
 },
 {
  "factText": "TEXT_1",
  "attributes": {"ATTRIBUTE_A": "VALUE_A1","ATTRIBUTE_B": "VALUE_B1"}
 },
 {
  "factText": "TEXT_2",
  "attributes": {"ATTRIBUTE_A": "VALUE_A2","ATTRIBUTE_B": "VALUE_B2"}
 },
],
"groundingSpec": {
  "citationThreshold": "CITATION_THRESHOLD",
  "enableAntiCitations": "ENABLE_ANTI_CITATION",
  "antiCitationThreshold": "ANTI_CITATION_THRESHOLD",
}
}'

    Substitua:

    • PROJECT_ID: o número ou ID do projeto do Google Cloud.

    • CANDIDATE: a string de candidato a resposta para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um ponto (um sinal de pontuação usado para encerrar a frase). Por exemplo, a frase "Eles usavam roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto.

    • TEXT: o segmento de texto a ser usado para aterramento, por exemplo, Titanic is a 1997 American epic... Academy Awards.. Consulte o texto completo em Exemplos de fatos.

    • ATTRIBUTE: o nome de um atributo de metadados associado ao fato, por exemplo, author ou title. É um rótulo definido pelo usuário para adicionar mais informações ao texto do fato. Por exemplo, se o texto do fato Toronto is the capital of Ontario tiver um atributo author com o valor Wikipedia, as seguintes declarações serão bem fundamentadas:

      • Wikipedia cites that Toronto is the capital of Ontario
      • Toronto is the capital of Ontario

      No entanto, a afirmação de que Government of Ontario claims that Toronto is the capital of Ontario não é tão fundamentada.

    • VALUE: o valor do atributo, por exemplo, Simple Wikipedia ou Titanic (1997 film).

    • CITATION_THRESHOLD: um valor flutuante de 0 a 1 que determina se um fato precisa ser citado para uma declaração na resposta indicada. Um limite maior leva a menos citações, mas fortes, para apoiar a alegação, e um limite mais baixo leva a mais citações, mas fracas, para apoiar a alegação. Se não for definido, o valor de limite padrão será 0,6.

    • ENABLE_ANTI_CITATION: um valor booleano Defina esse campo como true para ativar o recurso experimental e avaliar a pontuação de contradição. Remova esse campo ou defina-o como false para desativar esse recurso.

    • ANTI_CITATION_THRESHOLD: um valor flutuante de 0 a 1 que determina se um fato precisa ser citado como uma contradição de uma afirmação na resposta. Um limite maior leva a menos, mas mais fortes citações que contradizem a alegação, e um limite mais baixo leva a mais, mas mais fracos citações que contradizem a alegação. Se não for definido, o valor de limite padrão será 0,8.

Exemplo de solicitação

Usando os exemplos de fatos da seção anterior, é possível enviar a solicitação a seguir. Substitua o campo CANDIDATE por diferentes strings com fundamentos e contradições que você quer verificar.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
    -d '{
    "answerCandidate": "CANDIDATE",
    "facts": [
     {
      "factText": "Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. The movie is about the 1912 sinking of the RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.",
      "attributes": {"author":"Simple Wikipedia"}
     },
     {
      "factText": "James Cameron's \"Titanic\" is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era -- the \"ship of dreams\" -- which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912.",
      "attributes": {"author":"Simple Wikipedia"}
     }
    ],
    "groundingSpec": {
      "citationThreshold": "0.6",
      "enableAntiCitations": true,
      "antiCitationThreshold": "0.8",
    }
    }'

Exemplo de respostas com contradições

A tabela a seguir mostra um exemplo de resposta e a resposta quando você envia a solicitação de exemplo, com base nos exemplos de fatos.

Candidato a resposta Verificar a resposta de aterramento
Titanic was directed by James Cameron. It starred Brad Pitt and Kate Winslet Pontuação de suporte: 0.36

Pontuação de contradição: 0.49

Peças citadas:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
  2. [From FACT 1]...Titanic is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912....
Afirmações e citações:
  • 0. Titanic was directed by James Cameron.
    Citações: [0] Citações contrárias: []
    Verificação de embasamento necessária: true
  • 1. It starred Brad Pitt and Kate Winslet
    Citações: [] Citações contrárias: [0]
    Verificação de embasamento necessária: true

Receber uma pontuação de utilidade para uma resposta candidata

Para testar esse recurso experimental, entre em contato com a Equipe de Contas do Google e peça para ser adicionado à lista de permissões.

Além da pontuação de suporte e de contradição, a API de verificação de fundamentação pode fornecer uma pontuação de utilidade. Uma resposta útil é aquela que atende de maneira eficaz à solicitação do usuário (conforme declarado no comando) de uma forma informativa. A pontuação de utilidade é uma medida de como a resposta atende aos seguintes requisitos:

  • Aborda a intenção principal da instrução
  • Fornece detalhes completos e concisos
  • Responde diretamente à pergunta ou conclui a tarefa solicitada no comando
  • Oferece informações relevantes
  • É claro e direto
  • Evita detalhes desnecessários e jargões

Para receber uma pontuação de utilidade com a pontuação de fundamentação, você precisa fornecer um comando com os candidatos à resposta e os fatos. A API de verificação de fundamentação analisou a resposta candidata com o comando e deu uma pontuação que indica o quanto a resposta candidata foi útil. A pontuação está no intervalo de [0,1], em que quanto maior a pontuação, mais útil é a resposta.

Receber uma nota de utilidade

Para receber a pontuação de utilidade, siga estas etapas:

  1. Prepare sua resposta e o candidato.

  2. Chame o método check usando o seguinte comando curl:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
-d '{
"answerCandidate": "CANDIDATE",
"facts": [
{
  "factText": "TEXT_0",
  "attributes": {"ATTRIBUTE_A": "VALUE_A0","ATTRIBUTE_B": "VALUE_B0"}
},
{
  "factText": "TEXT_1",
  "attributes": {"ATTRIBUTE_A": "VALUE_A1","ATTRIBUTE_B": "VALUE_B1"}
},
{
  "factText": "TEXT_2",
  "attributes": {"ATTRIBUTE_A": "VALUE_A2","ATTRIBUTE_B": "VALUE_B2"}
}
],
"groundingSpec": {
  "enableHelpfulnessScore": true
},
"prompt": "PROMPT",
}'

    Substitua:

    • PROJECT_ID: o número ou ID do projeto do Google Cloud.

    • CANDIDATE: a string de candidato a resposta para a qual você quer receber uma pontuação de utilidade. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens.

    • TEXT: o segmento de texto a ser usado para aterramento, por exemplo, Titanic is a 1997 American epic... Academy Awards.. Consulte o texto completo em Exemplos de fatos.

    • ATTRIBUTE: o nome de um atributo de metadados associado ao fato, por exemplo, author ou title. É um rótulo definido pelo usuário para adicionar mais informações ao texto do fato. Por exemplo, se o texto do fato Toronto is the capital of Ontario tiver um atributo author com o valor Wikipedia, as seguintes declarações serão bem fundamentadas:

      • Wikipedia cites that Toronto is the capital of Ontario
      • Toronto is the capital of Ontario

      No entanto, a afirmação de que Government of Ontario claims that Toronto is the capital of Ontario não é tão fundamentada.

    • VALUE: o valor do atributo, por exemplo, Simple Wikipedia ou Titanic (1997 film).

    • PROMPT: o comando é a consulta para a qual a resposta foi gerada, por exemplo, Who directed and starred in the movie Titanic?.

Exemplo de solicitação

Usando os exemplos de fatos da seção anterior, é possível enviar a solicitação a seguir. Substitua o campo CANDIDATE por diferentes candidatos a resposta para receber uma pontuação de utilidade para a resposta.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
    -d '{
    "answerCandidate": "CANDIDATE",
    "facts": [
     {
      "factText": "Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. The movie is about the 1912 sinking of the RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.",
      "attributes": {"author":"Simple Wikipedia"}
     },
     {
      "factText": "James Cameron's \"Titanic\" is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era -- the \"ship of dreams\" -- which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912.",
      "attributes": {"author":"Simple Wikipedia"}
     }
    ],
    "groundingSpec": {
      "enableHelpfulnessScore": true
    },
    "prompt": "Who directed and starred in the movie Titanic?"
    }'

Exemplo de respostas com pontuações de utilidade

A tabela a seguir mostra exemplos de respostas candidatas com as notas de utilidade. Em cada caso, o comando é Who directed and starred in the Titanic?

Candidato a resposta Pontuação de utilidade Explicação sobre a pontuação
Titanic was directed by James Cameron. It starred Leonardo DiCaprio and Kate Winslet. 0.980 Pontuação concisa e completa
Cameron, DiCaprio and Winslet. 0.947 Incompleta
James Cameron's 1997 masterpiece, Titanic, captured the hearts of audiences worldwide with its tragic love story set against the backdrop of the ill-fated maiden voyage of the "unsinkable" ship. The film, a mesmerizing blend of historical drama and fictional romance, starred Leonardo DiCaprio as Jack Dawson, a penniless artist who falls for Rose DeWitt Bukater, a young woman trapped by her social standing and played exquisitely by Kate Winslet. Their passionate love affair unfolds amidst the grandeur and opulence of the Titanic, a floating palace of dreams that ultimately succumbs to a devastating fate. 0.738 Não é conciso

Receber pontuações no nível da reivindicação para uma resposta candidata

Além da pontuação de suporte no nível da resposta, você pode receber uma pontuação de suporte no nível da declaração para cada declaração em uma resposta candidata.

Para testar esse recurso experimental, entre em contato com a Equipe de Contas do Google e peça para ser adicionado à lista de permissões.

Para conferir as pontuações no nível da reivindicação, siga estas etapas:

  1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Definições e explicações dos termos.

  2. Chame o método check usando o seguinte comando curl:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
-d '{
"answerCandidate": "CANDIDATE",
"facts": [
 {
  "factText": "TEXT_0",
  "attributes": {"ATTRIBUTE_A": "VALUE_A0","ATTRIBUTE_B": "VALUE_B0"}
 },
 {
  "factText": "TEXT_1",
  "attributes": {"ATTRIBUTE_A": "VALUE_A1","ATTRIBUTE_B": "VALUE_B1"}
 },
 {
  "factText": "TEXT_2",
  "attributes": {"ATTRIBUTE_A": "VALUE_A2","ATTRIBUTE_B": "VALUE_B2"}
 },
],
"groundingSpec": {
  "citationThreshold": "CITATION_THRESHOLD",
  "enableClaimLevelScore": "ENABLE_CLAIM_LEVEL_SCORE",
}
}'

    Substitua:

    • PROJECT_ID: o número ou ID do projeto do Google Cloud.

    • CANDIDATE: a string de candidato a resposta para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um ponto (um sinal de pontuação usado para encerrar a frase). Por exemplo, a frase "Eles usaram roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto.

    • TEXT: o segmento de texto a ser usado para aterramento, por exemplo, Titanic is a 1997 American epic... Academy Awards.. Consulte o texto completo em Exemplos de fatos.

    • ATTRIBUTE: o nome de um atributo de metadados associado ao fato, por exemplo, author ou title. É um rótulo definido pelo usuário para adicionar mais informações ao texto do fato. Por exemplo, se o texto do fato Toronto is the capital of Ontario tiver um atributo author com o valor Wikipedia, as seguintes declarações serão bem fundamentadas:

      • Wikipedia cites that Toronto is the capital of Ontario
      • Toronto is the capital of Ontario

      No entanto, a afirmação de que Government of Ontario claims that Toronto is the capital of Ontario não é tão fundamentada.

    • VALUE: o valor do atributo, por exemplo, Simple Wikipedia ou Titanic (1997 film).

    • CITATION_THRESHOLD: um valor flutuante de 0 a 1 que determina se um fato precisa ser citado para uma declaração na resposta indicada. Um limite maior leva a menos citações, mas fortes, para apoiar a alegação, e um limite mais baixo leva a mais citações, mas fracas, para apoiar a alegação. Se não for definido, o valor de limite padrão será 0,6.

    • ENABLE_CLAIM_LEVEL_SCORE: um valor booleano Defina este campo como true para ativar o recurso de pontuação no nível da reivindicação. Para desativar esse recurso, remova esse campo ou defina-o como false.

Exemplo de solicitação

Usando os exemplos de fatos da seção anterior, é possível enviar a solicitação a seguir. Substitua o campo CANDIDATE por diferentes strings com a fundamentação de cada reivindicação que você quer verificar.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
    -d '{
    "answerCandidate": "CANDIDATE",
    "facts": [
     {
      "factText": "Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. The movie is about the 1912 sinking of the RMS Titanic. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.",
      "attributes": {"author":"Simple Wikipedia"}
     },
     {
      "factText": "James Cameron's \"Titanic\" is an epic, action-packed romance set against the ill-fated maiden voyage of the R.M.S. Titanic; the pride and joy of the White Star Line and, at the time, the largest moving object ever built. She was the most luxurious liner of her era -- the \"ship of dreams\" -- which ultimately carried over 1,500 people to their death in the ice cold waters of the North Atlantic in the early hours of April 15, 1912.",
      "attributes": {"author":"Simple Wikipedia"}
     }
    ],
    "groundingSpec": {
      "citationThreshold": "0.6",
      "enableClaimLevelScore": true,
    }
    }'

Exemplo de respostas com pontuações no nível da reivindicação

A tabela a seguir mostra um exemplo de resposta e a resposta quando você envia a solicitação de exemplo, com base nos exemplos de fatos.

Candidato a resposta Verificar a resposta de aterramento
Here is what I found. Titanic was directed by James Cameron. It starred Kate Winslet and Leonardo DiCaprio. Pontuação de suporte: 0.99

Fragmentos citados:
  1. [From FACT 0]....Titanic is a 1997 American epic romantic disaster movie. It was directed, written, and co-produced by James Cameron. It stars Kate Winslet and Leonardo DiCaprio. The movie was released on December 19, 1997. It received positive critical reviews. The movie won 11 Academy Awards, and was nominated for fourteen total Academy Awards.....
Afirmações e citações:
  • 0. Here is what I found.
    Verificação de aterramento necessária: false
  • 1. Titanic was directed by James Cameron.
    Citações: [0]
    Verificação de embasamento necessária: true
    Pontuação: 0.99
  • 2. It starred Kate Winslet and Leonardo DiCaprio.
    Citações: [0]
    Verificação de embasamento necessária: true
    Pontuação: 0.99

Verificar a conexão com um repositório de dados

Por padrão, a conexão à terra é verificada em relação a um conjunto de fatos fornecidos inline na chamada de API de verificação de conexão à terra. No entanto, como alternativa para fornecer os fatos inline, você pode verificar a resposta em potencial com todos os fatos em um repositório de dados da Vertex AI para Pesquisa.

Ao chamar a API check grounding, você fornece o nome de um app de pesquisa da Vertex AI. Por sua vez, os repositórios de dados não estruturados associados a esse app de pesquisa têm o conjunto de fatos que são usados para verificar o embasamento da resposta indicada.

Para verificar a conexão com um repositório de dados, siga estas etapas:

  1. Identifique um app de pesquisa genérico associado a pelo menos um repositório de dados que contenha dados não estruturados. Os documentos nesse repositório de dados servem como fonte de fatos de fundamentação.

    Para saber como criar um repositório de dados e um app de pesquisa, consulte Criar um repositório de dados de pesquisa e Criar um app de pesquisa.

  2. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

    1. No Console do Google Cloud, acesse a página Criador de agentes.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

  3. Chame o método check usando o seguinte comando curl:

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/groundingConfigs/default_grounding_config:check" \
-d '{
    "answerCandidate": "CANDIDATE",
    "groundingSource": {
      "searchSource": "projects/SOURCE_PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
    }
}'

    Substitua:

    • PROJECT_ID: o número ou ID do projeto do Google Cloud.

    • SOURCE_PROJECT_ID: o número ou o ID do projeto que contém o app para aterramento.

      Esse projeto de origem precisa estar na mesma região que seu projeto, por exemplo, global ou eu. Para informações gerais sobre multirregiões, consulte Localização.

    • CANDIDATE: a string de candidato a resposta para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Um candidato a resposta pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um ponto (um sinal de pontuação usado para encerrar a frase). Por exemplo, a frase "Eles usaram roupas de prateleira em 2024" tem sete tokens, incluindo seis palavras e um ponto.

    • APP_ID: o ID do app de pesquisa da Vertex AI que armazena dados não estruturados com os fatos que você quer usar como fonte de embasamento.