How to Write Design Docs for Machine Learning Systems

eugeneyan

eugeneyan

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

How to Write Design Docs for Machine Learning Systems

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

[ writing machinelearning engineering ] · 15 min read

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

This is part II of my answer to the top question on the topic poll (part I here): “How to write design documents for data science/machine learning projects?”

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

Also translated to Japanese (by Kaichi Nihira)

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

Design documents come in all shapes and sizes. But IMHO, they have the same purpose—to help the author think deeply about the problem and solution, and get feedback.

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

Thinking deeply comes with writing the design doc. To propose a good design, you have to research and understand the problem space. Then, communicating what you’ve learned via a document with different levels of detail forces you to clarify and organize your thoughts. Good writing does not come without good thinking.

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

“Full sentences are harder to write. They have verbs. The paragraphs have topic sentences. There is no way to write a six-page, narratively structured memo and not have clear thinking.” — Jeff Bezos

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

Distributing and getting feedback on design docs is also easier. They tend to be detailed, standalone documents that reviewers can read and provide comments on asynchronously. Contrast this to PowerPoint presentations which require a presenter and the audience in the same room (or now, in the same Zoom).

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

Is it a must to write a design doc? Of course not. But not writing one incurs the risk of building the wrong thing, or something that was requested but ends up unused. I’ve also observed costly projects halted due to design flaws discovered late in the project, because of an ill-defined problem statement or a tech choice that doesn’t scale. In hindsight, such waste could have been mitigated by investing time into writing and reviewing a design doc.

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

We’ll go over pointers on what to cover in design docs for machine learning systems—these pointers will guide the thinking process. My design docs tend to be structured via the Why, What, How framework shared last week (please skim it if you’ve not read it yet). Then, I’ll share how I get feedback via a two-step review process.

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

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

A simple template, available for the low price of free: ml-design-docs

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

The Why and What of design docs

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

A design doc should start by addressing the Whys and Whats.

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

Why should we solve this problem? Why now? Explain the motivation for your proposal and convince readers of its importance. What is the customer or business benefit? If you’re building a replacement system, explain why improvements to the existing system will not work as well. If there are alternatives, explain why your proposed system is better.

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

What are the success criteria? These are often framed as business goals, such as increased customer engagement, revenue, or reduced cost. They can also be framed as operational goals or new capabilities (e.g., ability to rollback models, serve features in real-time, etc.)

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

What are the requirements and constraints? Functional requirements are those that must be met to deliver the project. Describe them from the customer’s point of view—how will the customer experience it and/or benefit? Specific to machine learning, we’ll have specific requirements for each application, such as:

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

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

Non-functional/technical requirements define the quality of your system and determine how the system should be implemented. Usually, customers won’t notice them unless they’re not met (e.g., exceptionally high latency). Most systems will consider a similar set of requirements such as throughput, latency, security, data privacy, costs, etc.

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

What is in-scope vs out-of-scope? Some problems can be too big to solve all at once. To ship—and get feedback from customers—in a reasonable amount of time, we might need to chop it down to size. Be upfront about what’s out of scope. We might also need to take on tech debt to meet time and budget constraints. This is fine. Nonetheless, be deliberate about it and have a plan to pay off tech debt as soon as possible.

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

What are our assumptions? Make explicit your assumptions and understanding of the environment. For example, if building a recsys, how many products and users do you have? What is the expected number of requests per second? This guides how you frame the problem. It can be hard to apply reinforcement learning to large discrete action spaces (i.e., a large number of products) whereas simple approximate nearest neighbors scale well.

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

The How of design docs

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

Addressing the How in a design doc can look very different for each ML system. That said, here’s a list of things to consider in a design doc, split into two sections (methodology and implementation). These should serve as a checklist/reference and are not meant to be exhaustive. Remember, the aim of the design doc is to help you think and feedback. Thus, write whatever is necessary to achieve this goal.

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

Methodology: How to solve problems with data and ML

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

This section is similar to the methods section in machine learning papers. A couple of key points I usually cover are:

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

Problem statement. Declare how you’ll frame the problem. In machine learning, the same problem can have vastly different approaches. If it’s a recommender system, are you taking a content or collaboration-based approach? Will it be an item-to-item or user-to-item recommender? Is your system focused on candidate generation or ranking? Being specific helps narrow down your search space and simplifies the rest of the design doc.

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

Also, be clear about the problem you’re solving. For example, recommendation systems often involve solving a surrogate problem—the Netflix Challenge assumes that accurately predicting user ratings leads to effective movie recommendations. Other labels include the probability of a video being played and the number of minutes watched. The choice of your surrogate learning problem will have an outsized importance on A/B testing.

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

