Jump Start Solution: Generative AI Knowledge Base

Last reviewed 2024-03-01 UTC

This guide helps you understand and deploy the Generative AI Knowledge Base solution. This solution demonstrates how to build an extractive question-answering (EQA) pipeline to produce content for an internal knowledge base.

This document is intended for developers who have some background with LLMs. It assumes that you're familiar with basic cloud concepts, though not necessarily Google Cloud. Experience with Terraform is helpful.

Objectives

This solution guide helps you do the following:

  • Deploy an application that extracts question-and-answer pairs from your documents, along with a pipeline that triggers your application when a document is uploaded.
  • Train a prompt-based AI model using the output from your application.

Architecture

This solution deploys a Generative AI Knowledge Base application. The following diagram shows the architecture of the application infrastructure:

Architecture diagram of an application that uses Vertex AI Generative AI to extract question-and-answer pairs from documents

Request flow

The following steps detail the request processing flow of the application. The steps in the flow are numbered as shown in the preceding architecture diagram.

You start the Generative AI Knowledge Base application by uploading a document directly to a Cloud Storage bucket, either through the Google Cloud console or gcloud CLI.

  1. When the document is uploaded, it triggers a Cloud Function. This function runs the Extractive Question-Answering process.

  2. The function uses Document AI OCR to extract all text from the document.

  3. The function indexes the document into Vector Search. The Vector Search index provides context for the LLM to extract question-and-answer pairs based only on content that's extracted directly from the uploaded documents.

  4. The function uses Vertex AI to extract and generate questions and answers from the document.

  5. The function stores the extracted question-and-answer pairs in Firestore.

  6. A JSONL fine tuning dataset is generated from the Firestore database and stored in Cloud Storage.

  7. After manually validating that you are satisfied with the dataset, you can launch a fine tuning job on Vertex AI.

    When the tuning job is complete, the tuned model is deployed to an endpoint. After it's deployed to an endpoint, you can submit queries to the tuned model in a Colab notebook, and compare it with the foundation model.

Products used

This section describes the products that the solution uses.

If you're familiar with the Terraform configuration language, you can change some of the settings for the services.

Component Product description Purpose in this solution
Cloud Storage An enterprise-ready service that provides low-cost, no-limit object storage for diverse data types. Stores the PDF documents, extracted text, tuning dataset, and tuned model.
Eventarc A service that manages the flow of state changes (events) between decoupled microservices, routing events to various destinations while managing delivery, security, authorization, observability, and error handling. Watches for new documents in the Cloud Storage bucket and triggers an event in Cloud Functions.
Cloud Functions A lightweight serverless compute service that lets you create single-purpose, standalone functions that respond to Google Cloud events without the need to manage a server or runtime environment. Orchestrates the document processing steps.
Document AI A document understanding platform that takes unstructured data from documents and transforms it into structured data. You can automate tedious tasks, improve data extraction, and gain deeper insights from data. Extracts the text from the documents.
Vertex AI A machine learning platform that lets you train, test, tune, and deploy LLMs and generative AI applications. Generates questions and answers from the documents.
Vector Search A service that lets you use the same infrastructure that provides a foundation for Google products such as Google Search, YouTube, and Play. Lets you search embeddings to find semantically similar or related entities.
Firestore A fully managed, low-latency file system for VMs and clusters that offers high availability and high throughput. Stores the generated questions and answers.

Cost

For an estimate of the cost of the Google Cloud resources that the generative ai knowledge base solution uses, see the precalculated estimate in the Google Cloud Pricing Calculator.

Use the estimate as a starting point to calculate the cost of your deployment. You can modify the estimate to reflect any configuration changes that you plan to make for the resources that are used in the solution.

The precalculated estimate is based on assumptions for certain factors, including the following:

  • The Google Cloud locations where the resources are deployed.
  • The amount of time that the resources are used.

  • The amount of data stored in Cloud Storage.

  • The number of times the knowledge base application is invoked.

  • The computing resources used for tuning the model.

Before you begin

To deploy this solution, you first need a Google Cloud project and some IAM permissions.

Create or choose a Google Cloud project

When you deploy the solution, you choose the Google Cloud project where the resources are deployed. When you're deciding whether to use an existing project or to create a new project, consider the following factors:

  • If you create a project for the solution, then when you no longer need the deployment, you can delete the project and avoid continued billing. If you use an existing project, you must delete the deployment when you no longer need it.
  • Using a new project can help avoid conflicts with previously provisioned resources, such as resources that are used for production workloads.

If you want to deploy the solution in a new project, create the project before you begin the deployment.

To create a project, complete the following steps:

  1. In the Google Cloud console, go to the project selector page.

    Go to project selector

  2. To begin creating a Google Cloud project, click Create project.

  3. Name your project. Make a note of your generated project ID.

  4. Edit the other fields as needed.

  5. To create the project, click Create.

Get the required IAM permissions

To start the deployment process, you need the Identity and Access Management (IAM) permissions that are listed in the following table. If you have the roles/owner basic role for the project in which you plan to deploy the solution, then you already have all the necessary permissions. If you don't have the roles/owner role, then ask your administrator to grant these permissions (or the roles that include these permissions) to you.

