NLP API в смарт-скриптах (v2.268)¶

Нативный неймспейс NLP доступен в Lua, JavaScript и C# смарт-скриптах без дополнительных настроек. Python-скрипты получают URL NLP API через контекстную переменную nlp_api_url.

Реализация: NlpScriptApi (Lua), JsNlpApi (JS), CSharpNlpApi (C#). Внутри — делегирование в Valhalla.Nlp (IDeclensionService, ITextConversionService, ISpellChecker, IKeyboardLayoutService, ILemmatizer, IInMemoryFullTextSearch).

До v2.268 для склонения требовался ручной вызов HTTP.post("/api/nlp/declension", ...).

Кодировка параметров¶

Падежи (`case`)¶

Код	Падеж
`"nom"`	Именительный
`"gen"`	Родительный
`"dat"`	Дательный
`"acc"`	Винительный
`"ins"`	Творительный
`"prep"`	Предложный

Тип склонения (`type`)¶

Код	Что склоняет
`"auto"`	Автоопределение (по умолчанию)
`"fio"`	ФИО
`"noun"`	Существительное / словосочетание
`"title"`	Должность / звание
`"date"`	Дата прописью
`"number"`	Число с единицей измерения

Методы¶

Склонение¶

Lua	JavaScript / C#	Описание
`NLP.Inflect(text, case)`	`NLP.inflect(text, case)`	Склонение с автоопределением типа
`NLP.Inflect(text, case, type)`	`NLP.inflect(text, case, type)`	Склонение с явным типом
`NLP.InflectFio(name, case)`	`NLP.inflectFio(name, case)`	Склонение ФИО
`NLP.InflectNoun(phrase, case)`	`NLP.inflectNoun(phrase, case)`	Склонение существительного / словосочетания
`NLP.InflectDate(date, case)`	`NLP.inflectDate(date, case)`	Дата прописью в нужном падеже
`NLP.InflectNumber(num, unit, case)`	`NLP.inflectNumber(num, unit, case)`	Число с единицей измерения в нужном падеже

Числа прописью¶

Lua	JavaScript / C#	Описание
`NLP.NumWords(n)`	`NLP.numWords(n)`	Число прописью
`NLP.NumWordsRub(n)`	`NLP.numWordsRub(n)`	Сумма в рублях прописью
`NLP.NumWordsCurrency(n, code)`	`NLP.numWordsCurrency(n, code)`	Сумма в указанной валюте (`"USD"`, `"EUR"` и др.)

Конвертация форматов¶

Lua	JavaScript / C#	Описание
`NLP.HtmlToText(html)`	`NLP.htmlToText(html)`	HTML → plain text
`NLP.HtmlToMarkdown(html)`	`NLP.htmlToMarkdown(html)`	HTML → Markdown
`NLP.MarkdownToHtml(md)`	`NLP.markdownToHtml(md)`	Markdown → HTML
`NLP.SanitizeHtml(html)`	`NLP.sanitizeHtml(html)`	Очистка HTML от опасных тегов

Спеллчек и транслитерация¶

Lua	JavaScript / C#	Описание
`NLP.Spell(text)`	`NLP.spell(text)`	Спеллчек, язык определяется автоматически
`NLP.Spell(text, lang)`	`NLP.spell(text, lang)`	Спеллчек с явным языком (`"ru"` / `"en"`)
`NLP.Transliterate(text)`	`NLP.transliterate(text)`	Транслитерация (кириллица ↔ латиница)

Результат Spell — массив объектов { word, suggestions[] }.

Лемматизация¶

Лемматизация — приведение слова к начальной (словарной) форме: «воронки» → «воронка», «задачи» → «задача». Используется для нормализации текста перед поиском, сравнением, индексацией.

Реализация: HunspellLemmatizer на словарях Hunspell (ru_RU.dic/.aff, en_US.dic/.aff). Индекс строится один раз при инициализации и кэшируется в памяти. Регистр первой буквы исходного слова сохраняется в результате. Неизвестные слова (нет в словаре) возвращаются без изменений.

Lua	JavaScript / C#	Описание
`NLP.lemmatize(word, lang)`	`NLP.lemmatize(word, lang)`	Начальная форма слова. Если форм несколько — возвращается первая. Параметр `lang` по умолчанию `"ru"`, поддерживается также `"en"`
—	`NLP.getAllLemmas(word, lang)`	Все возможные начальные формы для омонимичных словоформ (например, «стали» → [«стать», «сталь»]). Возвращает массив строк. Доступно в JavaScript и C#
`NLP.normalize_text(text, lang)`	`NLP.normalizeText(text, lang)`	Нормализация всего текста: каждое слово приводится к начальной форме, пунктуация и числа сохраняются

Доступные коды языка (lang):

Код	Язык
`"ru"`	Русский (по умолчанию)
`"en"`	Английский

Полнотекстовый поиск (in-memory)¶

Полнотекстовый поиск по набору строк-кандидатов с учётом морфологии языка. На каждый вызов строится in-memory Lucene-индекс (RAMDirectory), выполняется поиск с анализатором, возвращаются top-K совпадений с оценкой релевантности. Подходит для поиска по коротким спискам (названия задач, категории, компании) непосредственно в смарт-скрипте — без внешнего индекса и HTTP-запроса.

Lua	JavaScript / C#	Описание
`NLP.search_in_memory(query, candidates, topK, lang)`	`NLP.searchInMemory(query, candidates, topK, lang)`	Полнотекстовый поиск по массиву строк-кандидатов

Параметры: - query (string) — поисковый запрос - candidates (string[]) — массив строк-кандидатов - topK (int, по умолчанию 10) — максимальное количество результатов - lang (string, по умолчанию "ru") — язык анализатора: "ru" — RussianAnalyzer, "en" — EnglishAnalyzer, любое другое значение — StandardAnalyzer

Результат — массив совпадений, отсортированный по убыванию релевантности. Каждый элемент содержит: - index — позиция строки в исходном массиве candidates - text — текст строки-кандидата - score — оценка релевантности (чем выше — тем лучше)

В Lua и JavaScript поля результата в нижнем регистре (index, text, score). В C# результат — IList<InMemoryFullTextMatch>, поля записи в PascalCase: Index, Text, Score.

Примеры:

-- Lua — найти наиболее релевантную компанию по неполному названию
local companies = {"ООО Ромашка", "ЗАО Ромашка-Сервис", "ИП Иванов А.А."}
local results = NLP.search_in_memory("ромашка", companies, 3, "ru")

for i = 1, #results do
  local r = results[i]
  SMART.post_comment(TaskID, r.text .. " (score: " .. r.score .. ")", {})
end

// JavaScript — поиск по списку категорий
var categories = ["Воронка продаж B2B", "Архив сделок", "Настройка воронки в CRM"];
var results = NLP.searchInMemory("воронка продаж", categories, 5, "ru");

// results: [{index: 2, text: "Настройка воронки в CRM", score: 1.23}, ...]

// C# — выбор наиболее подходящего шаблона
var templates = new[] { "Договор поставки", "Договор подряда", "Акт выполненных работ" };
var matches = NLP.SearchInMemory("договор", templates, topK: 2, lang: "ru");

// matches — IList<InMemoryFullTextMatch>; поля Index, Text, Score (PascalCase)
var best = matches.Count > 0 ? matches[0].Text : null;

Ограничения: - RussianAnalyzer Lucene 4.8 — лёгкий стеммер: учитывает основные падежные и числовые окончания, но не обрабатывает беглые гласные («воронка» → найдёт «воронки», но не «воронок»). - Индекс строится в памяти на каждый вызов — для больших массивов (тысячи строк) используйте предварительную лемматизацию с последующим точным сравнением. - Для поиска по данным платформы (задачи, файлы, справочники) используйте AI Search, а не in-memory поиск.

Раскладка и язык¶

Lua	JavaScript / C#	Описание
`NLP.SwitchLayout(text)`	`NLP.switchLayout(text)`	Переключение раскладки клавиатуры
`NLP.DetectLanguage(text)`	`NLP.detectLanguage(text)`	Определение языка (`"ru"` / `"en"`)
`NLP.IsWrongLayout(text)`	`NLP.isWrongLayout(text)`	Эвристика: текст набран в неверной раскладке

Примеры¶

Lua — формирование текста обращения со склонением¶

local fio      = SMART.get_ext_param_value(TaskID, 42)
local position = SMART.get_ext_param_value(TaskID, 43)

local text = "Уважаемый " .. NLP.InflectFio(fio, "nom") .. "!\n"
          .. "Ваша заявка передана "
          .. NLP.Inflect(position, "dat", "title") .. " на согласование."

SMART.post_comment(TaskID, text, {recipients = {responsible_user}})

JavaScript — договор с именительным и родительным падежами¶

var director = SMART.getExtParamValue(TaskID, 8);
var company  = SMART.getExtParamValue(TaskID, 10);

RESULT = "Договор заключён от лица " + NLP.inflectFio(director, "gen")
       + ", в интересах " + NLP.inflectNoun(company, "gen") + ".";

Lua — спеллчек перед отправкой комментария¶

local text   = SMART.get_ext_param_value(TaskID, 50)
local errors = NLP.Spell(text, "ru")

if #errors > 0 then
    local msg = "Обнаружены ошибки: "
    for _, err in ipairs(errors) do
        msg = msg .. err.word .. " → "
            .. table.concat(err.suggestions, "/") .. "; "
    end
    SMART.post_comment(TaskID, msg, {recipients = {owner_user}})
end

JavaScript — нормализация текста перед поиском¶

const query = SMART.getExtParamValue(TaskID, 100);
const normalized = NLP.normalizeText(query, "ru");
// «найти все воронки продаж» → «найти весь воронка продажа»
// — устойчиво к словоформам при сравнении с эталоном

JavaScript — омонимичные формы¶

const lemmas = NLP.getAllLemmas("стали", "ru");
// ["стать", "сталь"] — глагол и существительное

Python — склонение через nlp_api_url¶

import requests

r = requests.post(
    nlp_api_url + "/declension",
    json={"text": ctx["name"], "case": "dative", "type": "fio"}
)
declined = r.json()["result"]

Связанные документы¶

docs/domains/smart-actions/js-scripting-jint.md
docs/domains/smart-actions/python-scripting.md
docs/domains/smart-actions/csharp-scripting-roslyn.md