Method: projects.locations.collections.engines.servingConfigs.searchLite

Führt eine Suche aus. Ähnlich der Methode SearchService.Search, aber eine Lite-Version, die API-Schlüssel für die Authentifizierung zulässt, wobei keine OAuth- und IAM-Prüfungen erforderlich sind.

Diese Methode unterstützt nur die Suche auf öffentlichen Websites. Wenn Datenspeicher und Engines angegeben werden, die nicht mit der öffentlichen Website-Suche verknüpft sind, wird ein FAILED_PRECONDITION-Fehler zurückgegeben.

Diese Methode kann für ein einfaches Onboarding verwendet werden, ohne dass ein Authentifizierungs-Backend implementiert werden muss. Es wird jedoch dringend empfohlen, stattdessen SearchService.Search zu verwenden, da hier die erforderlichen OAuth- und IAM-Prüfungen für eine bessere Datensicherheit durchgeführt werden.

HTTP-Anfrage

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:searchLite

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
servingConfig

string

Erforderlich. Der Ressourcenname der Bereitstellungskonfiguration „servingConfigs.search“, z. B. projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config oder projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. Dieses Feld wird verwendet, um den Namen der Bereitstellungskonfiguration zu identifizieren, also die Gruppe von Modellen, die für die Suche verwendet werden.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
Felder
branch

string

Der Ressourcenname des Zweigs, z. B. projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

Verwenden Sie default_branch als Zweig-ID oder lassen Sie dieses Feld leer, um in Dokumenten im Standardzweig zu suchen.
query

string

Unbearbeitete Suchanfrage.
imageQuery

object (ImageQuery)

Rohe Bildanfrage.
pageSize

integer

Maximale Anzahl der zurückzugebenden Document. Der maximal zulässige Wert hängt vom Datentyp ab. Werte über dem Höchstwert werden implizit auf den Höchstwert umgewandelt.

  • Websites mit grundlegender Indexierung: Standard 10, maximal 25.
  • Websites mit erweiterter Indexierung: Standard 25, Maximum 50.
  • Andere: Standardwert 50, Maximalwert 100.

Wenn dieses Feld negativ ist, wird ein INVALID_ARGUMENT zurückgegeben.
pageToken

string

Ein Seitentoken, das von einem vorherigen SearchService.Search-Aufruf empfangen wurde. Geben Sie dieses an, um die nachfolgende Seite abzurufen.

Beim Paginieren müssen alle anderen für SearchService.Search bereitgestellten Parameter mit dem Aufruf übereinstimmen, der das Seitentoken bereitgestellt hat. Andernfalls wird der Fehler INVALID_ARGUMENT zurückgegeben.
offset

integer

Eine nullbasierte Ganzzahl, die den aktuellen Offset (d. h. die Startposition des Ergebnisses unter den von der API als relevant eingestuften Documents) in den Suchergebnissen angibt. Dieses Feld wird nur berücksichtigt, wenn pageToken nicht festgelegt wurde.

Wenn dieses Feld negativ ist, wird ein INVALID_ARGUMENT zurückgegeben.

Ein großer Offset wird möglicherweise auf einen angemessenen Grenzwert begrenzt.
oneBoxPageSize

integer

Die maximale Anzahl der Ergebnisse, die für OneBox zurückgegeben werden sollen. Dies gilt für jeden OneBox-Typ einzeln. Der Standardwert ist 10.
dataStoreSpecs[]

object (DataStoreSpec)

Spezifikationen, die die zu durchsuchenden DataStores sowie Konfigurationen für diese Datenspeicher definieren. Dies wird nur für Engines mit mehreren Datenspeichern berücksichtigt. Bei Engines mit einem einzelnen Datenspeicher sollten die Spezifikationen direkt unter SearchRequest verwendet werden.
filter

string

Die Filtersyntax besteht aus einer Ausdruckssprache zum Erstellen eines Prädikats aus einem oder mehreren Feldern der gefilterten Dokumente. Bei Filterausdrücken wird zwischen Groß- und Kleinschreibung unterschieden.

