llm-translate/doc/ru/options.md

# Настройки сервиса и модулей (плагинов)

После старта сервиса в папке `options` будут автоматически созданы файлы конфигураций для сервиса и
для всех имеющихся плагинов. Все параметры будут выставлены в предустановленные значения. 
При создании название параметров записываются по алфавиту.

Чтобы сбросить параметры какого-либо плагина или все настройки сразу, необходимо удалить соответсвующий файл (файлы)
из папки `options` и перезапустить сервис, удаленные файлы будут созданы со значениями по умолчанию.

Формат файлов - JSON. 

**Все изменения применяются только после перезапуска сервиса.**

В папке `options` могут находиться следующие настройки:
* `core.json` - базовые настройки сервиса. Эти настройки будут рассмотрены ниже.
* `plugin_file_xxx.json` - настройки перевода опредленного типа файлов или группы файлов.
Например, plugin_file_txt.json - настройки перевода текстовых файлов с расширением txt.
Более подробно про поддерживаемые плагины для перевода файлов 
и их настройки можно посмотреть [здесь](processing_files.md).
* `plugin_xxx` - все оставшиеся файлы, которые не начинаются с `plugin_file_` - настройки инструментов перевода.
Более подробно про поддерживаемые инструменты для перевода и их настройки можно посмотреть [здесь](translate_text.md).

## Настройки core

Настройки находятся в файле core.json

Ниже приведены настройки с их описанием, рекомендуемым значениям и сценариями использования.

* Группа **cache_params** - параметры кэширования. Для кэширования используется база данных SQLite.
* * disable_for_plugins - список плагинов перевода, для которых не нужно использовать кэширование. 
Значение по умолчанию - плагин "no_translate", так как это специализированный плагин для тестирования и разработки функциональности сервиса.
* * enabled - включен или выключен кэш. Позволяет ускорить обработку уже переведенного ранее текста.
* * expire_days - количество дней, в течение которых хранятся записи в кэше.
* * file - место расположения файла кэша.


* **default_translate_plugin** - плагин для перевода по умолчанию, будет загружен при старте сервиса и будет использован,
если в запросе перевода явно не указан другой инструмент плагин.


* Группа **file_processing_params** - обработка файлов, [документация](processing_files.md).
* * directory_in - папка, где будет производиться поиск файлов для перевода.
* * directory_out - папка, в которую будут сохраняться результаты перевода.
* * overwrite_processed_files - если true, позволяет перезаписывать файлы в папке directory_out, если они уже существуют.
Если false - файл не будет обработан и будет возвращен соответсвующий статус в результате.
* * preserve_original_text - если true, то при обработке файла сначала будет идти абзац исходного текста, затем - переведенного.
Если false - то исходный текст будет удален и останется только перевод.
* * Группа **context** - настройки дополнительного контекста для улучшения перевода. 
Для этого берется несколько предыдущих параграфов из текста и добавляется, как контекст для перевода.
* * * enabled - включено или выключено добавление контекста.
* * * prompt - текст, описывающий контекст и содержимое нескольких параграфов текста, который следует до переводимого.
Текст должен содержать сам запрос и слово `%%context_text%%`, которое будет заменено на предыдущий текст в файле.
В общем виде контекст должен быть такой: `Используй этот контекст для улучшений перевода. Контекст:\n%%context_text%%\n`
* * * expected_length - длина котекста (без описания) недолжна быть более этой длины (параметр `include_at_least_one_paragraph` может изменить это поведение)
* * * include_at_least_one_paragraph - включить как минимум один параграф из текста ранее, даже если его длина боле, чем `expected_length`.
* * * paragraph_join_str - символ для соединения параграфов контекста, если их более одного.

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


Если карта сильно греется, например, при переводе файлов, некоторая задержка позволит снизить нагрузку.
* Группа **text_processing_params** - настройки для обработки текста запросов и ответов.
Группу этих параметров можно добавить в настройки любого плагина перевода и в этом случае настройки группы будут применены вместо настроек из core-плагина. Подробнее - ниже в этом документе.
* * allowed_chars_ignoring_replace - если включен параметр `replace_not_text_chars`, все параметры, кроме букв, цифр 
и содержимого этого поля будут заменены на строку `replace_not_text_target_char`.
* * apply_for_request - применять обработку текста согласно указанным параметрам к тексту для перевода, запросу.
* * apply_for_response - применять обработку текста согласно указанным параметрам к переведенному тексту, ответу.
* * remove_identical_characters - удаляет в слове подряд идущие символы, если их число более, чем указано в параметре `remove_identical_characters_max_repeats`.
Например, слово "Приииивввееееет" при значении `remove_identical_characters_max_repeats` = 3, будет заменено на "Прииивввееет".
Как правило, более 3 букв в словах не встречается, и такие повторения букв используется для изобразительных оттенков речи, например, что слово было протяжно произнесено.
Такая замена позволяет улучшить результат, так как модель видит более близкое слово, которое может обработать.
* * remove_identical_characters_max_repeats - количество букв, идущих подряд, которое будет оставлено при
включенном параметре `remove_identical_characters`.
* * remove_multiple_spaces - удаление нескольких пробелов подряд, например "Привет, мир  1 и мир   2!" - оставит "Привет, мир 1 и мир 2!".
* * remove_repeated_words - удаление в предложении несколько слов, которые идут подряд, если их число более, чем указано в параметре `remove_repeated_words_max_repeats`.
Например, фраза "Привет, привет, привет, привет мир." при значении `remove_repeated_words_max_repeats` = 3 будет заменено на "Привет Привет Привет, мир.".
В этом преобразовании есть проблемы с регистром повторяющихся слов, знаками препинания, поэтому использование не рекомендуется.
* * replace_non_standard_new_lines_chars - заменяет комбинации символов новой строки, таких как `\r\n`, `\n\r`, `\r` на `\n`.
* * replace_not_text_chars - заменяет все символы, которые не являются буквами или цифрами, или не входят в строку-параметр 
`allowed_chars_ignoring_replace` на значение параметра `replace_not_text_target_char`.
Некоторые модели перевода плохо работают со специальными символами, поэтому для таких случаев этот параметр может улучшить перевод.
* * replace_not_text_target_char - строка, на которую будет заменен найденный символ при включенном параметре `replace_not_text_chars`.
* * Список значений **replace_text_from_to** - здесь можно указать значения `"текст-для-замены": "заменяемый текст"`.
Например, при таком значении параметра:
`replace_text_from_to: {
    "Alice": "Mallory",
    "123": "456"
}` текст "Alice sends a message 123 to Bob." будет заменено на "Mallory sends a message 456 to Bob."


