Initialize a RAG Application


This feature is in Private Preview. To try it, reach out to your Databricks contact.

Looking for a different RAG Studio doc? Go to the RAG documentation index

The following guide walks you through initializing a RAG Studio application.


The steps in this tutorial are done once per app to initialize your application’s code base. The steps in the remainder of the tutorials are repeated throughout your development process as you iterate on versions of the application.

Step 1: Initialize your development environment

  1. Follow the steps in Development Environment Setup to configure your development environment.

  2. Extract the RAG Studio Asset Bundle template to your home directory

    mkdir ~/.rag_studio
    cd ~/.rag_studio
    curl -O <URL to zip file provided by your Databricks contact>


    This step is only required due to the Private Preview status of the product.

Step 2: Configure the required infrastructure

Follow the steps in the Infrastructure Setup guide to create the required infrastructure.

By default, RAG Studio provisions new job clusters for tasks like data ingestion, RAG chain creation, and evaluation. For more information on cluster requirements, including instructions to instead use an interactive cluster, see Clusters.

Step 3: Initialize the application

  1. Open the terminal on your development machine and change to the directory you want to hold the application’s code base

  2. Initialize the sample application using the Asset Bundle template


    If you have multiple Databricks CLI profiles configured in ~/.databrickscfg, RAG Studio will use the default profile for creating your app.

    databricks bundle init ~/.rag_studio/rag-studio-0.0.0a2/
    > RAG Studio app name (e.g. hr-bot): databricks-docs-bot
    > Existing catalog name: <catalog-name>
    > Existing Unity Catalog schema name: <schema-name>
    > The secret scope used to access vector search endpoint: <secret-scope>
    > The secret key used to access vector search endpoint: <secret-key>
    ✨ Your Rag Studio workspace has been created in the 'databricks-docs-bot' directory!
    Please refer to the of your project for further instructions on getting started.


    Read the directory stucture reference doc to understand how the code base is structured.

  3. Change to the (new) folder databricks-docs-bot inside ~/rag_studio. The folder is named based on the app name you provided.

    cd databricks-docs-bot
  4. Install the required Python libraries

    pip install -r requirements.txt
  5. At this point, your environment is set up and you are ready to start development. Before we continue, let’s understand the ./rag command line interface - this interface is used to execute RAG Studio’s various workflows and tasks. Throughout the tutorial, we will show you how to use these commands, but you can always run ./rag --help or ./rag name-of-command --help to understand how to use a specific command.

    ./rag --help
    Usage: rag [OPTIONS] COMMAND [ARGS]...
      -h, --help  Show this message and exit.
      create-rag-version  Create and deploy a new version of the RAG chain...
      deploy-chain        Deploy the chain model for a given RAG version
      explore-eval        Run the exploration notebook on the evaluation results
      ingest-data         (Dev environment only) Ingest raw data from data...
      run-offline-eval    Run offline evaluation for a given chain version...
      run-online-eval     Run online evaluation on the currently-logged...
      setup-prod-env      Set up the EnvironmentName.REVIEWERS and...
      start-review        Start the review process for a given chain model...

Understanding how RAG Studio deployment jobs work

Deployment jobs in RAG Studio are managed with the ./rag command-line utility. When you start a deployment job, the job is run using Databricks Jobs on a compute cluster. In future releases, these deployment steps will not require provisioning a compute cluster.


If you press CTRL+C to terminate a deployment command, if the deployment job has started, it will remain running in the background. To stop the job, go to the URL printed in the console to stop the job in the Databricks Workflow UI.


By default, RAG Studio will provision new compute for each deployment job. If you prefer to use an existing compute cluster, you can pass -c <cluster-id> to any ./rag command. Alternatively, you can set a cluster_id in config/rag-config.yml in environment_config.development.cluster_id. Note that this only works in the development Environment.

To find <cluster-id> for your compute, open the cluster in the Databricks UI. In the cluster’s URL, the <cluster-id> is 0126-194718-ucabc7oi: https://<workspace-url>/?o=123456798#setting/clusters/0126-194718-ucabc7oi/configuration.

If you opt to use your own compute, ensure the cluster is using the MLR 13.3 runtime.

Step 4: Initialize the Environments

  1. Run the following command to initialize these Environments. This command takes about 10 minutes to run.

    ./rag setup-prod-env


    See Infrastructure and Unity Catalog assets created by RAG Studio for details of what is created in your Workspace and Unity Catalog schema.


    You can safely ignore warnings about multiple versions of the Databricks CLI.

    Databricks CLI v0.212.1 found at /opt/homebrew/bin/databricks

    Your current $PATH prefers running CLI v0.18.0 at /<your env path>/bin/databricks

    Because both are installed and available in $PATH, I assume you are trying to run the newer version. If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Step 5: Ingest sample data for your application


The default 📥 Data Ingestor downloads the Databricks documentation. You can modify the code in src/notebooks/ to ingest from another source or adjust config/rag-config.yml to use data from that already exists in a Unity Catalog Volume. The default 🗃️ Data Processor that ships with RAG Studio only supports HTML files. If you have other file types in your Unity Catalog Volume, follow the steps in Creating a 🗃️ Data Processor version to adjust the 🗃️ Data Processor code.

  1. Run the following command to start the data ingestion process. The default application will download the Databricks documentation to a Unity Catalog volume in your configured UC schema. This step takes approximately 10 minutes.


    The Unity Catalog catalog and schema are the ones that you configured in Step 3.

    ./rag ingest-data -e dev
  2. You will see the following message in your console when the ingestion completes.

    Run URL: <URL to the deployment Databricks Job>
    <timestamp> "[dev e] [databricks-docs-bot][dev] ingest_data" RUNNING
    <timestamp> "[dev e] [databricks-docs-bot][dev] ingest_data" TERMINATED SUCCESS
    Successfully downloaded and uploaded Databricks documentation articles to UC Volume '`catalog`.`schema`.`raw_databricks_docs`'%

Follow the next tutorial!

Ingest or connect raw data