Ricevere risposte e follow-up

Questa pagina introduce la ricerca con risposta e follow-up per Vertex AI Search e mostra come implementarla per le app di ricerca generica utilizzando le chiamate ai metodi.

La ricerca con risposta e domande di follow-up si basa sul metodo di risposta. Il metodo di risposta sostituisce le funzionalità di sintesi del metodo search precedente e tutte le funzionalità del metodo converse deprecato. Il metodo di risposta presenta anche alcune funzionalità aggiuntive importanti, come la capacità di gestire query complesse.

Funzionalità del metodo di risposta

Le funzionalità principali del metodo di risposta sono le seguenti:

  • La capacità di generare risposte a query complesse. Ad esempio, il metodo answer può suddividere le query complesse, come la seguente, in più query più piccole per restituire risultati migliori che vengono utilizzati per fornire risposte migliori:

    • "Quali sono le rispettive entrate di Google Cloud e Google Ads nel 2024?"
    • "Dopo quanti anni dalla sua fondazione, Google ha raggiunto un miliardo di dollari di entrate?"

  • La possibilità di combinare la ricerca e la generazione di risposte in una conversazione con più turni chiamando il metodo di risposta in ogni turno.

  • La possibilità di accoppiarsi con il metodo di ricerca per ridurre la latenza della ricerca. Puoi chiamare il metodo di ricerca e il metodo di risposta separatamente e visualizzare i risultati di ricerca e le risposte in iframe diversi in momenti diversi. Ciò significa che puoi mostrare ai tuoi utenti i risultati di ricerca (i 10 link blu) in millisecondi. Non è necessario attendere che le risposte vengano generate prima di poter mostrare i risultati di ricerca.

Le funzionalità di risposta e follow-up possono essere suddivise in tre fasi della query, della ricerca e della risposta:

Quando utilizzare la risposta e quando utilizzare la ricerca

Vertex AI Search dispone di due metodi utilizzati per eseguire query sulle app. Hanno funzionalità diverse, ma parzialmente sovrapposte.

Utilizza il metodo answer quando:

  • Vuoi una risposta (o un riepilogo) dei risultati di ricerca generata dall'AI.

  • Vuoi effettuare ricerche in più passaggi, ovvero ricerche che mantengono il contesto in modo da consentire domande di follow-up.

Utilizza il metodo search quando:

  • Ti servono solo i risultati di ricerca, non una risposta generata.

  • Vuoi che vengano restituiti più di dieci risultati di ricerca ("link blu").

  • Hai uno dei seguenti problemi:

    • Dati multimediali o sanitari
    • I tuoi embedding
    • Controlli sinonimi o reindirizzamento
    • Facet
    • Codici paese dell'utente

Utilizza i metodi di risposta e di ricerca insieme quando:

  • Vuoi restituire più di dieci risultati di ricerca e vuoi che venga generata una risposta.

  • Hai problemi di latenza e vuoi restituire e visualizzare rapidamente i risultati di ricerca prima che venga restituita la risposta generata.

Funzionalità della fase di query

La funzionalità di risposta e follow-up supporta l'elaborazione delle query in linguaggio naturale.

Questa sezione descrive e illustra le varie opzioni per la riformulazione e la classificazione delle query.

Riformulazione delle query

