Generative AI Google Brain

Vertex AI Search - Best Practices

10 min read

Vertex AI Search — Best Practices

Distilled from 21 notebooks tagged Vertex AI Search in the GoogleCloudPlatform/generative-ai repository. The From the notebooks section below cites the per-notebook source for grounding.

Do this

  • Test Vertex AI Search directly with a SearchRequest before using it for grounding, RAG, LangChain retrieval, or an Agent Engine deployment.
  • Wait for data store creation, engine creation, schema updates, document import, indexing, and app availability to complete before assuming search or grounding failures are meaningful.
  • Use the correct Discovery Engine endpoint for the data store location; global can use the default endpoint, while us, eu, or other regional locations require location-specific client options or hosts.
  • Create both a data store and a search app or engine when the integration requires an app; several workflows fail or return errors when only the data store exists.
  • Use SEARCH_TIER_ENTERPRISE and SEARCH_ADD_ON_LLM when summaries, extractive answers, grounding quality, or advanced LLM search features are needed.
  • Enable snippets, summaries with citations, query expansion, and spell correction when validating search quality and answer grounding.
  • Inspect grounding metadata, citations, grounding chunks, grounding supports, retrieval queries, and search queries to verify which documents support generated answers.
  • Use low temperature settings for search agents and concise grounded-answer workflows where deterministic retrieval-grounded behavior is preferred.
  • For document ingestion, represent unstructured documents in JSONL with stable IDs, content MIME types, content URIs, and structData metadata when metadata should influence filtering or retrieval.
  • Define schema fields as retrievable, indexable, searchable, filterable, dynamicFacetable, or specially mapped before relying on them for results, filters, facets, boosts, or metadata display.
  • Use layout-based parsing, chunking, ancestor headings, and appropriate chunk token sizes for complex documents with tables, lists, or structured sections.
  • Use Cloud Storage or BigQuery as source-of-truth import sources for structured or unstructured content unless inline rawBytes ingestion is specifically required.
  • Choose reconciliation mode deliberately: INCREMENTAL for adding or updating content, FULL when replacing a tutorial data set or enforcing a complete import state.
  • Batch embedding calls, use TextEmbeddingInput with task_type=“RETRIEVAL_DOCUMENT” for retrieval documents, define embedding vectors in the schema, and configure custom embedding ranking only after schema preparation.
  • Clean up billable resources after experimentation, including engines, data stores, RAG corpora, deployed agents, staging buckets, synthetic user events, and temporary documents.

Avoid this

  • Searching or grounding immediately after creation or import can return empty results, 404 engine-not-found errors, or weak answers because indexing and long-running operations are still in progress.
  • Using the wrong location or endpoint for a data store causes query, document, or deletion calls to fail, especially outside global locations.
  • Forgetting to create a search app or engine in addition to the data store breaks integrations such as LangChain retrieval and Gemini grounding workflows that expect both resources.
  • Leaving required APIs, billing, authentication, service accounts, or roles unset blocks resource creation, document retrieval, recrawl functions, Agent Engine access, and Discovery Engine calls.
  • Assuming Enterprise features are available on basic configurations leads to missing extractive answers, summaries, grounding quality, or LLM add-on behavior.
  • Relying on raw notebook placeholders such as project ID, engine ID, data store ID, staging bucket, client ID, or URLs causes failures until they are replaced with real project values.
  • Using invalid IDs or unsupported content formats causes ingestion problems; datastore names are constrained to lowercase letters, numbers, and hyphens, and some workflows convert Markdown to PDF before import.
  • Treating post-processed or custom-ranked results as if Vertex AI Search still knows the final impression order can corrupt user-event attribution unless the final impressions list is explicitly reported.

From the notebooks

Building a Conversational Search Agent with Agent Engine and RAG on Vertex AI Search

  • Test the Vertex AI Search function directly before wiring it into the agent.
  • Test the agent locally before deploying it to Agent Engine.
  • Use ChatMessageHistory and session_id to preserve conversational context across follow-up questions.
  • Set deployment requirements explicitly so Agent Engine has the needed LangChain and Discovery Engine packages.
  • Use temperature 0 for the demonstrated search agent behavior.

