How to Write Design Docs for Machine Learning Systems

eugeneyan

Начните здесь Статьи Выступления Прототипирование Обо мне

Как писать design-документы для систем машинного обучения

[ writing machinelearning engineering ] · 15 мин чтения

Это часть II моего ответа на самый популярный вопрос из опроса по темам (часть I здесь): «Как писать design-документы для проектов по data science / машинному обучению?»

Также переведено на японский (автор перевода — Kaichi Nihira)

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

Глубокое осмысление приходит вместе с написанием design-документа. Чтобы предложить хороший дизайн, нужно исследовать и понять проблемное пространство. Затем, излагая узнанное в документе с разными уровнями детализации, вы вынуждены прояснять и упорядочивать свои мысли. Хорошего текста не бывает без хорошего мышления.

«Полноценные предложения писать труднее. В них есть глаголы. У абзацев есть ключевые фразы. Невозможно написать шестистраничную записку с повествовательной структурой и при этом не мыслить ясно». — Jeff Bezos

Распространять design-документы и получать по ним обратную связь тоже проще. Как правило, это подробные, самодостаточные документы, которые рецензенты могут прочитать и прокомментировать асинхронно. Сравните это с презентациями PowerPoint, которые требуют, чтобы докладчик и аудитория находились в одной комнате (или теперь — в одном Zoom).

Обязательно ли писать design-документ? Конечно, нет. Но если его не написать, возникает риск построить не то, что нужно, или то, что запросили, но что в итоге окажется невостребованным. Я также видел, как дорогостоящие проекты останавливались из-за просчётов в дизайне, обнаруженных на поздней стадии, — из-за плохо сформулированной постановки задачи или технического выбора, который не масштабируется. Задним числом такие потери можно было бы смягчить, вложив время в написание и рецензирование design-документа.

Мы пройдёмся по подсказкам о том, что стоит освещать в design-документах для систем машинного обучения — эти подсказки будут направлять процесс мышления. Мои design-документы обычно строятся по фреймворку Why, What, How, о котором я рассказывал на прошлой неделе (пожалуйста, бегло просмотрите его, если ещё не читали). Затем я расскажу, как получаю обратную связь через двухэтапный процесс ревью.

Why и What design-документов How design-документов Методология: как решить проблему с помощью данных и ML Реализация: как построить и эксплуатировать систему Рассмотренные и отклонённые альтернативы Рецензирование design-документов в два этапа

Простой шаблон, доступный по низкой цене — бесплатно: ml-design-docs

Why и What design-документов

Design-документ должен начинаться с ответа на вопросы Why и What.

Почему мы должны решать эту проблему? Почему именно сейчас? Объясните мотивацию своего предложения и убедите читателей в его важности. В чём выгода для клиента или для бизнеса? Если вы строите систему на замену, объясните, почему улучшения существующей системы не сработают так же хорошо. Если есть альтернативы, объясните, почему предлагаемая вами система лучше.

Каковы критерии успеха? Их часто формулируют как бизнес-цели — например, рост вовлечённости клиентов, выручки или снижение издержек. Их также можно сформулировать как операционные цели или новые возможности (например, возможность откатывать модели, отдавать признаки в реальном времени и т. д.).

Каковы требования и ограничения? Функциональные требования — это те, что должны быть выполнены для сдачи проекта. Описывайте их с точки зрения клиента — как клиент будет это воспринимать и/или какую получит выгоду? Применительно к машинному обучению у нас будут специфические требования для каждого приложения, например:

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

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

Что входит в scope, а что нет? Некоторые проблемы слишком велики, чтобы решить их разом. Чтобы выпустить продукт — и получить обратную связь от клиентов — за разумное время, нам, возможно, придётся урезать задачу до приемлемого размера. Честно скажите, что остаётся за рамками scope. Возможно, нам также придётся взять на себя технический долг, чтобы уложиться в сроки и бюджет. Это нормально. Тем не менее делайте это осознанно и имейте план как можно скорее погасить этот технический долг.

Каковы наши допущения? Делайте явными свои допущения и понимание окружения. Например, если вы строите рекомендательную систему, сколько у вас товаров и пользователей? Сколько ожидается запросов в секунду? Это определяет, как вы формулируете задачу. Применять обучение с подкреплением к большим дискретным пространствам действий (то есть к большому числу товаров) бывает сложно, тогда как простой приближённый поиск ближайших соседей хорошо масштабируется.

