Справочник терминов для LLM-команды: как оформить словарь

Почему команда путает одни и те же слова

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

У команд, которые работают с LLM, это обычная история. Один термин живет сразу в трех слоях: в продукте, в интеграции и в правовом контуре. Для ML-инженера "модель" - это конкретная Llama, Qwen или DeepSeek. Для backend-разработчика то же слово может означать запись в конфиге маршрутизации. Для legal и compliance это уже часть разговора о данных, логах, маскировании PII и хранении в РФ по 152-ФЗ.

Из-за таких расхождений работа тормозится сильнее, чем кажется. Ревью затягивается, потому что люди спорят не о решении, а о словах. Тест-кейсы расходятся с описанием API. Релиз переносят не из-за бага, а из-за формулировки: что именно обещано пользователю - "OpenAI-совместимый эндпоинт", "прокси", "шлюз" или "маршрутизатор запросов".

Чаще всего разнобой всплывает здесь:

• в названиях полей API и элементов админки
• в тикетах и критериях приемки
• в договорных и правовых текстах
• в подписях дашбордов, логов и алертов

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

В RU LLM это особенно заметно. Слова "провайдер", "модель", "эндпоинт" и "лог" звучат привычно, но для разных ролей значат разное. Короткий словарь снимает эту путаницу до того, как она дойдет до релиза.

Что должно быть в словаре

Одна запись должна отвечать на пять простых вопросов: как термин называется, что он значит, как его не надо писать, где человек встречает его в продукте и кто за него отвечает. Если хотя бы одного блока нет, через пару недель команда снова начнет спорить о том же.

Проще всего хранить термин как короткую карточку. В ней обычно достаточно пяти полей:

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

Каноническое название должно быть одно. Не два равноправных варианта и не формула "можно так, можно так". Если команда выбрала слово "провайдер", не держите рядом "вендор" или "источник модели" как почти допустимые версии. Лучше сразу пометить их как нежелательные, чтобы редакторы, аналитики и разработчики не разошлись в разные стороны.

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

Пример из продукта снимает половину споров. Для RU LLM это может быть реальная строка из конфига вроде base_url=api.rullm.com, подпись в интерфейсе вроде "AI-Law" или поле в логе с идентификатором провайдера. Такой пример показывает не абстрактный смысл, а то, как термин живет в системе каждый день.

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

Как выбрать каноническое название

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

Сначала смотрите на тот канал, где ошибка обходится дороже всего. Для LLM-команды это обычно API, схемы данных и логи. Если термин уже живет в контракте API, не переводите его ради красоты. base_url, prompt caching или data residency лучше оставить на английском, если именно так их видят SDK, запросы и ответы. Русский перевод можно дать рядом как пояснение, но не как основное имя.

Отдельно разведите техническое имя и маркетинговое. Они могут сосуществовать, но не должны подменять друг друга. Например, "OpenAI-совместимый эндпоинт" описывает способ интеграции. Это не то же самое, что короткое продуктовое название. В словаре одно имя должно быть главным, а второе - помечено как описание или нежелательный вариант.

Форму термина тоже лучше закрепить заранее. Иначе словарь быстро расползется. Для каждого названия стоит зафиксировать число, регистр, сокращение и язык записи. Если команда использует AI-Law, OpenAI, base_url и "LLM" именно в таком виде, это и должно попасть в карточку.

Хорошее каноническое название короткое и узнаваемое. Плохое пытается угодить сразу всем - юристам, маркетингу и разработке. Если в RU LLM команда пишет в коде base_url, а в документации - "базовый URL шлюза", это уже два разных термина. Словарь нужен как раз для того, чтобы выбрать один основной вариант и убрать колебания.

Как отмечать запретные синонимы

Нежелательный синоним не стоит прятать внизу таблицы. Его лучше ставить рядом с каноническим названием, чтобы редактор, разработчик и саппорт сразу видели замену. Обычно хватает пяти полей: "канон", "вариант", "статус", "почему нельзя" и "чем заменить".

Записывайте не только формальные ошибки, но и живую речь команды. Если в чатах пишут "прокся", "роутер" или "наш OpenAI", эти формы тоже нужно внести. Иначе словарь выглядит аккуратно только на бумаге, а спорные слова продолжают жить в тикетах, презентациях и интерфейсе.

Причину запрета пишите прямо. Без общих фраз. Слово может путать объект, обещать лишнее или стирать границу между вашим продуктом и чужим. Для RU LLM формулировка "наш OpenAI" сбивает читателя: сервис дает OpenAI-совместимый эндпоинт, но не является OpenAI. Одна такая пометка экономит много правок.

Удобно делить варианты на три статуса:

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