As another example, consider fraud detection. This can be solved via unsupervised or supervised approaches. An unsupervised approach won’t need labels and can adopt techniques such as outlier detection via isolation forests or identifying fraud networks via graph clustering. A supervised approach will need to consider label acquisition and how to balance between precision (more uncaught fraud) and recall (more false alarms).

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

Data. Describe the data and entities your ML model will be trained on. Commonly used data include customer (e.g., demographics), customer events (e.g., clicks, purchases), and items (e.g., metadata, text description, images). If you’re using customer data, pay attention to the aspects of data privacy and security (covered under implementation).

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

Techniques. Outline the machine learning techniques you’ll try/tried. Include baselines for comparison. This section may also include details on how you’ll clean and prepare the data, as well as your feature engineering approach. While not necessary, it’s a good idea to provide sufficient detail so that readers can implement/reproduce your work.

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

Validation and experimentation. Explain how you’ll evaluate models offline. (IMHO, you won’t go wrong using a time-based split most of the time.) Note the difference between leave-one-last, temporal, random, and user-based splits. Explain your choice of evaluation metrics(s) and why you think they are good proxy metrics for production conditions. If you’ve conducted experiments with validation results, include them.

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

If you’re conducting an A/B test, specify if treatment and control groups will be split by customers or sessions. Indicate the metrics you’ll monitor and distinguish between success and guardrail metrics. Success metrics measure the extent of the desired outcome (e.g., increased clicks, conversion, etc.) Guardrail metrics protect the overall customer experience and prevent deterioration of the system—they ensure the outcome is at least neutral (to the customer) and cannot get worse no matter how success metrics improve. (As much as possible, the offline and online metrics should be correlated, but I’ve found this more of an art than science.)

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

Human-in-the-loop. Indicate how human intervention can be incorporated into your system. I’ve had category managers implement rules to prevent certain product categories (e.g., adult toys, lingerie, weapons) from appearing on the home page. Conversely, customers might want to exclude themselves from recommendations (e.g., they get recommendations they don’t want seen on their home page). If it’s an automated fraud detection/loan approval system, we might also want dollar value thresholds that trigger mandatory human review and approval.

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

Implementation: How to build and operate the system

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

This section lists the non-function/technical requirements and is more engineering-heavy; it’s not necessary to address all of them. If in doubt, consult engineers for help.

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

High-level design. It’s a good idea to start with a diagram providing a high-level view. System-context diagrams and data-flow diagrams work well. In ML systems, some key components are data stores, pipelines (e.g., data preparation, feature engineering, training), and serving. Show how components interact with one another. I often use data-flow diagrams to show how raw data is transformed and used to train models, as well as the input and output of my model in serving.

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

Infra + scalability. Briefly list the infra options and your final choice. Will it run on-premise, in the cloud, or a mix of both (e.g., data processing and training on-premise for data security, model serving in the cloud for scalability). If you work in big tech with many different compute and hosting options, try to narrow down your search space early. Also, consider how your choice of infra will impact scalability—it’s easier to scale a cloud-based system than to add server racks.

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

Performance (throughput + latency). Address requirements on throughput (i.e., requests per second) and latency (e.g., x ms @ p99) and list how performance can be improved (e.g., pre-computation, caching). If additional throughput is required (e.g., to handle peak sales days), will you scale vertically (i.e., bigger machines) or horizontally (i.e., more machines of the same size)—your ability to do this will be tied to your choice of infra.

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

Security. Specify how you’ll secure your application and authenticate users and incoming requests. If your application endpoint is publicly accessible, you might want to plan for a denial-of-service attack. Organizations with centralized security teams might have an internal certification process that you can undergo to identify and patch risks.

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

Data privacy. Indicate how you’ll protect and ensure the privacy of customer data. Will your ML model learn on personally identifiable information (PII)? If so, detail how this PII will be stored, processed, and used in your model. Also, address how your system will comply with data retention and deletion policies such as GDPR. (I’ve built systems—in healthcare and human resources—where the PII was considered so sensitive that we declined to receive, not to mention use.)

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

Monitoring + alarms. Operating a system without monitoring is like driving at night without headlights—the lack of visibility is unnerving. Detail how you’ll monitor your system performance (e.g., throughput, latency, error rate, etc.) Monitoring can be done server-side (e.g., model endpoint) or client-side (e.g., consumer), with the latter including network latency. Also list the alarms that will trigger human intervention (e.g., on-call).

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

Cost. This will be a key concern for decision-makers who hold the purse strings. It won’t make sense if the cost of operating your system exceeds the revenue it generates. This should include labour cost—how many engineers and scientists do you need to build the system, and for how long? If your system runs in the cloud, estimate the number of instances required for data processing (e.g., EMR clusters), and model training and serving (e.g., GPU instances, AWS Lambda).

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

Integration points. Define how downstream services will use and interact with your endpoint. Share how the API specification looks like, and the expected input and output data. Keeping the API generic enough ensures extendability to other consuming services (i.e., higher adoption of your system).

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

