Правила составления документации ML-проекта

Документация представляет собой текстовый или иллюстрационный материал, сопровождающий ПО и поясняющий методы и цели его использования, а также обладающий рядом свойств:

• может передаваться отдельно или быть встроенной в код;
• может содержаться в разных форматах (текст, видео, картинки);
• используется разными специалистами, связанными с одним проектом. 

В первую очередь документация необходима команде разработчиков проекта и её руководителю, а уже после менеджменту, клиентам из бизнес-среды, поставщикам, конечным потребителям. Отсутствие документации существенно усложнит процессы расширения штата или продуктовой линейки. Наличие сопроводительных документов позволяет ML-команде:

• быстро вводить в курс дела новых сотрудников;
• сокращать время, затрачиваемое на поиск необходимых материалов;
• усиливать обмен информацией в штате;
• структурировать рабочие процессы;
• планировать пути развития проекта;
• поддерживать данные в актуальном состоянии.

Частые проблемы, связанные с документацией

• В документации содержится слишком мало информации. Приходится часто дергать членов команды для получения нужных данных.
• Информации слишком много, и она разбросана по разным источникам – wiki, Slack, гугл-документы и презентации, бумажные носители.
• Информация неактуальна.
• Информация дублируется в разных источниках.

Итак, мы разобрались с основными целями создания и ведения документации и знаем, с какими проблемами нам предстоит столкнуться. Теперь поговорим о “правилах хорошего тона”, использование которых сильно уменьшит вероятность появления этих самых проблем.

Правила структуры и оформления документации

• Единая точка входа ко всей документации проекта. Это может быть страница в Notion, фрейм в Miro или Markdown-документ, форма не так важна. Главное, чтобы с этой страницы любой человек мог получить доступ к нужной ему информации.
• Единые правила оформления и стиля, наличие шаблонов. Немаловажным фактором для восприятия пользователем документации является наличие и консистентность общего стиля оформления документации.
• Стиль описания и подачи информации в документации соответствует культуре команды. Нет смысла придерживаться ненужного формализма во внутренних документах команды.
• В документах есть ссылки на другие релевантные документы.
• Важные места выделены.
• Используются оптимальные методы передачи информации. В зависимости от задачи документа может использоваться не только текст, но и картинки, графики, диаграммы, видео.

Правила использования и актуализации документации

• Определена целевая аудитория каждого документа – кто, как и зачем будет его использовать.
• Если документация не используется самой командой, то её актуализацию стоит встраивать в процессы в формате “definition of done”. Например, нельзя зарелизить новую модель, не обновив документацию.
• Использование методологии (“docs as code”) там, где это актуально. В данном случае документация является частью кодовой базы, лежит в репозитории и пишется в IDE. Данный подход “из коробки” даёт возможность версионирования, тестирования, ревью изменений документации.
• Производится регулярная ревизия документации. Включает себя в том числе отказ от устаревших или лишних документов.
• Встречи команды должны порождать новые “артефакты” (документы по итогам встречи). Например, дорожная карта реализации или лист договоренностей.
• Инвентаризация технического долга по документации. Да-да, техдолг по документации тоже является техдолгом.

Можно ли как-то измерить качество документации

Если у нас уже есть какая-то документация и процедуры её актуализации, можно ли попробовать померить её качество? Такие показатели действительно есть:

• Покрытие – какая часть кода проекта или DS-пайплайна покрыта документацией
• Доступность – сколько времени или кликов в среднем занимает поиск нужного документа
• Читаемость – насколько легко читать этот документ
• Количество посещений/обновлений документа за период

Мы пока не дошли до того, чтобы регулярно замерять динамику этих показателей, пока это кажется лишним. Но в качестве точки среза – почему нет?

Документация ML-проекта

В первой части статьи я рассказал про документацию процесса разработки. Однако ML-разработка довольно сильно отличается от классической разработки. Есть ли различия в документации?

Если максимально упростить пайплайн ML-разработки, то он будет выглядеть следующим образом:

1. Оценивается осуществимость и значимость проекта
2. Производится сбор, очистка и разметка данных
3. Генерируем гипотезы, тренируем модели
4. Оцениваем качество и устойчивость лучшей модели
5. Деплоим модель
6. Осуществляем мониторинг

Понятно, что этот пайплайн весьма условен, каких-то этапов может не быть, какие-то могут добавиться. Да и носит он, конечно, циклический характер, например на этапе оценки качества мы можем вернуться на этап генерации новых гипотез и построения моделей. Тем не менее, такое разделение позволит нам посмотреть на разные виды документации, характерные для разных этапов.

Что же может быть входной точкой в документацию

В нашем случае это карточка проекта, оформленная в Notion.

В таком случае в рамках проекта по маммографии документы распределены по группам: описание работы системы, код и model cards, эксперименты и идеи, данные и так далее.

Если мы углубимся в какую либо подгруппу, например, описание работы системы, то мы увидим внутри список документов и ссылок, связанных с данной предметной областью. Как мы видим внутри могут содержаться абсолютно разные документы, такие как Miro, Google-таблицы, PDF-файлы.

