Configurare i controlli di pubblicazione per la rete di ricerca

I controlli di pubblicazione (chiamati anche controlli) modificano il comportamento predefinito della modalità di pubblicazione di una richiesta quando vengono restituiti i risultati. I controlli di pubblicazione agiscono a livello di data store.

Ad esempio, i controlli possono aumentare e nascondere i risultati, filtrare le voci tra i risultati restituiti, associare le stringhe tra loro come sinonimi o reindirizzare i risultati a URI specificati.

Questa pagina descrive i controlli di pubblicazione per le app di ricerca. Per informazioni sull'utilizzo dei controlli di pubblicazione con i consigli sui contenuti multimediali, consulta Creare e gestire le configurazioni di pubblicazione.

Informazioni sui controlli di pubblicazione

Per modificare i risultati di una richiesta, devi prima creare un controllo della pubblicazione. Quindi, associa questo controllo alla configurazione di pubblicazione di un'app di ricerca. Una configurazione di pubblicazione configura i metadati utilizzati per generare risultati relativi al momento della pubblicazione, ad esempio risultati di ricerca o risposte. Un controllo di pubblicazione influisce sulle richieste pubblicate dall'app solo se il controllo è collegato alla configurazione di pubblicazione dell'app.

Alcuni controlli, come i controlli di miglioramento, hanno dipendenze dagli store di dati. Se un datastore viene rimosso da un'app, tutti i controlli dipendenti dal datastore vengono anche rimossi dall'app e diventano inattivi, ma non vengono eliminati.

Tipi di controlli di pubblicazione

Sono disponibili i seguenti tipi di controlli di pubblicazione:

Controllo Descrizione Disponibile per
Controllo del boost Modifica l'ordine restituito dei risultati App di ricerca con datastore che supportano uno schema, ad esempio datastore contenenti dati strutturati, siti web con dati strutturati (indicizzazione avanzata dei siti web), dati non strutturati con metadati o dati multimediali
Controllo filtro Rimuove le voci dai risultati restituiti App di ricerca con datastore che supportano uno schema, ad esempio datastore contenenti dati strutturati, siti web (indicizzazione avanzata dei siti web e ricerca di siti web di base), dati non strutturati con metadati o dati multimediali
Controllo dei sinonimi Associa le query tra loro App di ricerca con siti web (indicizzazione avanzata dei siti web), datastore strutturati, non strutturati o di contenuti multimediali
Controllo dei reindirizzamenti Reindirizza a un URI specificato Tutte le app di ricerca

Informazioni sulle condizioni

Quando crei un controllo, puoi facoltativamente definire una condizione che determina quando viene applicato. Le condizioni vengono definite utilizzando i campi condizione. I seguenti campi delle condizioni sono disponibili:

  • queryTerms. Un controllo facoltativo che viene applicato quando vengono cercate query specifiche. Quando viene utilizzata la condizione queryTerms, il controllo viene applicato quando il valore di queryTerms corrisponde a un termine in SearchRequest.query. I termini di query possono essere utilizzati solo quando Control.searchUseCase è impostato su SOLUTION_TYPE_SEARCH. In un singolo Control.condition è possibile specificare fino a 10 diversi queryTerms. Se non vengono specificati termini di query, il campo queryTerms viene ignorato.

  • activeTimeRange. Un controllo facoltativo che viene applicato quando una richiesta avviene in un intervallo di tempo specificato. Controlla che l'ora di ricezione di una richiesta sia compresa tra activeTimeRange.startTime e activeTimeRange.endTime. In un singolo Control.condition è possibile specificare fino a 10 intervalli activeTimeRange. Se il campoactiveTimeRange non è specificato, viene ignorato.

Se per un controllo sono specificati entrambi i tipi di condizioni, il controllo viene applicato alla richiesta di ricerca quando entrambi i tipi di condizioni sono soddisfatti. Se vengono specificati più valori per la stessa condizione, è sufficiente che uno solo dei valori corrisponda per soddisfare la condizione.

Ad esempio, considera la seguente condizione con due termini di query specificati:

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

