Verificar o embasamento com RAG

Como parte da sua experiência de Geração Aumentada de Recuperação (RAG) nos aplicativos de IA, você pode verificar a fundamentação para determinar o quanto um trecho de texto (chamado de candidato a resposta) está fundamentado em um determinado conjunto de textos de referência (chamados de fatos).

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

Para ser perfeita, toda declaração na resposta precisa ser apoiada por um ou mais dos fatos apresentados. Em outras palavras, a declaração é totalmente implicada pelos fatos. Se a proposição for apenas parcialmente implicada, ela não será considerada fundamentada. Por exemplo, a declaração "O Google foi fundado por Larry Page e Sergey Brin em 1975" está parcialmente correta. Os nomes dos fundadores estão certos, mas a data está errada. Portanto, toda a declaração é considerada sem fundamento. Nesta versão da API de embasamento de verificação, uma frase é considerada uma única declaração.

Você pode usar a API de verificação de embasamento para verificar qualquer trecho de texto. Pode ser um texto gerado por humanos ou uma resposta gerada automaticamente. Um caso de uso típico é verificar uma resposta gerada por LLM em relação a um determinado conjunto de fatos. A API check grounding foi projetada para ser rápida, com latência inferior a 500 ms. Essa velocidade permite que os chatbots chamem a API check grounding durante cada inferência, sem causar uma desaceleração significativa. A API também pode fornecer referências para apoiar as descobertas, assim os usuários podem saber 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ção, os chatbots podem filtrar respostas no momento da inferência que provavelmente contêm declarações alucinadas.

Esta página descreve como verificar o embasamento usando a API check grounding.

Recursos experimentais

Se quiser testar os seguintes recursos experimentais disponíveis para a API check grounding, entre em contato com sua equipe de conta do Google e peça para ser adicionado à lista de permissões:

• Anticitações:esse recurso oferece uma pontuação de contradição que indica o quanto a resposta contradiz os fatos apresentados. A resposta também inclui citações dos fatos contraditórios para cada declaração. Para mais informações, consulte Receber uma pontuação de contradição para um candidato a resposta.

• Pontuação de utilidade:é uma medida de como o candidato a resposta atende a uma determinada solicitação. Para mais informações, consulte Receber uma pontuação de utilidade para uma resposta candidata.

• Embasamento com um repositório de dados:use os fatos de embasamento de um repositório de dados da Vertex AI para Pesquisa em vez de fornecer fatos inline. Para mais informações, consulte Verificar o embasamento com um repositório de dados.

Termos definidos e explicados

Antes de usar a API check grounding, é útil entender as entradas e saídas e como estruturar os fatos de embasamento para ter os melhores resultados.

Dados de entrada

A API check grounding exige as seguintes entradas na solicitação.

• Candidato a resposta:pode ser qualquer trecho de texto cuja fundamentação você quer verificar. Por exemplo, no contexto da Vertex AI para Pesquisa, o candidato a resposta pode ser o resumo da pesquisa gerado que responde a uma consulta. Em seguida, a API determina o nível de embasamento do resumo nos fatos de entrada. Uma resposta candidata pode ter um comprimento máximo de 4.096 tokens, em que um token é definido como uma palavra em uma frase ou um período (um sinal de pontuação usado para terminar a frase). Por exemplo, a frase "Eles usaram roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto final.

• Fatos:um conjunto de segmentos de texto a serem usados como referências para embasamento. 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 não recomenda fornecer um fato muito grande que contenha todas as informações. Em vez disso, você pode ter resultados melhores dividindo fatos grandes em fatos menores e fornecendo atributos adequados para eles. Por exemplo, você pode dividir um fato grande por título, autor ou URL e fornecer essas informações em atributos.

• Limite de citação: um valor de ponto flutuante de 0 a 1 que controla a confiança para as citações que apoiam a resposta sugerida. Um limite mais alto impõe uma confiança mais rigorosa. Portanto, um limite mais alto gera menos citações, mas 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á embasada no conjunto de fatos fornecido. Ele aproxima vagamente a fração de declarações na resposta candidata que foram consideradas fundamentadas em um ou mais dos fatos fornecidos.

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

• Declarações e citações:as declarações e citações conectam uma declaração (normalmente uma frase) do candidato a resposta a um ou mais trechos citados que corroboram a declaração.

  Uma reivindicação é demarcada usando as posições de início e fim. Essas são as posições de byte da string de declaração codificada em UTF-8. Isso não é medido em caracteres e, portanto, precisa ser renderizado na interface do usuário, lembrando que alguns caracteres ocupam mais de um byte. Por exemplo, se o texto da declaração contiver caracteres não ASCII, as posições inicial e final vão variar quando medidas em caracteres (dependente da linguagem de programação) e em bytes (independente da linguagem de programação).

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

