Melhorar a qualidade da pesquisa e da RAG com a API Ranking

Como parte da sua experiência de geração aumentada por recuperação (RAG) na Pesquisa de Agentes, é possível classificar um conjunto de documentos com base em uma consulta.

A API de classificação recebe uma lista de documentos e os reclassifica com base na relevância deles para uma consulta. Em comparação com os embeddings, que analisam apenas a semelhança semântica de um documento e uma consulta, a API de classificação pode fornecer pontuações precisas sobre o nível de resposta de um documento a uma determinada consulta. A API de classificação pode ser usada para melhorar a qualidade dos resultados da pesquisa após 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 chamá-la. 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.

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

Casos de uso

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

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

• Encontrar o conteúdo certo para fornecer a um LLM para embasamento

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

• 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 divididos em blocos:

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

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

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

4. Consultar o índice da Pesquisa e recuperar os blocos mais relevantes.

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

Dados de entrada

Termo-chave: a API de classificação usa o termo registro 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 Pesquisa de Agentes, os registros inseridos na API de classificação estão no formato JSON e não foram indexados pela Pesquisa de Agentes.

A API de classificação requer 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. Para cada registro, inclua um título, um conteúdo ou ambos. O número máximo de tokens aceitos por registro depende da versão do modelo usada. Por exemplo, modelos até a versão 003 aceitam 512 tokens, enquanto a versão 004 aceita 1.024 tokens. Se o comprimento combinado do título e do conteúdo exceder o limite de tokens do modelo, o conteúdo extra será dividido e processado em segmentos. Se um registro for considerado muito longo, parte do conteúdo será truncada e ignorada.

  É possível incluir até 1.000 registros por solicitação.

  Por exemplo, uma matriz de registros é mais ou menos assim. Na realidade, muitos outros 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 que apenas o ID do registro seja retornado pela API ou se quer que o título e o conteúdo do registro também sejam retornados. 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. Especifica o modelo a ser usado para classificar os documentos. Se nenhum modelo for especificado, semantic-ranker-default@latest será usado, 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-003.

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

  "model": "semantic-ranker-default@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 para essa consulta e que já foram classificados por algum outro método, como uma pesquisa de palavras-chave ou uma busca vetorial. Em seguida, use a API de classificação para melhorar a qualidade da classificação e determinar uma pontuação que indica a relevância de cada registro para a consulta.

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

   O número máximo de tokens aceitos por registro depende da versão do modelo. Modelos até a versão 003, como semantic-ranker-512-003, aceitam 512 tokens por registro. A partir da versão 004, esse limite aumenta para 1.024 tokens. Se o tamanho combinado do título e do conteúdo exceder o limite de tokens do modelo, o conteúdo extra será dividido e processado em segmentos. Em casos extremos, se um registro for considerado muito longo, parte do conteúdo será truncada e ignorada.

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-default@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 ver um exemplo de comando curl e resposta.

    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-default@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 Agent Search Python.

Para autenticar na Pesquisa de Agentes, 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-default@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)

Para conferir um exemplo da API Ranking, execute o notebook "Avaliação Beir da API Ranking" em um dos seguintes ambientes:

Abrir no Colab | Ver no GitHub

Modelos compatíveis

Os modelos a seguir estão disponíveis.

Nome do modelo	Modelo padrão mais recente (semantic-ranker-default@latest)	Modelo rápido mais recente (semantic-ranker-fast@latest)	Entrada	Janela de contexto	Data de lançamento	Data de desativação
semantic-ranker-default-005	Sim	Não	Texto (25 idiomas)	1024	1º de setembro de 2026	A ser determinado
semantic-ranker-fast-005	Não	Sim	Texto (25 idiomas)	1024	1º de setembro de 2026	A ser determinado
semantic-ranker-default-004	Não	Não	Texto (25 idiomas)	1024	9 de abril de 2025	A ser determinado
semantic-ranker-fast-004	Não	Não	Texto (25 idiomas)	1024	9 de abril de 2025	A ser determinado
semantic-ranker-default-003	Não	Não	Texto (25 idiomas)	512	10 de setembro de 2024	A ser determinado
semantic-ranker-default-002	Não	Não	Texto (somente em inglês)	512	3 de junho de 2024	A ser determinado

A seguir

Saiba como usar o método de classificação com outras APIs de RAG para gerar respostas fundamentadas com base em dados não estruturados.