Содержание
  1. Как KeyBERT выбирает фразы
  2. Полный русский исходник и человеческий эталон
  3. Неверный unigram и регистр vocabulary
  4. Исправленный bigram и lowercase vocabulary
  5. Полный воспроизводимый конфиг
  6. Отдельная проверка найденных кандидатов
  7. Ranking и top_n без выдуманных scores
  8. Границы custom vectorizer и KeyLLM
  9. Частые вопросы
Обзоры

Обзор KeyBERT: ключевые фразы, регистр и кандидаты

17 ноября 2026 · 10 минут чтения

Обзор KeyBERT: ключевые фразы, регистр и кандидаты — это разбор экстрактивного конвейера, где CountVectorizer готовит кандидатов, эмбеддинги документа и фраз сравниваются по косинусной близости, а список ограничивает top_n. Ниже — русский учебный документ, негативный и исправленный конфиг, полный код проверки этапа кандидатов и границы настройки.

Как KeyBERT выбирает фразы

В документации проекта на maartengr.github.io описан порядок работы. Сначала извлекаются эмбеддинги документа и получается представление уровня всего текста. Затем считаются эмбеддинги для N-грамм — слов и словосочетаний. На последнем шаге косинусная близость показывает, какие фразы ближе всего к документу. По умолчанию KeyBERT сравнивает документ и кандидатов именно по косинусной близости.

Кандидаты формирует CountVectorizer из scikit-learn. В API KeyBERT параметр candidates передаёт готовые ключевые фразы, а параметр keyphrase_ngram_range задаёт длину кандидатов при штатном vectorizer. Документация KeyBERT отдельно помечает: candidates, keyphrase_ngram_range и stop_words не используются, если вы передали собственный vectorizer. Это ключевая деталь для диагностики.

Схема получается такой:

Этап Что происходит Кто отвечает
Кандидаты Текст разбивается на N-граммы, отбираются допустимые CountVectorizer
Эмбеддинги документа Текст превращается в вектор уровня документа Выбранная модель эмбеддингов
Эмбеддинги фраз Каждая N-грамма превращается в вектор Та же модель
Сравнение Косинусная близость фразы и документа KeyBERT
Отбор Ограничение списка и разнообразие top_n, MMR, MaxSum

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

Полный русский исходник и человеческий эталон

Возьмём короткий учебный документ про перенос заявок в CRM. Все данные составлены вручную, запуск библиотеки не проводился.

ТЕКСТ
Команда переносит заявки в единую CRM. После настройки CRM менеджер проверяет дубли заявок. Автоматизация уведомляет менеджера о новой заявке

Человеческий эталон аспектов для этого текста: «дубли заявок», «автоматизация», «CRM». Это назначенная вручную разметка, которую мы задаём сами. Она помогает оценить, попали ли нужные смыслы в кандидаты, и служит ориентиром при подборе модели и разнообразия.

Отдельно про регистр. Человек при сравнении приводит слова к одному виду через casefold и считает «CRM» и «crm» одним смыслом. Для человека это одна сущность в разном написании. Для CountVectorizer это разные строки, если регистр не выровнен. Разметка эталона отражает человеческий взгляд, а поведение vectorizer — техническое, и расхождение между ними и создаёт ошибку.

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

Неверный unigram и регистр vocabulary

Соберём негативный конфиг этапа кандидатов. Здесь ngram_range задан как (1, 1), то есть только униграммы, а в vocabulary перечислены четыре строки, включая «дубли заявок» и «CRM».

PYTHON5 строк
CountVectorizer(
    ngram_range=(1, 1),
    stop_words=None,
    vocabulary=["дубли заявок", "автоматизация", "CRM", "менеджер"],
)

Документация scikit-learn говорит, что lowercase по умолчанию включён и приводит все символы к нижнему регистру перед токенизацией. Значит, текст превращается в нижний регистр. Строка «CRM» в явном vocabulary тогда не совпадает с «crm» из текста. А «дубли заявок» состоит из двух слов и при диапазоне (1, 1) униграммой не является. По документации scikit-learn диапазон (1, 1) означает только униграммы.

Что остаётся фактически найденным на этом входе: «автоматизация» и «менеджер». Две допустимые униграммы из четырёх заявленных строк. Это ручное ожидание ненулевых признаков. В коде KeyBERT кандидаты конкретного документа выбираются по ненулевым индексам матрицы перед ранжированием. Из этого не следует, что эмбеддинги всего фиксированного словаря вообще не вычислялись.

