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).

До 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"`	Английский

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

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