Entorn de Desenvolupament per a Deep Learning — Nodes IAHUB de l'Espai cotib

Aquest és un entorn de desenvolupament basat en Docker, llest per a utilitzar, per executar entrenaments de deep learning als servidors d’Espai cotib. Està dirigit a membres de la universitat o col·laboradors que hagin obtingut accés a aquests servidors.

L’entorn ja ve preinstal·lat al vostre compte del servidor — no cal descarregar ni clonar res. Aquesta guia us acompanya pas a pas per connectar-vos al servidor, configurar el vostre projecte i executar el vostre codi.

Què inclou

L’entorn utilitza Python 3.11 amb suport per a CUDA 12.4. Les següents biblioteques estan instal·lades per defecte:

torch==2.8.0+cu128

La versió de torch indicada està compilada per a CUDA 12.8 però és compatible amb CUDA 12.4.

Qualsevol altra biblioteca que necessiteu es pot instal·lar fàcilment afegint-la al fitxer requirements.txt (vegeu el Pas 3).

Requisits previs

Abans de començar, assegureu-vos de tenir:

• Accés VPN: Haureu de tenir autorització per utilitzar la VPN de la universitat. Si no us podeu connectar, demaneu permisos.
• Credencials del servidor: L'administrador us proporcionarà una adreca IP del servidor, un nom d'usuari i una contrasenya.
• Una aplicació de terminal: A macOS o Linux ja ve integrada. A Windows podeu utilitzar PowerShell, Windows Terminal o qualsevol client SSH.

Pas 1: Connectar-se al servidor

Activar la VPN

Connecteu-vos a la VPN de la universitat abans de fer qualsevol altra cosa. Tot l'accés als servidors passa per ella.

Configurar SSH

SSH és l’eina que utilitzareu per connectar-vos al servidor des del vostre terminal. Per evitar escriure els detalls de connexió cada vegada, podeu guardar-los en un fitxer de configuració.

Obriu (o creeu) el fitxer ~/.ssh/config a la vostra màquina local i afegiu el seguent bloc:

Host EspaicotibServer
  HostName [IP_ADDR]
  User [username]

Substituïu [IP_ADDR] per la IP del servidor i [username] pel nom d'usuari que us han donat. Per exemple, si el vostre nom d'usuari és guest1 i la IP es aa.bb.cc.dd:

Host EspaicotibServer
  HostName aa.bb.cc.dd
  User guest1

Ara obriu un terminal i escriviu:

$ ssh EspaicotibServer

Se us demanarà la contrasenya. Escriviu-la i ja seréu dins del servidor.

X11 Forwarding (opcional)

El X11 forwarding permet que les finestres gràfiques del servidor (com ara gràfics de matplotlib o visualitzadors d’imatges) apareguin a la vostra pantalla local. Si teniu previst mostrar gràfics durant el vostre treball, afegiu aquestes línies a la vostra configuració SSH:

Host EspaicotibServer
  HostName aa.bb.cc.dd
  User guest1
  RemoteForward *:6040 /tmp/.X11-unix/[LOCAL_DISPLAY]
  ForwardX11 yes
  ForwardX11Trusted yes

Per trobar el valor de [LOCAL_DISPLAY], obriu un terminal a la vostra màquina local i executeu:

$ echo $DISPLAY

Si la sortida és :0, substituiu [LOCAL_DISPLAY] per X0. Si és :1, substituiu-lo per X1. Per exemple, si el vostre display és :0:

Host EspaicotibServer
  HostName aa.bb.cc.dd
  User guest1
  RemoteForward *:6040 /tmp/.X11-unix/X0
  ForwardX11 yes
  ForwardX11Trusted yes

Si no necessiteu sortida gràfica, podeu ometre això i la configuració SSH bàsica de la secció anterior és suficient.

Pas 2: Triar el vostre flux de treball