После переименования не стирайте старую форму сразу. Оставьте ее еще на несколько релизов с пометкой "не использовать" и датой замены. Например, если команда раньше писала "единый эндпоинт", а потом закрепила "OpenAI-совместимый эндпоинт", обе записи должны стоять рядом. Тогда новый сотрудник поймет, что речь об одном и том же, а редактор не вернет старое слово в текст случайно.

Как добавить примеры из продукта

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

Лучше брать примеры только из того, что уже есть в продукте. Подойдет экран с настройкой base_url, ответ OpenAI-совместимого эндпоинта, запись в audit trail или фрагмент лога с меткой AI-Law. Такие примеры проще проверить, и они не расходятся с реальной системой через месяц.

Каким должен быть хороший пример

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

Например, если канонический термин - "провайдер", хороший пример можно взять из ответа API, где отдельно видны модель и источник маршрутизации. Ошибка становится заметна сразу: команда пишет "модель RU LLM", хотя RU LLM в этом случае только проксирует запрос к внешнему провайдеру. Такой пример учит быстрее, чем длинное объяснение.

Хорошо, когда примеры собраны из разных источников: из интерфейса, ответов API, схем полей, логов, audit trail и текстов ошибок. Там путаница обычно видна лучше всего.

Перед публикацией обязательно убирайте все, что относится к клиенту. Имена компаний, токены, номера договоров, user ID, email, фрагменты промптов и любые персональные данные нужно маскировать. Даже если в логах уже есть PII masking, фрагмент все равно стоит проверить вручную. В словарь часто попадает то, что разработчик не замечает с первого взгляда.

Если выбираете между "красивым" и понятным примером, берите понятный. Немного неровный, но реальный кусок ответа API почти всегда полезнее, чем выдуманный образец.

Пример словаря для LLM-платформы

Хороший словарь не объясняет термин "вообще". Он фиксирует, как команда пишет его в интерфейсе, документации, тикетах и продажных материалах. Для LLM-платформы это особенно важно: одно неточное слово быстро смешивает архитектуру, продукт и требования к данным.

Ниже пример того, как может выглядеть запись в словаре для RU LLM.

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

Такой формат удобен по простой причине: спор заканчивается быстро. Редактор, PM и инженер смотрят в одну строку и сразу видят правильное имя, запрещенные замены и пример из продукта.

Как собрать первую версию за неделю

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

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

Если в одном месте написано "провайдер", в другом "вендор", а в тикетах еще и "источник модели", словарь должен оставить одно каноническое название. Для таких платформ это часто всплывает вокруг слов "модель", "маршрутизация", "эндпоинт", "шлюз", reverse proxy, data residency, "152-ФЗ".

За пять рабочих дней обычно можно сделать достаточно:

• День 1: собрать сырые термины из тикетов, README и UI в одну таблицу.
• День 2: сократить список до 30-50 слов, которые команда чаще всего путает.
• День 3: разбить их по блокам и назначить владельца на каждый блок.
• День 4: провести короткий разбор с ML, backend, product и legal.
• День 5: заморозить версию v0.1 и открыть очередь правок.

Владельцы нужны не ради формальности, а чтобы спор не висел неделями. ML-команда может отвечать за названия моделей и режимов вызова. Backend - за термины API, поля запросов и совместимость. Product - за слова в интерфейсе. Legal - за формулировки вокруг персональных данных, логов и требований 152-ФЗ.

Короткий разбор лучше делать на 30-40 минут. На такой встрече не редактируют весь словарь. Команда проходит только по спорным местам и сразу фиксирует одно решение.

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

Кто правит словарь и как хранить версии

Словарь должен жить там же, где команда уже читает рабочую документацию: в том же репозитории, в той же wiki или в том же разделе docs. Если держать его в отдельной таблице "на потом", через неделю появятся две версии, а через месяц никто не поймет, какая из них живая.

У словаря должен быть один владелец. Обычно это product writer, техлид или менеджер документации. Он не правит все в одиночку, но следит за правилами, принимает спорные решения и закрывает правки после review.

Разным командам не стоит заводить собственные копии. Поддержка, продукт, ML и юристы могут смотреть на один и тот же файл по-разному, но источник должен быть один. Если отделам нужны свои пометки, лучше добавить теги, статусы или отдельные представления, а не плодить дубли.

Как хранить изменения

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

Для каждого переименования записывайте минимум четыре вещи:

• старое название
• новое каноническое название
• причину правки
• дату и автора изменения

Причину стоит писать по-человечески, а не одной фразой вроде "уточнили формулировку". Лучше так: "Слово 'шлюз' оставили, потому что оно совпадает с формулировкой в продуктовой документации и не путается с хостингом моделей".

Это особенно полезно в LLM-команде, где один и тот же объект часто называют по-разному. Например, в документации RU LLM лучше один раз зафиксировать, когда команда пишет "OpenAI-совместимый эндпоинт", а когда - "API-шлюз". Иначе продукт, продажи и интеграторы начнут объяснять одну и ту же вещь разными словами.

