Модель картки написання Guide для ML інженерів

Модельна карта — це короткий документ, який описує модель ML — її мету, тренувальні дані, результати оцінки, обмеження і етичні роздуми. Спочатку запропоновані дослідниками Google в 2018 році, моделі карт стали стандартом для відповідальної документації моделей. Якщо ви працюєте з моделями ML професійно, ви будете писати і підтримувати карти моделей. Цей посібник показує вам, як це зробити, зрозумілою, професійною англійською мовою.

---

Що таке картка моделі?

** Модель картки ** є стандартизованим форматом документації для моделей ML, аналогічним до вкладки пакунка ліків або етикетки харчової цінності. Вона надає користувачам, аудиторам і командам нижнього рівня інформацію, яка їм потрібна, щоб вирішити, чи використовувати модель, зрозуміти її обмеження і розгорнути її відповідально.

«Перед тим, як розгорнути модель виробника, наша команда з відповідності попросила про карту моделі — зокрема, про розділ оцінки упереджень і про заплановані випадки використання»

---

Стандартна модель структури карт

Розділ 1: Детальні відомості про модель

Введіть модель з метаданими, які кожен може швидко сканувати.

Включити:

• Назва моделі і версія
• Тип моделі (наприклад, * класифікація тексту, генерація зображень, вбудована модель *)
• Організація/ команда, яка розробила його
• Дата навчання/ випуску
• Функціональна модель тренування і ключові гіперпараметри (необов’ язкові)
• Контакт для питань

Шаблон:**

## Model Details

- **Model name**: SupportClassifier v2.1
- **Model type**: Multi-label text classifier
- **Architecture**: Fine-tuned DistilBERT
- **Developed by**: ML Platform Team, Acme Corp
- **Date**: March 2026
- **Framework**: PyTorch 2.2, Hugging Face Transformers 4.38
- **Contact**: mlteam@acme.com

---

Розділ 2: Зазначене використання

Будь ясно про те, для чого модель розроблена - і що вона не є.

Підходить для:

«Ця модель розроблена для класифікації квитків на підтримку клієнтів в одну з 14 попередньо визначених категорій, щоб ввімкнути автоматичне маршрутизацію до відповідної черги підтримки»

** Використання поза сферою застосування: **

«Ця модель не розроблена для класифікації юридичних документів, медичного сортування або будь-якого випадку використання, де помилки можуть завдати матеріального збитку. Його не слід використовувати без людського нагляду в автоматизованих робочих потоках з високими ставками»

Критические англоязычные шаблоны:

• “спроектована для…” - говорить про мету
• “призначено для…” — рекомендована аудиторія
• • « не слід використовувати для … » * — явні виключення
• • “та модель не підходить для…” * — м’ яка мова виключення

---

Розділ 3: Тренувальні дані

Документуйте, які дані було використано, звідки вони були отримані, а також будь- які важливі застереження.

Включити:

• Назва і версія набору даних
• Розмір (кількість прикладів)
• Діапазон дат (коли були зібрані дані?)
• Джерело (внутрішнє, публічне, ліцензоване стороннім)
• Кроки передобробки
• Будь- які відомі відхилення у даних

Шаблон:**

## Training Data

The model was trained on the internal Customer Support Corpus v3 (Q1 2023 – Q4 2025):

- **Size**: 120,000 labelled support tickets
- **Languages**: English only
- **Label distribution**: Balanced across 14 categories (≈8,500 examples per class)
- **Preprocessing**: PII removed via named-entity redaction; tickets shorter than 10 tokens excluded
- **Known limitations**: Underrepresents tickets from APAC region (≈8% of training data). Performance on APAC tickets may be lower.

---

Розділ 4: Результати оцінки

Це найважливіший розділ для учасників, які вирішують, чи довіряти і розгортати модель.

Включити:

• Оцінка набору даних (назва, розмір, спосіб його створення)
• Основні метричні дані (з цифрами)
• Розбивка за підгрупами, якщо це можливо
• Порівняння з базою

Шаблон:**

## Evaluation Results

Evaluated on the held-out Support Test Set (15,000 tickets, Q1 2026):

| Metric | Score |
|--------|-------|
| Accuracy | 94.2% |
| Macro F1 | 0.91 |
| Macro Precision | 0.92 |
| Macro Recall | 0.90 |

**Baseline comparison**: The previous rule-based routing system achieved 71% accuracy
on the same test set.

**Subgroup performance** (by region):
| Region | Accuracy |
|--------|----------|
| North America | 95.8% |
| EMEA | 94.1% |
| APAC | 88.3% |

*Note: APAC performance is lower, consistent with underrepresentation in training data.*

---

Розділ 5: Етичні роздуми

Обговоріть упередження, справедливість і потенційний шкоду. Цей розділ потрібен для будь- якої моделі, яку буде розгорнуто для кінцевих користувачів.

Шаблон:**

## Ethical Considerations

**Bias**: The model may perform less accurately on tickets written in non-native English
due to lower representation of such language patterns in the training corpus.

**Fairness**: Routing errors may disproportionately affect APAC customers. We recommend
monitoring error rates by region in production and rebalancing training data before v3.

**Privacy**: Training data has been through PII redaction. No customer names, emails,
or account numbers are present in stored artefacts.

**Misuse risk**: Misclassification could delay critical support requests. Human
review is required for any ticket classified under 'Critical Outage' or 'Legal'.

