Описание модели в каталоге: какие поля нужны команде

Зачем команде нужен единый шаблон карточки

Когда в каталоге у модели написано только "быстрая", "умная" или "для продакшена", это почти ничего не объясняет. Для одного человека "быстрая" - это ответ за 700 мс. Для другого - приемлемая работа в пакетной задаче за 10 секунд. Без общего шаблона команда обсуждает не модель, а свои догадки о ней.

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

Из-за свободного формата ломаются простые вещи. Команда берет модель для чата поддержки, а потом выясняет, что она хорошо пишет текст, но плохо держит JSON-схему. Или модель подходит по качеству, но не проходит по классу данных для запросов с ПДн. Или в описании нет реальной задержки, и сервис упирается в SLA уже на первом пилоте.

Единый шаблон нужен не для бюрократии. Он нужен, чтобы по карточке за минуту принять обычные рабочие решения:

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

Хорошая карточка убирает споры на уровне слов и переводит разговор в проверяемые поля. Тогда вопрос "подходит или нет" решают по задержке, классу данных, контексту и формату вывода, а не по чужому впечатлению после одного удачного теста.

Это особенно важно там, где есть требования по 152-ФЗ или внутренние правила работы с данными. Если карточки заполнены кто как хочет, согласование тянется, пилоты буксуют, а инженеры держат лишние ограничения в голове. Когда шаблон один, каталог становится рабочим инструментом, а не витриной с красивыми ярлыками.

Какие поля стоит сделать обязательными

Пока в каталоге 20 моделей, детали еще можно держать в голове. Когда их 100 и больше, память заканчивается быстро. Если команда подключает модели через один OpenAI-совместимый шлюз, например RU LLM, путаница начинается еще раньше: имена похожи, API одинаковый, а поведение у моделей разное.

Хорошее описание модели похоже на техпаспорт. Меньше общих слов, больше фактов, по которым сразу видно, можно ли брать модель в работу.

Минимум, без которого карточка не работает

Указывайте полный идентификатор модели и версию без внутренних сокращений. "Qwen 3 32B" и "Qwen 3 32B Instruct" - уже разные варианты, а суффикс провайдера или дата релиза часто меняют качество, лимиты и цену.

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

Задержку фиксируйте в двух срезах: средняя и p95, отдельно для короткого и длинного запроса. Один показатель вроде "ответ за 2 секунды" почти бесполезен. Намного честнее задать профиль нагрузки: короткий запрос на 300 входных токенов и 200 выходных, длинный запрос на 10 000 входных токенов и 1 000 выходных.

Класс данных задавайте явно: открытые, внутренние, ПДн, чувствительные. Рядом добавляйте простое правило доступа. Например: "ПДн - только после маскирования", "чувствительные - нельзя", "внутренние - можно". Иначе люди читают метку по-своему, и каталог перестает защищать от ошибок.

Размер контекста и лимит на ответ тоже нужны в явном виде. Контекст 128k не означает, что модель спокойно вернет большой отчет. Если максимум ответа 4k токенов, длинная сводка оборвется на середине.

Поддержку JSON Schema, вызова инструментов и потокового ответа лучше отмечать по отдельности. Общая пометка "есть структурированный вывод" слишком расплывчата. Модель может стримить текст, но не держать строгую схему JSON. Для чата это терпимо, для бэкенда уже нет.

Как записывать поля

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

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

Как писать про задержку без путаницы

Одно число в карточке почти всегда вводит в заблуждение. Если написать просто "2 секунды", команда не поймет, это обычное время ответа или редкий удачный замер без нагрузки. Для работы нужен минимум из двух метрик: среднее время и p95. Среднее показывает обычный случай, а p95 - что увидит пользователь в плохие, но все еще частые моменты.

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

Полезно писать замеры по двум типам нагрузки: короткий запрос и длинный запрос. Например, 300 входных токенов и ответ до 150 токенов для диалога, а затем 8 000 входных токенов и ответ до 1 000 токенов для разбора документа. Одна и та же модель может быть быстрой в чате и заметно тяжелеть на длинном контексте.

Что фиксировать рядом с цифрами