La riformulazione delle query è attiva per impostazione predefinita. Questa funzionalità sceglie automaticamente il modo migliore per riformulare le query al fine di migliorare i risultati di ricerca. Questa funzionalità può gestire anche le query che non richiedono una nuova formulazione.

  • Suddividi le query complesse in più query ed esegui query secondarie sincrone.

    Ad esempio, una query complessa viene suddivisa in quattro query più piccole e semplici.

    Input utente Subquery create dalla query complessa
    Quali lavori e hobby hanno in comune Andie Ram e Arnaud Clément?
    • Professione di Andie Ram
    • Professione di Arnaud Clément
    • Andie Ram hobby
    • Hobby di Arnaud Clément

  • Sintetizza le query con più turni per rendere le domande di follow-up sensibili al contesto e stateful.

    Ad esempio, le query sintetizzate dall'input utente'utente a ogni turno potrebbero avere il seguente aspetto:

    Input utente Query sintetizzata
    Primo turno: laptop per la scuola laptop per la scuola
    Turn 2: not mac laptop per la scuola non mac
    Terza svolta: schermo più grande e ho bisogno anche di tastiera e mouse wireless laptop con schermo più grande per la scuola non Mac con tastiera e mouse wireless
    Gira a 4: e uno zaino laptop con schermo più grande per la scuola non Mac con tastiera e mouse wireless e uno zaino

  • Semplifica le query lunghe per migliorare il recupero.

    Ad esempio, una query lunga viene abbreviata in una semplice query.

    Input utente Query semplificata
    Sto cercando di capire perché il pulsante "Aggiungi al carrello" sul nostro sito web non funziona correttamente. Sembra che quando un utente fa clic sul pulsante, l'articolo non venga aggiunto al carrello e l'utente riceva un messaggio di errore. Ho controllato il codice e sembra essere corretto, quindi non so quale potrebbe essere il problema. Puoi aiutarmi a risolvere il problema? Il pulsante "Aggiungi al carrello" non funziona sul sito web.

  • Eseguire ragionamenti in più passaggi

    Il ragionamento multi-passaggio si basa sul paradigma ReAct (reason + act) che consente ai modelli linguistici di grandi dimensioni di risolvere attività complesse utilizzando il ragionamento in linguaggio naturale. Per impostazione predefinita, il numero massimo di passaggi è cinque.

    Ad esempio:

    Input utente Due passaggi per generare la risposta
    Dopo quanti anni dalla sua fondazione Google ha raggiunto un fatturato di 1 miliardo di dollari? Passaggio 1:
    [Riflessione]: devo sapere quando è stata fondata Google, quindi posso eseguire una query sulle entrate da allora.
    [Azione] Ricerca: quando è stata fondata Google? [Osserva i risultati di ricerca]: "1998"

    Passaggio 2:
    [Pensiero]: ora devo trovare le entrate annuali di Google dal 1998 e scoprire quando hanno superato 1 miliardo per la prima volta.
    [Azione] Ricerca: entrate di Google dal 1998
    [Osserva i risultati di ricerca] Entrate di Google nel 1998, entrate di Google nel 1999…..
    [Risposta]: Google ha raggiunto un fatturato di oltre 1 miliardo di dollari nel 2003 [1], 5 anni dopo la sua fondazione nel 1998 [2].

Classificazione delle query

Le opzioni di classificazione delle query consentono di identificare le query dirette e quelle che non cercano risposte. Per impostazione predefinita, le opzioni di classificazione delle query sono disattivate.

Per ulteriori informazioni sulle query ostili e di ricerca di risposte, consulta Ignorare le query ostili e Ignorare le query di ricerca di contenuti diversi dai riepiloghi.

Funzionalità della fase di ricerca

Per la ricerca, il metodo di risposta ha le stesse opzioni del metodo di ricerca. Ad esempio:

Funzionalità della fase di risposta

Durante la fase di risposta, quando le risposte vengono generate dai risultati di ricerca, puoi attivare le stesse funzionalità del metodo di ricerca. Ad esempio:

Ulteriori funzionalità della fase di risposta non disponibili nel metodo di ricerca:

  • Ottenere un punteggio di supporto per ogni affermazione (frase nella risposta generata). Un punteggio di supporto è un valore in virgola mobile nell'intervallo [0,1] che indica quanto la rivendicazione sia basata sui dati nello datastore. Per ulteriori informazioni, consulta Restituire i punteggi di assistenza per l'impianto di messa a terra.

  • Ottenere un punteggio di assistenza aggregato per la risposta. Il punteggio di supporto indica quanto la risposta è basata sui dati nello datastore. Per maggiori informazioni, consulta Scori di assistenza per il reso in base al grounding.

  • Fornisci solo risposte ben fondate. Puoi scegliere di restituire solo le risposte che soddisfano una determinata soglia del punteggio di assistenza. Per ulteriori informazioni, consulta Mostrare solo risposte ben fondate.

Prima di iniziare

A seconda del tipo di app, completa i seguenti requisiti:

Ricerca e risposta (di base)

Il seguente comando mostra come chiamare il metodo answer e restituire una risposta generata e un elenco di risultati di ricerca, con link alle fonti.

Questo comando mostra solo l'input richiesto. Le opzioni rimangono predefinite.

REST

Per eseguire ricerche e ottenere risultati con una risposta generata:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"}
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca. Ad esempio, "Confrontare i database BigQuery e Spanner?".

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandi della fase di query

Questa sezione mostra come specificare le opzioni per la fase di query della chiamata al metodo answer.

Ricerca e risposta (riformulazione disattivata)

Il seguente comando mostra come chiamare il metodo answer e restituire una risposta generata e un elenco di risultati di ricerca. La risposta potrebbe essere diversa da quella precedente perché l'opzione di riformulazione è disattivata.

REST