Начинаем с оценки проекта

На этапе оценки осуществимости и значимости проекта мы хотим собрать и агрегировать информацию, которой владеют разные группы пользователей – бизнес, аналитики, ML-специалисты, доменные эксперты, заказчики. Это позволяет нам создать общее понимание нюансов проекта, структурировать нужную информацию, которая позволит принять решение о старте проекта.

Примеров, как может выглядеть такой документ, очень много – AI Canvas, Mission Canvas, карточка проекта (design doc, чек-лист требований). В эту же группу можно включить технические задания от заказчиков.

Такие документы могут включать:

1. Описание проблемы и предположения о достижимой ценности продукта 
2. Варианты решения с ML и без него 
3. Требования к качеству (метрики)
4. Описание источников возможных данных
5. Другие требования (например, к железу и программному обеспечению)
6. Последствия ошибок системы и так далее
7. Этапы проекта
8. Технические риски и заключение по проекту
9. Конкуретная среда
10. Литература, научные статьи, видео по теме

Исходя из всей собранной информации мы готовим заключение о целесообразности или же её отсутствии для реализации проекта.

Принято положительное решение для реализации ML-проекта

После сбора и анализа такой информации, проведения встречи с бизнес-подразделением принимается решение о реализации или же отмене проекта. Допустим было принято положительное решение и теперь мы переходим к шагу №2 – “сбор, очистка и разметка данных”.

Поскольку в нашем случае мы работаем с медицинскими данными, то разметка данных – это отдельный важный процесс. В нашем случаи, разметчики – доменные эксперты, врачи, что ведёт к отдельным трудностям. Сам процесс разметки, разумеется, также описан в документации – процесс отбора разметчиков, инструкции врачам, принципы разрешения конфликтов в разметке.

Любой источник данных также требуется документировать. Это позволяет быстро получать информацию об источнике и объёме данных, их ограничений и свойств, генерировать новые гипотезы, связанные с данными – например, какие данные нужно доразметить или наоборот выбросить из датасета.

Datasets Cards

Документацию датасетов мы называем dataset cards. В зависимости от специфики данных, частоты их пополнения, типа разметки это может быть как просто статический документ, так и интерактивный дашборд. В идеале датасет-карды обладать следующими свойствами:

• версионирование – мы хотим понимать, какая документ соответствует той или иной версии датасета
• автообновление – если датасет-карт или дашборд подключен к БД с разметкой, то он всегда будет содержать актуальную информацию о датасетах
• интерактивность – должна быть возможность подробно глазами изучить тот или иной слайс данных или конкретный кейс

В зависимости от задачи датасет-кард может содержать различную информацию – примеры данных и разметки, описательные статистики, источник данных и описание процесса сбора данных, информация о разметчиках, известные проблемы и ограничения.

Собрали данные… Начинаем тренировать какие-то модели

Итак, мы определились с источниками данных, собрали их и разметили, создали документацию. Теперь пора начинать выдвигать гипотезы и тренировать модели для решения нашей бизнес-задачи.

Среди целей, которые мы ставим перед собой на данном этапе:

• Быстрая генерация, приоритезация и проверка гипотез
• Удобный анализ результатов экспериментов
• Возможность возврата к результатам предыдущих экспериментов
• Удобство разработки

Безусловно, ни одна из этих целей не решается только документацией, но документация должна поддерживать наше стремление к реализации каждой цели. Примеры документации на этом этапе – база гипотез, карточки экспериментов, документация кода, презентации по итогам серии экспериментов.

База гипотез – список приоритизированных идей на отработку. Он может содержать различную информацию и описание самой идеи, теги для удобной фильтрации контента внутри базы идей, оценки реализуемости и трудоемкости идеи (например, по ICE), дизайн-ревью и отчет по эксперименту, ссылка на эксперимент в трекере экспериментов.

В данном случае база идей реализована в Notion. Благодаря этому ее можно упорядочивать в необходимом нам формате. Например, по статусам, оценке “легкости реализации” и так далее. Отсюда мы можем попасть в саму карточку нужного нам эксперимента и посмотреть его детали.

Когда гипотеза попадает в базу она как правило описана очень верхнеуровнево, без деталей. Этой информации обычно недостаточно, чтобы точно оценить трудоёмкость гипотезы, конкретные шаги, нужные для её проверки, зависимости. Большая часть этой информации приходит уже в процессе анализа задачи. Когда конкретный человек из команды берет ее на себя, собирает инфорацию, гуглит статьи, смотрит репозитории, наличие и доступность данных, он описывает детали эксперимента (experiment design), чтобы обозначить план итоговой реализации. Этот план затем оценивают другие члены команды в рамках процедуры design review. Это помогает избавиться от проблем неправильного понимания задачи, расходования времени на переписывание после код-ревью, нерационального расходования времени во время проверки гипотезы.

