Salta el contingut

Rúbrica PR5073/02: API d'IA en Producció amb FastAPI i Docker

Pràctica: PR5073/02 — API d'IA en Producció amb FastAPI i Docker Mòdul: 5073 — Programació d'Intel·ligència Artificial Curs: IABD — Institut Sa Palomera, Blanes Pes sobre la nota del mòdul: 15%

Criteris d'avaluació

Criteri Pes Excel·lent (9-10) Notable (7-8) Aprovat (5-6) Insuficient (<5)
Disseny de l'API 20% Endpoints RESTful ben dissenyats, schemas Pydantic complets, versionat /api/v1/, error handling amb HTTPException, logging, middleware API ben estructurada amb Pydantic i versioning API funcional bàsica, estructura mínima API deficient, sense Pydantic ni estructura
Integració model IA 25% Model carregat eficientment (singleton pattern), almenys 2 endpoints d'IA funcionals, gestió d'errors del model, temps d'inferència documentat Model integrat correctament, 2 endpoints funcionals 1 endpoint d'IA funcional, sense gestió d'errors Sense integració d'IA real o no funcional
Docker i docker-compose 20% Dockerfile multi-stage, docker-compose amb tots els serveis, healthcheck a tots els serveis, variables d'entorn via .env, usuari no-root Docker configurat bé, healthcheck present Docker funcional sense multi-stage ni healthcheck Errors Docker, la imatge no construeix o no arrenca
Tests automàtics 15% Tests unitaris i d'integració, mocks per als models IA, cobertura >80%, tots els tests passen Tests principals presents (health, classify, generate), passen tots Algun test funcional, cobertura <50% Sense tests o cap test passa
Documentació Swagger 10% Documentació automàtica completa: descripció de cada endpoint, exemples de request/response, tags organitzats, descripció de l'API al títol Documentació present i correcta Documentació bàsica generada automàticament Absent o inaccessible
Personalització 5% Nom de l'alumne al títol de l'API, a totes les respostes JSON (alumne field), al nom del contenidor, als labels Docker i al header HTTP X-Alumne Nom visible a l'API i al JSON de resposta Nom parcialment present Absent o nom per defecte no canviat
Defensa oral 5% Explica les decisions d'arquitectura (per quin motiu FastAPI, singleton, multi-stage), respon preguntes imprevistes sobre REST i Docker Respon bé les preguntes bàsiques Respostes bàsiques amb suport del codi No pot explicar el funcionament o no compareix

Detall per criteri

Disseny de l'API (20%)

Excel·lent (9-10):

  • Estructura de directoris clara: app/, app/routers/, tests/
  • Endpoints RESTful: POST /api/v1/classify/sentiment, POST /api/v1/generate, etc.
  • Schemas Pydantic amb:
  • Validació de camps (min_length, max_length, ge, le)
  • Exemples (examples=["..."])
  • Descripcions (description="...")
  • Camp alumne a totes les respostes
  • Error handling amb HTTPException i codis HTTP correctes (422, 503, 504)
  • Middleware de logging que registra mètode, path, status i temps de resposta
  • Headers personalitzats (X-Alumne, X-Temps-Resposta-Ms)
  • Rate limiting configurat

Notable (7-8): - Estructura correcta amb app/routers/ - Pydantic ben usat, la majoria de camps validats - Error handling bàsic amb HTTPException - Sense middleware o rate limiting

Aprovat (5-6): - Estructura funcional però sense app/routers/ (tot a main.py) - Pydantic usat però sense validació detallada - Error handling mínim

Insuficient (<5): - API desordenada (tot en un fitxer sense estructura) - Sense Pydantic o validació de dades - Sense gestió d'errors (crashes en lloc d'errors HTTP)

Integració del model IA (25%)

Excel·lent (9-10):

  • Model carregat una sola vegada en memòria (singleton o lifespan)
  • Temps de primera càrrega documentat als logs
  • Almenys 2 endpoints d'IA funcionalment diferenciats:
  • Classificació de sentiment multilingüe
  • Generació de text via Ollama o API externa
  • Gestió d'errors específics del model:
  • Timeout de Ollama (requests.exceptions.Timeout → HTTP 504)
  • Model no disponible → HTTP 503
  • Background tasks per a logging asíncron
  • Temps d'inferència mesurat i loguejat

Notable (7-8): - 2 endpoints d'IA funcionals - Model carregat correctament - Gestió bàsica d'errors

Aprovat (5-6): - 1 endpoint d'IA funcional - Model carregat, però sense gestió d'errors

Insuficient (<5): - Sense integració de model real (respostes hardcoded) - Model no funciona o crasha l'API

Docker i docker-compose (20%)

Excel·lent (9-10):

Dockerfile multi-stage: 

FROM python:3.11-slim AS builder
# Instal·lar dependències
FROM python:3.11-slim AS runtime
# Copiar de builder, executar com a usuari no-root

