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

Como parte da sua experiência de Geração Aumentada de Recuperação (RAG) na Pesquisa de agente, você pode classificar um conjunto de documentos com base em uma consulta.

A API Ranking 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 analisam apenas a similaridade semântica de um documento e uma consulta, a API Ranking pode fornecer pontuações precisas sobre a qualidade da resposta de um documento a uma consulta específica. A API Ranking pode ser usada para melhorar a qualidade dos resultados da pesquisa após a recuperação de um conjunto inicial de documentos candidatos.

A API Ranking 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 de vetor e outras soluções de pesquisa.

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

Casos de uso

O principal caso de uso da API Ranking é melhorar a qualidade dos resultados da pesquisa.

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

  • 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 Ranking para melhorar a qualidade dos resultados de documentos 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 de vetor ou em outra solução de pesquisa.

  4. Consulte o índice de pesquisa e recupere os blocos mais relevantes.

  5. Reclassifique os blocos relevantes usando a API Ranking.

Dados de entrada

A API Ranking 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, conteúdo ou ambos. O número máximo de tokens com suporte por registro depende da versão do modelo que está sendo usada. Por exemplo, os modelos até a versão 003 oferecem suporte a 512 tokens, enquanto a versão 004 oferece suporte a 1024 tokens. Se o comprimento combinado do título e do conteúdo exceder o limite de tokens do modelo, o conteúdo extra será truncado. É possível incluir até 200 registros por solicitação.

    Por exemplo, uma matriz de registros é semelhante a esta. 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 Ranking 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 principais registros classificados:

    "topN": 10,

  • Opcional: uma configuração que especifica se você quer apenas o ID do registro retornado pela API ou se 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 é 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-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 Ranking sempre usará o modelo mais recente disponível.

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

Dados de saída

A API Ranking 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 Ranking uma consulta e um conjunto de registros relevantes para essa consulta e que já foram classificados por algum outro método, como uma pesquisa por palavras-chave ou uma pesquisa de vetor. Em seguida, use a API Ranking 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 número máximo de tokens com suporte por registro depende da versão do modelo. Os modelos até a versão 003, como semantic-ranker-512-003, oferecem suporte a 512 tokens por registro. A partir da versão 004, esse limite aumenta para 1024 tokens. Se o comprimento combinado do título e do conteúdo exceder o limite de tokens do modelo, o conteúdo extra será truncado.

  2. Chame o método rankingConfigs.rank usando o código a seguir:

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 Google Cloud projeto.
  • QUERY: a consulta em relação à qual 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.

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

Clique para ver 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-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 Pesquisa de agente Python.

Para autenticar na Pesquisa de agente, configure o Application Default Credentials. Se quiser 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)

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-004 Sim Não Texto (25 idiomas) 1024 9 de abril de 2025 A ser determinado
semantic-ranker-fast-004 Não Sim 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

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