How design-документов

Ответ на вопрос How в design-документе может выглядеть очень по-разному для каждой ML-системы. Тем не менее вот список того, что стоит учесть в design-документе, разбитый на две части (методология и реализация). Их следует воспринимать как чеклист/справочник, и они не претендуют на полноту. Помните: цель design-документа — помочь вам думать и получить обратную связь. Поэтому пишите всё, что необходимо для достижения этой цели.

Методология: как решать проблемы с помощью данных и ML

Этот раздел похож на раздел с методами в научных статьях по машинному обучению. Несколько ключевых моментов, которые я обычно освещаю:

Постановка задачи. Заявите, как вы будете формулировать проблему. В машинном обучении одну и ту же задачу можно решать совершенно разными подходами. Если это рекомендательная система, вы используете подход на основе контента или коллаборативный? Будет ли это рекомендатель item-to-item или user-to-item? На чём фокусируется ваша система — на генерации кандидатов или на ранжировании? Конкретика помогает сузить пространство поиска и упрощает остальную часть design-документа.

Также чётко определите, какую именно проблему вы решаете. Например, рекомендательные системы часто решают суррогатную задачу — Netflix Challenge исходит из того, что точное предсказание пользовательских оценок ведёт к эффективным рекомендациям фильмов. Другие метки включают вероятность того, что видео будет воспроизведено, и количество просмотренных минут. Выбор суррогатной обучающей задачи будет иметь чрезмерно большое значение для A/B-тестирования.

В качестве другого примера рассмотрим обнаружение мошенничества. Эту задачу можно решать как без учителя, так и с учителем. Подход без учителя не требует меток и может использовать такие техники, как обнаружение выбросов с помощью isolation forests или выявление мошеннических сетей через кластеризацию на графах. Подход с учителем потребует продумать получение меток и то, как балансировать между precision (больше непойманного мошенничества) и recall (больше ложных тревог).

Данные. Опишите данные и сущности, на которых будет обучаться ваша ML-модель. Часто используются данные о клиенте (например, демография), события клиента (например, клики, покупки) и товары (например, метаданные, текстовое описание, изображения). Если вы используете данные о клиентах, уделите внимание аспектам приватности и безопасности данных (рассмотрено в разделе реализация).

Техники. Опишите техники машинного обучения, которые вы попробуете/попробовали. Включите базовые методы (baselines) для сравнения. В этот раздел также могут войти подробности о том, как вы будете очищать и готовить данные, а также ваш подход к feature engineering. Хотя это и не обязательно, имеет смысл дать достаточно деталей, чтобы читатели могли реализовать/воспроизвести вашу работу.

Валидация и эксперименты. Объясните, как вы будете оценивать модели офлайн. (На мой взгляд, вы не ошибётесь, используя разбиение по времени в большинстве случаев.) Обратите внимание на различие между leave-one-last, темпоральным, случайным и пользовательским разбиениями. Объясните выбор метрик оценки и почему вы считаете их хорошими прокси-метриками для продакшн-условий. Если вы проводили эксперименты с результатами валидации, включите их.

Если вы проводите A/B-тест, укажите, будут ли treatment- и control-группы разбиваться по клиентам или по сессиям. Обозначьте метрики, которые вы будете отслеживать, и разделяйте метрики успеха и guardrail-метрики. Метрики успеха измеряют степень достижения желаемого результата (например, рост кликов, конверсии и т. д.). Guardrail-метрики защищают общий клиентский опыт и предотвращают деградацию системы — они гарантируют, что результат как минимум нейтрален (для клиента) и не может ухудшиться, как бы ни росли метрики успеха. (По возможности офлайн- и онлайн-метрики должны быть скоррелированы, но я обнаружил, что это скорее искусство, чем наука.)

Human-in-the-loop. Укажите, как в вашу систему может быть встроено вмешательство человека. У меня бывало, что category-менеджеры вводили правила, чтобы определённые категории товаров (например, секс-игрушки, нижнее бельё, оружие) не попадали на главную страницу. И наоборот, клиенты могут захотеть исключить себя из рекомендаций (например, они получают рекомендации, которые не хотят видеть на своей главной странице). Если это автоматическая система обнаружения мошенничества/одобрения кредитов, мы также можем захотеть задать пороги по денежной сумме, при превышении которых запускается обязательная проверка и подтверждение человеком.