Wenn dieses Feld nicht erkannt wird, wird INVALID_ARGUMENT zurückgegeben.

Das Filtern in Vertex AI-ServingConfigs.search erfolgt durch Zuordnen des LHS-Filterschlüssels zu einer Schlüsselattribut, das im Backend von Vertex AI-ServingConfigs.search definiert ist. Diese Zuordnung wird vom Kunden in seinem Schema definiert. Ein Media-Kunde hat in seinem Schema beispielsweise möglicherweise das Feld „name“. In diesem Fall würde der Filter so aussehen: filter --> name:'ANY("king kong")'

Weitere Informationen zum Filtern, einschließlich Syntax und Filteroperatoren, finden Sie unter Filter.
canonicalFilter

string

Der Standardfilter, der angewendet wird, wenn ein Nutzer eine Suche durchführt, ohne auf der Suchseite Filter zu aktivieren.

Der Filter, der auf jede Suchanfrage angewendet wird, wenn eine Qualitätsverbesserung wie die Erweiterung der Anfrage erforderlich ist. Wenn eine Abfrage nicht genügend Ergebnisse liefert, wird mit diesem Filter bestimmt, ob die Abfrageerweiterung aktiviert werden soll. Der ursprüngliche Filter wird weiterhin für die erweiterte Suche der Abfrage verwendet. Dieses Feld wird dringend empfohlen, um eine hohe Suchqualität zu erzielen.

Weitere Informationen zur Filtersyntax finden Sie unter SearchRequest.filter.
orderBy

string

Die Reihenfolge, in der Dokumente zurückgegeben werden. Dokumente können nach einem Feld in einem Document-Objekt sortiert werden. Lassen Sie das Feld leer, wenn die Ergebnisse nach Relevanz sortiert werden sollen. Bei orderBy wird zwischen Groß- und Kleinschreibung unterschieden.

Weitere Informationen zum Sortieren der Website-Suchergebnisse finden Sie unter Web-Suchergebnisse sortieren. Weitere Informationen zum Sortieren der Suchergebnisse für das Gesundheitswesen finden Sie unter Suchergebnisse für das Gesundheitswesen sortieren. Wenn dieses Feld nicht erkannt wird, wird INVALID_ARGUMENT zurückgegeben.
userInfo

object (UserInfo)

Informationen zum Endnutzer. Für Analysen und Personalisierung dringend empfohlen. UserInfo.user_agent wird verwendet, um deviceType für Analysen abzuleiten.
languageCode

string

Der BCP-47-Sprachcode, z. B. „en-US“ oder „sr-Latn“ Weitere Informationen finden Sie unter Standardfelder. Dieses Feld hilft, die Anfrage besser zu interpretieren. Wenn kein Wert angegeben ist, wird der Abfragesprachcode automatisch erkannt. Das ist aber möglicherweise nicht korrekt.
regionCode

string

Der Länder-/Regionscode (CLDR) eines Standorts im Unicode-Format, beispielsweise "US" und "419". Weitere Informationen finden Sie unter Standardfelder. Wenn festgelegt, werden die Ergebnisse basierend auf dem angegebenen „regionCode“ optimiert.
facetSpecs[]

object (FacetSpec)

Facettenspezifikationen für die Attributsuche. Wenn leer, werden keine Facetten zurückgegeben.

Es sind maximal 100 Werte zulässig. Andernfalls wird der Fehler INVALID_ARGUMENT zurückgegeben.
boostSpec

object (BoostSpec)

Mit der Boost-Spezifikation können Sie bestimmte Dokumente hervorheben. Weitere Informationen zum Boosten finden Sie unter Boost.
params

map (key: string, value: value (Value format))

Zusätzliche Suchparameter.

Für die Suche auf öffentlichen Websites sind nur die folgenden Werte zulässig:

  • user_country_code: String. Standardmäßig leer. Wenn der Wert nicht leer ist, werden die Ergebnisse basierend auf dem angegebenen Standort eingeschränkt oder optimiert. z. B. user_country_code: "au".