IAM permission required Predefined role that includes the required permissions

serviceusage.services.enable

Service Usage Admin
(roles/serviceusage.serviceUsageAdmin)

iam.serviceAccounts.create

Service Account Admin
(roles/iam.serviceAccountAdmin)

resourcemanager.projects.setIamPolicy

Project IAM Admin
(roles/resourcemanager.projectIamAdmin)
config.deployments.create
config.deployments.list
Cloud Infrastructure Manager Admin
(roles/config.admin)

Service account created for the solution

If you start the deployment process through the console, Google creates a service account to deploy the solution on your behalf (and to delete the deployment later if you choose). This service account is assigned certain IAM permissions temporarily; that is, the permissions are revoked automatically after the solution deployment and deletion operations are completed. Google recommends that after you delete the deployment, you delete the service account, as described later in this guide.

View the roles that are assigned to the service account

These roles are listed here in case an administrator of your Google Cloud project or organization needs this information.

  • roles/aiplatform.user
  • roles/artifactregistry.admin
  • roles/documentai.editor
  • roles/firebase.admin
  • roles/iam.serviceAccountUser
  • roles/serviceusage.serviceUsageAdmin
  • roles/iam.serviceAccountAdmin
  • roles/resourcemanager.projectIamAdmin

Deploy the solution

To help you deploy this solution with minimal effort, a Terraform configuration is provided in GitHub. The Terraform configuration defines all the Google Cloud resources that are required for the solution.

You can deploy the solution by using one of the following methods:

  • Through the console: Use this method if you want to try the solution with the default configuration and see how it works. Cloud Build deploys all the resources that are required for the solution. When you no longer need the deployed solution, you can delete it through the console. Any resources that you create after you deploy the solution might need to be deleted separately.

    To use this deployment method, follow the instructions in Deploy through the console.

  • Using the Terraform CLI: Use this method if you want to customize the solution or if you want to automate the provisioning and management of the resources by using the infrastructure as code (IaC) approach. Download the Terraform configuration from GitHub, optionally customize the code as necessary, and then deploy the solution by using the Terraform CLI. After you deploy the solution, you can continue to use Terraform to manage the solution.

    To use this deployment method, follow the instructions in Deploy using the Terraform CLI.

Deploy through the console

Complete the following steps to deploy the preconfigured solution.

  1. In the Google Cloud Jump Start Solutions catalog, go to the Generative AI Knowledge Base solution.

    Go to the Generative AI Knowledge Base solution

  2. Review the information that's provided on the page, such as the estimated cost of the solution and the estimated deployment time.

  3. When you're ready to start deploying the solution, click Deploy.

    A step-by-step interactive guide is displayed.

  4. Complete the steps in the interactive guide.

    Note the name that you enter for the deployment. This name is required later when you delete the deployment.

    When you click Deploy, the Solution deployments page is displayed. The Status field on this page shows Deploying.

  5. Wait for the solution to be deployed.

    If the deployment fails, the Status field shows Failed. You can use the Cloud Build log to diagnose the errors. For more information, see Errors when deploying through the console.

    After the deployment is completed, the Status field changes to Deployed.

  6. To view the Google Cloud resources that are deployed and their configuration, take an interactive tour in the console.

    Start the tour

For next steps, see Use the solution.

When you no longer need the solution, you can delete the deployment to avoid continued billing for the Google Cloud resources. For more information, see Delete the deployment.

Deploy using the Terraform CLI

This section describes how you can customize the solution or automate the provisioning and management of the solution by using the Terraform CLI. Solutions that you deploy by using the Terraform CLI are not displayed in the Solution deployments page in the Google Cloud console.

Set up the Terraform client

You can run Terraform either in Cloud Shell or on your local host. This guide describes how to run Terraform in Cloud Shell, which has Terraform preinstalled and configured to authenticate with Google Cloud.

The Terraform code for this solution is available in a GitHub repository.

  1. Clone the GitHub repository to Cloud Shell.

    Open in Cloud Shell

    A prompt is displayed to confirm downloading the GitHub repository to Cloud Shell.

  2. Click Confirm.

    Cloud Shell is launched in a separate browser tab, and the Terraform code is downloaded to the $HOME/cloudshell_open directory of your Cloud Shell environment.

  3. In Cloud Shell, check whether the current working directory is $HOME/cloudshell_open/terraform-genai-knowledge-base/. This is the directory that contains the Terraform configuration files for the solution. If you need to change to that directory, run the following command:

    cd $HOME/cloudshell_open/terraform-genai-knowledge-base/
    
  4. Initialize Terraform by running the following command:

    terraform init
    

    Wait until you see the following message:

    Terraform has been successfully initialized!
    

Configure the Terraform variables