Grounding with Vertex AI Search

  • Use environment variables for project and region defaults when parameters are not provided.
  • Create the Vertex AI Search engine with SEARCH_TIER_ENTERPRISE and SEARCH_ADD_ON_LLM for grounding quality.
  • Verify the search engine is ready by sending a SearchRequest before using it for grounded generation.
  • Inspect grounding_supports and grounding_chunks to understand which retrieved documents support the answer.
  • Delete the created engine and data store after the tutorial.

Intro to Grounding with Gemini in Vertex AI

  • Compare ungrounded and grounded responses to show the effect of grounding.
  • Use grounding metadata to display citations, grounding chunks, search queries, and retrieval queries.
  • Use Enterprise Web Search for web grounding when compliance requirements make Google Search logging unsuitable.
  • Use Vertex AI Search for internal documents that are not available on the public internet.
  • Delete projects, data stores, and disable APIs after the tutorial to avoid charges.

Vertex AI RAG Engine with Vertex AI Search

  • Use environment variables for GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_REGION when notebook parameters are not provided.
  • Use Vertex AI Search as the retrieval backend for large datasets, low-latency retrieval, and improved scalability.
  • Import documents from Cloud Storage using INCREMENTAL reconciliation mode.
  • Check the created corpus with rag.get_corpus before querying.
  • Clean up created RAG resources with rag.delete_corpus when delete_rag_corpus is enabled.

Building a photo recognition agent: Agent Engine setup

  • Pin setup dependencies for the notebook environment.
  • Restart the runtime after installing packages.
  • Initialize Vertex AI with project, location, and staging bucket before creating Agent Engine resources.
  • Define tool functions with typed arguments, docstrings, and dictionary responses.
  • Test the agent locally with agent.query before deploying it remotely.

Create a Vertex AI Datastore and Search Engine

  • Use ClientOptions with a regional discoveryengine endpoint when location is not global.
  • Use the default_collection parent path for datastore and engine creation.
  • Import documents into the default_branch from Cloud Storage using data_schema=“content”.
  • Use INCREMENTAL reconciliation mode for document import.
  • Enable SEARCH_TIER_ENTERPRISE and SEARCH_ADD_ON_LLM when summaries or advanced LLM features are needed.

Custom Embeddings with Vertex AI Search

  • Use TextEmbeddingInput with task_type=“RETRIEVAL_DOCUMENT” for document retrieval embeddings.
  • Batch embedding calls instead of embedding all texts at once.
  • Convert BigQuery integer IDs to strings before using them as document IDs.
  • Store HTML content in Cloud Storage and reference it from JSONL content.uri.
  • Define the embedding vector in the Discovery Engine schema before importing documents.

Clearbox for Ranking Tuning

  • Pin random seeds for reproducible training.
  • Compare trained models against individual signal baselines.
  • Train on reciprocal ranks for better stability across signal distribution changes.
  • Use ClearBox feature utilities such as FillNaN so production serving uses the same logic as training.
  • Make rank-like signals monotonically increasing before reciprocal-rank computation.

Gemini Enterprise custom agent with Vertex AI session

  • Use VertexAiSessionService when an agent needs persistent session state.
  • Split agent responsibilities into query completeness checking and itinerary generation.
  • Use a low temperature of 0.01 for the root agent configuration.
  • Use a session_service_builder when creating reasoning_engines.AdkApp.
  • Test the same multi-turn queries locally and through the remote Agent Engine app.

Intro to Gemini Enterprise

  • Fallback to the GOOGLE_CLOUD_PROJECT environment variable when PROJECT_ID is not supplied.
  • Use ClientOptions to select a regional Discovery Engine endpoint for non-global locations.
  • Include citations in both search summaries and generated answers.
  • Use query expansion and spell correction in the search request.
  • Use query rephrasing and query classification in the answer request.

Setup

  • Processes records in batches of 200 before calling the Rank API.
  • Uses ignore_record_details_in_response=True when only scores are needed.
  • Persists computed scores to Cloud Storage for reuse and inspection.
  • Filters evaluation to labeled datapoints to avoid underestimating model performance from unlabeled relevant examples.
  • Removes query-document pairs missing from either ground truth or predictions before metric calculation.

