Merge pull request microsoft#296 from nitya/main

Moved env setup to separate file for potential reuse.

04-prompt-engineering-fundamentals/1-introduction.ipynb

@@ -251,7 +251,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.10.13"
   },
   "orig_nbformat": 4
  },

04-prompt-engineering-fundamentals/README.md

@@ -2,9 +2,9 @@
 
 [![Prompt Engineering Fundamentals](./images/04-lesson-banner.png?WT.mc_id=academic-105485-koreyst)](https://youtu.be/r2ItK3UMVTk?WT.mc_id=academic-105485-koreyst)
 
-How you write your prompt to the LLM matters, a carefully crafted prompt can achieve a better result than one that isn't. But what even are these concepts, prompt, prompt engineering and how do I improve what I send to the LLM? Questions like these are what this chapter and the upcoming chapter are looking to answer.
+The way your write your prompt to an LLM also matters. A carefully-crafted prompt can achieve a better quality of response. But what exactly do terms like _prompt_ and _prompt engineering_ mean? And how do I improve the prompt _input_ that I send to the LLM? These are the questions we'll try to answer with in this chapter and the next.
 
-_Generative AI_ is capable of creating new content (e.g., text, images, audio, code etc.) in response to user requests. It achieves this using _Large Language Models_ (LLMs) like OpenAI's GPT ("Generative Pre-trained Transformer") series that are trained for using natural language and code.
+_Generative AI_ is capable of creating new content (e.g., text, images, audio, code etc.) in response to user requests. It achieves this using _Large Language Models_ like OpenAI's GPT ("Generative Pre-trained Transformer") series that are trained for using natural language and code.
 
 Users can now interact with these models using familiar paradigms like chat, without needing any technical expertise or training. The models are _prompt-based_ - users send a text input (prompt) and get back the AI response (completion). They can then "chat with the AI" iteratively, in multi-turn conversations, refining their prompt till the response matches their expectations.
 
@@ -27,14 +27,9 @@ Prompt engineering is currently more art than science. The best way to improve o
 
 The Jupyter Notebook accompanying this lesson provides a _sandbox_ environment where you can try out what you learn - as you go, or as part of the code challenge at the end. To execute the exercises you will need:
 
-1. An Azure OpenAI API key - the service endpoint for a deployed LLM.
-
-2. A Python Runtime - in which the Notebook can be executed.
-
-We have instrumented this repository with a _dev container_ that comes with a Python 3 runtime. Simply open the repo in GitHub Codespaces or on your local Docker Desktop, to activate the runtime automatically. Then open the notebook and select the Python 3.x kernel to prepare the Notebook for execution.
-
-The default notebook is set up for use with an Azure OpenAI service resource. Simply copy the `.env.copy` file in the root of the folder to `.env` and update the `AZURE_OPENAI_API_KEY=` and `AZURE_OPENAI_API_ENDPOINT=` lines with your API key and endpoint. You can check your credentials in the [Azure portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst), by navigating to your Azure OpenAI resource and then opening the _Keys and Endpoints_ tab in the left menu.
-Also, please add the name you assigned to your model when you created the deployment to the `AZURE_OPENAI_DEPLOYMENT` variable. The recommended model for this exercise is 'gpt-35-turbo'.
+1. **An Azure OpenAI API key** - the service endpoint for a deployed LLM.
+2. **A Python Runtime** - in which the Notebook can be executed.
+3. **Local Env Variables** - *complete the [SETUP](SETUP.md) steps now to get ready*.
 
 The notebook comes with _starter_ exercises - but you are encouraged to add your own _Markdown_ (description) and _Code_ (prompt requests) sections to try out more examples or ideas - and build your intuition for prompt design.
 

04-prompt-engineering-fundamentals/SETUP.md

@@ -0,0 +1,72 @@
+# Setup Your Dev Environment
+
+We have instrumented this repository with a _dev container_ that comes with a Python 3 runtime. Simply open the repo in GitHub Codespaces or on your local Docker Desktop, to activate the runtime automatically. Then open th Jupyter notebook and select the Python 3.x kernel to prepare the Notebook for execution.
+
+## 1. Create `.env` file
+
+The default notebook is set up for use with an [Azure OpenAI service resource](https://learn.microsoft.com/azure/ai-services/openai?WT.mc_id=academic-105485-koreyst). To configure this, we need to setup local environment variables for Azure as follows:
+
+1. Look in the root folder for a `.env.copy` file. It should contain a list of name-value pairs like this:
+
+    ```bash
+    AZURE_OPENAI_ENDPOINT='<add your endpoint here>'
+    AZURE_OPENAI_DEPLOYMENT='<add your deployment name here>' 
+    AZURE_OPENAI_KEY='<add your key here>'
+    AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your deployment name here>'
+    ```
+
+2. Make a copy of that file called `.env` using a command like this at the terminal:
+    ```bash
+    cp .env.copy .env
+    ```
+    This should create an identical copy _except that this file is .gitignore-d and will never get checked into source control_. We can now populate **this .env file** with the environment variable values (secrets) without fear of them being checked in accidentally. You can now move to the next section to start populating these variables.
+
+3. (Option) If you use GitHub Codespaces, you have the option to save environment variables as _Codespaces secrets_ associated with this repository. In that case, you won't need to setup a local .env file. **However, note that this option works only if you use GitHub Codespaces.** You will still need to setup the .env file if you use Docker Desktop instead.
+
+
+## 2. Populate `.env` file
+
+Let's take a quick look at the variable names to understand what they represent:
+
+| Variable | Description |
+|:---|:---|
+|AZURE_OPENAI_ENDPOINT| This is the deployed endpoint for an Azure OpenAI resource|
+|AZURE_OPENAI_KEY | This is the authorization key for using that service  |
+|AZURE_OPENAI_DEPLOYMENT| This is the _text generation_ model deployment endpoint |
+|AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT | This is the _text embeddings_ model deployment endpoint |
+| | | 
+
+For context, the last two variables refer to specific models that are used in chat completion (text generation model) and vector search (embeddings model) activities that are frequently used in generative AI applications. In the following sections, we'll locate the _values_ for these variables and set them in `.env` (replacing the content within the `' '`, but preserving the quotes).
+
+### 2.1 Use Azure Portal
+
+The Azure OpenAI endpoint and key values will be found in the [Azure Portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst) so let's start there.
+
+1. Navigate to the [Azure Portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst)
+1. Click the **Keys and Endpoint** option in the sidebar (menu at left).
+1. Click **Show Keys** - you should see the following: KEY 1, KEY 2 and Endpoint.
+1. Use the KEY 1 value for AZURE_OPENAI_KEY
+1. Use the Endpoint value for AZURE_OPENAI_ENDPOINT
+
+Next, we need the endpoints for the specific models we've deployed.
+1. Click the **Model deployments** option in the sidebar (left menu) for Azure OpenAI resource.
+1. In the destination page, click **Manage Deployments** 
+
+This will take you to the Azure OpenAI Studio website, where we'll find the other values as described below.
+
+### 2.2 Use Azure OpenAI Studio
+
+1. Navigate to [Azure OpenAI Studio](https://oai.azure.com?WT.mc_id=academic-105485-koreyst) **from your resource** as described above.
+1. Click the **Deployments** tab (sidebar, left) to view currently deployed models.
+1. If your desired model is not deployed, use **Create new deployment** to deploy it.
+1. You will need a _text-generation_ model - we recommend: **gpt-35-turbo**
+1. You will need a _text-embedding_ model - we recommend **text-embedding-ada-002**
+
+Now update the environment variables to reflect the _Deployment name_ used. This will typically be the same as the model name unless you changed it explcitly. So, as an example, you might have:
+
+```bash
+AZURE_OPENAI_DEPLOYMENT='gpt-35-turbo' 
+AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-ada-002'
+```
+
+**Don't forget to save the .env file when done**. You can now exit the file and return to the instructions for running the notebook.