The Terraform code that you downloaded includes variables that you can use to customize the deployment based on your requirements. For example, you can specify the Google Cloud project and the region where you want the solution to be deployed.

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-genai-knowledge-base/. If it isn't, go to that directory.

  2. In the same directory, create a text file named terraform.tfvars.

  3. In the terraform.tfvars file, copy the following code snippet, and set values for the required variables.

    • Follow the instructions that are provided as comments in the code snippet.
    • This code snippet includes only the variables for which you must set values. The Terraform configuration includes other variables that have default values. To review all the variables and the default values, see the variables.tf file that's available in the $HOME/cloudshell_open/terraform-genai-knowledge-base/ directory.
    • Make sure that each value that you set in the terraform.tfvars file matches the variable type as declared in the variables.tf file. For example, if the type that’s defined for a variable in the variables.tf file is bool, then you must specify true or false as the value of that variable in the terraform.tfvars file.
    # This is an example of the terraform.tfvars file.
    # The values in this file must match the variable types declared in variables.tf.
    # The values in this file override any defaults in variables.tf.
    
    # ID of the project in which you want to deploy the solution
    project_id = "PROJECT_ID"
    

Validate and review the Terraform configuration

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-genai-knowledge-base/. If it isn't, go to that directory.

  2. Verify that the Terraform configuration has no errors:

    terraform validate
    

    If the command returns any errors, make the required corrections in the configuration and then run the terraform validate command again. Repeat this step until the command returns the following message:

    Success! The configuration is valid.
    
  3. Review the resources that are defined in the configuration:

    terraform plan
    
  4. If you didn't create the terraform.tfvars file as described earlier, Terraform prompts you to enter values for the variables that don't have default values. Enter the required values.

    The output of the terraform plan command is a list of the resources that Terraform provisions when you apply the configuration.

    If you want to make any changes, edit the configuration and then run the terraform validate and terraform plan commands again.

Provision the resources

When no further changes are necessary in the Terraform configuration, deploy the resources.

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-genai-knowledge-base/. If it isn't, go to that directory.

  2. Apply the Terraform configuration:

    terraform apply
    
  3. If you didn't create the terraform.tfvars file as described earlier, Terraform prompts you to enter values for the variables that don't have default values. Enter the required values.

    Terraform displays a list of the resources that will be created.

  4. When you're prompted to perform the actions, enter yes.

    Terraform displays messages showing the progress of the deployment.

    If the deployment can't be completed, Terraform displays the errors that caused the failure. Review the error messages and update the configuration to fix the errors. Then run the terraform apply command again. For help with troubleshooting Terraform errors, see Errors when deploying the solution using the Terraform CLI.

    After all the resources are created, Terraform displays the following message:

    Apply complete!
    
  5. To view the Google Cloud resources that are deployed and their configuration, take an interactive tour in the console.

    Start the tour

Next, you can use the solution and see how it works.

When you no longer need the solution, you can delete the deployment to avoid continued billing for the Google Cloud resources. For more information, see Delete the deployment.

Use the solution

Once the solution is deployed, you can upload a document to index it and ask questions about it. Additionally, a JSON lines (JSONL) tuning dataset file is generated, which you can use to prompt-tune an LLM.

Upload a document and query the model

Begin using this solution by uploading a document, then ask the pre-trained LLM questions about the document.

To follow step-by-step guidance for this task directly in Google Cloud console, click Guide me.

Guide me

This task takes about 10 minutes to complete.

Tune the LLM

After you upload documents for the solution, you can use Vertex AI to tune an LLM with your question-and-answer pairs. Tuning the LLM is not an automated process. Before you tune the LLM, inspect your data and make sure that it's valid and accurate. After you are satisfied with the data, you can manually launch a tuning job and launch the LLM from the Model Registry.

The JSONL tuning file contains extracted content from your question-and-answer pairs. Each line in the file is a JSON entry with input_text and output_text fields. The input_text field contains the content from each question, and the output_text contains content from each respective answer.

For example, the following JSONL file contains the question "How many people live in Beijing" and the respective answer:

{"input_text": "CONTEXT: With over 21 million residents, Beijing is the
 world's most populous national capital city and is China's second largest
 city after Shanghai. QUESTION: How many people live in Beijing?,
"output_text": "21 million people"}

To follow step-by-step guidance for tuning your model directly in Google Cloud console, click Guide me.

Guide me

This walkthrough takes about 10 minutes to complete, but the model tuning can take an hour or more to finish processing.

Delete the deployment

When you no longer need the solution, delete the deployment. When you delete the deployment, you are no longer billed for the resources that you created.

Before you delete

Before you delete this solution, delete the Vector Search index deployment:

  1. Go to the Vector Search page.

    Go to Vector Search

  2. Click knowledge-base-index.

  3. Under Deployed indexes, click more_vert More.

  4. Click Undeploy.

You don't need to wait for the index deletion process to finish.

Delete through the console

Use this procedure if you deployed the solution through the console.

  1. In the Google Cloud console, go to the Solution deployments page.

    Go to Solution deployments

  2. Select the project that contains the deployment that you want to delete.

  3. Locate the deployment that you want to delete.

  4. Click Actions and then select Delete.

  5. Enter the name of the deployment and then click Confirm.

    The Status field shows Deleting.

    If the deletion fails, see the troubleshooting guidance in Error when deleting a deployment.

When you no longer need the Google Cloud project that you used for the solution, you can delete the project. For more information, see Optional: Delete the project.