Search tuning in Vertex AI Search

  • Prepare datasets in JSONL format with identifier-text pairs.
  • Represent query-to-answer mappings in tab-separated TSV files.
  • Upload additional tuning documents and datasets to Cloud Storage before datastore refresh and tuning.
  • Use INCREMENTAL document import when adding files to the datastore.
  • Keep a baseline search result before tuning so it can be compared with post-tuning behavior.

Defining custom attributes based on URL patterns in Vertex AI Search Website Datastores

  • Use global datastore location unless there is a specific reason to use us or eu.
  • Verify schema and URL mapping with getUriPatternDocumentData after setting it.
  • Make custom attributes indexable, retrievable, and searchable when they should affect retrieval and appear in responses.
  • Poll datastore and app availability because creation can take a few minutes.
  • Delete the app and datastore when no longer needed.

Ingestion of Unstructured Documents with Metadata in Vertex AI Search

  • Use layout-based chunking with a 500 token chunk size and ancestor headings when accuracy on complex documents matters.
  • Provide an explicit metadata schema when fields must be retrievable, indexable, searchable, filterable, or specially mapped.
  • Represent each document as JSONL with id, structData, content.mimeType, and content.uri.
  • Poll long-running operations for schema updates and document imports before relying on the datastore.
  • Keep documents, metadata, and generated JSONL in the same temporary bucket when cleanup simplicity matters.

Inline Ingestion of Documents into Vertex AI Search

  • Use GCS buckets or BigQuery tables as a source of truth when importing structured or unstructured documents unless inline ingestion is required.
  • Use Incremental or Full reconciliation modes depending on the import strategy and conflict-resolution needs.
  • Set mimeType consistently with the source file format, such as application/pdf or text/plain.
  • Add structData metadata when it should influence search filtering.
  • Poll datastore availability after creation before continuing.

Event-based Triggering of Manual Recrawl for Vertex AI Search Advanced Website Datastores

  • Use a Cloud Storage staging bucket for JSON files containing URLs to recrawl.
  • Trigger processing on google.cloud.storage.object.v1.finalized events and filter for .json files.
  • Use functions-framework, described as the recommended way at the time of the notebook.
  • Fetch an access token with google-auth default credentials before calling the REST API.
  • Set a request timeout and retry connection or timeout failures up to three times.

Parsing and Chunking in Vertex AI Search: Featuring BYO Capabilities

  • Create the datastore with layout parser for complex documents containing tables and lists.
  • Include ancestor headings with chunks to preserve heading context.
  • Use incremental reconciliation for document and chunk imports.
  • Poll datastore creation and import long-running operations before retrieving processed documents.
  • Export chunked JSON to Cloud Storage for offline review or editing before BYOC import.

Query-Level Boosting, Filtering, and Facets for Vertex AI Search Website Datastores

  • Evaluate Vertex AI Search results without extra rules before incrementally adding custom filters or boosts.
  • Apply boosting and filtering during retrieval rather than post-processing search results.
  • Use metadata fields as schema hooks for filters, facets, and boost conditions.
  • Use facets to translate user preferences into subsequent filtered search requests.
  • Start with smaller boost values and adjust as needed.

Recording Real-Time User Events in Vertex AI Search Datastores

  • Report both search events and view-item events with the same attribution token.
  • Include the impressions shown to the user in the search event.
  • Use userPseudoId to associate events with a user without requiring a named account.
  • Use JavaScript Pixel as the recommended alternative when the customer can control the page source.
  • Purge synthetic notebook events after testing.

Q&A Chatbot with Vertex AI Search for summarized website results without advanced indexing

  • Initialize Vertex AI with project and location before model use.
  • Use query expansion and spell correction with AUTO mode in SearchRequest.
  • Request snippets with ContentSearchSpec.SnippetSpec(return_snippet=True).
  • Handle empty search responses and exceptions by returning None or a fallback message.
  • Use low temperature for concise grounded answer generation.

Building Search Applications with Vertex AI Search

  • Use a custom prompt that tells the assistant to answer only from grounding snippets and not make up information.
  • Enable snippets, summaries, citations, query expansion, and spell correction in direct search requests.
  • Use safety settings when generating Gemini responses.
  • Ground Gemini answers in the Vertex AI Search data store instead of relying only on model knowledge.
  • Use extractive answers and document limits when configuring the LangChain VertexAISearchRetriever.

Back to Vertex AI Search · Best Practices Map

Graph View

Backlinks