Dokumentacja jako kod: dokumentacja techniczna zsynchronizowana z wersjami
Jak praktyki dokumentacji jako kodu pomagają utrzymać dokumentację techniczną z aktu o AI w zgodzie z każdą zmianą kodu.
Najważniejsze wnioski
- 1.Dostawcy systemów AI wysokiego ryzyka muszą aktualizować dokumentację techniczną (art. 11 ust. 1).
- 2.Dokumentacja jako kod przechowuje dokumentację techniczną w systemie kontroli wersji obok kodu.
- 3.Części można generować z kodu i danych z pipeline’u. Oceny wymagające osądu należą do ludzi.
- 4.Kontrola wersji pokazuje, co i kiedy się zmieniło, a nie to, że treść jest poprawna.
Obowiązek dotyczy dostawców, którzy wprowadzają systemy AI wysokiego ryzyka do obrotu w UE lub oddają je tam do użytku (art. 2 ust. 1 lit. a). Załącznik IV wymienia, co ma zawierać dokumentacja. Załącznik III to lista zastosowań wysokiego ryzyka w rozporządzeniu, np. rekrutacja. Załącznik I dotyczy AI w produktach objętych unijnymi przepisami bezpieczeństwa. Sekcja A załącznika I wymienia przepisy o produktach, np. o zabawkach i wyrobach medycznych. Sekcja B wymienia inne przepisy o produktach. W przypadku systemów z załącznika III obowiązek ma zastosowanie od 2 grudnia 2027 r. W przypadku systemów z sekcji A załącznika I ma zastosowanie od 2 sierpnia 2028 r. (rozporządzenie (UE) 2026/1744). Systemy wprowadzone do obrotu lub oddane do użytku przed tymi datami podlegają art. 111 ust. 2 w brzmieniu nadanym rozporządzeniem (UE) 2026/1744. Poza systemami z art. 111 ust. 1 są nim objęte tylko wtedy, gdy od właściwej daty ich konstrukcja ulega istotnym zmianom. Dla systemów przeznaczonych dla organów publicznych art. 111 ust. 2 wymaga niezbędnych kroków zapewniających zgodność do 2 sierpnia 2030 r.
W przypadku systemów AI wysokiego ryzyka związanych z produktami z sekcji B załącznika I art. 2 ust. 2 ogranicza, które przepisy mają zastosowanie. Stosuje się tylko art. 6 ust. 1 (zasady klasyfikacji), art. 60a (testowanie w warunkach rzeczywistych poza piaskownicami) oraz art. 102–112 (przepisy końcowe). Art. 57–59 dotyczą piaskownic regulacyjnych w zakresie AI. Stosuje się je tylko w zakresie, w jakim te przepisy o produktach uwzględniają wymogi rozporządzenia dla systemów AI wysokiego ryzyka. Art. 11 nie został tam wymieniony.
Obowiązki dostawcy określa art. 16. Ich naruszenie może kosztować do 15 mln EUR lub, w przypadku przedsiębiorstwa, do 3 % światowego rocznego obrotu (art. 99 ust. 4). Stosuje się wyższą kwotę. W przypadku mikroprzedsiębiorstw oraz małych i średnich przedsiębiorstw (MŚP, art. 3 pkt 14a) stosuje się niższą kwotę (art. 99 ust. 6).
W podejściu dokumentacja jako kod zmiany są sprawdzane w pull requestach, a każda wersja jest powiązana z wydaniem. Następny krok: proszę sprawdzić w tabeli poniżej, które z dziewięciu punktów załącznika IV można wygenerować z Państwa repozytorium.
Dlaczego dokumenty poza repozytorium się rozjeżdżają
Dokumenty w plikach Word, PDF lub wiki są oddzielone od kodu, który opisują.
Dokument może opisywać starą wersję
Aktualizacja wymaga pracy ręcznej
Co dokumentacja jako kod oznacza w praktyce
Dokumentacja jako kod stosuje praktyki inżynierii oprogramowania do dokumentacji technicznej:
Kontrola wersji
Dokumentacja techniczna znajduje się w tym samym repozytorium Git co kod. Każda zmiana to commit z autorem, datą i różnicą (diff), więc można przypisać wersję dokumentu do wersji kodu.
Generowanie tam, gdzie to możliwe
Niektóre sekcje można generować z bazy kodu, jak pokazuje tabela poniżej. Sekcje wymagające osądu piszą ludzie.
Kontrole w pipeline’ie
Państwa zespół może napisać regułę pipeline’u, która odrzuca pull request zmieniający model bez zmiany odpowiedniej sekcji dokumentu. Rozporządzenie tego nie wymaga.
Pakiety wydań
Każde wydanie łączy dokumenty z wersją oprogramowania, dzięki czemu można przygotować dokumentację, która odpowiadała danemu wydaniu.
Generowanie pomaga przy niektórych punktach załącznika IV bardziej niż przy innych
Generowanie pomaga częściowo przy 4 z 9 punktów załącznika IV, w niewielkim stopniu przy 4 i wcale przy 1. Dwie prawe kolumny to nasza ocena, a nie ocena rozporządzenia.
MŚP i małe spółki o średniej kapitalizacji (SMC, art. 3 pkt 14b) mogą podać elementy z załącznika IV w uproszczonej formie. Wynika to z art. 11 ust. 1 w brzmieniu nadanym rozporządzeniem (UE) 2026/1744. Te, które z tego korzystają, muszą użyć uproszczonego formularza, który ma opracować Komisja. Niższa kwota kary dotyczy także SMC (art. 99 ust. 6a).
| Punkt załącznika IV | Możliwe podejście | Pomoc generowania |
|---|---|---|
| 1. Ogólny opis systemu AI | Nazwy i wersje z manifestu, README i metadanych wydania | Częściowa |
| 2. Elementy systemu i proces jego opracowywania | Opisy architektury i pipeline’u z kodu; uzasadnienie projektu piszą ludzie | Częściowa |
| 3. Monitorowanie, funkcjonowanie i kontrola | Wskaźniki dokładności z wyników testów; ograniczenia i środki nadzoru ze strony człowieka piszą ludzie | Częściowa |
| 4. Adekwatność wskaźników skuteczności działania | Wskaźniki z pipeline’ów ewaluacji; uzasadnienie, że są odpowiednie, piszą ludzie | Niewielka |
| 5. System zarządzania ryzykiem (art. 9) | Rejestr ryzyka jako plik z wersjami; analizę ryzyka wykonują ludzie | Niewielka |
| 6. Istotne zmiany w całym cyklu życia | Historia Git i changelog dają surową listę; istotne zmiany wybiera dostawca | Częściowa |
| 7. Zastosowane normy | Utrzymywana lista w repozytorium | Niewielka |
| 8. Kopia unijnej deklaracji zgodności | Podpisana deklaracja przechowywana razem z wydaniem | Brak |
| 9. System monitorowania po wprowadzeniu do obrotu (art. 72) | Plan jako dokument z wersjami; dane z monitorowania pochodzą z działania systemu | Niewielka |
Przykładowy układ: pliki dokumentacji obok kodu
Ten układ to przykład, a nie wymagana struktura.
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.ymlPipeline może sprawdzać dokumenty przy każdym pull requeście
Skanowanie: analiza bazy kodu
Krok skanowania może użyć narzędzia, które wykrywa w kodzie standardowe wzorce frameworków ML. Własne wrappery i zaciemniony kod mogą zostać pominięte.
Generowanie: odświeżenie wersji roboczych
Pipeline buduje generowane sekcje od nowa z aktualnych danych wejściowych, więc diff pokazuje, co zmieniło się w dokumentach.
Walidacja: sprawdzenie kompletności
Reguły sprawdzają, czy wymagane sekcje istnieją i zawierają wymaganą treść. Kontrola treści nie jest kontrolą prawdziwości: poprawność weryfikują ludzie.
Raport: wynik w pull requeście
Pull request pokazuje, które kontrole zakończyły się powodzeniem, a które niepowodzeniem, dzięki czemu recenzent widzi wpływ na dokumentację, zanim zmiana zostanie włączona.
Zwykły tekst pozwala sprawdzać zmiany wiersz po wierszu, a ochrona gałęzi chroni historię
Pull requesty pokazują zmienione wiersze
Ochrona historii
Powiązane lektury
Źródła i odniesienia
- Regulation (EU) 2024/1689 (EU AI Act) — art. 2, 3, 11, 16, 43 i 99 oraz załączniki I, III i IV (załącznik IV: dziewięć punktów dokumentacji technicznej).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — daty stosowania (art. 113) oraz zmiany art. 2 ust. 2, art. 3, art. 11 ust. 1, art. 99 i art. 111 ust. 2 oraz nowy art. 60a.
- GitHub Docs — About protected branches — reguły ochrony gałęzi określają, czy współpracownicy mogą wykonać force push do gałęzi.
- Pro Git — Viewing the Commit History — historia commitów wymienia każdy commit z autorem, datą i komunikatem; z opcją patch pokazuje różnicę (diff).
Często zadawane pytania
Czym jest dokumentacja jako kod w przypadku dokumentacji wymaganej przez akt o AI?
Dokumentacja jako kod przechowuje dokumentację techniczną w systemie kontroli wersji, zmienia ją przez pull requesty i generuje jej części w pipeline’ie. Celem jest, by dokumentacja techniczna odpowiadała systemowi w wydanej wersji.
Dlaczego dokumenty poza repozytorium się rozjeżdżają?
Pliki Word i PDF są oddzielone od kodu, więc zmiana w kodzie ich nie aktualizuje. Ktoś musi je zaktualizować, bo art. 11 ust. 1 wymaga aktualizowania dokumentacji technicznej.
Czy dokumentacja jako kod spełnia wymogi załącznika IV?
Żadna praktyka sama nie spełnia załącznika IV. Załącznik IV określa treść w dziewięciu punktach. Dokumentacja jako kod pomaga utrzymać tę treść aktualną i możliwą do prześledzenia. Dostawca musi zapewnić, aby system spełniał wymogi rozdziału III sekcji 2, do których należy art. 11 (art. 16 lit. a).
Jakich narzędzi używa się do dokumentacji jako kodu?
Można połączyć Git, pliki Markdown lub YAML oraz pipeline CI do kontroli i generowania. Skaner lub generator może tworzyć sekcje, które da się wyprowadzić z kodu.
Jak często należy aktualizować dokumentację techniczną AI?
Art. 11 ust. 1 wymaga sporządzenia dokumentacji technicznej przed wprowadzeniem systemu do obrotu lub oddaniem go do użytku oraz jej aktualizowania. Art. 11 ust. 1 nie określa stałego odstępu. Nasza sugestia to przegląd przy każdym wydaniu i po każdej zmianie modelu, danych treningowych lub przewidzianego zastosowania. Istotna zmiana wymaga nowej oceny zgodności (art. 43 ust. 4). Istotna zmiana to zmiana po wprowadzeniu do obrotu lub oddaniu do użytku, której nie przewidziano ani nie zaplanowano w pierwszej ocenie zgodności. Wpływa ona na spełnianie wymagań dla systemów AI wysokiego ryzyka z rozdziału III sekcji 2 lub zmienia przewidziane zastosowanie (art. 3 pkt 23). Ocena zgodności to proces wykazywania, czy te wymagania spełniono (art. 3 pkt 20).
Scanara przygotowuje dowody na podstawie Państwa repozytoriów
Scanara odczytuje połączone repozytoria GitHub i uruchamia skany oparte na regułach pod kątem typowych wzorców AI i uczenia maszynowego. Może pominąć kod niestandardowy. Osobno generuje projekty dokumentacji na podstawie szablonów i Państwa odpowiedzi w ocenach, jako dowody dla Państwa pracy nad zgodnością. Klasyfikację ustalają Państwo.