Per eseguire ricerche e ottenere risultati con una risposta generata senza applicare la riformulazione della query, segui questi passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
           "queryRephraserSpec": {
              "disable": true
        }
    }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca. Ad esempio, "Confrontare i database BigQuery e Spanner?".

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Ricerca e risposta (specifica il numero massimo di passaggi)

Il seguente comando mostra come chiamare il metodo answer e restituire una risposta generata e un elenco di risultati di ricerca. La risposta è diversa dalle risposte precedenti perché è stato aumentato il numero di passaggi di riformulazione.

REST

Per eseguire ricerche e ottenere risultati con una risposta generata che consente fino a cinque passaggi di riformulazione, svolgi i seguenti passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryRephraserSpec": {
                "maxRephraseSteps": MAX_REPHRASE
             }
         }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca. Ad esempio, "Confrontare i database BigQuery e Spanner?".
    • MAX_REPHRASE: il numero massimo di passaggi per la riformulazione. Il valore massimo consentito è 5. Se non viene impostato o se viene impostato su un valore inferiore a 1, il valore è predefinito, 1.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Ricerca e risposta con classificazione delle query

Il seguente comando mostra come chiamare il metodo answer per verificare se una query è ostile, non cerca una risposta o nessuna delle due.

La risposta include il tipo di classificazione per la query, ma la risposta stessa non è interessata dalla classificazione. Se vuoi modificare il comportamento della risposta in base al tipo di query, puoi farlo nella fase di risposta. Consulta Ignorare le query dannose e Ignorare le query di ricerca non di riepilogo.

REST

Per determinare se una query è ostile o non cerca una risposta:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "queryUnderstandingSpec": {
            "queryClassificationSpec": {
                "types": ["QUERY_CLASSIFICATION_TYPE"]
             }
         }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca. Ad esempio, "ciao".
    • QUERY_CLASSIFICATION_TYPE: i tipi di query che vuoi identificare: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY o entrambi.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandi della fase di ricerca: cerca e rispondi con le opzioni dei risultati di ricerca

Questa sezione mostra come specificare le opzioni per la parte della fase di ricerca della chiamata al metodo answer, ad esempio l'impostazione del numero massimo di documenti restituiti, il potenziamento e i filtri, nonché come ottenere una risposta quando fornisci i tuoi risultati di ricerca.

Il comando seguente mostra come chiamare il metodo answer e specificare varie opzioni per la modalità di restituzione del risultato di ricerca. I risultati di ricerca sono indipendenti dalla risposta.

REST

Per impostare varie opzioni relative a quali e come vengono restituiti i risultati di ricerca, svolgi i seguenti passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
          "searchSpec": {
          "searchParams": {
            "maxReturnResults": MAX_RETURN_RESULTS,
            "filter": "FILTER",
            "boostSpec": BOOST_SPEC,
            "orderBy": "ORDER_BY",
            "searchResultMode": SEARCH_RESULT_MODE
           }
         }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca. Ad esempio, "Confrontare i database BigQuery e Spanner?"
    • MAX_RETURN_RESULTS: il numero di risultati di ricerca da restituire. Il valore predefinito è 10.
    • FILTER: il filtro specifica i documenti su cui viene eseguita la query. Se i metadati di un documento soddisfano la specifica del filtro, verrà eseguita una query sul documento. Per ulteriori informazioni, inclusa la sintassi dei filtri, consulta Filtra la ricerca generica per dati strutturati o non strutturati.
    • BOOST_SPEC: la specifica del miglioramento consente di migliorare determinati documenti nei risultati di ricerca, il che può influire sulla risposta. Per ulteriori informazioni, inclusa la sintassi per la specifica dell'incremento, consulta Migliorare i risultati di ricerca.
    • ORDER_BY: l'ordine in cui vengono restituiti i documenti. I documenti possono essere ordinati in base a un campo in un oggetto Document. L'espressione orderBy è sensibile alle maiuscole. Se questo campo non è riconoscibile, viene restituito un valore INVALID_ARGUMENT.
    • SEARCH_RESULT_MODE: specifica la modalità di risultato di ricerca: DOCUMENTS o CHUNKS. Per ulteriori informazioni, consulta Eseguire l'analisi e suddividere i documenti e ContentSearchSpec. Questo campo è disponibile solo nella versione v1alpha dell'API.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandi della fase di risposta

Questa sezione mostra come specificare opzioni specifiche per la risposta per la chiamata del metodo answer.

Ignora le query contraddittorie e quelle che non cercano una risposta

