ai-engineer-roadmap

🧠   AI Engineering

Da Zero a Ingegnere AI in Produzione

Una piattaforma di apprendimento pratica che porta gli ingegneri dalle basi dei transformer alla spedizione di sistemi AI in produzione.

108 lezioni approfondite su 15 categorie — RAG, agenti, valutazioni, fine-tuning, prompting — interconnesse con ricerca semantica, narrazione audio AI, un grafo della conoscenza interattivo, un tutor RAG e analisi della padronanza per ogni studente.

🚀 Avvio Rapido  ·  ✨ Funzionalità  ·  🧱 Stack  ·  🏗 Architettura  ·  🛠 Sviluppo

• 108 lezioni  ·  15 categorie  ·  5 grafi LangGraph  ·  22 tabelle DB  ·  10 valutatori di corsi

✨ Funzionalità

🚀 Avvio Rapido

Prerequisiti: Node 22.x · pnpm · un database Neon Postgres

pnpm install
cp .env.example .env.local   # compila le chiavi (vedi Environment sotto)

pnpm db:push                 # sincronizza lo schema con Neon
pnpm seed                    # importa 108 lezioni da content/*.md
pnpm dev                     # → http://localhost:3006 🎉

Questa è l'applicazione completa in sola lettura — ricerca, audio, grafo della conoscenza e analisi funzionano tutti senza un backend. Per le funzionalità AI (chat, generazione di articoli / flashcard / revisione corsi), esegui anche il backend LangGraph.

🧱 Stack

🏗 Architettura

graph TD
    Browser --> Next["Next.js su Vercel<br/>pages · API routes · server actions"]
    Next --> Adapter["data.ts adapter"]
    Adapter -->|"DATA_SOURCE=db"| DB[("Neon Postgres<br/>+ pgvector + checkpoints")]
    Adapter -->|"DATA_SOURCE=fs"| FS["content/*.md"]
    Next -->|"LANGGRAPH_URL + bearer"| Worker["CF Worker proxy"]
    Worker --> Container["FastAPI container :7860<br/>5 grafi LangGraph"]
    Container --> DeepSeek["DeepSeek API"]
    Container --> DB
    Next --> R2["Cloudflare R2<br/>file audio"]
    Next --> D1["Cloudflare D1<br/>progresso audio"]

Percorsi di richiesta: le pagine delle lezioni leggono tramite data.ts (DB o filesystem) e richiamano le lezioni correlate tramite similarità coseno pgvector. La chat esegue FTS + recupero vettoriale in Next.js, quindi invia snippet + cronologia al container LangGraph, che richiama DeepSeek e persiste il thread.

🔀 Pipeline LangGraph

• Generazione di contenuti (article_generate) — ricerca → schema → bozza → revisione → modifica, con un loop di revisione condizionale (max 2) controllato da conteggio parole, blocchi di codice, riferimenti incrociati, ≥5 diagrammi xyflow e sezioni obbligatorie. Esegue in puro Python in-process (nessun HTTP).
• Chat RAG (chat) — classifica l'intento (parola chiave vs. concettuale) → recupera (FTS / vettoriale / ibrido) → formatta il contesto → genera.
• Revisione corsi (course_review) — 10 valutatori esperti eseguono contemporaneamente tramite asyncio.gather, quindi un aggregatore pesato calcola il punteggio + il verdetto.

🗂 Layout del Progetto

app/                  Next.js App Router (lessons, AWS hub, applications, coursework, problems, api/*)
components/           Componenti React (search, audio-player, toc, …)
content/              File di lezione Markdown
src/db/               Client Neon + schema Drizzle (22 tabelle)
src/lib/              langgraph-client (typed POST /runs/wait)
lib/                  adattatore data.ts, query db, r2.ts, d1.ts, server actions
backend/              Python FastAPI + LangGraph (5 grafi, pytest + deepeval, wrangler)
scripts/              seed, scrape, review-courses, e2e
sql/ · migrations/    Setup Neon + migrazioni D1

🛠 Sviluppo

pnpm dev                       # avvia su :3006
pnpm db:push / db:studio       # sincronizza schema / apre Drizzle Studio
pnpm seed / seed:courses       # importa lezioni / catalogo Udemy
pnpm scrape:udemy              # scansiona argomenti AI/ML Udemy → external_courses

pnpm generate <slug>           # genera una lezione tramite LangGraph
pnpm generate:dry <slug>       # anteprima senza salvare
pnpm generate:batch            # genera tutte le lezioni mancanti
pnpm review:courses            # revisiona in batch i corsi non revisionati

pnpm backend:dev               # uvicorn --reload su :7860 (richiede backend/.env)
pnpm backend:deploy            # wrangler deploy da backend/

pnpm test:backend              # pytest (grafi fittizi, niente LLM/DB)
pnpm test:e2e                  # testa il worker deployato
pnpm test:deepeval             # LLM-judge gateway su chat + app_prep (~$0.05)
pnpm test:deepeval:all         # + course_review + article_generate (~$0.20)

DeepEval gate: ognuno dei 4 grafi guidati da LLM ha un set golden di 5 casi giudicato da una soglia di successo aggregata (attualmente 0.65, il limite inferiore empirico per i golden di 5 casi giudicati da DeepSeek). Escluso da pnpm test:backend per impostazione predefinita; abilitare tramite pnpm test:deepeval*.

Backend LangGraph

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --port 7860 --reload          # o: docker build / docker run

wrangler deploy                                # deploy su Cloudflare Containers
wrangler secret put DATABASE_URL DEEPSEEK_API_KEY LANGGRAPH_AUTH_TOKEN

Una volta deployato, imposta LANGGRAPH_URL + LANGGRAPH_AUTH_TOKEN nell'ambiente Vercel in modo che /api/chat e i percorsi di preparazione/memorizzazione raggiungano il container. La prima configurazione di pytest utilizza un venv isolato: cd backend && python3.12 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt.

Ambiente

DATABASE_URL=             # stringa di connessione Neon (usata anche dal container backend)
OPENAI_API_KEY=
DEEPSEEK_API_KEY=
LANGGRAPH_URL=            # http://127.0.0.1:7860 in locale; URL workers.dev in produzione
LANGGRAPH_AUTH_TOKEN=     # token bearer condiviso tra Next.js e backend
NEXT_PUBLIC_DATA_SOURCE=  # "db" | "fs"
NEXT_PUBLIC_R2_DOMAIN=    # dominio CDN audio
R2_ACCOUNT_ID= R2_ACCESS_KEY_ID= R2_SECRET_ACCESS_KEY= R2_BUCKET_NAME=
CLOUDFLARE_ACCOUNT_ID= CLOUDFLARE_AUDIO_D1_ID= CLOUDFLARE_D1_API_TOKEN=

Costruito con Next.js 15 · LangGraph · Neon pgvector · Cloudflare

Da zero a ingegnere AI in produzione — una lezione alla volta.

⬆ Torna su