Such- und RAG-Qualität mit Ranking API verbessern

Im Rahmen von Retrieval Augmented Generation (RAG) in der Agent Search können Sie eine Reihe von Dokumenten basierend auf einer Abfrage einstufen.

Die Ranking API nimmt eine Liste von Dokumenten entgegen und stuft sie neu ein, je nachdem, wie relevant sie für eine Abfrage sind. Im Gegensatz zu Einbettungen, bei denen nur die semantische Ähnlichkeit zwischen einem Dokument und einer Abfrage betrachtet wird, kann die Ranking API Ihnen genaue Werte dafür liefern, wie gut ein Dokument eine bestimmte Abfrage beantwortet. Die Ranking API kann verwendet werden, um die Qualität der Suchergebnisse zu verbessern, nachdem eine erste Gruppe von Kandidatendokumenten abgerufen wurde.

Die Ranking API ist zustandslos. Daher müssen Sie Dokumente nicht indexieren, bevor Sie die API aufrufen. Sie müssen nur die Abfrage und die Dokumente übergeben. Dadurch eignet sich die API gut für die erneute Einstufung von Dokumenten aus der Vektorsuche und anderen Suchlösungen.

Auf dieser Seite wird beschrieben, wie Sie die Ranking API verwenden, um eine Reihe von Dokumenten basierend auf einer Abfrage einzustufen.

Anwendungsfälle

Der primäre Anwendungsfall der Ranking API ist die Verbesserung der Qualität von Suchergebnissen.

Die Ranking API kann jedoch in jedem Szenario nützlich sein, in dem Sie herausfinden müssen, welche Inhalte für die Abfrage eines Nutzers am relevantesten sind. Die Ranking API kann Ihnen beispielsweise bei Folgendem helfen:

  • Die richtigen Inhalte für die Fundierung eines LLM finden

  • Die Relevanz einer vorhandenen Suchfunktion verbessern

  • Relevante Abschnitte eines Dokuments identifizieren

Der folgende Ablauf beschreibt, wie Sie die Ranking API verwenden können, um die Qualität der Ergebnisse für in Blöcke unterteilte Dokumente zu verbessern:

  1. Verwenden Sie die Document AI Layout Parser API, um eine Reihe von Dokumenten in Blöcke aufzuteilen.

  2. Verwenden Sie eine Einbettungs-API, um Einbettungen für jeden Block zu erstellen.

  3. Laden Sie die Einbettungen in die Vektorsuche oder eine andere Suchlösung.

  4. Fragen Sie Ihren Suchindex ab und rufen Sie die relevantesten Blöcke ab.

  5. Stufen Sie die relevanten Blöcke mit der Ranking API neu ein.

Eingabedaten

Für die Ranking API sind die folgenden Eingaben erforderlich:

  • Die Abfrage, für die Sie die Einträge einstufen.

    Beispiel:

    "query": "Why is the sky blue?"
    
  • Eine Reihe von Einträgen, die für die Abfrage relevant sind. Die Einträge werden als Array von Objekten bereitgestellt. Jeder Eintrag kann eine eindeutige ID, einen Titel und den Inhalt des Dokuments enthalten. Geben Sie für jeden Eintrag entweder einen Titel, Inhalt oder beides an. Die maximal unterstützten Tokens pro Eintrag hängen von der Modellversion ab, die verwendet wird. Modelle bis Version 003 unterstützen beispielsweise 512 Tokens, während Version 004 1.024 Tokens unterstützt. Wenn die kombinierte Länge von Titel und Inhalt das Tokenlimit des Modells überschreitet, wird der zusätzliche Inhalt abgeschnitten. Sie können bis zu 200 Einträge pro Anfrage einfügen.

    Ein Eintrag-Array sieht beispielsweise so aus. In der Realität wären viel mehr Einträge im Array enthalten und der Inhalt wäre viel länger:

    "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."
       }
    ]
    
  • Optional: Die maximale Anzahl von Einträgen, die von der Ranking API zurückgegeben werden sollen. Standardmäßig werden alle Einträge zurückgegeben. Sie können jedoch das Feld topN verwenden, um weniger Einträge zurückzugeben. Alle Einträge werden unabhängig vom festgelegten Wert eingestuft.

    Dadurch werden beispielsweise die 10 am besten eingestuften Einträge zurückgegeben:

    "topN": 10,
    
  • Optional: Eine Einstellung, die angibt, ob nur die ID des von der API zurückgegebenen Eintrags oder auch der Titel und Inhalt des Eintrags zurückgegeben werden sollen. Standardmäßig wird der vollständige Eintrag zurückgegeben. Der Hauptgrund für diese Einstellung ist, die Größe der Antwortnutzlast zu reduzieren.

    Wenn Sie beispielsweise auf true setzen, wird nur die Eintrag-ID zurückgegeben, nicht der Titel oder Inhalt:

    "ignoreRecordDetailsInResponse": true,
    
  • Optional: Der Modellname. Dadurch wird das Modell angegeben, das zum Einstufen der Dokumente verwendet werden soll. Wenn kein Modell angegeben ist, wird semantic-ranker-default@latest verwendet, das automatisch auf das neueste verfügbare Modell verweist. Wenn Sie auf ein bestimmtes Modell verweisen möchten, geben Sie einen der in Unterstützte Modelleaufgeführten Modellnamen an, z. B. semantic-ranker-512-003.

    Im folgenden Beispiel ist model auf semantic-ranker-default@latest gesetzt. Das bedeutet, dass die Ranking API immer das neueste verfügbare Modell verwendet.

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

