Dokumentacja jako kod: zgodność z unijnym aktem o AI zsynchronizowana z wersjami
Jak praktyki dokumentacji-jako-kodu zapewniają aktualność dokumentacji zgodności z unijnym aktem o AI przy każdej zmianie kodu.
Najważniejsze wnioski
- 1.Dokumentacja techniczna wymagana przez unijny akt o AI musi dokładnie odzwierciedlać aktualny stan Twojego systemu AI — statyczne dokumenty tracą zgodność z każdą zmianą kodu.
- 2.Dokumentacja jako kod traktuje pliki zgodności jako artefakty pod kontrolą wersji, generowane, walidowane i wdrażane wraz z bazą kodu.
- 3.Podejście to umożliwia ciągłą zgodność: dokumentacja jest zawsze aktualna, audytowalna i powiązana z dokładną wersją kodu, którą opisuje.
- 4.Dokumentacja zsynchronizowana z wersją eliminuje najczęstszy błąd w audycie: dokumentację, która nie odpowiada wdrożonemu systemowi.
Unijny akt o AI wymaga, aby systemy AI wysokiego ryzyka utrzymywały kompleksową dokumentację techniczną (Annex IV) dokładnie opisującą projektowanie, rozwój i działanie systemu. Kluczowym słowem jest "dokładnie" — dokumentacja opisująca system sprzed sześciu miesięcy nie spełnia wymagań, jeśli system od tego czasu się zmienił.
Dokumentacja jako kod to praktyka inżynierska rozwiązująca ten problem przez traktowanie dokumentacji zgodności jako artefaktu kodu: pod kontrolą wersji, automatycznie generowanej, walidowanej w CI/CD i wdrażanej wraz z opisywanym przez nią oprogramowaniem.
Dlaczego tradycyjna dokumentacja zawodzi w zakresie zgodności AI
Tradycyjna dokumentacja zgodności istnieje w dokumentach Word, plikach PDF lub wikii — oderwana od bazy kodu, którą opisuje. Tworzy to trzy krytyczne problemy:
Niezgodność wersji
Twoja dokumentacja opisuje wersję 2.3 Twojego systemu AI. Produkcja działa na wersji 2.7. Sekcja zarządzania ryzykiem odnosi się do potoku danych, który został przebudowany dwa sprinty temu. W audycie ta niezgodność jest ustaleniem — potencjalnie poważnym.
Brak ścieżki audytu
Article 12 wymaga prowadzenia rejestrów, które rejestrują zmiany w systemie AI. Plik PDF na współdzielonym dysku nie ma historii zmian powiązanej ze zmianami kodu. Nie możesz wykazać, że dokumentacja została zaktualizowana, gdy system uległ zmianie.
Ręczny obciążenie związane z utrzymaniem
Ktoś musi ręcznie przeglądać i aktualizować dokumentację po każdej istotnej zmianie kodu. W praktyce tak się nie dzieje — aktualizacje są łączone co kwartał w najlepszym razie, tworząc okna niezgodności.
Co dokumentacja jako kod oznacza w praktyce
Dokumentacja jako kod stosuje praktyki inżynierii oprogramowania do dokumentacji zgodności:
Kontrola wersji
Dokumenty zgodności żyją w tym samym repozytorium Git co kod. Każda zmiana dokumentacji to commit z autorem, znacznikiem czasu i diffem. Możesz prześledzić każdy stan dokumentacji z powrotem do dokładnej wersji kodu, którą opisywał.
Automatyczne generowanie
Kluczowe sekcje dokumentacji są generowane z samej bazy kodu. Architektura systemu, opisy przepływu danych, specyfikacje modeli i dokumentacja API są wyodrębniane, a nie pisane ręcznie.
Walidacja CI/CD
Kontrole kompletności i dokładności dokumentacji działają w Twoim potoku CI/CD. Pull request zmieniający model AI, ale nieaktualizujący odpowiedniej sekcji dokumentacji, nie przechodzi przez potok.
Niezmienne artefakty wydania
Każde wydanie łączy dokumentację zgodności z wersją oprogramowania. Zawsze możesz wygenerować dokładną dokumentację, która była obowiązująca w dowolnym momencie — kluczowa możliwość w audytach.
Mapowanie na wymagania Annex IV
Annex IV definiuje 9 sekcji wymaganej dokumentacji technicznej dla systemów AI wysokiego ryzyka. Oto jak dokumentacja jako kod stosuje się do każdej z nich:
| Sekcja Annex IV | Podejście dokument-jako-kod | Poziom automatyzacji |
|---|---|---|
| 1. Opis ogólny | Generowany z manifestu projektu + README | Częściowy |
| 2. Opis szczegółowy | Dokumentacja architektury z analizy kodu | Wysoki |
| 3. Monitorowanie i testowanie | Raporty testów z potoku CI/CD | Wysoki |
| 4. Zarządzanie ryzykiem | Rejestr ryzyka jako kod + wyniki skanowania | Częściowy |
| 5. Zarządzanie danymi | Dokumentacja potoku danych ze schematu + DVC | Częściowy |
| 6. Nadzór człowieka | Dokumentacja mechanizmu nadzoru z wzorców kodu | Wysoki |
| 7. Dokładność i odporność | Wskaźniki wydajności z potoków ewaluacji | Wysoki |
| 8. Instrukcje użytkowania | Generowane z dokumentacji API + konfiguracja | Częściowy |
| 9. Dziennik zmian i modyfikacji | Historia Git + generowanie dziennika zmian | Pełny |
Wzorzec implementacji
Praktyczna konfiguracja dokumentacji jako kodu dla zgodności z unijnym aktem o AI opiera się na tym wzorcu:
your-ai-system/
├── src/ # Application code
├── docs/
│ └── compliance/
│ ├── annex-iv/ # Annex IV technical documentation
│ │ ├── 01-general.md
│ │ ├── 02-detailed.md
│ │ ├── 03-monitoring.md
│ │ └── ...
│ ├── risk-registry.yaml # Machine-readable risk registry
│ ├── data-governance.md # Data governance description
│ └── oversight.md # Human oversight mechanisms
├── .scanara/
│ └── config.yaml # Compliance scanning configuration
├── tests/
│ └── compliance/ # Compliance validation tests
└── .github/
└── workflows/
└── compliance.yml # CI/CD compliance checksIntegracja CI/CD
Potok zgodności działa na każdym pull requeście:
Skanowanie — analiza bazy kodu
Automatyczne skanowanie identyfikuje komponenty systemu AI, przepływy danych, użycie modeli, wzorce nadzoru człowieka i potencjalne luki w zgodności z artykułami unijnego aktu o AI.
Generowanie — aktualizacja dokumentacji
Automatycznie generowane sekcje są regenerowane z aktualnej bazy kodu. Diffy pokazują dokładnie, co zmieniło się w dokumentacji w wyniku zmian kodu.
Walidacja — sprawdzanie kompletności
Reguły polityk walidują, że wszystkie wymagane sekcje Annex IV są obecne, kompletne i spójne z analizą bazy kodu. Brakujące lub przestarzałe sekcje powodują niepowodzenie potoku.
Raport — wynik zgodności
Wynik zgodności jest obliczany i raportowany na pull requeście. Recenzenci widzą wpływ każdej zmiany kodu na zgodność przed scaleniem.
Korzyści dla zespołów inżynierskich
Zawsze gotowy na audyt
Brak pośpiechu przed audytami. Dokumentacja jest zawsze aktualna, ponieważ jest generowana z bazy kodu. Każdą wersję można zrekonstruować z historii Git.
Przyjazny dla deweloperów
Inżynierowie pracują w swoich istniejących narzędziach: Git, Markdown, YAML, CI/CD. Brak logowania do oddzielnej platformy zgodności. Brak ręcznego wprowadzania danych.
Niezmienna historia
Git zapewnia odporny na manipulacje dziennik każdej zmiany dokumentacji. Możesz udowodnić, kiedy dokumentacja została utworzona, kto ją napisał i jakiej wersji kodu odpowiadała.
Zmniejszone zmęczenie zgodnością
Automatyzacja obsługuje powtarzające się elementy. Inżynierowie skupiają się na sekcjach wymagających ludzkiej oceny: ocenach ryzyka, opisach zamierzonego celu i projektowaniu mechanizmów nadzoru.
Zacznij od automatycznego skanowania
Scanara integruje się z Twoim potokiem CI/CD, aby skanować Twoją bazę kodu AI, generować dokumentację zgodności i utrzymywać jej synchronizację z każdym commitem. Dokumentacja jako kod — wbudowana.
Źródła i odniesienia
- Regulation (EU) 2024/1689 — Annex IV (Technical Documentation) — 9 obowiązkowych sekcji, które musi obejmować dokumentacja techniczna Annex IV.
Często zadawane pytania
Jak pomaga Scanara
Scanara automatyzuje zgodność z EU AI Act od kodu do dossier. Połącz swoje repozytoria GitHub i otrzymaj raporty zgodności w kilka minut.