Skip to content

02-setup-local.md

Latest commit

 

History

History
230 lines (156 loc) · 9.7 KB

02-setup-local.md

File metadata and controls

230 lines (156 loc) · 9.7 KB
Raw

Configurazione Locale 🖥️

Segui questa guida se preferisci lavorare direttamente sul tuo portatile.
Hai due possibilità: (A) Python nativo + virtual-env oppure (B) Dev Container di VS Code con Docker.
Scegli quella che ti sembra più semplice—entrambe portano agli stessi contenuti.

1. Prerequisiti

Strumento Versione / Note
Python 3.10 + (scaricalo da https://python.org)
Git Ultima versione (incluso in Xcode / Git per Windows / gestore pacchetti Linux)
VS Code Facoltativo ma consigliato https://code.visualstudio.com
Docker Desktop Solo per l’Opzione B. Installazione gratuita: https://docs.docker.com/desktop/

💡 Tip – Verifica gli strumenti nel terminale:
python --version, git --version, docker --version, code --version

2. Opzione A – Python Nativo (la più veloce)

Step 1 Clona questo repository

git clone https://github.com/<your-github>/generative-ai-for-beginners
cd generative-ai-for-beginners

Step 2 Crea & attiva un ambiente virtuale

python -m venv .venv          # make one
source .venv/bin/activate     # macOS / Linux
.\.venv\Scripts\activate      # Windows PowerShell

✅ Il prompt ora dovrebbe iniziare con (.venv)—significa che sei dentro l’ambiente virtuale.

Step 3 Installa le dipendenze

pip install -r requirements.txt

Salta alla Sezione 3 sulle API keys

2. Opzione B – Dev Container VS Code (Docker)

Abbiamo preparato questo repository e corso con un container di sviluppo che offre un ambiente universale per Python3, .NET, Node.js e Java. La configurazione si trova nel file devcontainer.json nella cartella .devcontainer/ alla radice del repository.

Perché scegliere questa opzione? Ambiente identico a Codespaces; nessun problema di dipendenze.

Step 0 Installa gli extra

Docker Desktop – verifica che docker --version funzioni. Estensione VS Code Remote – Containers (ID: ms-vscode-remote.remote-containers).

Step 1 Apri il repository in VS Code

File ▸ Apri cartella… → generative-ai-for-beginners

VS Code rileva .devcontainer/ e mostra un messaggio.

Step 2 Riapri nel container

Clicca su “Reopen in Container”. Docker costruisce l’immagine (≈ 3 min la prima volta). Quando appare il prompt nel terminale, sei dentro il container.

2. Opzione C – Miniconda

Miniconda è un installer leggero per Conda, Python e alcuni pacchetti. Conda è un gestore di pacchetti che semplifica la creazione e la gestione di diversi ambienti virtuali e pacchetti Python. È utile anche per installare pacchetti non disponibili tramite pip.

Step 0 Installa Miniconda

Segui la guida di installazione di MiniConda per configurarlo.

conda --version

Step 1 Crea un ambiente virtuale

Crea un nuovo file di ambiente (environment.yml). Se stai seguendo con Codespaces, crealo nella directory .devcontainer, quindi .devcontainer/environment.yml.

Step 2 Compila il file di ambiente

Aggiungi il seguente snippet al tuo environment.yml

name: <environment-name>
channels:
 - defaults
 - microsoft
dependencies:
- python=<python-version>
- openai
- python-dotenv
- pip
- pip:
    - azure-ai-ml

Step 3 Crea il tuo ambiente Conda

Esegui i comandi qui sotto nel terminale

conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer sub path applies to only Codespace setups
conda activate ai4beg

Consulta la guida agli ambienti Conda se incontri problemi.

2 Opzione D – Jupyter Classico / Jupyter Lab (nel browser)

A chi è rivolto?
Chi preferisce l’interfaccia classica di Jupyter o vuole lavorare sui notebook senza VS Code.

Step 1 Assicurati che Jupyter sia installato

Per avviare Jupyter in locale, apri il terminale, vai nella cartella del corso ed esegui:

jupyter notebook

oppure

jupyterhub

Questo avvierà Jupyter e l’URL per accedervi verrà mostrato nel terminale.

Una volta aperto l’URL, vedrai la struttura del corso e potrai navigare tra i file *.ipynb. Ad esempio, 08-building-search-applications/python/oai-solution.ipynb.

3. Aggiungi le tue API Keys

Proteggere le API keys è fondamentale quando sviluppi applicazioni. Ti consigliamo di non salvare mai le API keys direttamente nel codice. Se le pubblichi in un repository pubblico, rischi problemi di sicurezza e costi indesiderati se qualcuno le usa in modo improprio. Ecco una guida passo-passo per creare un file .env per Python e aggiungere il GITHUB_TOKEN:

  1. Vai nella cartella del tuo progetto: Apri il terminale e spostati nella directory principale del progetto dove vuoi creare il file .env.

    cd path/to/your/project

  2. Crea il file .env: Usa il tuo editor preferito per creare un nuovo file chiamato .env. Dal terminale puoi usare touch (su sistemi Unix) o echo (su Windows):

    Sistemi Unix:

    touch .env

    Windows:

    echo . > .env

  3. Modifica il file .env: Apri il file .env con un editor di testo (es. VS Code, Notepad++, o altro). Aggiungi questa riga, sostituendo your_github_token_here con il tuo vero token GitHub:

    GITHUB_TOKEN=your_github_token_here

  4. Salva il file: Salva le modifiche e chiudi l’editor.

  5. Installa python-dotenv: Se non l’hai già fatto, installa il pacchetto python-dotenv per caricare le variabili d’ambiente dal file .env nella tua applicazione Python. Puoi installarlo con pip:

    pip install python-dotenv

  6. Carica le variabili d’ambiente nel tuo script Python: Nel tuo script Python, usa il pacchetto python-dotenv per caricare le variabili dal file .env:

    from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Access the GITHUB_TOKEN variable
github_token = os.getenv("GITHUB_TOKEN")

print(github_token)

Fatto! Hai creato il file .env, aggiunto il tuo token GitHub e lo hai caricato nella tua applicazione Python.

🔐 Non committare mai .env—è già incluso in .gitignore. Le istruzioni complete per i provider sono in providers.md.

4. E ora?

Voglio… Vai a…
Iniziare la Lezione 1 01-introduction-to-genai
Configurare un provider LLM providers.md
Conoscere altri studenti Unisciti al nostro Discord

5. Risoluzione dei problemi

Sintomo Soluzione
python not found Aggiungi Python al PATH o riapri il terminale dopo l’installazione
pip non riesce a costruire wheels (Windows) pip install --upgrade pip setuptools wheel e riprova.
ModuleNotFoundError: dotenv Esegui pip install -r requirements.txt (l’ambiente non è stato installato).
Errore build Docker No space left Docker Desktop ▸ Settings ▸ Resources → aumenta lo spazio su disco.
VS Code continua a chiedere di riaprire Potresti avere entrambe le opzioni attive; scegli una (venv o container)
Errori OpenAI 401 / 429 Controlla il valore di OPENAI_API_KEY / limiti di richieste.
Errori con Conda Installa le librerie Microsoft AI con conda install -c microsoft azure-ai-ml

Disclaimer:
Questo documento è stato tradotto utilizzando il servizio di traduzione automatica Co-op Translator. Pur impegnandoci per garantire l’accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un traduttore umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall’uso di questa traduzione.