Die verfügbaren Codes finden Sie unter Ländercodes.

  • searchType: double. Standardmäßig leer. Ermöglicht die Suche in Nicht-Webseiten, je nach Wert. Der einzige gültige Wert, der nicht der Standardwert ist, ist 1. Damit wird die Bildersuche aktiviert. z. B. searchType: 1.
queryExpansionSpec

object (QueryExpansionSpec)

Die Spezifikation für die Suchanfragenerweiterung, die die Bedingungen angibt, unter denen die Suchanfragenerweiterung erfolgt.
spellCorrectionSpec

object (SpellCorrectionSpec)

Die Spezifikation für die Rechtschreibkorrektur, die den Modus angibt, in dem die Rechtschreibkorrektur wirksam wird.
userPseudoId

string

Eine eindeutige Kennung für das Tracking von Besuchern. Dies kann beispielsweise mit einem HTTP-Cookie implementiert werden, mit dem ein Besucher auf einem einzelnen Gerät eindeutig identifiziert werden kann. Diese eindeutige Kennung sollte sich nicht ändern, wenn sich der Besucher auf der Website an- oder abmeldet.

Dieses Feld sollte KEINEN festen Wert wie unknown_visitor haben.

Dies sollte dieselbe ID wie UserEvent.user_pseudo_id und CompleteQueryRequest.user_pseudo_id sein.

Das Feld muss ein UTF-8-codierter String mit einer Längenbeschränkung von 128 Zeichen sein. Andernfalls wird der Fehler INVALID_ARGUMENT zurückgegeben.
contentSearchSpec

object (ContentSearchSpec)

Eine Spezifikation zum Konfigurieren des Verhaltens der Inhaltssuche.
embeddingSpec

object (EmbeddingSpec)

Verwendet die bereitgestellte Einbettung, um zusätzliche semantische Dokumente abzurufen. Der Abruf basiert auf dem Skalarprodukt von SearchRequest.EmbeddingSpec.EmbeddingVector.vector und dem Dokument-Embedding, das in SearchRequest.EmbeddingSpec.EmbeddingVector.field_path bereitgestellt wird.

Wenn SearchRequest.EmbeddingSpec.EmbeddingVector.field_path nicht angegeben ist, wird ServingConfig.EmbeddingConfig.field_path verwendet.
rankingExpression

string

Optional. Mit dem Ranking-Ausdruck wird das benutzerdefinierte Ranking beim Abrufen von Dokumenten gesteuert. Dadurch wird ServingConfig.ranking_expression überschrieben. Die Syntax und die unterstützten Funktionen hängen vom Wert von rankingExpressionBackend ab. Wenn rankingExpressionBackend nicht angegeben ist, wird standardmäßig RANK_BY_EMBEDDING verwendet.

Wenn rankingExpressionBackend nicht angegeben oder auf RANK_BY_EMBEDDING festgelegt ist, sollte es sich um eine einzelne Funktion oder mehrere Funktionen handeln, die durch „+“ verbunden sind.

  • rankingExpression = function, { " + ", function };

Unterstützte Funktionen:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Funktionsvariablen:

  • relevanceScore: Vordefinierte Keywords, die verwendet werden, um die Relevanz zwischen Anfrage und Dokument zu messen.
  • embedding_field_path: Das Dokumenteinbettungsfeld, das mit dem Abfrageeinbettungsvektor verwendet wird.
  • dotProduct: Einbettungsfunktion zwischen embedding_field_path und dem Abfrage-Einbettungsvektor.

Beispiel für einen Rankingausdruck:

Wenn ein Dokument das Einbettungsfeld „doc_embedding“ hat, könnte der Ranking-Ausdruck 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding) lauten.

