--- language: - ru - en license: apache-2.0 base_model: DeepPavlov/rubert-base-cased library_name: transformers pipeline_tag: token-classification tags: - ner - token-classification - pii - secret-detection - credentials - masking - russian - bert --- # ner_rus_bert-secret_detection Дообученная голова `BertForTokenClassification` поверх `DeepPavlov/rubert-base-cased`, которая размечает в русскоязычном тексте **учётные данные** (логины, пароли, токены, ключи), **персональные данные** (ФИО, организации, локации) и **номера договоров**. Основной сценарий, под который она обучалась - маскирование пользовательских сообщений и фрагментов конфигов перед отправкой во внешнюю LLM. > **Модель — половина системы.** В проде она работает **в объединении с > детерминированным regex-слоем**, и все опубликованные ниже цифры покрытия > учётных данных относятся к объединению `NER ∪ regex`. Одна NER заметно слабее > по recall — так и задумано: её задача добирать то, что не ловится регулярками > (естественная формулировка, кириллица, контекст), не переусердствуя с ложными > срабатываниями. Обе половины лежат в этом репозитории: `core/scrubber.py` + > `gitleaks.toml` > См. [Детерминированный слой](#детерминированный-слой). ## Метки 17 BIO-тегов, 8 типов сущностей: | Группа | Метки | |---|---| | Учётные данные | `LOGIN`, `PASSWORD`, `AUTH_TOKEN`, `SECRET_KEY` | | ПДн | `PERSON`, `LOCATION`, `ORGANIZATION` | | Прочее | `CONTRACT_NUMBER` | Схема — `B-`/`I-`/`O`, полный список в `config.json` (`id2label`). ## Быстрый старт ```python from transformers import pipeline ner = pipeline( "token-classification", model="fef2/ner_rus_bert-secret_detection", aggregation_strategy="simple", ) text = 'user = svc_billing, password = "Xt7#pQm2Zr", api_key: sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' for e in ner(text): print(f"{e['entity_group']:<12} {e['score']:.3f} {text[e['start']:e['end']]!r}") ``` ``` LOGIN 0.936 'svc_billing' PASSWORD 0.993 'Xt7#pQm2Zr' SECRET_KEY 0.996 'sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' ``` Обратите внимание: режьте исходную строку по `start`/`end`, а **не** берите поле `word` — pipeline отдаёт его склеенным из wordpiece, с лишними пробелами (`'svc _ billing'`). **У `pipeline()` три ограничения, из-за которых он годится только для проб.** Он не режет длинный вход на окна — текст длиннее 512 wordpiece падает с `RuntimeError: The size of tensor a (1218) must match the size of tensor b (512)`; не нормализует юникод; и это **только NER**, без детерминированного слоя. Для настоящей работы возьмите `predict.py` из этого репозитория. ## Правильный путь: `predict.py` `predict.py` — перенос инференс-логики развёрнутого сервиса целиком: NFC-нормализация, нарезка на окна по 384 реальных wordpiece по границам предложений, BIO-декод, детерминированный слой, смещения в символах, склейка пересекающихся спанов. Нужны только `torch` и `transformers` — regex-половина на чистом stdlib. ```bash python predict.py --text 'password = "Xt7#pQm2Zr"' # замаскированный текст python predict.py --file документ.txt --spans # спаны построчно cat лог.txt | python predict.py --json # спаны в JSON cat лог.txt | python predict.py --json --no-rules # только NER, без regex ``` ```python from predict import Detector det = Detector("fef2/ner_rus_bert-secret_detection", device="cpu") # cuda / mps text = ('Коллеги, доступ к стенду: user = svc_billing, password = "Xt7#pQm2Zr", ' 'api_key: sk-live-4f9a2b7c1e6d8f3a0b5c9d2e. Ответственный — Петров Сергей ' 'Иванович (ПАО «Сбербанк», Санкт-Петербург), договор № 77-АБ/2025-4412.') for s in det.spans(text): print(f"{s.start:>4} {s.end:>4} {s.label:<16} {s.source:<5} {s.text!r}") print(det.mask(text)) ``` ``` 33 44 LOGIN ner 'svc_billing' 58 68 PASSWORD both 'Xt7#pQm2Zr' 80 112 SECRET_KEY both 'sk-live-4f9a2b7c1e6d8f3a0b5c9d2e' 130 152 PERSON ner 'Петров Сергей Иванович' 154 167 ORGANIZATION ner 'ПАО «Сбербанк' 170 185 LOCATION ner 'Санкт-Петербург' 198 213 CONTRACT_NUMBER ner '77-АБ/2025-4412' ``` `source` говорит, кто нашёл спан: `ner`, `regex` или `both` (нашли оба — самый спокойный случай). У чисто regex-спанов `score` равен `None`: у детерминированного правила нет вероятности, и подставлять туда единицу было бы враньём. Документ на 6800 символов режется на 4 окна и размечается целиком — граница окна не теряет спаны, потому что нарезка идёт по концам предложений и абзацев. ### Четыре контракта, которые легко нарушить **Окно — 384 *реальных* wordpiece.** Модель обучалась на окнах такого размера, и `plan_windows` закладывает 384 токена **без** учёта `[CLS]`/`[SEP]`, то есть `max_length=386` при токенизации. Если считать по-хагингфейсовски — 384 вместе со служебными, — в окно попадёт 382 реальных токена, и предсказания на длинных текстах разойдутся: два лишних wordpiece меняют каждый контекстный эмбеддинг последовательности. На эталонном сплите в этот зазор попадают 280 строк из 6312, и 5 из них предсказываются иначе. **Смещения — по NFC-нормализованному тексту.** `Detector.spans()` сам приводит вход к NFC, и `start`/`end` — индексы кодовых точек **нормализованной** строки. Для латиницы и обычной кириллицы это то же самое, но текст с составными символами (диакритика, вставки из PDF) после нормализации меняет длину, и спаны «поедут». Режьте по спанам нормализованную строку: ```python import unicodedata normalized = unicodedata.normalize("NFC", text) # ровно то, что видела модель fragment = normalized[span.start:span.end] ``` **Батчи, а не по одному.** Пропускная способность здесь берётся из батчей; `Detector(batch_size=...)` задаёт размер микро-батча окон. На CPU замеренная скорость NER-половины — около **9.5k токенов/с**; на GPU в FP16 (`fp16=True`, включается автоматически при `device="cuda"`) она перестаёт быть узким местом задолго до regex-слоя. **Модель не решает, что делать со спаном.** `mask()` подставляет `[REDACTED:LABEL]` — это пример, а не политика. Обратимое маскирование (плейсхолдеры с обратной подстановкой), пороги по `score`, отдельная политика на `PERSON` против `SECRET_KEY` — всё это ваш слой поверх спанов. ## Детерминированный слой Рядом с моделью по тому же тексту работает второй, полностью детерминированный детектор — `core.scrubber.credential_sites`. Итоговый набор спанов есть **объединение** двух источников с последующей склейкой. Он даёт постоянный, не зависящий от чекпоинта пол по типовым форматам, а NER добирает то, что регуляркой не описывается. Внутри — три детектора: | Детектор | Что ищет | Метки | |---|---|---| | `kv` | `ключ = значение` с онтологией ключей (`password`, `пароль`, `api_key`, `токен`, `login`…) | `PASSWORD` `SECRET_KEY` `AUTH_TOKEN` `LOGIN` | | `cli` | значения у известных флагов известных команд (`--password=…`, `curl -u user:pass`) | `PASSWORD` `AUTH_TOKEN` | | `opaque` | непрозрачные высокоэнтропийные значения + правила gitleaks | `AUTH_TOKEN` `SECRET_KEY` `SECRET` | Правила gitleaks отбираются по идентификатору (`…token…` → `AUTH_TOKEN`, `…key…`/`…secret…` → `SECRET_KEY`), из 222 правил конфига до рантайма доходят **168** — остальные отсеиваются фильтром по имени либо не компилируются под `re` без предупреждений. `load_gitleaks_rules` возвращает вторым значением именно счётчик отброшенных. `cli` бьёт по таблице «команда → флаг» и отдаёт только само значение пароля или токена; логин из `-u user:pass` в объединение не попадает, а голая строка подключения (`postgres://user:pass@host`) не покрывается вовсе — это осознанная граница релиза, см. [Ограничения](#ограничения). Слой умеет отличать живое значение от инертного: `${DB_PASSWORD}`, `os.environ["TOKEN"]`, ``, `changeme` и уже проставленные маркеры `[REDACTED:…]` он не трогает (`core._shim.is_inert_value`). Спан с меткой `SECRET` — это опознанное непрозрачное значение, тип которого установить не удалось; в модельный набор из 17 меток он не входит и приходит только отсюда. Замеренная цена этой половины на тестовом сплите: 2891 срабатывание, из них 452 не задевают ни одного gold-спана; вычёркивается 3.03 % всех символов, из которых 0.37 % корпуса лежит вне gold-спанов. Слой чисто питоновский и держит GIL — около 0.7 мс на текст (~460k токенов/с на ядро), так что в проде именно он, а не GPU, упирается в потолок пропускной способности. Отключается через `Detector(rules=None)` или `--no-rules` — но тогда цифры ниже к вам не относятся. ## Обучение | | | |---|---| | Базовая модель | `DeepPavlov/rubert-base-cased` (vocab 119547, 12 слоёв, 768) | | Шаги / batch / lr | 8000 · 32 · 3e-5, warmup 800, weight decay 0.1, grad clip 1.0, AMP | | Окно | 384 wordpiece | | Выбор чекпоинта | по `credential_any_f1` на валидации (максимизируется вклад NER в детекцию учётных данных: пол от регулярок постоянен) | | Данные | синтетические семейства учётных данных в русскоязычном контексте (kv-pair в сообщениях, конфигах и коде) + replay-доля 0.35 на общий русский NER, чтобы не потерять ПДн | ## Ограничения * **CLI и DSN — вне зоны ответственности.** Строки подключения (`postgres://user:pass@host`) и пароли в аргументах команд сознательно не входят в целевую поверхность релиза и на ней не измерялись. Модель на них ведёт себя неровно: `psql -U reporter -W 'Qw!7823ml' -h db.corp.ru` → спан `PASSWORD` захватывает открывающую кавычку, а хвост имени хоста уезжает в `LOGIN`. Детерминированный слой подстраховывает только известные флаги известных команд. Целевая поверхность — **kv-pair**: `ключ = значение` в сообщениях, конфигах и коде. * **Границы спанов не всегда аккуратны.** Модель может отрезать закрывающую кавычку (`'ПАО «Сбербанк'`) или разделить фразу на два спана. Для маскирования это безопасно (спан всё равно вычёркивается), для извлечения сущностей — учитывайте. * **Не детектор «всех секретов».** Формат, не похожий ни на одно из обученных семейств и не покрытый регуляркой, будет пропущен. Recall 0.967 — это про объединение на распределении сплита, а не гарантия на вашем корпусе. Измерьте на своих данных. * **Один seed.** Веса выпущены под пилот, из одного прогона; трёхсидовая сертификация релиза не проводилась. * **Происхождение данных.** Общая NER-часть (`PERSON`/`ORGANIZATION`/`LOCATION`) опирается на публичные русские NER-корпуса; учётные данные — синтетика. Настоящих секретов в обучающем корпусе нет. ## Файлы ``` config.json · model.safetensors веса (BertForTokenClassification, fp32, 709 МБ) tokenizer.json · vocab.txt · … токенизатор (fast, BertTokenizer, cased) predict.py инференс: окна · NFC · BIO-декод · объединение gitleaks.toml правила детерминированного слоя core/scrubber.py детерминированный слой: kv · cli · opaque core/_shim.py инертные значения, NFC, вспомогательное core/slot_ontology.yaml онтология ключей для kv-детектора ``` `core/` скопирован без изменений из `masking-service/core` бандла `r3-2026-07-22` — того же кода, что крутится в проде; `predict.py` вызывает `load_gitleaks_rules` и `credential_sites` из него, а не переписывает их. У `scrubber.py` есть ещё и CLI датасетного пайплайна (`python -m core.scrubber`) - к инференсу он отношения не имеет, его можно игнорировать.