• Verificação de embasamento necessária: com cada declaração, um booleano "grounding-check-required" é retornado. Quando isso retorna como False, significa que o sistema considera que a declaração não exige embasamento e, portanto, citações e anticitaçõ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 embasamento.

  Quando o grounding-check-required retorna como true, significa que uma verificação de embasamento foi realizada e as pontuações de suporte, citações e anticitações, se houver, são retornadas.

Receber uma pontuação de suporte para um candidato a resposta

Para saber o quanto uma resposta candidata está fundamentada em um conjunto de fatos, siga estas etapas:

1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Termos definidos e explicados.

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

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

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 alguns exemplos de fatos e atributos. Esses exemplos ajudam você a entender a resposta de embasamento 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 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 respostas e respostas fundamentadas

A tabela a seguir mostra exemplos de diferentes candidatos a respostas e respostas ao enviar a solicitação de exemplo, com base nos fatos de exemplo.

Receber pontuações no nível da declaração para um candidato a resposta

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 acessar as pontuações no nível da declaração, siga estas etapas:

1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Termos definidos e explicados.

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/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",
     "enableClaimLevelScore": "ENABLE_CLAIM_LEVEL_SCORE",
   }
   }'
   

   Substitua:

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

   • CANDIDATE: a string de resposta candidata para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Uma resposta candidata pode ter um tamanho 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 terminar a frase). Por exemplo, a frase "Eles usaram roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto final.

   • TEXT: o segmento de texto a ser usado para embasamento. 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 declaração de que Government of Ontario claims that Toronto is the capital of Ontario não é tão bem fundamentada.

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

   • CITATION_THRESHOLD: um valor de ponto flutuante de 0 a 1 que determina se um fato precisa ser citado para uma declaração no candidato a resposta. Um limite mais alto leva a menos citações, mas mais fortes, para apoiar a declaração. Já um limite mais baixo leva a mais citações, mas mais fracas. Se não for definido, o valor 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 declaração. Para desativar esse recurso, remova o campo ou defina-o como false.

Exemplo de solicitação

Usando os fatos de exemplo da seção anterior, você pode enviar a seguinte solicitação. Substitua o campo CANDIDATE por diferentes strings cuja fundamentação por declaração 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",
      "enableClaimLevelScore": true,
    }
    }'

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

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

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. A pontuação de contradição aproxima a fração de declarações que contradizem os fatos fornecidos.

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

Receber uma pontuação de contradição

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

1. Prepare seu conjunto de fatos. Para mais informações e exemplos, consulte Termos definidos e explicados.

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

   • CANDIDATE: a string de resposta candidata para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Uma resposta candidata pode ter um tamanho 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 terminar a frase). Por exemplo, a frase "Eles usaram roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto final.

   • TEXT: o segmento de texto a ser usado para embasamento. 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 declaração de que Government of Ontario claims that Toronto is the capital of Ontario não é tão bem fundamentada.

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

   • CITATION_THRESHOLD: um valor de ponto flutuante de 0 a 1 que determina se um fato precisa ser citado para uma declaração no candidato a resposta. Um limite mais alto leva a menos citações, mas mais fortes, para apoiar a declaração, e um limite mais baixo leva a mais citações, mas mais fracas. Se não for definido, o valor 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 contradizendo uma declaração na resposta candidata. Um limite mais alto leva a menos citações, mas mais fortes, que contradizem a declaração, e um limite mais baixo leva a mais citações, mas mais fracas, que contradizem a declaração. Se não for definido, o valor de limite padrão será 0,8.

Exemplo de solicitação

Usando os fatos de exemplo da seção anterior, você pode enviar a seguinte solicitação. Substitua o campo CANDIDATE por diferentes strings que você quer verificar quanto a embasamento e contradições.

    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 candidato a resposta e a resposta quando você envia a solicitação de exemplo, com base nos fatos de exemplo.

Receber uma classificação de utilidade para um candidato a resposta

Para testar esse recurso experimental, entre em contato com a equipe da sua conta 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 embasamento da verificaçã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 forma informativa. A classificação de utilidade é uma medida de como a resposta faz o seguinte:

• Aborda o objetivo principal do comando
• Fornece detalhes completos de forma concisa
• Responde diretamente à pergunta feita ou conclui a tarefa solicitada no comando
• Oferece informações relevantes
• É clara e direta
• Evita detalhes e jargões desnecessários