Без условий замера цифры спорят друг с другом, а не помогают. Достаточно четырех вещей:

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

Если команда работает через RU LLM, полезно прямо указывать, что тесты шли через единый эндпоинт и где находился клиент. Для российских команд это меняет картину: задержка из Москвы до модели в российском ЦОДе и до внешнего провайдера ощущается по-разному.

Еще один полезный столбец в карточке - "порог для сценария". Он отвечает на простой вопрос: после какого времени модель уже мешает задаче. Для онлайн-чата порог может быть 1,5 секунды до первого токена. Для внутреннего анализа заявок допустимы 8-12 секунд полного ответа. Такая пометка быстро отсекает неподходящие варианты.

Хорошая запись выглядит так: "Короткий чатовый запрос, Москва, 20 параллельных сессий: TTFT 0,8 с в среднем, p95 1,4 с; полный ответ 2,1 с в среднем, p95 3,7 с. Длинный документ: TTFT 1,9 с, полный ответ 11,6 с, p95 18,2 с. Для подсказок оператору подходит, для живого диалога с клиентом на длинных промптах уже тормозит".

Как помечать класс данных и ограничения

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

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

Сам класс не заменяет ограничений. В карточке рядом должны стоять короткие поля: ПДн, коммерческая тайна, маскирование PII, аудит-трейлы, логи, бэкапы. Тогда человек видит не абстрактную "безопасность", а конкретный режим работы модели.

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

Место хранения логов и бэкапов тоже лучше вынести в отдельные строки. Для 152-ФЗ это не мелочь. Если логи и бэкапы лежат в РФ, напишите это коротко. Если маршрут модели уводит данные за пределы российского контура, карточка должна говорить об этом сразу.

Если вы работаете через RU LLM, часть этих полей можно заполнить без догадок: сервис хранит логи и бэкапы на серверах в РФ, а маскирование PII, AI-Law метки и аудит-трейлы встроены в каждый запрос. Это хороший пример того, как юридическое требование превращается в понятные поля каталога, а не в длинный абзац.

Хорошая метка класса данных всегда связана с внутренним правилом: что разрешает 152-ФЗ, когда нужен отдельный контур, кто согласует исключение. Если карточка не отвечает на эти вопросы за 20 секунд, команда начнет додумывать сама.

Что писать про контекст и структурированный вывод

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

На практике рабочий запас почти всегда меньше максимума. Если модель заявляет 128k, в каталоге лучше писать не только это, но и то, что при 80-100k она еще держит инструкцию, а ближе к пределу чаще теряет детали, путает ссылки на фрагменты текста или начинает сжимать ответ.

Контекст

Лимит на ответ нужен отдельным полем. Иначе разработчик видит большой входной контекст, отправляет длинный документ и ждет развернутый итог, а модель обрезает ответ на середине таблицы или JSON. Для каталога удобен такой формат: "Контекст: 128k. Рабочий запас: до 96k. Ответ: до 4k токенов".

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

Структурированный вывод

Поле "структурированный вывод JSON" лучше не сводить к "да/нет". Команде нужно знать, держит ли модель строгую JSON Schema или она просто обычно возвращает JSON-похожий текст. Для продакшена это большая разница.

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

Лучше сразу дать мини-примеры. Валидный ответ: {"status":"approved","score":0.91,"reasons":["доход подтвержден"]}. Невалидный ответ: Результат проверки: {"status":"approved","score":"0.91"}. Во втором случае модель добавила лишний текст и вернула число строкой.

Если вы гоняете модели через единый API, как в RU LLM, эти пометки особенно полезны: один и тот же SDK не спасает от того, что разные модели по-разному держат схему. Пара честных строк в каталоге экономит много времени на парсинге, ретраях и ручной чистке ответов.

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

Описание модели должно отвечать на простой вопрос: что команда сможет сделать с этой моделью в реальной работе. Если в карточке написано только про бенчмарки, люди начинают гадать. Если там есть понятные сценарии вроде "разобрать письмо клиента и поставить один из 12 статусов за 1,5 секунды", выбор идет намного быстрее.

Лучше давать 5-7 примеров задач на языке бизнеса, а не на языке тестов и лидербордов. Подойдут такие формулировки:

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

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

