Skip to content

Commit 3ff33b2

Browse files
koreyspacekoreyspace
authored
Merge pull request #853 from angpt/main
Reorg docs to make it easier for beginners to follow
2 parents 1e52f87 + 1ff3355 commit 3ff33b2

File tree

6 files changed

+299
-46
lines changed

6 files changed

+299
-46
lines changed

‎00-course-setup/01-setup-cloud.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Cloud Setup ☁️ – GitHub Codespaces
2+
3+
**Use this guide if you don’t want to install anything locally.**
4+
Codespaces gives you a free, browser-based VS Code instance with all dependencies pre-installed.
5+
6+
---
7+
8+
## 1. Why Codespaces?
9+
10+
| Benefit | What it means for you |
11+
|---------|----------------------|
12+
| ✅ Zero installs | Works on Chromebook, iPad, school lab PCs… |
13+
| ✅ Pre-built dev container | Python 3, Node.js, .NET, Java already inside |
14+
| ✅ Free quota | Personal accounts get **120 core-hours / 60 GB-hours per month** |
15+
16+
> 💡 **Tip**
17+
> Keep your quota healthy by **stopping** or **deleting** idle codespaces
18+
> (View ▸ Command Palette ▸ *Codespaces: Stop Codespace*).
19+
20+
---
21+
22+
## 2. Create a Codespace (one click)
23+
24+
1. **Fork** this repo (top-right **Fork** button).
25+
2. In your fork, click **Code ▸ Codespaces ▸ Create codespace on main**.
26+
![ialog showing buttons to create a codespace](./images/who-will-pay.webp?WT.mc_id=academic-105485-koreyst)
27+
28+
✅ A browser VS Code window opens and the dev container starts building.
29+
This takes **~2 minutes** the first time.
30+
31+
## 3. Add your API key (the safe way)
32+
33+
### Option A Codespaces Secrets — Recommended
34+
35+
1. ⚙️ Gear icon -> Command Pallete-> Codespaces : Manage user secret -> Add a new secret.
36+
2. Name: OPENAI_API_KEY
37+
3. Value: paste your key → Add secret
38+
39+
That’s it—our code will pick it up automatically.
40+
41+
### Option B .env file (if you really need one)
42+
43+
```bash
44+
cp .env.copy .env
45+
code .env # fill in OPENAI_API_KEY=your_key_here
46+
```