Wenn rankingExpressionBackend auf RANK_BY_FORMULA gesetzt ist, werden die folgenden Ausdruckstypen (und Kombinationen davon, die mit den Operatoren „+“ oder „*“ verkettet werden) unterstützt:

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0) – Transformation des reziproken Rangs mit dem zweiten Argument als Nennerkonstante.
  • isNan(signal) – gibt 0 zurück, wenn das Signal NaN ist, andernfalls 1.
  • fillNan(signal1, signal2 | double): Wenn signal1 „NaN“ ist, wird „signal2 | double“ zurückgegeben, andernfalls „signal1“.

Hier sind einige Beispiele für Ranking-Formeln, in denen die unterstützten Ranking-Ausdruckstypen verwendet werden:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) – Die meisten Werte werden nach dem Logarithmus von keywordSimilarityScore mit geringfügiger semantic_smilarity_score-Anpassung eingestuft.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) – Rangfolge nach dem Exponenten von semanticSimilarityScore. Der Wert wird mit 0 gefüllt, wenn er „NaN“ ist. Außerdem wird dem endgültigen Ergebnis eine konstante Anpassung von 0,3 hinzugefügt, wenn semanticSimilarityScore „NaN“ ist.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16) – meistens nach dem reziproken Rang von keywordSimilarityScore mit geringfügiger Anpassung des reziproken Rangs von semantic_smilarity_score.

