Tenim el llenguatge (07-01), les llibreries base (07-02) i el mapa d'eines (07-03). Falta el que converteix tot això en un taller en què diverses persones puguin treballar avui i d'aquí a un any: l'entorn. Als mòduls 3 a 6 hem escrit scripts solts, amb un fitxer novamarket_ml.py del qual importàvem funcions, sense dir mai quina versió de Python o de scikit-learn calia, on es desava cada cosa ni com comprovar que continuava funcionant. Aquesta lliçó ho ordena: entorns virtuals i gestió de dependències (venv, pip, requirements.txt, conda, uv/poetry) i per què fixar versions és part de la reproduïbilitat, juntament amb les llavors; Jupyter amb les seves virtuts i les seves trampes (l'estat ocult); Colab i Kaggle com a laboratoris amb GPU gratuïta; els IDE (VS Code, PyCharm); Git aplicat a projectes d'IA (què es versiona i què no); una estructura de projecte recomanada que aplicarem de debò: refactoritzarem el codi de NovaMarket en un paquet src/novamarket/ amb dades.py, entrenar.py i tests amb pytest, i ho executarem; i, per tancar, quan cal GPU o núvol i què és Docker. És important perquè el projecte que la Marta i el Diego abordaran al mòdul 8 no cap en un notebook: necessita aquesta estructura per sobreviure al primer canvi de persona, de màquina o de versió.

1. El problema: "a la meva màquina funciona"
2. Entorns virtuals amb venv i dependències amb pip
3. requirements.txt, conda/mamba, uv i poetry
4. Reproduïbilitat: versions + llavors
5. Jupyter Notebook i JupyterLab: cel·les, kernel i estat ocult
6. Google Colab i Kaggle Notebooks
7. IDE: VS Code i PyCharm
8. Git per a projectes d'IA: què versionar i què no
9. Estructura de projecte recomanada
10. Codi: refactoritzar NovaMarket a src/novamarket/ amb tests
11. GPU, CPU i núvol: quan cal
12. Docker com a entorn reproduïble
13. Errors Comuns i Consells
14. Exercicis
15. Conclusió

La Marta entrena el predictor de devolucions al seu portàtil, obté AUC 0,844 i passa l'script a un company. A ell li falla en importar, o li dona un altre número, o el joblib no carrega. Les causes són sempre les mateixes: una altra versió de Python o d'una llibreria, un altre ordre d'execució de les cel·les del notebook, una altra llavor o cap, dades diferents en un fitxer amb el mateix nom. L'entorn de desenvolupament és el conjunt de decisions que elimina aquestes causes una a una: aïllar dependències, fixar versions, fixar llavors, ordenar el codi, versionar-lo, provar-lo i, quan cal, empaquetar la màquina sencera.

Un entorn virtual és una carpeta amb el seu propi intèrpret de Python (enllaçat al del sistema) i la seva pròpia col·lecció de paquets, aïllada de les altres. Cada projecte té el seu, i així el projecte A pot fer servir una versió de pandas i el B una altra sense trepitjar-se. venv ve amb Python:

pip instal·la paquets des de PyPI (l'índex públic de Python) resolent dependències: en demanar scikit-learn porta NumPy, SciPy, joblib i threadpoolctl. La regla d'or: no instal·lis mai llibreries al Python del sistema; sempre en un entorn del projecte. L'entorn del curs és exactament això: un venv amb NumPy, pandas, scikit-learn, Matplotlib, PyTorch (CPU) i, des d'aquesta lliçó, pytest.

Perquè una altra persona (o tu d'aquí a un any) recreï l'entorn, s'escriu la llista de paquets amb versions en un fitxer:

Convenció habitual: un requirements.txt amb el que tu decideixes (paquets directes, fixats amb == els que importen) i un fitxer de bloqueig generat amb freeze per reproduir al bit. Alternatives que veuràs als equips:

Un environment.yml de conda equivalent, il·lustratiu:

conda env create -f environment.yml i conda activate novamarket. Tria una eina per projecte i no les barregis.

Un resultat és reproduïble si una altra persona obté el mateix número. Calen dues coses que hem separat al curs i que ara ajuntem:

• Llavors: np.random.default_rng(42), random_state=42 a scikit-learn, torch.manual_seed(42), i shuffle amb llavor a train_test_split i DataLoader. Sense elles, les 3.000 comandes, la partició i la inicialització de la xarxa canvien a cada execució. (En GPU, algunes operacions són no deterministes encara que fixis la llavor; PyTorch documenta com forçar-ho a canvi de velocitat.)
• Versions: la mateixa llavor en una altra versió de NumPy o de scikit-learn pot donar una altra seqüència o un altre resultat numèric, i un joblib desat amb una versió pot no carregar amb la següent (07-01, 07-03). Per això el requirements.txt amb == i per això, a la secció 10, l'script d'entrenament desarà al costat del model un JSON amb la versió de Python i de scikit-learn amb què es va entrenar.

Reproduïble = codi versionat + dades identificades + versions fixades + llavors fixades. Les quatre; amb tres, el número canvia.

Jupyter és l'entorn interactiu per excel·lència de la ciència de dades: un document (.ipynb) amb cel·les de codi i de text (Markdown), que s'executen una a una contra un kernel (un procés Python viu que guarda les variables). JupyterLab és la interfície moderna amb pestanyes, explorador de fitxers i terminal. Es llança amb jupyter lab des de l'entorn activat, i obre el navegador. Les seves virtuts són evidents: veus el head() i el gràfic al costat del codi, iteres ràpid, documentes mentre explores. Les seves trampes vénen del mateix:

• Estat ocult: les variables viuen al kernel, no al document. Si executes la cel·la 5, després la 2 i després edites i executes la 5 una altra vegada, el notebook que veus no correspon a l'estat del kernel. El cas típic: esborres la cel·la que definia comandes i tot continua funcionant... fins que reinicies, i llavors NameError. Un altre: canvies test_size a la cel·la 3 però no reexecutes la 4, i l'AUC que veus és l'antic.
• Ordre d'execució: els números entre claudàtors [7] a l'esquerra de cada cel·la diuen l'ordre real; si no van de dalt a baix, desconfia.
• Bones pràctiques que eviten gairebé tots els disgustos: (1) abans de donar per bo un resultat, "Restart Kernel and Run All" (reiniciar i executar-ho tot de dalt a baix; si falla, el notebook mentia); (2) importacions i paràmetres a les primeres cel·les; (3) no deixar cel·les de prova desordenades: esborra-les o mou-les a un apèndix; (4) funcions que es repeteixen, a un mòdul .py del projecte (secció 9) i importar-les, no copiar-les de notebook en notebook; (5) exportar a script quan el codi madura: jupyter nbconvert --to script exploracio.ipynb genera exploracio.py, o millor, copiar a mà el que val al mòdul; (6) netejar sortides abans de pujar a Git (els .ipynb amb sortides guarden imatges i taules i fan il·legibles les diferències): jupyter nbconvert --clear-output --inplace, o eines com nbstripout.
• Un notebook és per explorar i explicar; el codi que s'executa cada dia (entrenar, servir) va en mòduls i scripts. Aquesta frontera és la que traçarem a la secció 10.

Quan no tens GPU, o vols compartir un notebook sense que ningú instal·li res, hi ha dos laboratoris gratuïts al navegador:

• Google Colab: notebooks Jupyter allotjats per Google, amb Python i les llibreries habituals preinstal·lades, i accés a GPU (i TPU) gratuïta amb límits de temps de sessió, d'hores per dia i de memòria que canvien i que a la versió gratuïta no es garanteixen; les versions de pagament amplien el contingent. La sessió és efímera: en tancar-se es perd el que hi hagi al disc, així que les dades es pugen a cada sessió o es llegeixen de Google Drive.
• Kaggle Notebooks: semblant, integrat amb els conjunts de dades i competicions de Kaggle, amb un contingent setmanal d'hores de GPU i molts notebooks públics dels quals aprendre.
• Com pujar un CSV (descripció, no executable aquí): a Colab, el panell lateral de fitxers té un botó de pujada, o des de codi from google.colab import files; files.upload() obre un diàleg; per a fitxers grans, muntar Drive amb drive.mount('/content/drive') i llegir amb pd.read_csv('/content/drive/MyDrive/comandes.csv'). A Kaggle, "Add Data" afegeix un dataset (propi o públic) que apareix sota /kaggle/input/.
• Cauteles: no pugis dades personals de clients reals a un servei extern sense l'avaluació de 02-04; fixa versions perquè l'entorn preinstal·lat canvia; i desa el notebook i els models fora de la sessió (Drive, Git) perquè desapareixen.

Un editor amb suport de Python multiplica la productivitat davant del notebook per al codi de mòduls:

• Visual Studio Code amb les extensions Python i Jupyter: autocompleció, navegació al codi, formatatge, execució de notebooks dins de l'editor i "cel·les" en fitxers .py amb # %% (el millor de tots dos mons: script versionable que s'executa per trossos), depurador amb punts d'interrupció (molt millor que sembrar print per veure per què el ColumnTransformer dona 22 columnes en lloc de 21), terminal integrat, Git integrat, i selecció de l'intèrpret de l'entorn virtual (Python: Select Interpreter → .venv).
• PyCharm: l'IDE de JetBrains, més "tot inclòs" (l'edició Community és gratuïta; la Professional hi afegeix suport científic i notebooks). Excel·lent refactorització i depuració.
• Altres: Spyder (interfície tipus MATLAB/RStudio, amb conda), Positron, o qualsevol editor amb servidor de llenguatge. L'elecció és personal; el que no és opcional és fer servir l'intèrpret de l'entorn del projecte i tenir a mà depurador i tests.