docker-compose.yml amb: - Servei ollama-[alumne] amb healthcheck - Servei api-ia-[alumne] amb depends_on condicionat a service_healthy - Healthcheck per a cada servei - Variables d'entorn via environment: i fitxer .env - Volums nomenats per a persistència dels models - Labels Docker amb nom de l'alumne

Notable (7-8): - Docker configurat correctament - Healthcheck present - docker-compose funcional amb depends_on

Aprovat (5-6): - Dockerfile funcional però sense multi-stage - docker-compose bàsic sense healthcheck

Insuficient (<5): - La imatge Docker no construeix correctament - docker-compose no arrenca els serveis - Sense Dockerfile (instruccions manuals)

Tests automàtics (15%)

Excel·lent (9-10):

  • Tests organitzats en classes: class TestSistema, class TestClassificacio, class TestGeneracio
  • Ús de @patch per a mockejar models IA (els tests no necessiten els models reals)
  • Cobertura >80% (verificada amb pytest --cov=app)
  • Tests que verifiquen:
  • Codi HTTP correcte per a cada cas (200, 422, 503)
  • Camps obligatoris a la resposta (alumne, etiqueta, puntuació)
  • Casos límit (text buit, text massa llarg, temperatura fora de rang)
  • Presència del header X-Alumne
  • Tots els tests passen (pytest tests/ -v amb 0 failures)

Notable (7-8): - Tests principals presents: health, classify, generate - Ús de mocks per als models - Cobertura entre 50-80% - Tots els tests passen

Aprovat (5-6): - Algun test funcional (health check com a mínim) - Sense mocks, els tests necessiten els models reals per a passar - Cobertura <50%

Insuficient (<5): - Sense tests o cap test passa - Tests que no estan relacionats amb la pràctica

Documentació Swagger (10%)

La documentació Swagger s'accedeix a http://localhost:8000/docs i ha d'incloure:

Excel·lent (9-10): - Títol de l'API amb el nom de l'alumne - Descripció completa de l'API (Markdown) - Cada endpoint amb: - Descripció clara de per a qué serveix - Esquema de request amb exemples - Esquema de response amb descripció de cada camp - Codis d'error documentats (422, 503...) - Tags organitzats per secció (Classificació, Generació, Sistema) - Es pot executar directament des de Swagger UI ("Try it out")

Notable (7-8): - Documentació present i correcta - Exemples a la majoria d'endpoints - Tags presents

Aprovat (5-6): - Documentació bàsica generada automàticament per FastAPI - Sense exemples ni descripcions addicionals

Insuficient (<5): - /docs no accessible o retorna error - Documentació present però completament buida

Personalització (5%)

Llocs on ha d'aparèixer el nom real de l'alumne:

Lloc Exemple
Títol de l'API FastAPI "API Intel·ligència Artificial - maria_puig"
Nom del contenidor container_name: api-ia-maria-puig
Camp alumne a totes les respostes JSON "alumne": "maria_puig"
Header HTTP X-Alumne: maria_puig
Labels Docker "alumne=maria_puig"
Logs d'arrencada "Arrancant API - maria_puig"

Atenció

Els alumnes que lliurin la pràctica amb el nom "joan_garcia" (del template) en lloc del seu identificador real rebran puntuació 0 en aquest criteri.

Defensa oral (5%)

Durada: 5-10 minuts. El professor tria entre 3 i 5 preguntes:

Preguntes sobre l'arquitectura: - "Per quin motiu has separat els endpoints en fitxers classify.py i generate.py en lloc de tenir-ho tot a main.py?" - "Qué es el pattern singleton i per quin motiu l'uses per als models d'IA?" - "Qué fa exactament el middleware de logging? Quan s'executa?"

Preguntes sobre Docker: - "Qué es un Dockerfile multi-stage i quina avantatge te respecte a un Dockerfile d'una sola fase?" - "Qué fa el healthcheck a docker-compose? Qui el crida?" - "Per quin motiu fas servir depends_on: condition: service_healthy en lloc de simplement depends_on?"

Preguntes sobre tests: - "Qué es un mock i per quin motiu els uses als tests de l'API d'IA?" - "Com comprovaríes que el test de generació de text funciona sense tenir Ollama en marxa?" - "Qué es la cobertura de codi i com l'has mesurat?"

Preguntes sobre REST: - "Per quin motiu l'endpoint de classificació usa el mètode HTTP POST en lloc de GET?" - "Qué vol dir que l'API segueix el versioning /api/v1/? Per a qué serveix?" - "Com tractaria l'API una petició amb un JSON malformat?"

Fulla de puntuació

Alumne: _____ Grup: _ Data: _______

Criteri Pes Puntuació (0-10) Puntuació ponderada
Disseny de l'API 20%
Integració model IA 25%
Docker i docker-compose 20%
Tests automàtics 15%
Documentació Swagger 10%
Personalització 5%
Defensa oral 5%
TOTAL 100%

Nota final: _ / 10

Observacions del professor:

Signatura del professor: _____ Data: _______