Die folgenden Signale werden unterstützt:

  • semanticSimilarityScore: Anpassung der semantischen Ähnlichkeit, die mithilfe der Einbettungen berechnet wird, die von einem proprietären Google-Modell generiert werden. Dieser Wert gibt an, wie semantisch ähnlich eine Suchanfrage und ein Dokument sind.
  • keywordSimilarityScore: Bei der Anpassung von Keyword-Übereinstimmungen wird die BM25-Rankingfunktion (Best Match 25) verwendet. Dieser Wert wird mithilfe eines probabilistischen Modells berechnet, um die Wahrscheinlichkeit zu schätzen, dass ein Dokument für eine bestimmte Anfrage relevant ist.
  • relevanceScore: Anpassung der semantischen Relevanz, bei der ein proprietäres Google-Modell verwendet wird, um die Bedeutung und Absicht hinter der Anfrage eines Nutzers im Kontext der Inhalte in den Dokumenten zu ermitteln.
  • pctrRank: Anpassung der prognostizierten Conversion-Rate als Rang. Die prognostizierte Klickrate (pCTR) wird verwendet, um die Relevanz und Attraktivität eines Suchergebnisses aus Nutzersicht zu bewerten. Eine höhere pCTR deutet darauf hin, dass das Ergebnis eher der Suchanfrage und Absicht des Nutzers entspricht. Das ist ein wichtiges Signal für das Ranking.
  • freshnessRank: Aktualitätsanpassung als Rang
  • documentAge: Die Zeit in Stunden seit der letzten Aktualisierung des Dokuments, eine Gleitkommazahl (z.B. 0,25 entspricht 15 Minuten.
  • topicalityRank: Anpassung der Aktualität als Rang. Es wird ein proprietäres Google-Modell verwendet, um die keywordbasierte Überschneidung zwischen der Anfrage und dem Dokument zu ermitteln.
  • baseRank: der Standardrang des Ergebnisses
rankingExpressionBackend

enum (RankingExpressionBackend)

Optional. Das Backend, das für die Auswertung des Ranking-Ausdrucks verwendet werden soll.
userLabels

map (key: string, value: string)

Die Nutzerlabels, die auf eine Ressource angewendet werden, müssen die folgenden Anforderungen erfüllen:

  • Jede Ressource kann bis zu 64 Labels haben.
  • Jedes Label muss ein Schlüssel/Wert-Paar sein.
  • Schlüssel haben eine Mindestlänge von einem Zeichen und eine maximale Länge von 63 Zeichen und dürfen nicht leer sein. Werte dürfen leer sein und haben eine maximale Länge von 63 Zeichen.
  • Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig.
  • Der Schlüsselabschnitt eines Labels darf nur einmal vorkommen. Sie können jedoch denselben Schlüssel für mehrere Ressourcen verwenden.
  • Schlüssel müssen mit einem Kleinbuchstaben oder einem internationalen Zeichen beginnen.

Weitere Informationen finden Sie im Google Cloud-Dokument.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Optional. Konfiguration für Funktionen zur Interpretation von Anfragen in natürlicher Sprache, z. B. zum Extrahieren strukturierter Feldfilter aus der Anfrage. Weitere Informationen finden Sie in dieser Dokumentation. Wenn naturalLanguageQueryUnderstandingSpec nicht angegeben ist, wird keine zusätzliche Verarbeitung von Abfragen in natürlicher Sprache durchgeführt.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search as you type-Konfiguration. Wird nur für die Branche IndustryVertical.MEDIA unterstützt.
displaySpec

object (DisplaySpec)

Optional. Konfiguration für die Anzeige von Funktionen wie der Hervorhebung von Übereinstimmungen in Suchergebnissen.
session

string

Der Name der Sitzungsressource. Optional.

Mit der Sitzung können Nutzer mehrere /search API-Aufrufe ausführen oder /search API-Aufrufe und /answer API-Aufrufe koordinieren.

Beispiel 1 (mehrere /search-API-Aufrufe): Rufen Sie die /search-API mit der Sitzungs-ID auf, die im ersten Aufruf generiert wurde. Hier wird die vorherige Suchanfrage bei der Bewertung der Anfrage berücksichtigt. Wenn die erste Frage beispielsweise „Wie hat sich Alphabet im Jahr 2022 entwickelt?“ lautet, und die aktuelle Frage „Wie sieht es mit 2023 aus?“ lautet, wird sie als „Wie hat sich Alphabet 2023 entwickelt?“ interpretiert.

Beispiel 2 (Abstimmung zwischen /search-API-Aufrufen und /answer-API-Aufrufen): Rufen Sie die /answer-API mit der im ersten Aufruf generierten Sitzungs-ID auf. Die Antwort wird hier im Kontext der Suchergebnisse aus dem ersten Suchaufruf generiert.

Die Funktion „servingConfigs.search“ für mehrere Anfragen ist derzeit in der privaten GA-Phase. Verwenden Sie stattdessen die Version v1alpha oder v1beta, bevor wir diese Funktion allgemein verfügbar machen. Alternativ können Sie das Google-Supportteam bitten, Sie auf die Zulassungsliste zu setzen.
sessionSpec

object (SessionSpec)

Sitzungsspezifikation.

Kann nur verwendet werden, wenn session festgelegt ist.
relevanceThreshold

enum (RelevanceThreshold)

Der Relevanzschwellenwert der Suchergebnisse.

Standardmäßig wird der von Google definierte Grenzwert verwendet, bei dem ein Gleichgewicht zwischen Präzision und Erinnerung angestrebt wird, um sowohl sehr genaue Ergebnisse als auch eine umfassende Abdeckung relevanter Informationen zu erzielen.

Diese Funktion wird für die Suche im Gesundheitswesen nicht unterstützt.
personalizationSpec

object (PersonalizationSpec)

Die Spezifikation für die Personalisierung.

Wenn sowohl ServingConfig.personalization_spec als auch SearchRequest.personalization_spec festgelegt sind, überschreibt SearchRequest.personalization_spec ServingConfig.personalization_spec.
relevanceScoreSpec

object (RelevanceScoreSpec)

Optional. Die Spezifikation für die Rückgabe des Relevanzwerts.
searchAddonSpec

object (SearchAddonSpec)

Optional. Mit SearchAddonSpec werden Add-ons für die Suche gemäß dem neuen Preismodell deaktiviert. Dieses Feld wird nur für Suchanfragen unterstützt.

Antworttext

Wenn der Vorgang erfolgreich abgeschlossen wurde, enthält der Antworttext eine Instanz von SearchResponse.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

Weitere Informationen finden Sie unter Authentication Overview.