Challenge 00 - Prerequisites - Ready, Set, GO!

Home - Next Challenge >

Introduction

Thank you for participating in the OpenAI Fundamentals What The Hack. Before you can hack, you will need to set up some prerequisites.

Description

In this challenge, you will set up the necessary prerequisites and environment to complete the rest of the hack, including:

Azure Subscription

You will need an Azure subscription to complete this hack. If you don’t have one, get a free trial here…

Setup Jupyter Notebook Environment

You will be working with Jupyter Notebooks and Python to interact with Azure OpenAI for the hack.

Jupyter Notebooks are an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. It’s useful for a wide range of tasks, such as data cleaning and transformation, numerical simulation, statistical modeling, data visualization, and machine learning.

Jupyter notebooks require an environment to run in.

You can use GitHub Codespaces where we have a pre-configured Jupyter lab environment set up and ready to go for you, or you can setup a Jupyter lab environment on your local workstation.

A GitHub Codespace is a development environment that is hosted in the cloud that you access via a browser. All of the pre-requisite developer tools for this hack are pre-installed and available in the codespace.

We highly recommend using GitHub Codespaces to make it easier to complete this hack.

Use GitHub Codespaces

You must have a GitHub account to use GitHub Codespaces. If you do not have a GitHub account, you can Sign Up Here.

GitHub Codespaces is available for developers in every organization. All personal GitHub.com accounts include a monthly quota of free usage each month. GitHub will provide users in the Free plan 120 core hours, or 60 hours of run time on a 2 core codespace, plus 15 GB of storage each month.

You can see your balance of available codespace hours on the GitHub billing page.

The GitHub Codespace for this hack will host the Jupyter Notebook files, configuration files, and other data files needed for this event. Here are the steps you will need to follow:

NOTE: Make sure you do not sign in with your enterprise managed Github account.

Once you are signed in:

Your Codespace environment should load in a new browser tab. It will take approximately 3-5 minutes the first time you create the codespace for it to load.

You are ready to run the Jupyter Notebook files, hooray! Skip to section: Setup Microsoft Foundry Project

NOTE: If you close your Codespace window, or need to return to it later, you can go to GitHub Codespaces and you should find your existing Codespaces listed with a link to re-launch it.

Use Local Workstation

NOTE: You can skip this section if are using GitHub Codespaces!

If you want to setup a Jupyter Notebooks environment on your local workstation, expand the section below and follow the requirements listed.

Click to expand/collapse Local Workstation Requirements

To work on your local workstation, please ensure you have the following tools and resources before hacking:

Student Resources

The Jupyter notebooks, starter code, and sample data sources for this hack are available in a Student Resources package.

The rest of the challenges will refer to the relative paths inside the Resources.zip file where you can find the various resources to complete the challenges.

Visual Studio Code

Visual Studio Code is a code editor which you will work with Jupyter notebooks.

Setup GitHub Copilot

For parts of this hack we will be relying heavily on GitHub Copilot for coding. Please setup VS Code with GitHub Copilot

Python
  • Python Installation, version at least >= 3.6, the minimum requirement for using OpenAI’s GPT-3.5-based models, such as ChatGPT.
Conda
  • Conda Installation, for project environment management and package management, version >= conda 4.1.6. Anaconda distribution is a popular Python distribution, while Miniconda is the lightweight version of Anaconda.
  • Environment setup:
    • Open Anaconda Prompt or your favourite terminal and verify Python and Conda installations using python --version and conda --version
    • Create a project environment using Conda - conda create --name <env_name>
    • Activate Conda environment - conda activate <env_name>
    • Install required libraries and packages, provided in the form of a requirements.txt file in the root folder of the Resources.zip file. We recommend using pip or Conda in a virtual environment to do so. For example, you can run pip install -r requirements.txt
    • Open the project in VS Code using code .
    • If you are using Visual Studio Code, make sure you change your Python interpreter (CTRL+SHIFT+P) to select the project/virtual environment that you just created.

For more information, see Jupyter Notebooks in VS Code

Azure CLI (Optional)

While it is not necessary for this hack, you may wish to use the Azure CLI to interact with Azure in addition to the Azure Portal.

Cloud Environment

There is a THIRD way of setting up a Jupyter Notebook environment if you don’t want to set it up on your local workstation or use GitHub Codespaces. You can set one up in the cloud with Azure Machine Learning Studio and take advantage of Azure Compute power.

For more information, see: Run Jupyter Notebooks in your Workspace

Once you have an Azure Machine Learning Studio Workspace set up, you can upload the contents of the /notebooks folder in your Resources.zip file to it. For more information on this, see: How to create and manage files in your workspace


Deploy Microsoft Foundry Resources