Risks and uncertainties. Risks are the known unknowns; uncertainties are the unknown unknowns. Call them out to the best of your ability. This allows reviewers to help spot design flaws and rabbit holes, and provide feedback on how to avoid/address them.

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

Other stuff. There’s a non-exhaustive list of other concerns that might be relevant to your system. This includes ops strategy (e.g., monitoring, on-call), model rollbacks, quality assurance, extensibility, and model footprint and power consumption (if used in mobile apps). Address them if they are key to your system.

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

Alternatives considered and rejected

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

It’s useful to include a section on alternatives you’ve considered but rejected. List their pros and cons as well as the rationale for your decision. Your decision will be based on your assumptions about the environment and the requirements, so it’s good to document it down. If the environment changes, this section can help you reconsider past decisions.

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

This section helps you dive into the ambiguous, hidden choices and the implicit decisions made while designing your system. Being transparent allows others to check your blind spots and correct invalid assumptions. The aim is to suggest improvements to your design early, saving you from making bad or unnecessarily difficult design choices.

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

By now, you might be looking for a template. I would too. Nonetheless, I’ve come to realize there’s no perfect template for design docs. The optimal structure and sections will differ for each ML system.

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

My experience has also made me hesitant about providing and using templates. Followed blindly, templates lead to authors playing fill-in-the-blanks. As a result, they overly focus on filling in the sections, and neglect aspects unique to their system or application. Conversely, some templates have redundant sections where you rehash information that your audience already knows (e.g., organization/team tech stack)—this is a waste of document real estate and your readers’ time.

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

Writing with the intent of thinking deeply and getting feedback helps with crafting a good design doc. Focus on what you and others need to know before implementing the system; share enough detail so others can provide meaningful feedback. Doing this usually leads to good design docs. Also, use the pointers above to guide you.

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

Nonetheless, if you're still looking for a template to guide your thinking, here's a minimal template that's deliberately lean.

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

Reviewing design docs in two stages

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

I find it helpful to conduct reviews in two stages: pre-review and review.

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

Pre-review involves quickly iterating and seeking feedback from a small group (often as part of the writing process). At this stage, the design doc might be a tad rough around the edges, with open questions and paths to explore. Nonetheless, my reviewers express a preference for being involved early as the raw and fluid state (of the design) allows them to provide feedback that meaningfully shapes the direction of the system. This is the stage where mentors and seniors can help to narrow the search space and simplify the design.

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

At this stage, the document will likely be low resolution and lacking in details—this is a feature, not a bug, and allow for quickly brainstorming and iterating through alternatives. Mine looks like an outline of the eventual design doc, with most of the details and feedback in bullet form. Much of it doesn’t make it into the final design doc.

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

I tend to conduct pre-reviews one-on-one in a casual setting, usually with individual team members or mentors. If you’re doing this, be clear that it’s the pre-review phase. I’ve caused unnecessary concern when a pre-reviewer thought he was reading the final design doc (when it was just the first iteration).

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

The review will be more formal and involve a larger audience of senior technical folk and decision-makers. Be clear what you want from the review. What risks/uncertainties need to be addressed? What decisions need to be made? What help do you need? If you’ve done your pre-review well, it shouldn’t be too common to make major design changes at this stage.

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

At this stage, the design doc should have the necessary details and be in structured prose. Quantified estimates (e.g., throughput, latency, cost) and offline experiment results (e.g., hit@10, nDCG) will be very helpful. Diagrams are a must. Questions asked by pre-reviewers can be addressed in the appendix via a FAQ section.

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

Scott wrote a post that includes suggestions on how to conduct meetings (at Amazon) such as “having the right people in the room” and “checking your ego at the door”. I think much of it applies to design doc reviews as well so I’ll refer you to his post.

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

Conclusion

Заключение

Writing design docs is overhead. Minor changes (e.g., adding a feature column) or low-effort tasks (e.g., a few days) shouldn’t need a design doc—the cost of writing a full design doc will outweigh the benefits. Alternatively, prototyping can be a feasible approach for smaller systems.

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

Nonetheless, it can be useful to write a design doc when:

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

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

Whether you’re writing your first or 20th design doc for a machine learning system, I hope this write-up will be helpful for you. Did I miss anything? Reach out @eugeneyan!

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

Here's part 2 - Design docs for machine learning systems

• Framing it via Why, What, How
• Methodology: Solving the problem with data & ML
• Implementation: Building & operating the system
• Reviewing your design doc via a two-step processhttps://t.co/KQYpZg0sCp

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

Thanks to Yang Xinyi for reading drafts of this.

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

If you found this useful, please cite this write-up as:

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

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

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

or

или

@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/} }

@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/} }

Join 11,800+ readers getting updates on machine learning, RecSys, LLMs, and engineering.

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