Git guarda la història del codi i permet treballar a diverses persones sense trepitjar-se; GitHub/GitLab l'allotgen. En un projecte d'IA hi ha una particularitat: les dades i els models són grans, canvien per raons diferents del codi i de vegades són confidencials. La regla:

Per a dades i models es fan servir DVC (Data Version Control: desa a Git un fitxer petit amb el hash de la dada i la dada en un emmagatzematge extern, S3, Drive, un disc de xarxa) o Git LFS (Large File Storage). Només els esmentem: per a NovaMarket començarem amb .gitignore i una carpeta compartida, i DVC quan calgui.

Flux mínim:

Dels scripts solts dels mòduls 3-6 a un projecte que una altra persona entén en un minut. Estructura per a NovaMarket:

Principis: data/raw/ és intocable (el que arriba es desa tal qual; tota la resta es recalcula amb codi); els notebooks es numeren i expliquen una història; el codi reutilitzable viu al paquet src/novamarket/ (la carpeta src/ evita que Python importi per accident una còpia sense instal·lar); models/ guarda artefactes amb les seves mètriques al costat; tests/ comprova el que no es pot trencar; i README.md diu com arrencar. Existeixen plantilles (Cookiecutter Data Science és la més coneguda) que generen això amb més carpetes (reports/, configs/, docs/); comença petit i afegeix-ne quan ho necessitis.

Ho muntarem de debò. Creem l'estructura, movem les funcions de novamarket_ml.py (mòduls 4-5) a src/novamarket/dades.py, escrivim entrenar.py com a script executable, un test mínim amb pytest i ho executem tot.

1. Crear l'estructura (en un terminal, amb l'entorn activat):

2. src/novamarket/__init__.py (converteix la carpeta en paquet):

3. src/novamarket/dades.py: les funcions que ja coneixes, sense canvis, amb una capçalera. Reproduïm la primera completa; embrutar_comandes, preparar_comandes i crear_preparacio (amb les seves llistes NUMERIQUES, BINARIES, NOMINALS, ORDINALS) es copien tal qual de 04-03:

4. src/novamarket/entrenar.py: funcions importables i script executable, separats per if __name__ == "__main__":. Al costat del model desa un JSON amb mètrica, paràmetres i versions (secció 4):

if __name__ == "__main__": és la línia que fa possibles totes dues coses: quan executes el fitxer, __name__ val "__main__" i corre el bloc; quan un altre mòdul (o un test) fa from novamarket.entrenar import entrenar, __name__ val "novamarket.entrenar" i el bloc no s'executa. argparse converteix --n 3000 en args.n, amb valors per defecte i --help gratis.

5. pyproject.toml: el fitxer estàndard de metadades del projecte; aquí també li diu a pytest on és el codi:

pip install -e . (instal·lació editable) registra el paquet a l'entorn apuntant a src/, de manera que import novamarket funciona des de qualsevol carpeta i els canvis al codi es veuen sense reinstal·lar. Alternativa sense instal·lar: PYTHONPATH=src python -m novamarket.entrenar.

6. tests/test_dades.py i tests/test_entrenar.py: pytest descobreix funcions test_* i comprova els assert. Provem el que no es pot trencar: reproduïbilitat, forma, les 21 columnes, absència de NaN, un AUC mínim i que el desament escriu els dos fitxers:

7. requirements.txt, .gitignore i README.md com a les seccions 3, 8 i 9 (el .gitignore ignora .venv/, __pycache__/, .ipynb_checkpoints/, data/raw/* i data/processed/* llevat dels .gitkeep, models/*.joblib, models/*.pt i .env).

8. Executar. Tests, entrenament i comprovació de Git, amb les sortides reals:

Quatre tests en menys d'un segon, el mateix AUC 0,844 de 04-04 obtingut amb una ordre des del terminal, un JSON que diu amb quines versions es va entrenar, i un repositori en què el model binari no entra però les seves mètriques sí. Aquest és el punt de partida del mòdul 8: quan a 08-01 hi afegim predir.py (que carrega models/model_devolucions.joblib com a 07-03) o canviem el model, els tests diran en un segon si alguna cosa s'ha trencat.

Tot el curs ha corregut en CPU, i aquesta és la resposta per a la major part del que fa NovaMarket: taules de milers o centenars de milers de files amb scikit-learn, l'MLP de 497 paràmetres, les regles, l'optimització. La GPU cal quan el càlcul són grans multiplicacions de matrius repetides: entrenar CNN sobre imatges reals, afinar un transformer, executar LLM locals; aquí accelera de 10 a 100 vegades. Comprovar-la i fer-la servir a PyTorch:

(A Mac amb Apple Silicon l'equivalent és torch.backends.mps.is_available() i "mps".) Opcions, de menor a major cost: la CPU del portàtil; Colab/Kaggle per provar amb GPU gratis (secció 6); una màquina virtual amb GPU al núvol (AWS, Azure, Google Cloud i proveïdors especialitzats) que es paga per hora i s'apaga en acabar; serveis gestionats d'ML d'aquests proveïdors; o una GPU pròpia si l'ús és continu. La pregunta del Diego ("cal?") es respon mesurant: si l'entrenament en CPU triga minuts, no; si triga dies, sí, i tot i així convé primer reduir dades o model per iterar ràpid i fer servir la GPU només per a l'execució final.

L'últim esglaó de la reproduïbilitat és empaquetar la màquina sencera: sistema operatiu, Python, llibreries amb versió, codi i ordre d'arrencada, en una imatge que corre igual al portàtil de la Marta, al servidor de NovaMarket i al núvol. Això és Docker (o Podman). Un Dockerfile il·lustratiu per servir el predictor amb l'API de 07-03:

docker build -t novamarket-devolucions . construeix la imatge i docker run -p 8000:8000 novamarket-devolucions l'arrenca; el web de NovaMarket crida http://servidor:8000/risc-devolucio. Docker no substitueix venv en el dia a dia del desenvolupament (és més pesant), però és la manera estàndard de lliurar un servei i de garantir que "a la meva màquina funciona" vulgui dir "a totes". Kubernetes (07-01) orquestra molts contenidors; fora de l'abast del curs.

• Instal·lar-ho tot al Python del sistema. Tard o d'hora dos projectes demanen versions incompatibles i alguna cosa del sistema deixa de funcionar. Un entorn per projecte, sempre.
• requirements.txt sense versions, o sense requirements.txt. Sis mesos després, pip install porta versions noves i el joblib no carrega o el número canvia. Fixa amb == el que importa i guarda un freeze.
• Notebooks que només funcionen en l'ordre en què es van executar. "Restart Kernel and Run All" abans de donar res per bo; funcions a mòduls; sortides netes abans de pujar a Git.
• Dades i models a Git. El repositori s'engreixa fins a ser inutilitzable i pots publicar dades personals. .gitignore des del primer commit; DVC o emmagatzematge extern per al que és gran.
• Llavors sense versions o versions sense llavors. Totes dues, i anotades al costat del model (el JSON de la secció 10).
• Tests que proven el que és trivial i no el que és fràgil. Prova la forma de la matriu, l'absència de NaN, la reproduïbilitat, un llindar de mètrica; són les fallades que de debò passen en tocar preparar_comandes.
• Comprar GPU abans de mesurar. Cronometra en CPU, redueix el problema, prova a Colab; després decideix.
• Rutes absolutes al codi (/home/marta/comandes.csv). Rutes relatives a l'arrel del projecte o configurables per argument; pathlib.Path en lloc de concatenar cadenes.

Exercici 1. Afegeix al projecte un mòdul src/novamarket/predir.py amb una funció carregar(ruta="models/model_devolucions.joblib") i una altra predir_risc(model, comanda: dict) -> float que construeixi un DataFrame d'una fila i retorni la probabilitat de devolució, més un bloc if __name__ == "__main__": que predigui per a una comanda d'exemple. Escriu un test que entreni amb entrenar(n=1500), desi a tmp_path, carregui amb carregar i comprovi que predir_risc retorna un número entre 0 i 1 i igual a pipe.predict_proba sobre la mateixa comanda.

Exercici 2. Simula el problema de l'estat ocult: en un notebook (o mentalment, descrivint les cel·les), defineix a la cel·la 1 llindar = 0.5, a la cel·la 2 una funció que faci servir llindar, executa la cel·la 3 que la crida; després canvia la cel·la 1 a llindar = 0.3 sense reexecutar-la i torna a executar la 3. Quin llindar s'aplica? Què mostra el notebook? Què passa en fer "Restart and Run All"? Proposa dos canvis en l'organització del notebook que evitin el problema.

Exercici 3. Escriu el .gitignore, el requirements.txt (amb les versions que facis servir) i un Dockerfile il·lustratiu per a un projecte que serveixi la xarxa bayesiana de diagnòstic d'incidències de 06-03 com a API. Justifica què entra a Git i què no, i per què en aquest cas el "model" (les taules de probabilitat condicional) probablement sí que s'hauria de versionar a Git, a diferència de model_devolucions.joblib.

Solució 1.

Executat a l'entorn del curs: pytest passa 5 tests, i python -m novamarket.predir imprimeix risc de devolució: 0.048 (la mateixa comanda de 07-03). Amb això el projecte té les tres peces del cicle (dades, entrenar, predir) provades.

Solució 2. S'aplica 0,5: la cel·la 1 es va editar però no es va executar, així que la variable llindar del kernel continua valent 0,5; el notebook mostra llindar = 0.3 a la cel·la 1 i un resultat calculat amb 0,5, és a dir, menteix. En fer "Restart and Run All" el kernel es buida, s'executa la cel·la 1 amb 0,3 i el resultat canvia; si algú hagués copiat el resultat anterior a un informe, seria irreproduïble. Dos canvis: (1) paràmetres i funcions al principi, i la regla de reexecutar des de dalt després de qualsevol canvi de paràmetre (o directament "Run All Above" abans de la cel·la de resultats); (2) treure la funció a src/novamarket/ amb llindar com a argument explícit (decidir(prob, llindar=0.5)) i cridar-la amb el valor visible a la cel·la, de manera que no hi hagi cap variable global de la qual dependre.

Solució 3. .gitignore: .venv/, __pycache__/, .ipynb_checkpoints/, .env, i data/raw/* (els històrics d'incidències reals, confidencials); no s'ignora src/novamarket/xarxa_incidencies.py ni un configs/cpt_incidencies.json amb les taules de probabilitat. requirements.txt: numpy==..., pandas==..., fastapi, uvicorn, pytest (i pgmpy==... si se substitueix l'enumeració de 06-03 per pgmpy, 07-03). Dockerfile: igual que el de la secció 12, copiant src/, configs/ i servir_incidencies.py, amb CMD ["uvicorn", "servir_incidencies:app", ...]. Per què el "model" sí que va a Git: les taules de probabilitat condicional de la xarxa de 06-03 són poques desenes de números escrits o revisats per persones (coneixement explícit, com les regles de 06-02), petites, llegibles com a text i amb valor d'auditoria (qui va canviar la probabilitat de "defecte de fàbrica" i quan?): exactament el que Git fa bé. model_devolucions.joblib és un binari generat per codi a partir de dades: es regenera amb entrenar.py, no es llegeix ni es revisa línia a línia, i el seu lloc és un magatzem d'artefactes amb el JSON de mètriques i versions a Git.

Amb aquesta lliçó el taller de la Marta queda muntat. Hem vist per què "a la meva màquina funciona" és l'enemic i com es combat: entorns virtuals (venv) amb un intèrpret i uns paquets per projecte; dependències fixades a requirements.txt (o environment.yml, uv, poetry) i l'equació de la reproduïbilitat, versions + llavors + codi + dades identificades; Jupyter per explorar i explicar, amb la disciplina de reiniciar i executar-ho tot i de moure el codi madur a mòduls; Colab i Kaggle com a laboratoris amb GPU gratuïta i sessions efímeres; VS Code i PyCharm amb depurador i l'intèrpret de l'entorn; Git amb la frontera clara entre el que es versiona (codi, dependències, mètriques petites) i el que no (dades, models grans, secrets), i DVC a l'horitzó; una estructura de projecte (data/, notebooks/, src/novamarket/, models/, tests/) que hem construït de debò, amb dades.py, entrenar.py executable des del terminal (AUC 0,844 i un JSON amb versions), un pyproject.toml i quatre tests de pytest que passen en un segon; i les decisions d'infraestructura: CPU llevat de prova del contrari, GPU i núvol quan el càlcul ho demani, Docker per lliurar el servei igual a tot arreu.

I amb això tanquem el mòdul 7. Vam començar a 07-01 triant Python i SQL entre els llenguatges de la IA; a 07-02 vam aprendre a manejar de debò NumPy, pandas i Matplotlib amb les comandes i la demanda de NovaMarket; a 07-03 vam situar cada llibreria a la seva tasca i vam desar i recarregar el predictor de devolucions i l'MLP; i a 07-04 ho hem ordenat tot en un projecte reproduïble amb entorn, estructura, Git i tests. La Marta té el llenguatge, les eines i el taller; el Diego té un entrenar.py que qualsevol pot executar i un repositori que no s'engreixa amb dades. El que encara no tenen és un mètode per portar un cas d'ús de la idea a producció: definir el problema de negoci, decidir la mètrica, muntar les dades, iterar sobre el model, validar-lo, desplegar-lo i vigilar-lo, aprenent dels projectes que han sortit bé i dels que no. És el mòdul 8, Projectes i Casos d'Estudi, que comença a 08-01, Desenvolupament d'un Projecte d'IA, amb la Marta i el Diego abordant de cap a cap, dins de l'estructura novamarket_ia/ que acabem de crear, el projecte del predictor de devolucions.