Il seguente comando mostra come evitare di rispondere alle query dirette e alle query che non cercano una risposta quando viene chiamato il metodo answer.

REST

Per saltare la risposta alle query ostili o che non cercano una risposta, procedi come segue:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreAdversarialQuery": true,
           "ignoreNonAnswerSeekingQuery": true
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Mostra solo risposte pertinenti

Vertex AI Search può valutare la pertinenza dei risultati per una query. Se nessun risultato viene considerato sufficientemente pertinente, anziché generare una risposta da risultati non pertinenti o minimamente pertinenti, puoi scegliere di restituire una risposta di riserva: "We do not have a summary for your query."

Il seguente comando mostra come restituire la risposta di riserva in caso di risultati irrilevanti quando viene chiamato il metodo answer.

REST

Per restituire una risposta di riserva se non vengono trovati risultati pertinenti, svolgi i seguenti passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "ignoreLowRelevantContent": true
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Restituire i punteggi di supporto per l'isolamento a terra

Il seguente comando mostra come restituire i punteggi di supporto per le risposte e le rivendicazioni.

Per informazioni generali sulla grounding in Vertex AI, consulta Verificare la grounding con RAG. Il metodo groundingConfigs.check viene chiamato dal metodo answer.

REST

Per restituire un punteggio di supporto per ogni affermazione (frase nella risposta) e un punteggio di supporto aggregato per la risposta, svolgi i seguenti passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "includeGroundingSupports": true,
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.

Mostra solo risposte ben fondate

Il seguente comando mostra come restituire solo le risposte ritenute ben fondate nel corpus, le informazioni nello datastore. Le risposte poco fondate vengono filtrate.

Scegli una soglia di livello basso o alto per il punteggio di supporto alla messa a terra. La risposta viene poi restituita solo se soddisfa o supera questo livello. Puoi fare esperimenti con le due soglie di filtro e senza alcuna soglia per determinare quale livello di filtro è più probabile che fornisca i risultati migliori per i tuoi utenti.

Per informazioni generali sulla grounding in Vertex AI, consulta Verificare la grounding con RAG. Il metodo groundingConfigs.check viene chiamato dal metodo answer.

REST

Per restituire una risposta solo se soddisfa una soglia del punteggio di assistenza, svolgi i seguenti passaggi:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "groundingSpec": {
           "filteringLevel": "FILTER_LEVEL"
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • FILTER_LEVEL: un'enumerazione per filtrare le risposte in base al punteggio di assistenza per l'orientamento. Le opzioni sono: FILTERING_LEVEL_LOW e FILTERING_LEVEL_HIGH. Se filteringLevel non è incluso, alla risposta non viene applicato alcun filtro del punteggio di assistenza.

Specifica il modello di risposta

Il seguente comando mostra come modificare la versione del modello utilizzata per generare le risposte.

Per informazioni sui modelli supportati, consulta Versioni e ciclo di vita dei modelli di generazione di risposte.

REST

Per generare una risposta utilizzando un modello diverso da quello predefinito:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "modelSpec": {
              "modelVersion": "MODEL_VERSION",
           }
         }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • MODEL_VERSION: la versione del modello che vuoi utilizzare per generare la risposta. Per ulteriori informazioni, consulta la sezione Versioni e ciclo di vita del modello di generazione di risposte.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Specifica un preambolo personalizzato

Il seguente comando mostra come impostare un preambolo per la risposta generata. Un preambulo contiene istruzioni in linguaggio naturale per personalizzare la risposta. Puoi richiedere personalizzazioni come lunghezza, livello di dettaglio, stile di output (ad es. "semplice"), lingua di output, punto focale della risposta e formato (ad es. tabelle, elenchi puntati e XML). Ad esempio, un preambolo potrebbe essere "Spiega come se fossi un bambino di dieci anni".

Il preambolo può avere un effetto significativo sulla qualità della risposta generata. Per informazioni su cosa scrivere nei preamboli ed esempi di preamboli efficaci, consulta Informazioni sui preamboli personalizzati.

REST

Per generare una risposta utilizzando un modello diverso da quello predefinito:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "promptSpec": {
               "preamble": "PREAMBLE",
           }
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • PREAMBLE: un'istruzione in linguaggio naturale per personalizzare la risposta. Ad esempio, prova show the answer format in an ordered list o give a very detailed answer.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Includi citazioni

Il seguente comando mostra come richiedere l'inclusione delle citazioni nella risposta.

REST

Per generare una risposta utilizzando un modello diverso da quello predefinito:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "includeCitations": INCLUDE_CITATIONS
        }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • INCLUDE_CITATIONS: specifica se includere i metadati della citazione nella risposta. Il valore predefinito è false.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Impostare il codice lingua della risposta