Els servidors tenen Anaconda instal·lat, de manera que podeu crear i gestionar els vostres propis entorns conda si ho preferiu. Si ja esteu familiaritzats amb conda, podeu utilitzar-lo sense cap problema.

La resta d’aquesta guia cobreix l’entorn basat en Docker, que està preconfigurat i llist per a utilitzar. És l’opció recomanada si voleu començar ràpidament sense haver de gestionar entorns manualment.

Pas 3: El vostre projecte al servidor

Un cop connectats al servidor, trobareu una carpeta anomenada Projects al vostre directori d'inici. A dins hi ha una plantilla de projecte anomenada DeepLearningTemplate. Podeu canviar-li el nom per adaptar-la al vostre projecte:

$ mv ~/Projects/DeepLearningTemplate ~/Projects/MyProject

Dins de la carpeta del projecte hi ha una subcarpeta anomenada repo. És aquí on es fa tota la feina. Té la següent estructura:

repo
  |___ dataset
  |___ src
  |___ docker-compose.yml
  |___ Dockerfile
  |___ requirements.txt
  |___ .env

Aquí teniu per a què serveix cada element:

• src: Conté tot el codi del projecte. Copieu el vostre codi aquí, amb l'estructura que tingui.
• dataset: Aquesta carpeta està buida al servidor. Quan el contenidor Docker estigui en marxa, el vostre dataset serà accessible aquí gracies a un mapejat configurat al fitxer .env (vegeu el Pas 5). No copieu el vostre dataset directament en aquesta carpeta. Deixeu-la tal com està.
• requirements.txt: Fitxer de requeriments de Python. Afegiu aquí qualsevol biblioteca addicional que necessiteu (una per línia, p. ex. scikit-learn==1.7.2). S'instal·laran automàticament quan es construeixi la imatge Docker.
• .env: Fitxer de configuració de variables d'entorn. L'editareu al Pas 5.
• docker-compose.yml: Utilitzat per Docker per llançar l'entorn. No el modifiqueu.
• Dockerfile: Defineix com es construeix la imatge. No el modifiqueu.

Pas 4: Copiar els vostres fitxers al servidor

Per copiar el vostre codi i dataset des de la vostra màquina local al servidor, podeu utilitzar scp. Per exemple:

$ scp -r ./my_code/ EspaicotibServer:~/Projects/MyProject/repo/src/
$ scp -r ./my_dataset/ EspaicotibServer:~/Datasets/

També podeu utilitzar rsync o qualsevol altre mètode de transferència de fitxers que preferiu.

Nota: Copieu el vostre dataset a ~/Datasets/ al servidor (no dins de la carpeta repo). El contenidor Docker el mapejarà automàticament.

Pas 5: Configurar les variables d'entorn

Abans d'executar l'entorn, obriu el fitxer .env dins de la carpeta repo i reviseu les seguents variables:

• PROJECT_NAME: Un nom per al vostre projecte. S'utilitza per donar nom al contenidor Docker. Podeu posar el que vulgueu (p. ex. my_training_project).
• DATASET: La ruta on el vostre dataset esta emmagatzemat al servidor (no dins del contenidor). Trobareu que ja està configurat apuntant a ~/Datasets/. Assegureu-vos d'haver copiat el vostre dataset allà (vegeu el Pas 4). Aquesta carpeta es munta dins del contenidor a /home/devuser/repo/dataset com a bind mount de lectura/escriptura, de manera que qualsevol canvi que feu dins del contenidor també s'aplica a la carpeta original del servidor.
• CONTAINER_DISPLAY: El valor de la variable DISPLAY utilitzada per al X11 forwarding. Trobareu que ja està configurat. Només és rellevant si heu configurat el X11 forwarding al Pas 1.

Pas 6: Executar l'entorn

Des del terminal on esteu connectats via SSH, navegueu a la carpeta repo i inicieu l'entorn:

$ cd ~/Projects/MyProject/repo
$ docker compose up -d