Что писать в каждом примере

У каждого сценария должны быть три опоры:

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

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

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

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

Как собрать карточку модели по шагам

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

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

1. Сначала утвердите одну форму для всех новых моделей. В ней должны быть одинаковые поля, одинаковые единицы измерения и одинаковые правила заполнения. Если поле нельзя проверить, его лучше убрать или переписать.
2. Потом снимите замеры на одном и том же наборе промптов. Не смешивайте тесты из поддержки, аналитики и генерации кода в одну цифру. Возьмите короткий набор типовых запросов и прогоняйте через него каждую новую модель.
3. После этого согласуйте класс данных. Безопасность и юристы должны явно сказать, можно ли отправлять в модель внутренние документы, персональные данные, платежную информацию или только обезличенный текст.
4. Дальше проверьте совместимость на коротком техническом тесте. Достаточно нескольких сценариев: валидный JSON, сломанный JSON, вызов инструмента, повторный вызов после ошибки. Такой тест быстро показывает, можно ли ставить модель в прод.
5. В конце назначьте владельца карточки и дату пересмотра. У модели может смениться провайдер, цена, лимит контекста или поведение на structured output. Если никто не отвечает за обновление, карточка стареет за пару недель.

Если вы подключаете модели через RU LLM, полезно фиксировать в карточке не только имя модели, но и конкретный маршрут или провайдера. Один и тот же класс модели у разных поставщиков может дать разную задержку, лимиты и поведение на JSON.

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

Пример для службы поддержки банка

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

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

Для такого сценария в карточке стоит сразу указать:

• тип входа: короткие обращения до 300-500 токенов;
• класс данных: только обезличенный текст;
• задержка: p50 и p95 на коротких запросах;
• structured output: стабильный JSON по фиксированной схеме;
• примеры задач: категория обращения, уровень риска, черновик ответа.

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

В карточке лучше писать не "быстро" и не "поддерживает JSON", а конкретно. Например: p95 - 1.4 с на входе 250 токенов и выходе 120 токенов; успешная выдача JSON по схеме - 98.7% на наборе из 2 000 обращений.

Ожидаемый ответ можно зафиксировать так:

{
  "category": "card_payment_issue",
  "risk": "medium",
  "draft_reply": "Проверю детали операции и подскажу, что делать дальше."
}

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

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

Где команда ошибается чаще всего

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

Первая ошибка - писать "низкая задержка" вместо чисел. Для чата, классификации и извлечения данных это разные режимы. Лучше указать хотя бы p50 и p95, отдельно для времени до первого токена и для полного ответа, и рядом дать условия замера: размер входа, размер ответа, потоковый режим или нет. Иначе "быстро" у одного человека значит 2 секунды, а у другого 12.

Вторая ошибка связана с контекстом. В карточку часто ставят максимальный лимит из описания провайдера, например 128k, и на этом успокаиваются. На деле рабочий предел обычно ниже: качество падает, цена растет, а длинный промпт начинает тормозить весь сценарий. Поэтому нужны два поля: жесткий максимум и рабочий лимит, на котором команда уже проверила модель на своих задачах.

Третья ошибка - один класс данных для всех случаев. Так делать нельзя. Модель может подходить для обезличенных обращений, но не подходить для запросов с паспортными данными, номером карты или внутренними документами. Класс данных стоит привязывать не к названию модели, а к сценарию и защитным мерам. Если команда работает через RU LLM, в карточке можно отдельно отметить, что сценарий допустим только при маскировании PII и хранении логов внутри РФ.

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

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

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

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

Короткая проверка и следующие шаги

Даже хорошая карточка быстро стареет, если ее не проверять по простому чек-листу. На это обычно хватает пары минут.

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

Под рукой стоит держать короткую проверку:

• сверить задержку, цену, размер контекста и дату последнего замера;
• проверить метки по данным: что можно отправлять, что нельзя, где нужны маскирование и аудит;
• убедиться, что у модели есть 2-3 реальные задачи, а не общие фразы вроде "для текста";
• удалить поля, по которым никто не выбирает модель;
• обновить карточку, если изменилась версия модели, провайдер или тариф.

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

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

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

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