Classificar e reclassificar documentos com a 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, é possível classificar um conjunto de documentos com base em uma consulta.

A API de classificação recebe uma lista de documentos e os classifica novamente com base na relevância deles para uma consulta. Em comparação com os embeddings, que consideram apenas a semelhança semântica de um documento e uma consulta, a API de classificação pode oferecer pontuações precisas sobre a capacidade de um documento responder a uma determinada consulta. A API de classificação pode ser usada para melhorar a qualidade dos resultados da pesquisa depois de recuperar um conjunto inicial de documentos candidatos.

A API de classificação não tem estado, então não é necessário indexar documentos antes de chamar a API. Basta transmitir a consulta e os documentos. Isso torna a API adequada para reclassificar documentos da pesquisa vetorial e de outras soluções de pesquisa.

Esta página descreve como usar a API de classificação para classificar um conjunto de documentos com base em uma consulta.

Casos de uso

O caso de uso principal da API de classificação é melhorar a qualidade dos resultados da pesquisa.

No entanto, a API de classificação pode ser valiosa para qualquer cenário em que você precise encontrar quais conteúdos são mais relevantes para a consulta de um usuário. Por exemplo, a API de classificação pode ajudar você a:

• Encontrar o conteúdo certo para fornecer a um LLM para fundamentação

• Melhorar a relevância de uma experiência de pesquisa

• Identificar seções relevantes de um documento

O fluxo a seguir descreve como usar a API de classificação para melhorar a qualidade dos resultados de documentos fragmentados:

1. Use a API Document AI Layout Parser para dividir um conjunto de documentos em blocos.

2. Use uma API de embedding para criar embeddings para cada um dos blocos.

3. Carregue os embeddings na Pesquisa de vetor ou em outra solução de pesquisa.

4. Consultar o índice de pesquisa e extrair os blocos mais relevantes.

5. Reclassifique os blocos relevantes usando a API de classificação.

Dados de entrada

Termo-chave: a API de classificação usa o termo record para indicar um documento. Um registro é composto por um ID, um título e o conteúdo de um documento. Ao contrário dos documentos contidos nos repositórios de dados da Vertex AI para Pesquisa, os registros inseridos na API de classificação estão no formato JSON e não foram indexados pela Vertex AI para Pesquisa.

A API de classificação exige as seguintes entradas:

• A consulta para a qual você está classificando os registros.

  Exemplo:

  "query": "Why is the sky blue?"
  

• Um conjunto de registros relevantes para a consulta. Os registros são fornecidos como uma matriz de objetos. Cada registro pode incluir um ID exclusivo, um título e o conteúdo do documento. Inclua um título, conteúdo ou ambos para cada registro. Se o comprimento do título e do conteúdo juntos exceder 512 tokens, o conteúdo adicional será truncado. É possível incluir até 200 registros por solicitação.

  Por exemplo, uma matriz de registros tem esta aparência. Na realidade, muitos registros seriam incluídos na matriz, e o conteúdo seria muito mais longo:

  "records": [
     {
         "id": "1",
         "title": "The Color of the Sky: A Poem",
         "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
     },
     {
         "id": "2",
         "title": "The Science of a Blue Sky",
         "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
     }
  ]
  

• Opcional: o número máximo de registros que você quer que a API de classificação retorne. Por padrão, todos os registros são retornados. No entanto, é possível usar o campo topN para retornar menos registros. Todos os registros são classificados, independentemente do valor definido.

  Por exemplo, isso retorna os 10 registros mais bem classificados:

  "topN": 10,
  

• Opcional: uma configuração que especifica se você quer apenas o ID do registro retornado pela API ou se você também quer o título e o conteúdo do registro. Por padrão, o registro completo é retornado. O principal motivo para definir isso é se você quiser reduzir o tamanho do payload de resposta.

  Por exemplo, definir como true retorna apenas o ID do registro, não o título ou o conteúdo:

  "ignoreRecordDetailsInResponse": true,
  

• Opcional: o nome do modelo. Isso especifica o modelo a ser usado para classificar os documentos. Se nenhum modelo for especificado, semantic-ranker-512@latest será usado, o que aponta automaticamente para o modelo mais recente disponível. Para apontar para um modelo específico, especifique um dos nomes de modelo listados em Modelos compatíveis, por exemplo, semantic-ranker-512-002.

  No exemplo abaixo, model é definido como semantic-ranker-512@latest. Isso significa que a API de classificação sempre vai usar o modelo mais recente disponível.

  "model": "semantic-ranker-512@latest"
  

Dados de saída

A API de classificação retorna uma lista classificada de registros com as seguintes saídas:

• Pontuação: um valor flutuante entre 0 e 1 que indica a relevância do registro.

• ID: o ID exclusivo do registro.

• Se solicitado, o objeto completo: o ID, o título e o conteúdo.

  Exemplo:

{
    "records": [
        {
            "id": "2",
            "score": 0.98,
            "title": "The Science of a Blue Sky",
            "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
        },
        {
            "id": "1",
            "score": 0.64,
            "title": "The Color of the Sky: A Poem",
            "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
        }
    ]
}

Classificar (ou reclassificar) um conjunto de registros de acordo com uma consulta

Normalmente, você fornece à API de classificação uma consulta e um conjunto de registros relevantes a essa consulta e que já foram classificados por algum outro método, como uma pesquisa de palavra-chave ou uma pesquisa vetorial. Em seguida, use a API de classificação para melhorar a qualidade da classificação e determinar uma pontuação que indique a relevância de cada registro para a consulta.

1. Receba a consulta e os registros resultantes. Verifique se cada registro tem um ID e um título, conteúdo ou ambos.

   O modelo aceita até 512 tokens por registro. Se o comprimento combinado do título e do conteúdo for maior que 512 tokens, o conteúdo extra será truncado.

2. Chame o método rankingConfigs.rank 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/rankingConfigs/default_ranking_config:rank" \
-d '{
"model": "semantic-ranker-512@latest",
"query": "QUERY",
"records": [
    {
        "id": "RECORD_ID_1",
        "title": "TITLE_1",
        "content": "CONTENT_1"
    },
    {
        "id": "RECORD_ID_2",
        "title": "TITLE_2",
        "content": "CONTENT_2"
    },
    {
        "id": "RECORD_ID_3",
        "title": "TITLE_3",
        "content": "CONTENT_3"
    }
]
}'

Substitua:

• PROJECT_ID: o ID do seu projeto do Google Cloud.
• QUERY: a consulta em que os registros são classificados e pontuados.
• RECORD_ID_n: uma string exclusiva que identifica o registro.
• TITLE_n: o título do registro.
• CONTENT_n: o conteúdo do registro.

Observação: para testar a API, digite seus próprios valores nesses marcadores de posição e cole o comando no Cloud Shell. No entanto, na realidade, a matriz records seria maior.

Para informações gerais sobre esse método, consulte rankingConfigs.rank.

Clique para conferir um exemplo de comando e resposta do curl.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/rankingConfigs/default_ranking_config:rank" \
    -d '{
        "model": "semantic-ranker-512@latest",
        "query": "what is Google gemini?",
        "records": [
            {
                "id": "1",
                "title": "Gemini",
                "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side."
            },
            {
                "id": "2",
                "title": "Gemini",
                "content": "Gemini is a cutting edge large language model created by Google."
            },
            {
                "id": "3",
                "title": "Gemini Constellation",
                "content": "Gemini is a constellation that can be seen in the night sky."
            }
        ]
    }'
    

{
    "records": [
        {
            "id": "2",
            "title": "Gemini",
            "content": "Gemini is a cutting edge large language model created by Google.",
            "score": 0.97
        },
        {
            "id": "3",
            "title": "Gemini Constellation",
            "content": "Gemini is a constellation that can be seen in the night sky.",
            "score": 0.18
        },
        {
            "id": "1",
            "title": "Gemini",
            "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side.",
            "score": 0.05
        }
    ]
}

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.RankServiceClient()

# The full resource name of the ranking config.
# Format: projects/{project_id}/locations/{location}/rankingConfigs/default_ranking_config
ranking_config = client.ranking_config_path(
    project=project_id,
    location="global",
    ranking_config="default_ranking_config",
)
request = discoveryengine.RankRequest(
    ranking_config=ranking_config,
    model="semantic-ranker-512@latest",
    top_n=10,
    query="What is Google Gemini?",
    records=[
        discoveryengine.RankingRecord(
            id="1",
            title="Gemini",
            content="The Gemini zodiac symbol often depicts two figures standing side-by-side.",
        ),
        discoveryengine.RankingRecord(
            id="2",
            title="Gemini",
            content="Gemini is a cutting edge large language model created by Google.",
        ),
        discoveryengine.RankingRecord(
            id="3",
            title="Gemini Constellation",
            content="Gemini is a constellation that can be seen in the night sky.",
        ),
    ],
)

response = client.rank(request=request)

# Handle the response
print(response)

Modelos compatíveis

Os seguintes modelos estão disponíveis.

Nome do modelo	Modelo mais recente (semantic-ranker-512@latest)	Entrada	Janela de contexto	Data de lançamento	Data de desativação
semantic-ranker-512-003	Sim	Texto (25 idiomas)	512	10 de setembro de 2024	A ser determinado
semantic-ranker-512-002	Não	Texto (somente em inglês)	512	3 de junho de 2024	A ser determinado

A seguir

Aprenda a usar o método de classificação com outras APIs de RAG para gerar respostas com embasamento a partir de dados não estruturados.