‎00-course-setup/02-setup-local.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Local Setup 🖥️
2+
3+
**Use this guide if you prefer to run everything on your own laptop.**
4+
You have two paths: **(A) native Python + virtual-env** or **(B) VS Code Dev Container with Docker**.
5+
Choose whichever feels easier—both lead to the same lessons.
6+
7+
## 1. Prerequisites
8+
9+
| Tool | Version / Notes |
10+
|--------------------|--------------------------------------------------------------------------------------|
11+
| **Python** | 3.10 + (get it from <https://python.org>) |
12+
| **Git** | Latest (comes with Xcode / Git for Windows / Linux package manager) |
13+
| **VS Code** | Optional but recommended <https://code.visualstudio.com> |
14+
| **Docker Desktop** | *Only* for Option B. Free install: <https://docs.docker.com/desktop/> |
15+
16+
> 💡 **Tip** – Verify tools in a terminal:
17+
> `python --version`, `git --version`, `docker --version`, `code --version`
18+
19+
## 2. Option A – Native Python (quickest)
20+
21+
### Step 1 Clone this repo
22+
23+
```bash
24+
git clone https://github.com/<your-github>/generative-ai-for-beginners
25+
cd generative-ai-for-beginners
26+
```
27+
28+
### Step 2 Create & activate a virtual environment
29+
30+
```bash
31+
python -m venv .venv # make one
32+
source .venv/bin/activate # macOS / Linux
33+
.\.venv\Scripts\activate # Windows PowerShell
34+
```
35+
36+
✅ Prompt should now start with (.venv)—that means you’re inside the env.
37+
38+
### Step 3 Install dependencies
39+
40+
```bash
41+
pip install -r requirements.txt
42+
```
43+
44+
Skip to Section 3 on [API keys](#3-add-your-api-keys)
45+
46+
## 2. Option B – VS Code Dev Container (Docker)
47+
48+
We setup this repository and course with a [development container](https://containers.dev?WT.mc_id=academic-105485-koreyst) that has a Universal runtime that can support Python3, .NET, Node.js and Java development. The related configuration is defined in the `devcontainer.json` file located in the `.devcontainer/` folder at the root of this repository.
49+
50+
>**Why choose this?**
51+
>Identical environment to Codespaces; no dependency drift.
52+
53+
### Step 0 Install the extras
54+
55+
Docker Desktop – confirm ```docker --version``` works.
56+
VS Code Remote – Containers extension (ID: ms-vscode-remote.remote-containers).
57+
58+
### Step 1 Open the repo in VS Code
59+
60+
File ▸ Open Folder… → generative-ai-for-beginners
61+
62+
VS Code detects .devcontainer/ and pops a prompt.
63+
64+
### Step 2 Reopen in container
65+
66+
Click “Reopen in Container”. Docker builds the image (≈ 3 min first time).
67+
When the terminal prompt appears, you’re inside the container.
68+
69+
## 2. Option C – Miniconda
70+
71+
[Miniconda](https://conda.io/en/latest/miniconda.html?WT.mc_id=academic-105485-koreyst) is a lightweight installer for installing [Conda](https://docs.conda.io/en/latest?WT.mc_id=academic-105485-koreyst), Python, as well as a few packages.
72+
Conda itself is a package manager, that makes it easy to setup and switch between different Python [**virtual environments**](https://docs.python.org/3/tutorial/venv.html?WT.mc_id=academic-105485-koreyst) and packages. It also comes in handy for installing packages that are not available via `pip`.
73+
74+
### Step 0 Install Miniconda
75+
76+
Follow the [MiniConda installation guide](https://docs.anaconda.com/free/miniconda/#quick-command-line-install?WT.mc_id=academic-105485-koreyst) to set it up.
77+
78+
```bash
79+
conda --version
80+
```
81+
82+
### Step 1 Create a virtual environment
83+
84+
Create a new environment file (*environment.yml*). If you are following along using Codespaces, create this within the `.devcontainer` directory, thus `.devcontainer/environment.yml`.
85+
86+
### Step 2 Populate your environment file
87+
88+
Add the following snippet to your `environment.yml`
89+
90+
```yml
91+
name: <environment-name>
92+
channels:
93+
- defaults
94+
- microsoft
95+
dependencies:
96+
- python=<python-version>
97+
- openai
98+
- python-dotenv
99+
- pip
100+
- pip:
101+
- azure-ai-ml
102+
103+
```
104+
105+
### Step 3 Create your Conda environment
106+
107+
Run the commands below in your command line/terminal
108+
109+
```bash
110+
conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer sub path applies to only Codespace setups
111+
conda activate ai4beg
112+
```
113+
114+
Refer to the [Conda environments guide](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html?WT.mc_id=academic-105485-koreyst) if you run into any issues.
115+
116+
## 2 Option D – Classic Jupyter / Jupyter Lab (in your browser)
117+
118+
> **Who’s this for?**
119+
> Anyone who loves the classic Jupyter interface or wants to run notebooks without VS Code.
120+
121+
### Step 1 Ensure Jupyter is installed
122+
123+
To start Jupyter locally, head over to the terminal/command line, navigate to the course directory, and execute:
124+
125+
```bash
126+
jupyter notebook
127+
```
128+
129+
or
130+
131+
```bash
132+
jupyterhub
133+
```
134+
135+
This will start a Jupyter instance and the URL to access it will be shown within the command line window.
136+
137+
Once you access the URL, you should see the course outline and be able to navigate to any `*.ipynb` file. For example, `08-building-search-applications/python/oai-solution.ipynb`.
138+
139+
## 3. Add Your API Keys
140+
141+
Keeping your API keys safe and secure is important when building any type of application. We recommend not to store any API keys directly in your code. Committing those details to a public repository could result in security issues and even unwanted costs if used by a bad actor.
142+
Here's a step-by-step guide on how to create a `.env` file for Python and add the `GITHUB_TOKEN`:
143+
144+
1. **Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to your project's root directory where you want to create the `.env` file.
145+
146+
```bash
147+
cd path/to/your/project
148+
```
149+
150+
2. **Create the `.env` File**: Use your preferred text editor to create a new file named `.env`. If you're using the command line, you can use `touch` (on Unix-based systems) or `echo` (on Windows):
151+
152+
Unix-based systems:
153+
154+
```bash
155+
touch .env
156+
```
157+
158+
Windows:
159+
160+
```cmd
161+
echo . > .env
162+
```
163+
164+
3. **Edit the `.env` File**: Open the `.env` file in a text editor (e.g., VS Code, Notepad++, or any other editor). Add the following line to the file, replacing `your_github_token_here` with your actual GitHub token:
165+
166+
```env
167+
GITHUB_TOKEN=your_github_token_here
168+
```
169+
170+
4. **Save the File**: Save the changes and close the text editor.
171+
172+
5. **Install `python-dotenv`**: If you haven't already, you'll need to install the `python-dotenv` package to load environment variables from the `.env` file into your Python application. You can install it using `pip`:
173+
174+
```bash
175+
pip install python-dotenv
176+
```
177+
178+
6. **Load Environment Variables in Your Python Script**: In your Python script, use the `python-dotenv` package to load the environment variables from the `.env` file:
179+
180+
```python
181+
from dotenv import load_dotenv
182+
import os
183+
184+
# Load environment variables from .env file
185+
load_dotenv()
186+
187+
# Access the GITHUB_TOKEN variable
188+
github_token = os.getenv("GITHUB_TOKEN")
189+
190+
print(github_token)
191+
```
192+
193+
That's it! You've successfully created a `.env` file, added your GitHub token, and loaded it into your Python application.
194+
195+
🔐 Never commit .env—it’s already in .gitignore.
196+
Full provider instructions live in [`providers.md`](03-providers.md).
197+
198+
## 4. What’s next?
199+
200+
| I want to… | Go to… |
201+
|---------------------|-------------------------------------------------------------------------|
202+
| Start Lesson 1 | [`01-introduction-to-genai`](../01-introduction-to-genai/README.md) |
203+
| Setup an LLM Provider | [`providers.md`](03-providers.md) |
204+
| Meet other learners | [Join our Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst) |
205+
206+
## 5. Troubleshooting
207+
208+
| Symptom | Fix |
209+
|-------------------------------------------|-----------------------------------------------------------------|
210+
| `python not found` | Add Python to PATH or re-open terminal after install |
211+
| `pip` cannot build wheels (Windows) | `pip install --upgrade pip setuptools wheel` then retry. |
212+
| `ModuleNotFoundError: dotenv` | Run `pip install -r requirements.txt` (env wasn’t installed). |
213+
| Docker build fails *No space left* | Docker Desktop ▸ *Settings* ▸ *Resources* → increase disk size. |
214+
| VS Code keeps prompting to reopen | You may have both Options active; choose one (venv **or** container)|
215+
| OpenAI 401 / 429 errors | Check `OPENAI_API_KEY` value / request rate limits. |
216+
| Errors using Conda | Install Microsft AI libraries using `conda install -c microsoft azure-ai-ml`|

‎00-course-setup/SETUP.md renamed to ‎00-course-setup/03-providers.md

Lines changed: 13 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,4 @@
1-
# Setup Your Dev Environment
2-
3-
We setup this repository and course with a [development container](https://containers.dev?WT.mc_id=academic-105485-koreyst) that has a Universal runtime that can support Python3, .NET, Node.js and Java development. The related configuration is defined in the `devcontainer.json` file located in the `.devcontainer/` folder at the root of this repository.
4-
5-
To activate the dev container, launch it in [GitHub Codespaces](https://docs.github.com/en/codespaces/overview?WT.mc_id=academic-105485-koreyst) (for a cloud-hosted runtime) or in [Docker Desktop](https://docs.docker.com/desktop/?WT.mc_id=academic-105485-koreyst) (for a local device-hosted runtime). Read [this documentation](https://code.visualstudio.com/docs/devcontainers/containers?WT.mc_id=academic-105485-koreyst) for more details on how dev containers work within VS Code.
6-
7-
> [!TIP]
8-
> We recommend using GitHub Codespaces for a quick start with minimal effort. It provides a generous [free usage quota](https://docs.github.com/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts?WT.mc_id=academic-105485-koreyst) for personal accounts. Configure [timeouts](https://docs.github.com/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces?WT.mc_id=academic-105485-koreyst) to stop or delete inactive codespaces to maximize your quota usage.
9-
10-
11-
## 1. Executing Assignments
12-
13-
Each lesson will have _optional_ assignments that may be provided in one or more programming languages including: Python, .NET/C#, Java and JavaScript/TypeScript. This section provides general guidance related to executing those assignments.
14-
15-
### 1.1 Python Assignments
16-
17-
Python assignments are provided either as applications (`.py` files) or Jupyter notebooks (`.ipynb` files).
18-
- To run the notebook, open it in Visual Studio Code then click _Select Kernel_ (at top right) and select the default Python 3 option shown. You can now _Run All_ to execute the notebook.
19-
- To run Python applications from command-line, follow assignment-specific instructions to ensure you select the right files and provide required arguments
20-
21-
## 2. Configuring Providers
1+
# Choosing & Configuring an LLM Provider 🔑
222

233
Assignments **may** also be setup to work against one or more Large Language Model (LLM) deployments through a supported service provider like OpenAI, Azure or Hugging Face. These provide a _hosted endpoint_ (API) that we can access programmatically with the right credentials (API key or token). In this course, we discuss these providers:
244

@@ -36,19 +16,19 @@ Assignments **may** also be setup to work against one or more Large Language Mod
3616
| | | | | |
3717

3818
Follow the directions below to _configure_ this repository for use with different providers. Assignments that require a specific provider will contain one of these tags in their filename:
39-
- `aoai` - requires Azure OpenAI endpoint, key
40-
- `oai` - requires OpenAI endpoint, key
41-
- `hf` - requires Hugging Face token
19+
20+
- `aoai` - requires Azure OpenAI endpoint, key
21+
- `oai` - requires OpenAI endpoint, key
22+
- `hf` - requires Hugging Face token
4223

4324
You can configure one, none, or all providers. Related assignments will simply error out on missing credentials.
4425

45-
### 2.1. Create `.env` file
26+
## Create `.env` file
4627

4728
We assume that you have already read the guidance above and signed up with the relevant provider, and obtained the required authentication credentials (API_KEY or token). In the case of Azure OpenAI, we assume you also have a valid deployment of an Azure OpenAI Service (endpoint) with at least one GPT model deployed for chat completion.
4829

4930
The next step is to configure your **local environment variables** as follows:
5031

51-
5232
1. Look in the root folder for a `.env.copy` file that should have contents like this:
5333

5434
```bash
@@ -74,10 +54,9 @@ The next step is to configure your **local environment variables** as follows:
7454

7555
3. Fill in the values (replace placeholders on right side of `=`) as described in the next section.
7656

77-
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.
78-
57+
4. (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.
7958

80-
### 2.2. Populate `.env` file
59+
## Populate `.env` file
8160

8261
Let's take a quick look at the variable names to understand what they represent:
8362

@@ -93,8 +72,7 @@ Let's take a quick look at the variable names to understand what they represent:
9372

9473
Note: The last two Azure OpenAI variables reflect a default model for chat completion (text generation) and vector search (embeddings) respectively. Instructions for setting them will be defined in relevant assignments.
9574

96-
97-
### 2.3 Configure Azure: From Portal
75+
## Configure Azure: From Portal
9876

9977
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.
10078

@@ -111,7 +89,7 @@ Next, we need the endpoints for the specific models we've deployed.
11189

11290
This will take you to the Azure OpenAI Studio website, where we'll find the other values as described below.
11391

114-
### 2.4 Configure Azure: From Studio
92+
## Configure Azure: From Studio
11593

11694
1. Navigate to [Azure OpenAI Studio](https://oai.azure.com?WT.mc_id=academic-105485-koreyst) **from your resource** as described above.
11795
1. Click the **Deployments** tab (sidebar, left) to view currently deployed models.
@@ -128,10 +106,10 @@ AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-ada-002'
128106

129107
**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.
130108

131-
### 2.5 Configure OpenAI: From Profile
109+
## Configure OpenAI: From Profile
132110

133111
Your OpenAI API key can be found in your [OpenAI account](https://platform.openai.com/api-keys?WT.mc_id=academic-105485-koreyst). If you don't have one, you can sign up for an account and create an API key. Once you have the key, you can use it to populate the `OPENAI_API_KEY` variable in the `.env` file.
134112

135-
### 2.6 Configure Hugging Face: From Profile
113+
## Configure Hugging Face: From Profile
136114

137-
Your Hugging Face token can be found in your profile under [Access Tokens](https://huggingface.co/settings/tokens?WT.mc_id=academic-105485-koreyst). Don't post or share these publicly. Instead, create a new token for this project usage and copy that into the `.env` file under the `HUGGING_FACE_API_KEY` variable. _Note:_ This is technically not an API key but is used for authentication so we are keeping that naming convention for consistency.
115+
Your Hugging Face token can be found in your profile under [Access Tokens](https://huggingface.co/settings/tokens?WT.mc_id=academic-105485-koreyst). Don't post or share these publicly. Instead, create a new token for this project usage and copy that into the `.env` file under the `HUGGING_FACE_API_KEY` variable. _Note:_ This is technically not an API key but is used for authentication so we are keeping that naming convention for consistency.

0 commit comments

Comments
 (0)