* Группа **text_split_params** - параметры разбиения большого текста на части, чтобы модель могла корректно их обработать.
Группу этих параметров можно добавить в настройки любого плагина перевода и в этом случае настройки группы будут применены вместо настроек из core-плагина. Подробнее - ниже в этом документе.
* * sentence_splitter - если включен параметр `split_by_sentences_only`, определяет, какой инструмент будет использоваться для того, чтобы разбить текст на предложения.
если указан `blingfire` - будет использоваться этот инструмент, во всех остальных случаях - `pysbd`.
Нужны специальные инструменты, потому что просто разбить текст по знакам препинания нельзя, например одно это предложение будет разбито на несколько частей:
"_Mr. John Johnson Jr. was born in the U.S.A but earned his Ph.D. in Israel before joining Nike Inc. as an engineer._".
* * split_by_paragraphs_and_length - разбивать частями на несколько параграфов, но так, чтобы длина одной части была не более
значения параметра, указанного в `split_expected_length`, за исключением первого параграфа. Ниже приведен пример расчет разбиения.
* * split_by_paragraphs_only - разбивать текст только по параграфам. Число частей будет равно числу параграфов.
* * split_by_sentences_and_length - разбивать частями на несколько предложений, но так, чтобы длина одной части была не более
значения параметра, указанного в `split_expected_length`, за исключением первого предложения. Ниже приведен пример расчет разбиения.
* * split_by_sentences_only - разбивать текст только по предложениям. Число частей будет равно числу предложений.
* * split_expected_length - при включенном параметре `split_by_paragraphs_and_length` или `split_by_sentences_and_length` размер части
* будет не более этого значения, за исключением первого параграфа или предложения. Ниже приведен пример расчет разбиения.

* Группа **translation_params** - параметры перевода.
Группу этих параметров можно добавить в настройки любого плагина перевода и в этом случае настройки группы будут применены вместо настроек из core-плагина. Подробнее - ниже в этом документе.
* * default_from_lang - двухбуквенный код языка, будет использован, как язык оригинала, если он не был явно указан.
* * default_to_lang - двухбуквенный код языка, будет использован, как язык, на который необходимо перевести, если он не был явно указан.
* * sleep_after_translate - время в секундах (может быть дробным, например, 0.1), которое севрис будет ожидать после завершения перевода.

* Группа **rest_log_params** - параметры логирования запросов и ответов перевода.
* * translate_req_text - логирование исходного текста
* * translate_resp_text - логирование текста перевода
* * translate_validation_errors - логирование ошибок в текстах запросов

* **v** - служебное значение, версия плагина. При повышении версии плагин дополнит файл конфигурации новыми параметрами.

### Как текст разбивается на части при использовании параметра split_expected_length

Пример: включен параметр `split_by_paragraphs_and_length` и `split_expected_length` = 500, есть текст
**параграфов** следующей длины: 100, 700, 250, 50, 50, 400, 150, 200.

Текст будет разбит на части и включать следующие параграфы:
1. 100 (100 + следующий параграф 700 больше, чем ограничение 500)
2. 700 (700 больше, чем ограничение в 500, но хотя бы один параграф в части должен быть обязательно)
3. 250, 50, 50 (200 + 50 + 50 = 300, меньше, чем ограничение в 500, но следующий параграф - 400, уже больше ограничения)
4. 400 (меньше чем ограничение в 500, но следующий параграф - 150, 400 + 150 превысит ограничение)
5. 150, 200 - (меньше чем ограничение в 500)

Аналогичное разбиение будет выполнено и при включенном параметре `split_by_sentences_and_length` и `split_expected_length` = 500, и
**предложениях** следующей длины: 100, 700, 250, 50, 50, 400, 150, 200.

Как видно, при малом значении лимита, размер полученных частей может быть как сильно меньше, так и сильно больше лимита.
Но при установке лимита в 1500 - 2000 или более, это будет проявляться в меньшей степени.

### Переопределение групп параметров в настройках плагинов переводов.

Некоторые группы параметров - такие, как **text_processing_params**, **text_split_params**, **translation_params** - 
можно добавить в файлы настроек конкретного плагина и тогда эти настройки заменят настройки в **core**-плагине.

Необходимо переопределить полностью всю группу, если будет указан только один параметр - то и прочитан будет только он.

Это нужно для более удобной работы с плагинами, например языки для перевода по умолчанию чаще всего англо-русский,
но для плагина madlad всегда используются языки японско-русский.