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

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

Die Ranking API nimmt eine Liste von Dokumenten und ordnet sie neu, je nachdem, wie relevant die Dokumente für eine Abfrage sind. Im Vergleich zu Einbettungen, die nur die semantische Ähnlichkeit eines Dokuments und einer Abfrage berücksichtigen, kann die Ranking API genaue Werte dafür liefern, wie gut ein Dokument eine bestimmte Abfrage beantwortet. Mit der Ranking API kann die Qualität der Suchergebnisse verbessert werden, nachdem eine erste Gruppe von Kandidatendokumenten abgerufen wurde.

Die Ranking API ist zustandslos, sodass Dokumente vor dem Aufrufen der API nicht indexiert werden müssen. Sie müssen nur die Abfrage und die Dokumente übergeben. Dadurch eignet sich die API gut für die Neuanordnung 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 anhand einer Abfrage zu bewerten.

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 Anfrage eines Nutzers am relevantesten sind. Die Ranking API kann Ihnen beispielsweise bei Folgendem helfen:

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

  • Relevanz einer vorhandenen Suchfunktion verbessern

  • Relevante Abschnitte eines Dokuments identifizieren

Im folgenden Ablauf wird beschrieben, wie Sie die Ranking API verwenden können, um die Qualität der Ergebnisse für aufgeteilte 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 der Blöcke 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 Chunks ab.

  5. Ordnen Sie die relevanten Blöcke mithilfe der Ranking API neu an.

Eingabedaten

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

  • Die Abfrage, für die Sie die Datensätze bewerten.

    Beispiel:

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

  • Eine Reihe von Datensätzen, die für die Abfrage relevant sind. Die Datensätze 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 verwendeten Modellversion ab. 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 in Segmente aufgeteilt und verarbeitet. Wenn ein Eintrag als zu lang gilt, wird ein Teil des Inhalts abgeschnitten und ignoriert.

    Sie können bis zu 1.000 Einträge pro Anfrage angeben.

    Ein Datensatz-Array sieht beispielsweise so aus. In der Praxis würden viel mehr Einträge in das Array aufgenommen 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 Datensätzen, die die Ranking API zurückgeben soll. 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 sortiert.

    Beispiel: Hier werden die zehn am höchsten bewerteten Datensätze zurückgegeben:

    "topN": 10,

  • Optional: Eine Einstellung, die angibt, ob nur die ID des Datensatzes von der API zurückgegeben werden soll oder ob auch der Titel und der Inhalt des Datensatzes zurückgegeben werden sollen. Standardmäßig wird der vollständige Datensatz zurückgegeben. Der Hauptgrund für die Festlegung ist, wenn Sie die Größe der Antwortnutzlast reduzieren möchten.

    Wenn Sie beispielsweise true festlegen, wird nur die Datensatz-ID zurückgegeben, nicht der Titel oder Inhalt:

    "ignoreRecordDetailsInResponse": true,

  • Optional: Der Modellname. Gibt das Modell an, das für das Ranking 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 Modellnamen an, die unter Unterstützte Modelle aufgeführt sind, z. B. semantic-ranker-512-003.

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

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

Ausgabedaten

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

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

  • ID: die eindeutige ID des Eintrags.

  • Falls angefordert, das vollständige Objekt: ID, Titel und 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 Datensätzen anhand einer Abfrage bewerten (oder neu bewerten)

In der Regel stellen Sie der Ranking API eine Abfrage und eine Reihe von Datensätzen zur Verfügung, die für diese Abfrage relevant sind und bereits mit einer anderen Methode wie einer Keyword-Suche 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 der einzelnen Datensätze für die Abfrage angibt.

  1. Rufen Sie die Abfrage und die resultierenden Einträge ab. Jeder Eintrag muss eine ID und entweder einen Titel, Inhalt oder beides haben.

    Die maximale Anzahl unterstützter Tokens pro Eintrag hängt von der Modellversion ab. Modelle bis Version 003, z. B. semantic-ranker-512-003, unterstützen 512 Tokens pro Eintrag. Ab Version 004 wird dieses Limit auf 1.024 Tokens erhöht. Wenn die kombinierte Länge von Titel und Inhalt das Tokenlimit des Modells überschreitet, wird der zusätzliche Inhalt in Segmente aufgeteilt und verarbeitet. In extremen Fällen, wenn ein Eintrag als zu lang gilt, wird ein Teil des Inhalts abgeschnitten und ignoriert.

  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 ID Ihres Projekts in Google Cloud .
  • QUERY: die Abfrage, anhand derer die Datensätze eingestuft und bewertet werden.
  • RECORD_ID_n: Ein eindeutiger String, der den Eintrag identifiziert.
  • TITLE_n: der Titel des Datensatzes.
  • CONTENT_n: der Inhalt des Datensatzes.

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 Agentensuche für Python.

Richten Sie zur Authentifizierung bei der Agentensuche 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 Verlaufszeitraum Releasedatum Datum der Außerbetriebnahme
semantic-ranker-default-005 Ja Nein Text (25 Sprachen) 1.024 1. September 2026 Noch nicht bekannt
semantic-ranker-fast-005 Nein Ja Text (25 Sprachen) 1.024 1. September 2026 Noch nicht bekannt
semantic-ranker-default-004 Nein Nein Text (25 Sprachen) 1.024 09. April 2025 Noch nicht bekannt
semantic-ranker-fast-004 Nein Nein 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

Hier erfahren Sie, wie Sie die Ranking-Methode mit anderen RAG APIs verwenden, um fundierte Antworten aus unstrukturierten Daten zu generieren.