Il seguente comando mostra come impostare il codice lingua per le risposte.

REST

Per generare una risposta utilizzando un modello diverso da quello predefinito:

  1. Esegui il seguente comando curl:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "answerGenerationSpec": {
           "answerLanguageCode": "ANSWER_LANGUAGE_CODE"
           }
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search su cui vuoi eseguire una query.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • ANSWER_LANGUAGE_CODE: un codice lingua per la risposta. Utilizza i tag lingua definiti da BCP47: Tag per identificare le lingue.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION"                    # Values: "global", "us", "eu"
# engine_id = "YOUR_APP_ID"


def answer_query_sample(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.AnswerQueryResponse:
    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.ConversationalSearchServiceClient(
        client_options=client_options
    )

    # The full resource name of the Search serving config
    serving_config = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/servingConfigs/default_serving_config"

    # Optional: Options for query phase
    # The `query_understanding_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/QueryUnderstandingSpec
    query_understanding_spec = discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec(
        query_rephraser_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryRephraserSpec(
            disable=False,  # Optional: Disable query rephraser
            max_rephrase_steps=1,  # Optional: Number of rephrase steps
        ),
        # Optional: Classify query types
        query_classification_spec=discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec(
            types=[
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.ADVERSARIAL_QUERY,
                discoveryengine.AnswerQueryRequest.QueryUnderstandingSpec.QueryClassificationSpec.Type.NON_ANSWER_SEEKING_QUERY,
            ]  # Options: ADVERSARIAL_QUERY, NON_ANSWER_SEEKING_QUERY or both
        ),
    )

    # Optional: Options for answer phase
    # The `answer_generation_spec` below includes all available query phase options.
    # For more details, refer to https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/AnswerGenerationSpec
    answer_generation_spec = discoveryengine.AnswerQueryRequest.AnswerGenerationSpec(
        ignore_adversarial_query=False,  # Optional: Ignore adversarial query
        ignore_non_answer_seeking_query=False,  # Optional: Ignore non-answer seeking query
        ignore_low_relevant_content=False,  # Optional: Return fallback answer when content is not relevant
        model_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.ModelSpec(
            model_version="gemini-1.5-flash-001/answer_gen/v2",  # Optional: Model to use for answer generation
        ),
        prompt_spec=discoveryengine.AnswerQueryRequest.AnswerGenerationSpec.PromptSpec(
            preamble="Give a detailed answer.",  # Optional: Natural language instructions for customizing the answer.
        ),
        include_citations=True,  # Optional: Include citations in the response
        answer_language_code="en",  # Optional: Language code of the answer
    )

    # Initialize request argument(s)
    request = discoveryengine.AnswerQueryRequest(
        serving_config=serving_config,
        query=discoveryengine.Query(text="What is Vertex AI Search?"),
        session=None,  # Optional: include previous session ID to continue a conversation
        query_understanding_spec=query_understanding_spec,
        answer_generation_spec=answer_generation_spec,
    )

    # Make the request
    response = client.answer_query(request)

    # Handle the response
    print(response)

    return response

Comandi per le domande aggiuntive

I follow-up sono query con più turni. Dopo la prima query in una sessione di follow-up, le "volte" successive prendono in considerazione le interazioni precedenti. Con le domande di follow-up, il metodo di risposta può anche suggerire domande correlate, che gli utenti possono scegliere anziché inserire le proprie domande di follow-up.

Tutte le funzionalità di risposta e di follow-up descritte nelle sezioni precedenti, come citazioni, filtri, SafeSearch, l'ignorare determinati tipi di query e l'utilizzo di un preambolo per personalizzare le risposte, possono essere applicate insieme ai follow-up.

Esempio di sessione di follow-up

Di seguito è riportato un esempio di una sessione con follow-up. Supponiamo che tu voglia informazioni sulle vacanze in Messico:

  • Curva 1:

    • Tu: Qual è il periodo migliore dell'anno per fare una vacanza in Messico?

    • Rispondi con i follow-up: il periodo migliore per fare le vacanze in Messico è durante la stagione secca, da novembre ad aprile.

  • Gira 2:

    • Tu: Qual è il tasso di cambio?

    • Rispondi con domande di follow-up: 1 dollaro statunitense equivale a circa 17,65 pesos messicani.

  • Curva 3:

    • Tu: Qual è la temperatura media a dicembre?

    • Rispondi con i follow-up: la temperatura media varia da 21 a 26 °C. La temperatura media di Cancún è di circa 25 °C.

Senza domande successive, la tua domanda "Qual è il tasso di cambio?" non avrebbe risposta perché la ricerca normale non saprebbe che ti interessa il tasso di cambio messicano. Analogamente, senza i follow-up, non avremmo il contesto necessario per fornirti le temperature specifiche per il Messico.

Quando chiedi "Qual è il periodo migliore dell'anno per fare le vacanze in Messico?", oltre a rispondere alla tua domanda, la risposta e le domande di follow-up possono suggerire altre domande che potresti porre, ad esempio "Qual è il mese più economico per fare le vacanze in Messico?" e "Quali sono i mesi di alta stagione in Messico?".

Una volta attivata la funzionalità delle domande correlate, le domande vengono restituite come stringhe in ConverseConversationResponse.

Informazioni sulle sessioni

Per capire come funzionano i follow-up in Vertex AI Search, devi conoscere le sessioni.

Una sessione è composta da query di testo fornite da un utente e da risposte fornite da Vertex AI Search.

Queste coppie di query e risposta sono a volte chiamate turn. Nell'esempio precedente, il secondo turno è composto da "Qual è il tasso di cambio?" e "1 dollaro statunitense equivale a circa 17,65 pesos messicani".

Le sessioni vengono archiviate con l'app. Nell'app, una sessione è rappresentata dalla risorsa sessione.

Oltre a contenere i messaggi di query e risposta, la risorsa sessione ha:

  • Un nome univoco (l'ID sessione).

  • Uno stato (in corso o completato).

  • Uno pseudo ID utente, ovvero un ID visitatore che monitora l'utente. Può essere assegnata in modo programmatico.

  • Un'ora di inizio e un'ora di fine.

  • Una svolta, ovvero una coppia di query e risposta.

Memorizzare le informazioni sulla sessione e ricevere risposte

Puoi utilizzare la riga di comando per generare risposte e risposte di ricerca e per memorizzarle, insieme a ogni query in una sessione.

REST

Per utilizzare la riga di comando per creare una sessione e generare risposte dall'input dell'utente, segui questi passaggi:

  1. Specifica l'app in cui vuoi archiviare la sessione:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions" \
  -d '{
        "userPseudoId": "USER_PSEUDO_ID"
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.

    • APP_ID: l'ID dell'app Vertex AI Search.

    • USER_PSEUDO_ID: si tratta di un identificatore univoco per monitorare un visitatore proveniente dalla rete di ricerca. Ad esempio, puoi implementarlo con un cookie HTTP, che identifica in modo univoco un visitatore su un singolo dispositivo.

    Comando e risultato di esempio

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/sessions"
-d '{
"userPseudoId": "test_user"
}'

    
{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
  "state": "IN_PROGRESS",
  "userPseudoId": "test_user",
  "startTime": "2024-09-13T18:47:10.465311Z",
  "endTime": "2024-09-13T18:47:10.465311Z"
}

  2. Prendi nota dell'ID sessione, i numeri alla fine del campo name: nella risposta JSON. Nel risultato dell'esempio, l'ID è 5386462384953257772. Ti servirà questo ID nel passaggio successivo.

  3. Genera una risposta e aggiungila a una sessione nella tua app:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:answer" \
  -d '{
        "query": { "text": "QUERY"},
        "session": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
          "searchSpec":{ "searchParams": {"filter": "FILTER"} }
}'
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • QUERY: una stringa di testo libero contenente la domanda o la query di ricerca.
    • SESSION_ID: l'ID della sessione che hai creato nel passaggio 1. Si tratta delle cifre alla fine del name: campo, indicato nel passaggio 2. Per una sessione, utilizza lo stesso ID sessione in ogni turno.
    • FILTER: un campo di testo per filtrare la ricerca utilizzando un'espressione di filtro. Il valore predefinito è una stringa vuota. Il modo in cui crei il filtro varia a seconda che tu abbia dati non strutturati con metadati, dati strutturati o dati del sito web. Per ulteriori informazioni, consulta Filtrare la ricerca generica per dati strutturati o non strutturati e Filtrare la ricerca sul sito web.

    Comando e risultato di esempio

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:answer"
-d '{
"query": { "text": "Compare bigquery with spanner database?"},
"session":  "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
}'
    
    
{
  "answer": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072",
    "state": "SUCCEEDED",
    "answerText": "BigQuery and Spanner are both powerful tools that can be used together to handle transactional and analytical workloads. Spanner is a fully managed relational database optimized for transactional workloads, while BigQuery is a serverless data warehouse designed for business agility. Spanner provides seamless replication across regions in Google Cloud and processes over 1 billion requests per second at peak. BigQuery analyzes over 110 terabytes of data per second. Users can leverage federated queries to read data from Spanner and write to a native BigQuery table. \n",
    "steps": [
      {
        "state": "SUCCEEDED",
        "description": "Rephrase the query and search.",
        "actions": [
          {
            "searchAction": {
              "query": "Compare bigquery with spanner database?"
            },
            "observation": {
              "searchResults": [
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/ecc0e7547253f4ca3ff3328ce89995af",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/how-spanner-and-bigquery-work-together-handle-transactional-and-analytical-workloads",
                  "title": "How Spanner and BigQuery work together to handle transactional and analytical workloads | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "Using Cloud \u003cb\u003eSpanner\u003c/b\u003e and \u003cb\u003eBigQuery\u003c/b\u003e also allows customers to build their \u003cb\u003edata\u003c/b\u003e clouds using Google Cloud, a unified, open approach to \u003cb\u003edata\u003c/b\u003e-driven transformation ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/d7e238f73608a860e00b752ef80e2941",
                  "uri": "https://cloud.google.com/blog/products/databases/cloud-spanner-gets-stronger-with-bigquery-federated-queries",
                  "title": "Cloud Spanner gets stronger with BigQuery-federated queries | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "As enterprises compete for market share, their need for real-time insights has given rise to increased demand for transactional \u003cb\u003edatabases\u003c/b\u003e to support \u003cb\u003edata\u003c/b\u003e ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/e10a5a3c267dc61579e7c00fefe656eb",
                  "uri": "https://cloud.google.com/blog/topics/developers-practitioners/replicating-cloud-spanner-bigquery-scale",
                  "title": "Replicating from Cloud Spanner to BigQuery at scale | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... \u003cb\u003eSpanner data\u003c/b\u003e into \u003cb\u003eBigQuery\u003c/b\u003e for analytics. In this post, you will learn how to efficiently use this feature to replicate large tables with high throughput ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                },
                ...
                {
                  "document": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/8100ad36e1cac149eb9fc180a41d8f25",
                  "uri": "https://cloud.google.com/blog/products/gcp/from-nosql-to-new-sql-how-spanner-became-a-global-mission-critical-database",
                  "title": "How Spanner became a global, mission-critical database | Google Cloud Blog",
                  "snippetInfo": [
                    {
                      "snippet": "... SQL \u003cb\u003evs\u003c/b\u003e. NoSQL dichotomy may no longer be relevant." The \u003cb\u003eSpanner\u003c/b\u003e SQL query processor, while recognizable as a standard implementation, has unique ...",
                      "snippetStatus": "SUCCESS"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "session": {
    "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943",
    "state": "IN_PROGRESS",
    "userPseudoId": "test_user",
    "turns": [
      {
        "query": {
          "queryId": "projects/123456/locations/global/questions/741830",
          "text": "Compare bigquery with spanner database?"
        },
        "answer": "projects/123456/locations/global/collections/default_collection/engines/my-app/sessions/16002628354770206943/answers/4861507376861383072"
      }
    ],
    "startTime": "2024-09-13T18:47:10.465311Z",
    "endTime": "2024-09-13T18:47:10.465311Z"
  },
  "answerQueryToken": "NMwKDAjFkpK3BhDU24uZAhIkNjZlNDIyZWYtMDAwMC0yMjVmLWIxMmQtZjQwMzA0M2FkYmNj"
}

  4. Ripeti il passaggio 3 per ogni nuova query nella sessione.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def create_session(
    project_id: str,
    location: str,
    engine_id: str,
    user_pseudo_id: str,
) -> discoveryengine.Session:
    """Creates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        user_pseudo_id: A unique identifier for tracking visitors. For example, this
          could be implemented with an HTTP cookie, which should be able to
          uniquely identify a visitor on a single device.
    Returns:
        discoveryengine.Session: The newly created Session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    session = client.create_session(
        # The full resource name of the engine
        parent=f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}",
        session=discoveryengine.Session(user_pseudo_id=user_pseudo_id),
    )

    # Send Session name in `answer_query()`
    print(f"Session: {session.name}")
    return session

Recupera una sessione dal datastore

Il seguente comando mostra come chiamare il metodo get e recuperare una sessione dalldatastore.

REST

Per ottenere una sessione da un datastore:

  1. Esegui il seguente comando curl:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • SESSION_ID: l'ID della sessione che vuoi recuperare.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def get_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Retrieves a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = client.get_session(name=name)

    print(f"Session details: {session}")
    return session

Eliminare una sessione dall'app

Il comando seguente mostra come chiamare il metodo delete ed eliminare una sessione dall'datastore.

Per impostazione predefinita, le sessioni più vecchie di 60 giorni vengono eliminate automaticamente. Tuttavia, se vuoi eliminare una determinata sessione, ad esempio se contiene contenuti sensibili, utilizza questa chiamata API per eliminarla.

REST

Per eliminare una sessione da un'app:

  1. Esegui il seguente comando curl:

    curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • SESSION_ID: l'ID della sessione che vuoi eliminare.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def delete_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> None:
    """Deletes a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    client.delete_session(name=name)

    print(f"Session {name} deleted.")

Aggiornare una sessione

Esistono diversi motivi per cui potresti voler aggiornare una sessione. Ad esempio, per eseguire una delle seguenti operazioni:

  • Contrassegnare una sessione come completata
  • Unire i messaggi di una sessione in un'altra
  • Modificare lo pseudo ID di un utente

Il seguente comando mostra come chiamare il metodo patch e aggiornare una sessione nelldatastore.

REST

Per aggiornare una sessione da un'app:

  1. Esegui il seguente comando curl:

    curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions/SESSION_ID?updateMask=state" \
  -d '{
        "state": "NEW_STATE"
      }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • SESSION_ID: l'ID della sessione che vuoi aggiornare.
    • NEW_STATE: il nuovo valore per lo stato, ad esempio IN_PROGRESS.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine
from google.protobuf import field_mask_pb2


def update_session(
    project_id: str,
    location: str,
    engine_id: str,
    session_id: str,
) -> discoveryengine.Session:
    """Updates a session.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
        session_id: The ID of the session.
    Returns:
        discoveryengine.Session: The updated Session.
    """
    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the session
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}/sessions/{session_id}"

    session = discoveryengine.Session(
        name=name,
        state=discoveryengine.Session.State.IN_PROGRESS,  # Options: IN_PROGRESS, STATE_UNSPECIFIED
    )

    # Fields to Update
    update_mask = field_mask_pb2.FieldMask(paths=["state"])

    session = client.update_session(session=session, update_mask=update_mask)
    print(f"Updated session: {session.name}")
    return session

Elenca tutte le sessioni

Il seguente comando mostra come chiamare il metodo list e elencare le sessioni nelldatastore.

REST

Per elencare le sessioni di un'app:

  1. Esegui il seguente comando curl:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Elenca le sessioni per un utente

Il seguente comando mostra come chiamare il metodo list per elencare le sessioni associate a un utente o un visitatore.

REST

Per elencare le sessioni associate a un utente o un visitatore:

  1. Esegui il seguente comando curl:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • USER_PSEUDO_ID: lo pseudo ID dell'utente di cui vuoi elencare le sessioni.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response

Elenca le sessioni per un utente e uno stato

Il seguente comando mostra come chiamare il metodo list per elencare le sessioni in un determinato stato per un determinato utente.

REST

Per elencare le sessioni aperte o chiuse di un utente associate a un determinato utente o visitatore, procedi nel seguente modo:

  1. Esegui il seguente comando curl:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/sessions?filter=userPseudoId=USER_PSEUDO_ID%20AND%20state=STATE"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • USER_PSEUDO_ID: lo pseudo ID dell'utente di cui vuoi elencare le sessioni.
    • STATE: lo stato della sessione: STATE_UNSPECIFIED (chiusa o sconosciuta) o IN_PROGRESS (aperta).

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine_v1 as discoveryengine


def list_sessions(
    project_id: str,
    location: str,
    engine_id: str,
) -> discoveryengine.ListSessionsResponse:
    """Lists all sessions associated with a data store.

    Args:
        project_id: The ID of your Google Cloud project.
        location: The location of the app.
        engine_id: The ID of the app.
    Returns:
        discoveryengine.ListSessionsResponse: The list of sessions.
    """

    client = discoveryengine.ConversationalSearchServiceClient()

    # The full resource name of the engine
    parent = f"projects/{project_id}/locations/{location}/collections/default_collection/engines/{engine_id}"

    response = client.list_sessions(
        request=discoveryengine.ListSessionsRequest(
            parent=parent,
            filter='state="IN_PROGRESS"',  # Optional: Filter requests by userPseudoId or state
            order_by="update_time",  # Optional: Sort results
        )
    )

    print("Sessions:")
    for session in response.sessions:
        print(session)

    return response