** Корисні фрази: **

• • “може непропорційно вплинути…” *
• “ми рекомендуємо моніторинг…”
• “для… потрібна перевірка людиною”
• “модель не розроблена для автономного прийняття рішень в…”

---

Розділ 6: Обмеження та відомі проблеми

Модель карти повинна бути чесною щодо режимів аварій.

Шаблон:**

## Limitations

- The model was trained on English-only data and will perform poorly on
  multilingual tickets or heavily code-switched text.
- Tickets shorter than 15 tokens may produce unreliable classifications.
- The model does not distinguish between 'Billing – refund' and 'Billing – dispute'
  in ambiguous cases; see error analysis for examples.
- Performance degrades on ticket categories introduced after the training cutoff
  (December 2025).

---

Розділ 7: Розгортання та інфраструктура

Оперативні дані для команд, що розгортають модель.

Включити:

• Визначення апаратних вимог
• Очікувана затримка
• Обслуговування структури
• Моніторинг рекомендацій

Шаблон:**

## Deployment Notes

- **Hardware**: CPU inference sufficient; single-instance p99 latency ~45ms
- **Memory**: 512MB RAM minimum; 1GB recommended
- **Serving**: TorchServe 0.9; model is packaged as `.mar` artefact
- **Monitoring**: Track accuracy, F1 per category, and inference latency.
  Alert if accuracy drops below 90% over a rolling 7-day window.
- **Retraining trigger**: Quarterly or when accuracy drops below 88%.

---

Мова програмування Лінгвістична мова програмування

Будь конкретним, а не неопределенным

❌ “Модель добре працює на більшості вхідних даних.” ✅ “Модель досягає 94% точності на випробувальному наборі з 15 000 квитків.”

Будь чесним щодо обмежень

❌ “Модель обробляє всі типи квитків.” ✅ “Модель може виробляти ненадійні виводи для типів квитків, які не присутні в тренувальних даних.”

Використовувати пасивний голос для стандартних вказівок документації

• “Модель тренировалась на…”
• “Оцінка була виконана…”
• “ПІІ було видалено перед тренуванням.”

Використовувати активний голос для рекомендацій

• • “Ми рекомендуємо моніторинг…” *
• “Командам слід уникати використання цієї моделі для…”

---

Practice

Поглибте свій словниковий запас документації з ML за допомогою ** Набір вправ з прикладного штучного інтелекту та права ** і ** Інженер-технолог з інженерних систем **.

Мова програмування: мова програмування для інженерів

Написання картки моделі не просто про детальний опис роботи вашої моделі; це про передачу складної інформації чітко і ефективно різноманітній команді - часто включаючи колег, які розвивають свою вправність в англійській мові. Як інженер з машинного навчання, ви повинні точно сформулювати технічні деталі, але також пам’ятати про використану мову, щоб всі розуміли наслідки вашої роботи. Це особливо важливо при співпраці над проектами, де члени команди можуть не володіти англійською мовою.

Одна з найпоширеніших проблем виникає під час перегляду коду. Уявіть, що ви отримуєте коментар на кшталт: «Цій частині потрібно більше ясності. Пояснення джерел тренувальних даних недостатньо. “Хоча технічно коректно, ця фраза може відчуватися різкою і потенційно заляканою для когось, хто все ще будує свій словниковий запас. Більш конструктивним підходом було б: «Чи можете ви розібратися в джерелах, використаних для створення тренувального набору даних? Зокрема, чи могли б ви додати речення, яке описує * походження даних * — звідки вони походять і чи є у них якісь відомі упередження?» Використання таких термінів, як « походження даних », негайно сигналізує про технічну концепцію, але якщо ви оформите запит як запрошення до * розробки *, зворотній зв’ язок буде більш доступним. Аналогічно, в обговореннях Slack про описи PR, уникнення надто коротких або жаргонних заяв є життєво важливим. Замість того, щоб просто сказати « Оновлена модель », спробуйте « Внесено зміни для поліпшення точності прогнозування набору перевірки, як це виміряно за рахунком F1. » Останнє забезпечує контекст і кількісну метрику — речі, які часто легше зрозуміти навіть з обмеженою вправністю у англійській мові.

Крім того, пам’ ятайте про пасивний голос. Хоча іноді неминуча в технічних описах, надмірне використання може затемнити відповідальність. Замість « Модель було оцінено за допомогою … » краще сказати « Ми * оцінили * модель … » Цей простий зсув підкреслює вашу роль і внесок. Зверніть увагу на те, як ви описуєте обмеження — прийнятними є такі формулювання, як « Модель має обмеження », але надання докладнішого пояснення — « Модель демонструє меншу точність для зображень у умовах слабкого освітлення через недостатність даних тренування у цих сценаріях » — значно збільшить ясність. Нарешті, не вагайтеся попросити про пояснення, якщо ви не впевнені в розумінні когось. Швидке запитання на кшталт «Чи має це пояснення сенс?» може запобігти непорозумінням і сприяти більш співпрацюючому середовищу.

Пам’ятайте, ефективне спілкування - це двостороння дорога. Будучи обізнаним про ваш вибір мови і пропонуючи підтримку колегам, які розвивають свої навички англійської мови, ви значно сприяєте створенню більш інклюзивної і продуктивної інженерної команди.