Версии удобно хранить как обычные релизы документа: v1.0, v1.1, v1.2. Старые термины не удаляйте без следа. Переносите их в историю или в список запретных синонимов. Тогда команда увидит не только текущее правило, но и путь, которым к нему пришла.

Ошибки, которые ломают словарь

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

Частая проблема - слово без блока с запретными синонимами. Тогда один и тот же объект в задачах, документации и сообщениях поддержки называют по-разному: "шлюз", "прокси", "роутер". Поиск ломается, новые люди путаются, а спор о словах возвращается каждую неделю.

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

Отдельная проблема - разрыв между интерфейсом и API. Команда может переименовать термин в интерфейсе, но забыть про схему API, примеры в SDK, тексты ошибок и логи. Для пользователя это уже два разных понятия. В RU LLM это особенно заметно: если в интерфейсе пишут "LLM-шлюз", а в API и служебных сообщениях остается reverse proxy, люди начинают искать разницу там, где ее нет.

Путаница с регуляторными терминами бьет еще сильнее. Требования 152-ФЗ, метки AI-Law и внутренние пометки команды нельзя хранить в одном поле и одним тоном. 152-ФЗ описывает правовой режим работы с данными. AI-Law может относиться к маркировке и следу запроса. Внутренняя метка вроде "проверено юристами" говорит только о вашем процессе. Если смешать эти слои, команда начнет воспринимать внутреннее правило как закон.

Хороший словарь работает как фильтр. Он помогает быстро выбрать одно имя, отвергнуть остальные и одинаково назвать сущность в интерфейсе, API и документации. Если запись этого не делает, ее лучше сократить и собрать заново.

Короткая проверка перед публикацией

Перед выпуском словаря полезнее всего не спорить о стиле, а открыть 5-10 карточек подряд и проверить, можно ли пользоваться ими без пояснений в чате. Если на третьей карточке человек начинает спрашивать: "а это то же самое, что и...", значит словарь еще сырой.

Сначала посмотрите на названия. У термина должно быть одно основное имя, и только оно должно идти в интерфейсы, документацию и тикеты. Если в одной карточке вы пишете "API-шлюз", а в другой рядом живет reverse proxy как почти допустимый вариант, команда снова начнет говорить по-разному.

С нежелательными синонимами нужна жесткость. Они должны вести к одному каноническому термину, а не спорить между собой. Плохой признак - когда "эндпоинт", "базовый URL" и base_url размечены так, что каждый тянет в свою сторону. Нормальный вариант - один термин, а остальные формы помечены как недопустимые или как частные случаи.

Потом проверьте пример. Он должен показывать слово в живой фразе из продукта, а не в учебном вакууме. Для такой платформы лучше работает строка вроде: "Клиент меняет base_url на api.rullm.com и сохраняет тот же SDK". По ней сразу видно, где термин живет и как его понимает команда.

Перед публикацией хватает короткого списка:

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

Последний тест совсем простой. Дайте карточку человеку, который не писал словарь. Если он без подсказки понимает, чем "OpenAI-совместимый эндпоинт" отличается от "маршрутизации запросов" или зачем нужна метка AI-Law, карточка готова. Если нет, правьте текст, а не читателя.

Такой проход занимает 20-30 минут, но именно он делает словарь рабочим, а не формальным документом.

Что сделать после запуска словаря

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

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

Для начала достаточно четырех шагов:

• добавить словарь в чеклист онбординга
• вставить канонические термины в шаблоны задач и PRD
• проверить типовые промпты, FAQ и тексты поддержки
• использовать словарь при ревью документации и тикетов

Тогда словарь перестает быть отдельным файлом и начинает влиять на язык команды.

Раз в месяц полезно проводить короткий разбор спорных слов. Обычно хватает 30 минут. За это время команда успевает решить, что считать "провайдером", где уместно слово "модель", а где точнее писать "эндпоинт" или "маршрутизация запроса".

Отдельно следите за терминами, которые ломают общение вовне. Частая ошибка выглядит так: инженер говорит "данные остаются в РФ", а заказчик понимает это как полный локальный инференс. Если на деле в России хранятся логи и бэкапы, а запросы идут через внешнего провайдера, формулировку нужно исправить сразу. Иначе команда продает одно, обсуждает второе, а внедряет третье.

Если вы строите LLM-архитектуру в России, полезно сверять словарь с тем, как термины используются в RU LLM и в документации rullm.com. Там особенно важно не смешивать API-шлюз, провайдера, хостинг модели, OpenAI-совместимый эндпоинт, data residency и требования 152-ФЗ. Отдельно стоит закрепить формулировки вроде "маскирование PII" и "аудит-трейл", чтобы юристы, инженеры и аккаунт-команда говорили одинаково.

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