Ausgabedaten

Die Ranking API gibt eine eingestufte Liste von Einträgen mit den folgenden Ausgaben zurück:

  • Score: Ein Gleitkommawert zwischen 0 und 1, der die Relevanz des Eintrags angibt.

  • ID: Die eindeutige ID des Eintrags.

  • Falls angefordert, das vollständige Objekt: die ID, der Titel und der Inhalt.

    Beispiel:

{
    "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."
        }
    ]
}

Eine Reihe von Einträgen anhand einer Abfrage einstufen (oder neu einstufen)

In der Regel geben Sie der Ranking API eine Abfrage und eine Reihe von Einträgen, die für diese Abfrage relevant sind und bereits mit einer anderen Methode wie einer Stichwortsuche oder einer Vektorsuche eingestuft wurden. Anschließend verwenden Sie die Ranking API, um die Qualität des Rankings zu verbessern und einen Wert zu ermitteln, der die Relevanz jedes Eintrags für die Abfrage angibt.

  1. Rufen Sie die Abfrage und die resultierenden Einträge ab. Achten Sie darauf, dass jeder Eintrag eine ID und entweder einen Titel, Inhalt oder beides hat.

    Die maximale Anzahl der unterstützten Tokens pro Eintrag hängt von der Modell version ab. Modelle bis Version 003, z. B. semantic-ranker-512-003, unterstützen 512 Tokens pro Eintrag. Ab Version 004 erhöht sich dieses Limit auf 1.024 Tokens. Wenn die kombinierte Länge von Titel und Inhalt das Tokenlimit des Modells überschreitet, wird der zusätzliche Inhalt abgeschnitten.

  2. Rufen Sie die Methode rankingConfigs.rank mit dem folgenden Code auf:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID. Google Cloud
  • QUERY: die Abfrage, anhand derer die Einträge eingestuft und bewertet werden.
  • RECORD_ID_n: ein eindeutiger String, der den Eintrag identifiziert.
  • TITLE_n: der Titel des Eintrags.
  • CONTENT_n: der Inhalt des Eintrags.

Allgemeine Informationen zu dieser Methode finden Sie unter rankingConfigs.rank.

Klicken Sie hier, um ein Beispiel für einen curl-Befehl und eine Antwort zu sehen.

    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

Weitere Informationen finden Sie in der API-Referenzdokumentation zur Agent Search Python API.

Richten Sie zur Authentifizierung bei der Agent Search die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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)

Unterstützte Modelle

Die folgenden Modelle sind verfügbar.

Modellname Neuestes Standardmodell (semantic-ranker-default@latest) Neuestes schnelles Modell (semantic-ranker-fast@latest) Eingabe Kontextfenster Releasedatum Datum der Außerbetriebnahme
semantic-ranker-default-004 Ja Nein Text (25 Sprachen) 1.024 09. April 2025 Noch nicht bekannt
semantic-ranker-fast-004 Nein Ja Text (25 Sprachen) 1.024 09. April 2025 Noch nicht bekannt
semantic-ranker-default-003 Nein Nein Text (25 Sprachen) 512 10. September 2024 Noch nicht bekannt
semantic-ranker-default-002 Nein Nein Text (nur Englisch) 512 3. Juni 2024 Noch nicht bekannt

Nächste Schritte

Informationen zur Verwendung der Ranking-Methode mit anderen RAG-APIs zum Generieren fundierter Antworten aus unstrukturierten Daten.