Nota: La primera vegada que executeu aquesta comanda, Docker construirà la imatge, cosa que pot trigar uns quants minuts. Les execucions posteriors seran molt més ràpides.

Això crea el contenidor. La carpeta del vostre projecte es munta a /home/devuser/repo dins del contenidor, i el dataset estarà a /home/devuser/repo/dataset.

Per obtenir una shell dins del contenidor:

$ docker compose exec dev_service bash

Des d'allà podeu executar els vostres scripts:

$ python src/main.py

Per aturar l'entorn, sortiu primer del contenidor (escriviu exit o premeu Ctrl+D) i després executeu:

$ docker compose down -v

Quan l'entorn s'atura, el contenidor s'elimina, pero tots els canvis als fitxers del projecte i al dataset es conserven a les carpetes del servidor.

Verificacio de la configuracio

Un cop l'entorn estigui en marxa, podeu verificar que tot funciona correctament.

Comprovar l'acces a la GPU:

$ docker compose exec dev_service python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"

Comprovar el X11 forwarding (nomes si l'heu configurat al Pas 1):

$ docker compose exec dev_service xeyes

També podeu executar el codi d'exemple a src/main.py dins del contenidor — crea un gràfic amb matplotlib que hauria d'aparèixer a la vostra pantalla local si el X11 forwarding funciona.

Utilitzar VS Code (opcional)

Podeu utilitzar Visual Studio Code per treballar al servidor amb una experiència completa d’IDE, incloent-hi edició, accés al terminal i depuració. Aquesta secció explica com connectar VS Code al servidor i després al contenidor Docker en execució.

Extensions necessàries

Instal·leu les següents extensions al vostre VS Code local:

• Remote - SSH (ms-vscode-remote.remote-ssh): Permet a VS Code connectar-se al servidor via SSH.
• Dev Containers (ms-vscode-remote.remote-containers): Permet a VS Code connectar-se a un contenidor Docker en execució.

Les podeu instal·lar des del panell d'Extensions (Ctrl+Shift+X) cercant pels seus noms.

Connectar-se al servidor

1. Obriu VS Code.
2. Obriu la Paleta de Comandes (Ctrl+Shift+P) i escriviu Remote-SSH: Connect to Host....
3. Seleccioneu EspaicotibServer de la llista (llegeix el vostre ~/.ssh/config).
4. VS Code obrirà una nova finestra connectada al servidor. Se us demanarà la contrasenya.
5. Un cop connectats, obriu la carpeta repo del vostre projecte: File > Open Folder, i navegueu a ~/Projects/MyProject/repo.

Iniciar el contenidor

Obriu un terminal dins de VS Code (Ctrl+`) i inicieu l'entorn Docker:

$ docker compose up -d

Connectar-se al contenidor

1. Obriu la Paleta de Comandes (Ctrl+Shift+P) i escriviu Dev Containers: Attach to Running Container....
2. Seleccioneu el contenidor de la llista (tindrà el nom del vostre PROJECT_NAME, p. ex. my_training_project-dev).
3. VS Code obrirà una nova finestra connectada al contenidor. Ara esteu treballant dins de l'entorn Docker.

Instal·lar extensions dins del contenidor

La primera vegada que us connecteu al contenidor, haureu d'instal·lar extensions a dins perquè les funcionalitats d'edició de codi funcionin. Obriu el panell d'Extensions (Ctrl+Shift+X) i instal·leu:

• Python (ms-python.python)
• Pylance (ms-python.vscode-pylance)

VS Code recorda quines extensions estaven instal·lades per a una imatge de contenidor determinada, de manera que només cal fer-ho una vegada (excepte si es reconstrueix la imatge).

Depuració

El contenidor exposa el port 5678, que es pot utilitzar per depurar amb debugpy. Si necessiteu configurar una configuració de depuració, podeu crear un fitxer launch.json a .vscode/ dins del contenidor amb els parametres adequats per al vostre projecte.