Реализация: как построить и эксплуатировать систему

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

Высокоуровневый дизайн. Хорошая идея — начать с диаграммы, дающей общий взгляд. Хорошо подходят системно-контекстные диаграммы и диаграммы потоков данных. В ML-системах ключевые компоненты — это хранилища данных, пайплайны (например, подготовка данных, feature engineering, обучение) и serving. Покажите, как компоненты взаимодействуют друг с другом. Я часто использую диаграммы потоков данных, чтобы показать, как сырые данные преобразуются и используются для обучения моделей, а также вход и выход моей модели на этапе serving.

Инфраструктура + масштабируемость. Кратко перечислите варианты инфраструктуры и ваш окончательный выбор. Будет ли система работать on-premise, в облаке или в смешанном режиме (например, обработка данных и обучение on-premise ради безопасности данных, а serving модели в облаке ради масштабируемости)? Если вы работаете в крупной технологической компании со множеством различных вариантов вычислений и хостинга, постарайтесь сузить пространство поиска как можно раньше. Также подумайте, как ваш выбор инфраструктуры повлияет на масштабируемость — облачную систему масштабировать проще, чем добавлять серверные стойки.

Производительность (пропускная способность + задержка). Рассмотрите требования к пропускной способности (то есть запросов в секунду) и задержке (например, x мс @ p99) и перечислите, как можно улучшить производительность (например, предвычисления, кэширование). Если требуется дополнительная пропускная способность (например, чтобы выдержать пиковые дни распродаж), будете ли вы масштабироваться вертикально (то есть более мощные машины) или горизонтально (то есть больше машин того же размера) — ваша возможность сделать это будет связана с выбором инфраструктуры.

Безопасность. Укажите, как вы будете защищать своё приложение и аутентифицировать пользователей и входящие запросы. Если эндпоинт вашего приложения общедоступен, возможно, стоит подготовиться к атаке типа отказ в обслуживании (denial-of-service). В организациях с централизованными командами безопасности может быть внутренний процесс сертификации, который вы можете пройти, чтобы выявить и устранить риски.

Приватность данных. Укажите, как вы будете защищать и обеспечивать приватность клиентских данных. Будет ли ваша ML-модель обучаться на персонально идентифицируемой информации (PII)? Если да, опишите, как эта PII будет храниться, обрабатываться и использоваться в вашей модели. Также рассмотрите, как ваша система будет соответствовать политикам хранения и удаления данных, таким как GDPR. (Я строил системы — в здравоохранении и в управлении персоналом, — где PII считалась настолько чувствительной, что мы отказывались её получать, не говоря уже о том, чтобы использовать.)

Мониторинг + оповещения. Эксплуатировать систему без мониторинга — всё равно что ехать ночью без фар: отсутствие видимости нервирует. Опишите подробно, как вы будете отслеживать производительность системы (например, пропускную способность, задержку, частоту ошибок и т. д.). Мониторинг можно вести на стороне сервера (например, эндпоинт модели) или на стороне клиента (например, потребителя), причём во втором случае учитывается сетевая задержка. Также перечислите оповещения, которые будут запускать вмешательство человека (например, дежурного on-call).

Стоимость. Это будет ключевой заботой для лиц, принимающих решения и держащих кошелёк. Не имеет смысла, если стоимость эксплуатации вашей системы превышает приносимую ею выручку. Сюда следует включить и стоимость труда — сколько инженеров и учёных нужно для построения системы и на какой срок? Если ваша система работает в облаке, оцените количество инстансов, необходимых для обработки данных (например, кластеры EMR), а также для обучения и serving модели (например, GPU-инстансы, AWS Lambda).

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

Риски и неопределённости. Риски — это известные неизвестные; неопределённости — это неизвестные неизвестные. Обозначьте их в меру своих возможностей. Это позволяет рецензентам помочь выявить просчёты в дизайне и тупиковые ходы, а также дать рекомендации, как их избежать/устранить.