La condizione sarà soddisfatta per una richiesta con SearchRequest.query="gShoe" o una richiesta con SearchRequest.query="gBoot", ma non sarà soddisfatta con SearchRequest.query="gSandal" o con qualsiasi altra stringa.

Se non vengono specificate condizioni, il controllo viene applicato sempre.

Per ulteriori informazioni, consulta il campo Condition nella documentazione di riferimento dell'API.

Creare e collegare i controlli di pubblicazione con incremento

Un controllo della pubblicazione con incremento è definito come un controllo con un boostAction.

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione con incremento.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

  1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

    1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    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/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • BOOST_VALUE: un numero a virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono retrocessi (vengono visualizzati più in basso nei risultati). Quando il valore è positivo, i risultati vengono promossi (vengono visualizzati più in alto nei risultati). Per ulteriori informazioni, consulta boostAction.
    • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene applicato il potenziamento. In caso contrario, non viene apportata alcuna modifica. Se questo campo è vuoto, l'aumento viene applicato a tutti i documenti nello datastore. Per la sintassi di filtro, consulta Sintassi dell'espressione di filtro. Nota: non è possibile filtrare il campo del documento title.
    • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui documenti devono essere migliorati da questo controllo. Il formato del percorso completo della risorsa è projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Questo datastore deve essere collegato al motore specificato nella richiesta.

  3. Collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Sostituisci BOOST_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Crea e allega i controlli di pubblicazione dei filtri

Un controllo di pubblicazione del filtro è definito come un controllo con un filterAction.

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione dei filtri.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

  1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

    1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    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/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene visualizzato nei risultati. In caso contrario, il documento non è presente nei risultati. Per la sintassi di filtro, consulta Sintassi dell'espressione di filtro. Per ulteriori informazioni, vedi filterAction. Nota: non è possibile filtrare il campo del documento title.

  3. Collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Sostituisci FILTER_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Creare e associare controlli di pubblicazione di sinonimi

Un controllo di pubblicazione dei sinonimi è definito come un controllo con un synonymsAction.

Segui le istruzioni riportate di seguito per creare un controllo della pubblicazione di sinonimi.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

  1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

    1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    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/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • SYNONYMS_N: un elenco di stringhe associate tra loro, che aumenta la probabilità che ciascuna mostri risultati simili. Sebbene sia più probabile che tu ottenga risultati simili, quando cerchi ciascuna delle voci dei sinonimi, potresti non ricevere tutti i risultati pertinenti per tutti i sinonimi associati. Devi specificare almeno due sinonimi e puoi specificarne fino a 100. Ogni sinonimo deve essere codificato in UTF-8 e in minuscolo. Non sono consentite stringhe duplicate. Ad esempio, puoi aggiungere "pixel", "smartphone Android" e "smartphone Google" come sinonimi. Per ulteriori informazioni, vedi synonymsAction.

  3. Collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Sostituisci SYNONYMS_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Crea e collega i controlli di pubblicazione dei reindirizzamenti

Un controllo di pubblicazione di reindirizzamento consente di reindirizzare gli utenti a un URI fornito. I controlli di reindirizzamento sono definiti come un controllo con un redirectAction.

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione con reindirizzamento.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

  1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

    1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    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/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • REDIRECT_URI_N: un URI a cui viene eseguito il reindirizzamento. Può avere una lunghezza massima di 2000 caratteri. Ad esempio, se il valore del termine di query è "assistenza", puoi impostare un reindirizzamento alla pagina dell'assistenza tecnica anziché restituire (o non restituire) i risultati di ricerca per "assistenza". In questo esempio, l'URI di reindirizzamento diventa "https://www.example.com/support". Per ulteriori informazioni, vedi redirectAction.

  3. Collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Sostituisci REDIRECT_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Passaggi successivi

  • Per comprendere l'impatto di un controllo della pubblicazione sulla qualità della ricerca di un'app di ricerca generica, valuta la qualità della ricerca. Per ulteriori informazioni, consulta Valutare la qualità della ricerca.