Para receber uma pontuação de utilidade junto com a pontuação de embasamento, forneça um comando com as respostas candidatas e os fatos. A API de verificação de embasamento analisa a resposta candidata com o comando e atribui uma pontuação que indica o quanto a resposta candidata é útil para responder ao comando. A pontuação está no intervalo [0,1], em que quanto maior a pontuação, mais útil é a resposta.

Receber uma nota de utilidade

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

1. Prepare o comando e a resposta candidata.

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

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

   • TEXT: o segmento de texto a ser usado para embasamento. 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 declaração de que Government of Ontario claims that Toronto is the capital of Ontario não é tão bem fundamentada.

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

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

Exemplo de solicitação

Usando os fatos de exemplo da seção anterior, você pode enviar a seguinte solicitação. Substitua o campo CANDIDATE por diferentes opções de resposta para receber uma pontuação de utilidade.

    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 candidatos a respostas com pontuações de utilidade. Em cada caso, o comando é Who directed and starred in the Titanic?

Verificar o embasamento com um repositório de dados

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

Ao chamar a API de verificação de embasamento, 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 contêm o conjunto de fatos usados para verificar o embasamento da resposta sugerida.

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

Para verificar o embasamento em um repositório de dados, siga estas etapas:

1. Identifique um app de pesquisa personalizada associado a pelo menos um repositório de dados com dados não estruturados. Os documentos nesse repositório de dados servem como fonte para os fatos de embasamento.

   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 Google Cloud , acesse a página Aplicativos de IA.

      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": {
           "servingConfig": "projects/SOURCE_PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
         }
       }
   }'
   

   Substitua:

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

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

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

   • CANDIDATE: a string de resposta candidata para a qual você quer receber uma pontuação de suporte. Por exemplo, Titanic was directed by James Cameron. It was released in 1997.. Uma resposta candidata pode ter um tamanho 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 terminar a frase). Por exemplo, a frase "Eles usavam roupas prontas em 2024" tem sete tokens, incluindo seis palavras e um ponto final.

   • APP_ID: o ID do app de pesquisa da Vertex AI cujos repositórios de dados não estruturados contêm os fatos que você quer usar como fonte de embasamento.

   Exemplo de comando e resultado

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/groundingConfigs/default_grounding_config:check" \
   -d '{
       "answerCandidate": "Titanic was directed by James Cameron. It was released in 1997.",
       "groundingSource": {
         "searchSource": {
           "servingConfig": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search"
         }
       }
   }'
   
   {
   "supportScore": 0.9884292,
   "claims": [
   {
     "startPos": 0,
     "endPos": 63,
     "claimText": "Titanic was directed by James Cameron. It was released in 1997.",
     "citationIndices": [
       0,
       1
     ],
     "groundingCheckRequired": true
   }
   ],
   "citedFacts": [
   {
     "chunkText": "James Cameron\'s \"Titanic\" is more than just a movie; it\'s a cinematic experience.  Released in 1997, the film masterfully intertwines a fictional love story with the historical tragedy of the RMS Titanic. Leonardo DiCaprio and Kate Winslet deliver captivating performances as Jack and Rose, two young lovers from different worlds who find each other amidst the grandeur of the doomed ship.",
     "sourceInfo": {
       "searchSource": {
         "documentId": "projects/123456/locations/global/collections/default_collection/dataStores/my-app/branches/0/documents/movie_reviews.pdf",
         "documentTitle": "movie_reviews",
         "documentLink": "gs://my-bucket-123/pdf/movie_reviews.pdf"
       }
     }
   },
   {
     "chunkText": "James Cameron\'s epic romance and disaster film \"Titanic,\" released in 1997, captured the hearts of audiences worldwide.  The film tells the fictional love story of Jack and Rose, two young people from different social classes who meet aboard the ill-fated RMS Titanic.  Cameron\'s masterful storytelling, combined with groundbreaking visual effects, brought the historical tragedy to life on the big screen, resulting in a cinematic phenomenon that resonated with viewers of all ages.",
     "sourceInfo": {
       "searchSource": {
         "documentId": "projects/123456/locations/global/collections/default_collection/dataStores/my-app/branches/0/documents/popular_films",
         "documentTitle": "popular_films",
         "documentLink": "gs://my-bucket-123/pdf/popular_films.pdf"
       }
     }
   }
   ]
   }
   

   Os campos de saída são diferentes de quando a fonte de embasamento é fornecida como fatos em linha. Quando um repositório de dados é usado para embasamento, os fatos citados são identificados por ID do documento, título e link do repositório. Os fatos citados de um repositório não podem ser identificados por índice de fatos.