Прочее. Существует неполный список других вопросов, которые могут быть актуальны для вашей системы. Сюда входят операционная стратегия (например, мониторинг, дежурство on-call), откаты моделей, обеспечение качества, расширяемость, а также размер модели и энергопотребление (если она используется в мобильных приложениях). Рассматривайте их, если они ключевые для вашей системы.

Рассмотренные и отклонённые альтернативы

Полезно включить раздел об альтернативах, которые вы рассмотрели, но отклонили. Перечислите их плюсы и минусы, а также обоснование вашего решения. Ваше решение будет основано на допущениях об окружении и о требованиях, поэтому его стоит задокументировать. Если окружение изменится, этот раздел поможет вам пересмотреть прошлые решения.

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

К этому моменту вы, возможно, ищете шаблон. Я бы тоже искал. Тем не менее я пришёл к выводу, что идеального шаблона для design-документов не существует. Оптимальная структура и разделы будут различаться для каждой ML-системы.

Мой опыт также сделал меня осторожным в отношении предоставления и использования шаблонов. Если следовать им слепо, шаблоны приводят к тому, что авторы играют в «заполни пропуски». В результате они чрезмерно сосредотачиваются на заполнении разделов и пренебрегают аспектами, уникальными для их системы или приложения. И наоборот, в некоторых шаблонах есть избыточные разделы, где вы пересказываете информацию, которую ваша аудитория уже знает (например, технологический стек организации/команды) — это пустая трата места в документе и времени ваших читателей.

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

Тем не менее, если вы всё же ищете шаблон, который направит ваше мышление, вот минимальный шаблон, намеренно сделанный лаконичным.

Рецензирование design-документов в два этапа

Я считаю полезным проводить рецензирование в два этапа: pre-review и review.

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

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

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

Review будет более формальным и охватит более широкую аудиторию из старших технических специалистов и лиц, принимающих решения. Чётко обозначьте, чего вы хотите от ревью. Какие риски/неопределённости нужно проработать? Какие решения нужно принять? Какая помощь вам нужна? Если вы хорошо провели pre-review, вносить серьёзные изменения в дизайн на этом этапе должно потребоваться нечасто.

На этом этапе design-документ должен содержать необходимые детали и быть написан структурированной прозой. Очень помогут количественные оценки (например, пропускная способность, задержка, стоимость) и результаты офлайн-экспериментов (например, hit@10, nDCG). Диаграммы обязательны. Вопросы, заданные pre-рецензентами, можно вынести в приложение в виде раздела FAQ.

Scott написал пост с рекомендациями о том, как проводить совещания (в Amazon), например «иметь в комнате нужных людей» и «оставлять своё эго за дверью». Думаю, многое из этого применимо и к ревью design-документов, поэтому отсылаю вас к его посту.

Заключение

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

Тем не менее писать design-документ бывает полезно, когда:

Проблема и/или решение неоднозначны или плохо изучены (например, блокчейн). Влияние велико (например, обращено к клиентам, имеет нижестоящее воздействие на другие сервисы). Трудозатраты на реализацию велики (например, несколько команд на протяжении нескольких месяцев).

Пишете ли вы свой первый или двадцатый design-документ для системы машинного обучения, надеюсь, эта статья окажется вам полезной. Я что-то упустил? Напишите мне @eugeneyan!

Вот часть 2 — Design-документы для систем машинного обучения • Подача через Why, What, How • Методология: решение проблемы с помощью данных и ML • Реализация: построение и эксплуатация системы • Рецензирование вашего design-документа в два этапа https://t.co/KQYpZg0sCp — Eugene Yan (@eugeneyan) March 9, 2021

Спасибо Yang Xinyi за чтение черновиков.

Если вы нашли это полезным, пожалуйста, ссылайтесь на эту статью так:

Yan, Ziyou. (Mar 2021). How to Write Design Docs for Machine Learning Systems. eugeneyan.com. https://eugeneyan.com/writing/ml-design-docs/.

или

@article{yan2021design, title = {How to Write Design Docs for Machine Learning Systems}, author = {Yan, Ziyou}, journal = {eugeneyan.com}, year = {2021}, month = {Mar}, url = {https://eugeneyan.com/writing/ml-design-docs/} }

Присоединяйтесь к 11 800+ читателям, получающим обновления о машинном обучении, RecSys, LLM и инженерии.