Documentazione come codice: documentazione tecnica sincronizzata con le versioni
Come le pratiche di documentazione come codice aiutano a tenere la documentazione tecnica del Regolamento sull'IA allineata a ogni modifica del codice.
Punti chiave
- 1.I fornitori di sistemi di IA ad alto rischio devono tenere aggiornata la documentazione tecnica (articolo 11, paragrafo 1).
- 2.La documentazione come codice tiene la documentazione tecnica nel controllo di versione, accanto al codice.
- 3.Alcune parti si possono generare dal codice e dai dati della pipeline. Le valutazioni discrezionali richiedono persone.
- 4.Il controllo di versione mostra che cosa è cambiato e quando, non che il contenuto sia corretto.
L'obbligo ricade sui fornitori di sistemi di IA ad alto rischio. Vale per chi li immette sul mercato dell'UE o li mette in servizio, ai sensi dell'articolo 2, paragrafo 1, lettera a). L'allegato IV elenca ciò che la documentazione deve contenere. L'allegato III è l'elenco degli usi ad alto rischio del regolamento, come la selezione del personale. L'allegato I riguarda l'IA in prodotti soggetti alla normativa di sicurezza dell'UE. La sezione A dell'allegato I elenca norme sui prodotti, come quelle su giocattoli e dispositivi medici. La sezione B elenca altre norme sui prodotti. Per i sistemi dell'allegato III l'obbligo si applica dal 2 dicembre 2027. Per i sistemi della sezione A dell'allegato I si applica dal 2 agosto 2028 (regolamento (UE) 2026/1744). I sistemi immessi sul mercato o messi in servizio prima di tali date rientrano nell'articolo 111, paragrafo 2. Tale paragrafo è stato sostituito dal regolamento (UE) 2026/1744. Salvo i sistemi dell'articolo 111, paragrafo 1, sono coperti solo se, dalla data applicabile, subiscono modifiche significative della progettazione. Per i sistemi destinati alle autorità pubbliche, l'articolo 111, paragrafo 2, richiede le misure necessarie alla conformità entro il 2 agosto 2030.
Per i sistemi di IA ad alto rischio collegati a prodotti della sezione B dell'allegato I, l'articolo 2, paragrafo 2, limita le disposizioni applicabili. Si applicano solo l'articolo 6, paragrafo 1 (regole di classificazione), e gli articoli da 102 a 112 (disposizioni finali). Si applica anche l'articolo 60a (prove in condizioni reali al di fuori degli spazi di sperimentazione). Gli articoli da 57 a 59 riguardano gli spazi di sperimentazione normativa per l'IA. Si applicano solo nella misura in cui tali norme integrano i requisiti del regolamento per l'IA ad alto rischio. L'articolo 11 non figura tra queste.
Gli obblighi del fornitore sono nell'articolo 16. La violazione può costare fino a 15 milioni di EUR o, per un'impresa, al 3 % del fatturato mondiale annuo (articolo 99, paragrafo 4). Vale l'importo più alto. Per le microimprese e le piccole e medie imprese (PMI, articolo 3, punto 14a) vale l'importo più basso (articolo 99, paragrafo 6).
Con la documentazione come codice, le modifiche vengono riviste nelle pull request e ogni versione è collegata a un rilascio. Prossimo passo: verificate, con la tabella qui sotto, quali dei nove punti dell'allegato IV potete generare dal vostro repository.
Perché i documenti fuori dal repository si discostano dal sistema
I documenti in file Word, PDF o wiki sono separati dal codice che descrivono.
Un documento può descrivere una versione vecchia
L'aggiornamento è un lavoro manuale
Che cosa significa in pratica la documentazione come codice
La documentazione come codice applica alla documentazione tecnica le pratiche dell'ingegneria del software:
Controllo di versione
La documentazione tecnica si trova nello stesso repository Git del codice. Ogni modifica è un commit con autore, data e diff, così potete associare una versione del documento a una versione del codice.
Generazione, dove possibile
Alcune sezioni si possono generare dalla base di codice, come mostra la tabella qui sotto. Le sezioni che richiedono valutazioni discrezionali sono scritte da persone.
Controlli nella pipeline
Il vostro team può scrivere una regola di pipeline che fa fallire una pull request quando il modello cambia ma la sezione corrispondente del documento no. Il regolamento non la richiede.
Pacchetti di rilascio
Ogni rilascio raggruppa i documenti con la versione del software, così potete produrre la documentazione corrispondente a un dato rilascio.
La generazione aiuta più per alcuni punti dell'allegato IV che per altri
La generazione aiuta in parte per 4 dei 9 punti dell'allegato IV, poco per 4 e per nulla per 1. Le due colonne di destra sono una nostra valutazione, non del regolamento.
Le PMI e le piccole imprese a media capitalizzazione (SMC, articolo 3, punto 14b) possono fornire gli elementi dell'allegato IV in forma semplificata. Ciò discende dall'articolo 11, paragrafo 1, come modificato dal regolamento (UE) 2026/1744. Chi lo fa deve usare il modulo semplificato che la Commissione deve istituire. L'importo più basso della sanzione vale anche per le SMC (articolo 99, paragrafo 6a).
| Punto dell'allegato IV | Approccio possibile | La generazione aiuta |
|---|---|---|
| 1. Descrizione generale del sistema di IA | Nomi e versioni dal manifest, dal README e dai metadati di rilascio | In parte |
| 2. Elementi del sistema e del suo processo di sviluppo | Descrizioni dell'architettura e della pipeline dal codice; motivazioni di progettazione scritte da persone | In parte |
| 3. Monitoraggio, funzionamento e controllo | Dati di accuratezza dai risultati dei test; limitazioni e misure di sorveglianza umana scritte da persone | In parte |
| 4. Adeguatezza delle metriche di prestazione | Metriche dalle pipeline di valutazione; la motivazione della loro adeguatezza è scritta da persone | Poco |
| 5. Sistema di gestione dei rischi (articolo 9) | Registro dei rischi come file versionato; l'analisi dei rischi è svolta da persone | Poco |
| 6. Modifiche pertinenti durante il ciclo di vita | La cronologia Git e il changelog forniscono l'elenco grezzo; il fornitore sceglie le modifiche pertinenti | In parte |
| 7. Norme applicate | Un elenco mantenuto nel repository | Poco |
| 8. Copia della dichiarazione di conformità UE | La dichiarazione firmata conservata insieme al rilascio | Nessuno |
| 9. Sistema di monitoraggio successivo all'immissione sul mercato (articolo 72) | Il piano come documento versionato; i dati di monitoraggio provengono dall'operatività | Poco |
Esempio di struttura: file di documentazione accanto al codice
Questa struttura è un esempio, non una struttura obbligatoria.
your-ai-system/
├── src/
├── docs/
│ └── compliance/
│ ├── annex-iv/
│ │ ├── 01-general-description.md
│ │ ├── 02-development-process.md
│ │ └── ...
│ ├── risk-register.yaml
│ └── oversight.md
├── tests/
│ └── docs/
└── .github/
└── workflows/
└── docs-check.ymlUna pipeline può controllare i documenti a ogni pull request
Scansione: analizzare la base di codice
Una fase di scansione può usare uno strumento che rileva nel codice gli schemi standard dei framework di ML. Wrapper personalizzati e codice offuscato possono sfuggire.
Generazione: aggiornare le bozze
La pipeline ricostruisce le sezioni generate dagli input attuali, così il diff mostra che cosa è cambiato nei documenti.
Validazione: verificare la completezza
Le regole verificano che le sezioni richieste esistano e contengano i contenuti richiesti. Un controllo del contenuto non è un controllo di veridicità: l'esattezza la verificano le persone.
Report: mostrare il risultato nella pull request
La pull request mostra quali controlli sono stati superati o falliti, così chi la rivede vede l'impatto sulla documentazione prima che la modifica venga integrata.
Il testo semplice consente la revisione riga per riga, e la protezione del branch tutela la cronologia
Le pull request mostrano le righe modificate
Proteggere la cronologia
Letture correlate
Fonti e riferimenti
- Regulation (EU) 2024/1689 (EU AI Act) — articoli 2, 3, 11, 16, 43 e 99 e allegati I, III e IV (allegato IV: nove punti della documentazione tecnica).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — date di applicazione (articolo 113) e modifiche agli articoli 2, paragrafo 2, 3, 11, paragrafo 1, 99 e 111, paragrafo 2, e il nuovo articolo 60a.
- GitHub Docs — About protected branches — le regole di protezione del branch stabiliscono se i collaboratori possono fare un force push su un branch.
- Pro Git — Viewing the Commit History — la cronologia dei commit elenca ogni commit con autore, data e messaggio; con l'opzione patch mostra il diff.
Domande frequenti
Che cos'è la documentazione come codice per la documentazione richiesta dal Regolamento UE sull'IA?
La documentazione come codice tiene la documentazione tecnica nel controllo di versione, la modifica tramite pull request e ne genera alcune parti in una pipeline. L'obiettivo è che la documentazione tecnica corrisponda al sistema così com'è stato rilasciato.
Perché i documenti fuori dal repository si discostano dal sistema?
I file Word e i PDF sono separati dal codice, quindi una modifica al codice non li aggiorna. Qualcuno deve aggiornarli, perché l'articolo 11, paragrafo 1, richiede che la documentazione tecnica sia tenuta aggiornata.
La documentazione come codice soddisfa l'allegato IV?
Nessuna pratica soddisfa da sola l'allegato IV. L'allegato IV stabilisce il contenuto in nove punti. La documentazione come codice aiuta a mantenere quel contenuto aggiornato e tracciabile. Il fornitore deve garantire che il sistema rispetti i requisiti del capo III, sezione 2, tra cui l'articolo 11 (articolo 16, lettera a)).
Quali strumenti si usano per la documentazione come codice?
Potete combinare Git, file Markdown o YAML e una pipeline CI per i controlli e la generazione. Uno scanner o generatore può produrre le sezioni ricavabili dal codice.
Con quale frequenza va aggiornata la documentazione tecnica dell'IA?
L'articolo 11, paragrafo 1, richiede che la documentazione tecnica sia redatta prima dell'immissione del sistema sul mercato o della sua messa in servizio e che sia tenuta aggiornata. L'articolo 11, paragrafo 1, non fissa un intervallo. Suggeriamo di rivederla a ogni rilascio e dopo ogni modifica del modello, dei dati di addestramento o della finalità prevista. Una modifica sostanziale richiede una nuova valutazione della conformità (articolo 43, paragrafo 4). Una modifica sostanziale è un cambiamento successivo all'immissione sul mercato o alla messa in servizio che la prima valutazione della conformità non aveva previsto né pianificato. Incide sul rispetto dei requisiti per i sistemi di IA ad alto rischio del capo III, sezione 2, o cambia la finalità prevista (articolo 3, punto 23). Una valutazione della conformità è il processo che dimostra se tali requisiti sono soddisfatti (articolo 3, punto 20).
Scanara prepara evidenze dai vostri repository
Scanara legge i vostri repository GitHub collegati ed esegue scansioni basate su regole per individuare pattern comuni di IA e machine learning. Può non rilevare il codice non standard. Separatamente genera bozze di documentazione a partire da modelli e dalle vostre risposte alle valutazioni, come evidenze per il vostro lavoro di conformità. La classificazione la decidete voi.