Now that you have a Jupyter notebook environment setup, you need to:

We have provided an automation script that will perform these tasks for you. However, you may wish to complete these tasks manually to become more familiar with Microsoft Foundry.

NOTE: If you are limited on time, we recommend using the automation script option.

Automate Microsoft Foundry Deployment

We have provided a deployment script and a set of Bicep templates which will deploy and configure the Azure AI resources which you will use for this hackathon. You can find these files in the /infra folder of your Codespace or the student Resources.zip package.

Login to the Azure CLI from the terminal in your GitHub Codespace or local workstation:

az login

NOTE: If you have access to multiple Azure subscriptions, you may need to switch to the subscription you want to work with.

If you are using GitHub Codespaces, the az login command will use a Device Code to login. If your organization’s Azure policy prevents this, follow these steps as an alternative:

Execute the following commands in your GitHub Codespace or local workstation terminal window to initiate the deployment:

cd infra
chmod +x deploy.sh
./deploy.sh

NOTE: By default, the script will create an Azure resource group for you named rg-microsoft-foundry-secure. You may optionally specify a resourceGroupName and/or location parameters if you need the resources deployed to a specific resource group or region. The default location is “eastus” if you don’t specify one.

./deploy.sh --resourceGroupName "[resource-group-name]" --location "[location]"

Manual Microsoft Foundry Deployment

NOTE: You can skip this section if you chose to automate the deployment. It is strongly recommended that you use the automated approach. If you’d like to understand more what the automated approach is doing, you can use GitHub Copilot to explain what the deployment script and associated Bicep files are doing.

If you want to deploy the Microsoft Foundry resources, expand the section below and follow instructions there.

Click to expand/collapse Manual Deployment Instructions

Setup Azure Microsoft Foundry Project

Navigate to Microsoft Foundry to create your Microsoft Foundry project.

  • Click on the + Create New button.
  • Choose Microsoft Foundry resource for the resource type. Click the Next button
    • Fill out a name for your project. Note: You should not need to specify Advanced Options unless you need or want to change the region because of capacity constraints. Click the Create button
  • From the Azure portal (or you can use an Infrastructure as Code approach if you prefer using Bicep/Terraform/ARM/CLI)
    • Create an Azure AI Search service
    • Specify a service name for your Azure AI Search. You can use the same resource group and location as the Microsoft Foundry resource. Note: Make sure you set the Pricing Tier to Standard (Basic/Free is not supported)

Deploy Azure OpenAI Models

Now we will deploy the needed large language models from Azure OpenAI.

  • Navigate to the Microsoft Foundry
  • On the left navigation bar, under My Assets, click on Models + endpoints. Click the Deploy Model button and select Deploy base model
  • Deploy the following 3 models in your Azure OpenAI resource.
    • gpt-4o
    • gpt-4o-mini
    • text-embedding-ada-002

Setup Jupyter Notebooks Configuration File

The code in the Jupyter notebooks retrieve their configuration values from environment variables configured in a .env file. Some of these configuration values are secrets (such as the key to access your Azure OpenAI resource).

NOTE: A .env file should never be stored in a Git repo. Therefore, we have provided a sample file named .env.sample that contains a list of environment variables required by the Jupyter notebooks.

You will find the .env.sample file in the root of the codespace. If you are working on your local workstation, you will find the .env.sample file in the root of the folder where you have unpacked the student Resources.zip file.

  • Rename the file from .env.sample to .env.
  • Add all the required Azure resource credentials in the .env file. This includes: Azure OpenAI, model deployments, AI Search, Azure Document Intelligence, and Azure Blob
    • For Azure OpenAI and Model Deployments, you can find these credentials in Azure Microsoft Foundry:
      • Navigate to the Microsoft Foundry
      • You will need the values for OPENAI_API_BASE, AZURE_DOC_INTELLIGENCE_ENDPOINT, AZURE_AI_SEARCH_ENDPOINT, AZURE_AI_PROJECT_ENDPOINT, and AZURE_BLOB_STORAGE_ACCOUNT_NAME to put in your .env file. Use your favorite search tool or Github Copilot to figure out where to retrieve these values either in the Foundry Portal, Azure Portal, or using the Azure CLI.

    TIP: Learn more about using .env files here.

NOTE: We have also provided a .gitignore file that should prevent you from accidentally committing your own .env file to a Git repo during this hack.

NOTE: On MacOS, files that start with a . are hidden files and are not viewable in Finder when browsing the file system. They will be visible in both VS Code or GitHub Codespaces.

</br>

Success Criteria

To complete this challenge successfully, you should be able to:

If using GitHub Codespaces:

If working on a local workstation:

Learning Resources