Результаты реализации гипотез могут быть описаны в различном формате в зависимости от “ожиданий” и их важности. В некоторых случаях достаточно односложного комментария, а в некоторых необходимо готовить презентацию и обсуждать результаты и дальнейшие идеи с коллегами.

Использование трекера (в нашем случае это ClearML) позволяет обеспечить репродуцируемость эксперимента и в любой момент получить информацию о его метриках, версии кода, гиперпараметрах.

В трекере можно сравнить результаты разных экспериментов, изучить метрики, сформулировать выводы. Всё это по сути тоже является частью документации ML-проекта.

Натренировали. Выбрали лучшую модель. Теперь пора оценить её качество и устойчивость

На этом этапе мы хотим оценить качество модели, сравнить её с предыдущей версией, понять ограничения и особенности модели. Например, новая модель может работать с конкретным типом данных (снимки с определённого типа оборудования) хуже. И это также важно знать и учиывать.

В качестве артефактов документации на этом этапе у нас появляются model card, дашборды с таблицами и метриками, отчёты по анализу ошибок.

Model Card – описание ML-системы, которая включает в себя следующую информацию:

• Изменения в последней версии
• Описание обучающих и тестовых данных
• Описание архитектуры сети, препроцессинга и других компонентов
• Описание требований к входным данным
• Описание аутпутов системы
• Метрики
• Описание известных ограничений и проблем

Модел-кард для разных групп пользователей может иметь разный итоговый вид. Например, для бизнес или конечных пользователей можно включить рекомендуемые сценарии использования системы, но убрать лишнюю информацию об архитектуре сети.

Мы храним такую документацию в формате docs-as-code – в нашем случае, это Markdown-док, который версионируется и прилинкован к конкретным коммитам. По важным же релизам могут быть экспортированы и PDF.

Круто. Теперь мы можем задеплоить модель и подготовить ее в продакшну!

Деплой как и любой другой ML-процесс порождает свой класс специфичных документов. Среди которых :

• Отчеты по тестам (test reports)Автоматизированные тестыРезультаты a/b тестовОтчеты по опросы пользователей
• Автоматизированные тесты
• Результаты a/b тестов
• Отчеты по опросы пользователей
• Дашборды и регулярные автоматические отчёты 
• Post-mortem по итогам инцидентов на проде (документация события, несущего негативные последствия с целью анализа и устранения его причин)
• Документация API
• Change Notes
• Прочая документация, связанная с релизами

Ну и куда без общей документации

Конечно, на ML-проекте появляется и всякая общая и процессная документация. Примеры из нашей практики:

• Team Canvas

Очень полезный элемент для онбординга новых сотрудников. Документ описывает состав команды, ценности команды, зоны ответственности внутри команды и между сотрудниками, процессы, встречи и их формат, командные ритуалы и правила

• Доски и скоринговые карты собеседований сотрудников
• Таблица с описанием встреч

Таблица встреч – очень полезная вещь, которая обеспечивает понимание цели, участников и артефактов встреч для всех сотрудников. Для планирования стреч и напоминаний мы также используем гугл-календари.

• Гайдлайны по написанию кода
• База знаний – по коду, инфраструктуре, ML, заметки со встреч с доменными экспертами (врачами)
• Доска онбординга
• Общее Миро со всей информациейСтратегия и цели компании/проектаРоадмапы
• Стратегия и цели компании/проекта
• Роадмапы

В зависимости от вида документа и его целевой аудитории варьируется и лицо, поддерживающее документ. Кроме того, важно в целом создавать культуру ведения документации в компании, формировать понимание каждого члена компании, что документация и её актуализация приносит конкретную ценность, экономит время и устраняет дублирование работы.

Отдельно хочу остановиться на таком моменте как автоматизация документации. Во-первых, чем меньше мы в целом делаем руками – тем меньше нужды в ручном написании документации. Например, если мы ставим эксперименты в джупитере или меняем данные руками в эксель-табличках, то и документацию нужно будет написать руками. А работа с эксперимент-трекером или БД с разметкой автоматически создаёт нужные артефакты.

Помимо этого, есть разные инструменты, которые позволяют автоматизировать процесс создания и актуализация документации – Swagger, плагины для IDE, интерактивные датасет-карды (о них можно прочесть выше), DVC-пайплайны, методология docs-as-code.

Заключение и рекомендации

Качественная документация – залог возможности успешного масштабирования как разработки, так и бизнеса в целом.

Что бы я предложил вам сделать уже сейчас?

• Провести аудит документации и по каждому документу ответить на вопросы из списка (можно найти в первой части статьи), сформировать бэклог техдолга по документации.
• Создать единую точку входа в документации (если её еще нет).
• Оценить, для каких документов подходит методология docs-as-code, актуализацию каких документов можно автоматизировать.
• Собрать обратную связь от разных групп (ML-инженеры, пользователи, разметчики, бизнес и другие команды).
• Тренироваться писать хорошие технические (и не только) тексты.

Если вы хотите узнать ещё больше об организации процессов ML-разработки, подписывайтесь на наш Телеграм-канал Варим ML.