Строка vocabulary Причина пропажи Найдена?
дубли заявок биграмма при диапазоне (1, 1) нет
автоматизация униграмма, регистр совпал да
CRM в тексте после lowercase стало crm нет
менеджер униграмма, регистр совпал да

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

Исправленный bigram и lowercase vocabulary

Исправленный конфиг меняет две вещи: диапазон N-грамм расширяется до (1, 2), а строка «CRM» в vocabulary записана в нижнем регистре как «crm».

PYTHON5 строк
CountVectorizer(
    ngram_range=(1, 2),
    stop_words=None,
    vocabulary=["дубли заявок", "автоматизация", "crm", "менеджер"],
)

По документации scikit-learn диапазон (1, 2) означает униграммы и биграммы вместе. Теперь «дубли заявок» попадает в допустимые кандидаты как биграмма, а «crm» совпадает с текстом после приведения к нижнему регистру. Множество найденных допустимых фраз содержит все четыре кандидата.

Здесь важно не перепутать две разные вещи. Это ожидаемый oracle допустимости кандидатов. Он показывает, какие фразы vectorizer способен найти в тексте. Он не предсказывает порядок top-3, не даёт косинусных оценок и не является выводом модели. При фиксированном vocabulary имя признака может оставаться в get_feature_names_out даже с нулевым счётчиком. Функция found ниже выбирает только ненулевые признаки данного документа. Поэтому наличие имени колонки ещё не означает допустимого кандидата для его ранжирования.

Ещё одно следствие: выбранный top_n=3 ограничивает финальный список. Он не обещает, что в него войдут все четыре кандидата. Даже когда все четыре допустимы, отбор может оставить три. Это ожидаемое следствие выбранного ограничения длины.

Полный воспроизводимый конфиг

Ниже полный короткий код для самостоятельной проверки этапа кандидатов. Библиотеки и модель в рамках этого разбора не вызывались; код приведён как воспроизводимый учебный пример.

PYTHON27 строк
from sklearn.feature_extraction.text import CountVectorizer
from keybert import KeyBERT

doc = "Команда переносит заявки в единую CRM. После настройки CRM менеджер проверяет дубли заявок. Автоматизация уведомляет менеджера о новой заявке"

bad = CountVectorizer(
    ngram_range=(1, 1),
    stop_words=None,
    vocabulary=["дубли заявок", "автоматизация", "CRM", "менеджер"],
)
fixed = CountVectorizer(
    ngram_range=(1, 2),
    stop_words=None,
    vocabulary=["дубли заявок", "автоматизация", "crm", "менеджер"],
)

def found(vectorizer):
    matrix = vectorizer.fit_transform([doc])
    names = vectorizer.get_feature_names_out()
    return {str(names[i]) for i in matrix.nonzero()[1]}

assert found(bad) == {"автоматизация", "менеджер"}
assert found(fixed) == {"дубли заявок", "автоматизация", "crm", "менеджер"}

model = KeyBERT(model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
keywords = model.extract_keywords(doc, vectorizer=fixed, top_n=3)
print(keywords)

Разберём, что делает каждая часть. Функция found строит матрицу признаков по одному документу, берёт имена признаков и возвращает множество тех, что реально встретились в тексте — по ненулевым индексам. Два assert фиксируют ожидаемое поведение: негативный конфиг находит две фразы, исправленный — четыре. Дальше создаётся модель KeyBERT с мультиязычной моделью и вызывается извлечение с исправленным vectorizer и top_n=3.

Мультиязычная модель указана по её первичному каталогу Sentence Transformers. В каталоге sbert.net она описана как мультиязычная версия sentence-transformers/paraphrase-MiniLM-L12-v2, обученная на параллельных данных для более чем 50 языков, причём язык ввода указывать не нужно. Фактическая установка, загрузка и запуск в этом разборе не проводились.

Отдельная проверка найденных кандидатов

Проверку стоит разделить на два независимых шага. Первый — допустимость кандидатов: какие фразы vectorizer способен найти в тексте. Второй — отбор и ранжирование: что модель вернёт в итоговом списке. Смешивать их в одной проверке неудобно, потому что причины сбоя лежат в разных местах.

Порядок диагностики:

  1. Выпишите человеческий эталон аспектов заранее, до запуска.
  2. Прогоните vectorizer отдельно и посмотрите множество найденных фраз.
  3. Сравните его с эталоном: чего не хватает и почему.
  4. Проверьте регистр строк vocabulary против lowercase текста.
  5. Проверьте диапазон N-грамм против длины нужных фраз.
  6. Только после этого переходите к подбору модели и разнообразия.

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

Для разнообразия в API KeyBERT есть параметр diversity — степень разнообразия результатов в диапазоне от 0 до 1 при включённом use_mmr. Для MaxSum есть параметр, задающий число кандидатов к рассмотрению при включённом use_maxsum. Это отдельные рычаги отбора, и трогать их имеет смысл после того, как этап кандидатов проверен.

Ranking и top_n без выдуманных scores

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

top_n задаёт, сколько фраз вернуть. Параметр ограничивает длину списка; качество выбранных фраз проверяют отдельно. Когда допустимых кандидатов больше, чем top_n, часть останется за пределами результата. Когда меньше — список будет короче.

Параметр Что задаёт Чего не гарантирует
top_n длину итогового списка попадание конкретных фраз
diversity разнообразие при use_mmr смысловую точность
число кандидатов MaxSum охват при use_maxsum правильный порядок
keyphrase_ngram_range длину фраз работу с вашим vectorizer

При повторном использовании word_embeddings документация KeyBERT требует согласовать параметры формирования словаря между extract_embeddings и extract_keywords: candidates, keyphrase_ngram_range, stop_words, min_df и переданный vectorizer. Состав и порядок признаков должны соответствовать строкам эмбеддингов. Это требование к кандидатам, изменения одного top_n не создают новый словарь.

Границы custom vectorizer и KeyLLM

Когда вы передаёте собственный vectorizer, настройки candidates, keyphrase_ngram_range и stop_words в extract_keywords не переопределяют его поведение. В нашем примере всеми этими вещами управляют внутри CountVectorizer: диапазон N-грамм, список стоп-слов и фиксированный vocabulary заданы там. Это ожидаемое следствие приоритета переданного объекта.

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

KeyLLM — отдельный интерфейс работы с LLM в кодовой базе KeyBERT. Конкретный LLM-бэкенд выбирают отдельно. Поведение выбранного LLM-бэкенда здесь не проверялось. Наш пример ограничен экстрактивным маршрутом и допустимостью кандидатов. Условия MMR и MaxSum разъясняются отдельно; поддержка представления сама по себе не является гарантией качества для русского текста.

Каталог Sentence Transformers предупреждает: модели, хорошо показавшие себя в таблице лидеров, не обязательно хорошо работают на ваших задачах, поэтому важно экспериментировать с разными перспективными моделями. Для русского текста это значит — проверяйте на своём документе и своём эталоне.

Частые вопросы

Что такое KeyBERT и как он извлекает ключевые фразы?
KeyBERT — библиотека экстрактивного извлечения ключевых фраз. Сначала она получает эмбеддинг документа, затем эмбеддинги N-грамм-кандидатов, а после сравнивает их по косинусной близости. Кандидатов готовит CountVectorizer из scikit-learn.

Почему KeyBERT не находит нужную фразу в русском тексте?
Сначала проверьте этап допустимости кандидатов. Фраза может не совпасть по регистру со строками vocabulary или не подойти по длине N-граммы. Проверьте vectorizer отдельно, до сравнения эмбеддингов.

Как передать свой vectorizer в KeyBERT?
Создайте CountVectorizer с нужными ngram_range, stop_words и vocabulary и передайте его в extract_keywords. При этом candidates, keyphrase_ngram_range и stop_words в самом вызове поведение vectorizer не переопределяют.

Что делает top_n и почему фраз меньше, чем кандидатов?
top_n ограничивает длину итогового списка. Когда допустимых кандидатов больше, чем top_n, часть остаётся за пределами результата. Это ожидаемое следствие ограничения длины списка.

Чем KeyLLM отличается от обычного KeyBERT?
KeyLLM — отдельный интерфейс для извлечения фраз с помощью LLM; обязательный внешний сервис этим названием не задаётся. Его ответы относятся к другому подходу и не описывают поведение экстрактивного конвейера с CountVectorizer и косинусной близостью.

Читайте также

3 материала