# Speller

**Speller** — микросервис проверки орфографии. Используется в интерфейсах **Webim** для подсветки ошибок и выдачи вариантов исправления. Поддерживаются русский и английский языки. Возможна работа с внешним провайдером орфографии по настройке аккаунта. Сервис не хранит пользовательские данные и не изменяет тексты автоматически.

## Функции

Сервис обладает следующими функциями:

  * проверка слов и фраз на орфографические ошибки;

  * предложения корректных вариантов замены;

  * учёт аккаунтных словарей: разрешённых (`spelling_dict`) и запрещённых (`forbidden_spelling_dict`) слов;

  * использование внешнего провайдера орфографии по настройкам аккаунта совместно со встроенными словарями **Webim**; при этом слова, присутствующие в `spelling_dict`, считаются корректными и вообще не отправляются во внешний спеллер;

  * публикация метрик для мониторинга.

## Настройки аккаунта

Работа **Speller** зависит от ряда параметров [*account config*](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html).

Основные параметры:

| Параметр                   | Назначение                                                                                                                                                                                                                         |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `disable_spell_check`      | Полностью отключает проверку орфографии для аккаунта. При `true` обращения к сервису не выполняются из интерфейсов.                                                                                                                |
| `spell_check_force`        | Принудительно включает проверку орфографии для аккаунта. При `true` проверка выполняется для всех операторов, оператор не может отключить её в интерфейсе.                                                                         |
| `server_dicts_spell_check` | Включает использование и управление аккаунтными словарями (`spelling_dict`, `forbidden_spelling_dict`, `candidate_spelling_dict`) при проверке текста. При `false` раздел управления словарями в интерфейсе аккаунта недоступен.   |
| `spelling_dict`            | JSON-словарь корректных слов. Слова из этого словаря считаются написанными правильно и не подлежат исправлению; сервис не отправляет их во внешний спеллер.                                                                        |
| `forbidden_spelling_dict`  | JSON-словарь запрещённых слов. Слова из этого словаря всегда считаются некорректными и не могут быть добавлены в список корректных слов. При этом они отправляются во внешний спеллер, и по ним предлагаются варианты исправления. |
| `candidate_spelling_dict`  | JSON-словарь слов-кандидатов, ожидающих подтверждения администратором в интерфейсе управления словарём.                                                                                                                            |

Подробное описание этих параметров и работы словаря приведено в статье
[«Настройка проверки орфографии и словаря»](https://webim.ru/kb/for-admins/spell-settings.html).

## Сетевые требования

Сервис доступен по HTTP на порту **8000/tcp**. Все клиентские запросы обрабатываются на этом же порту. Номер порта задаётся переменной окружения `API_WEB_PORT` (значение по умолчанию — `8000`).

Метрики **Prometheus** доступны по пути `/metrics` на HTTP-порте сервиса.

Для **hosted-клиентов** необходимо открыть следующие порты для узла со **Speller**.
Указаны значения по умолчанию; актуальные порты следует уточнять по `.env` файла сервиса.

| Направление | Назначение                                 | Порт/протокол                              | Примечание                                                                                   |
|-------------|--------------------------------------------|--------------------------------------------|----------------------------------------------------------------------------------------------|
| Входящие    | HTTP-API Speller                           | `API_WEB_PORT` (по умолчанию **8000/tcp**) | Для балансировщика/прокси и доступа к `/metrics`.                                            |
| Исходящие   | Бэкенд Webim                               | **443/tcp**                                | Загрузка настроек аккаунта, проверка сессии операторов и другие запросы к основному бэкенду. |
| Исходящие   | Кэш (Redis)                                | порт, указанный в `REDIS_CACHE_LOCATION`   | Доступ к Redis, используемому сервисом Speller.                                              |
| Исходящие   | Внешний провайдер орфографии (опционально) | **443/tcp**                                | Используется при включении соответствующей опции в редакторе настроек аккаунта.              |

## Переменные окружения

Работа микросервиса **Speller** настраивается через файл `.env`.
Ниже перечислены основные параметры, влияющие на сеть и взаимодействие с бэкендом.

| Переменная             | Назначение                                                                                                                                                                                                  |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `REDIS_CACHE_LOCATION` | Строка подключения к Redis (host, порт, номер базы), используемому для кэша сервиса. Например: `redis://redis:6379/1`.                                                                                      |
| `API_WEB_PORT`         | Порт HTTP-API Speller, в том числе endpoint `/metrics`.                                                                                                                                                     |
| `SENTRY_DSN`           | DSN для отправки логов и ошибок в Sentry.                                                                                                                                                                   |
| `SENTRY_ENV`           | Имя окружения (environment) для Sentry.                                                                                                                                                                     |
| `ACCOUNT_NAME`         | Имя аккаунта Webim, от имени которого выполняются запросы к бэкенду.                                                                                                                                        |
| `ROOT_URL_FORMAT`      | Шаблон базового URL для обращения к бэкенду Webim. Например: `https://{account_name}.webim.ru`; вместо `{account_name}` сервис подставит имя аккаунта.                                                      |
| `ASPELL_DIR`           | Путь к системным словарям `aspell` на сервере.                                                                                                                                                              |
| `REQUEST_TIMEOUT`      | Тайм-аут в секундах для HTTP-запросов Speller к бэкенду Webim и внешним провайдерам (проверка сессии оператора, загрузка настроек аккаунта, запросы к внешнему спеллеру). По умолчанию имеет значение `10`. |

## Масштабирование и отказоустойчивость

Сервис имеет **stateless**-архитектуру, горизонтально масштабируется за балансировщиком L7. При масштабировании требуется **общий кэш (Redis)** для всех экземпляров.

Рекомендуемая схема масштабирования:

  1. Подготовить общий **Redis**.

  1. Запустить несколько экземпляров **Speller**.

  1. Распределять трафик через **балансировщик/ingress**.

  1. Подключить сбор метрик с `/metrics` и алертинг.

## Логирование и мониторинг

Логи приложения пишутся в стандартный вывод процесса и включают: запуск/останов, параметры окружения запуска, обработанные запросы, ошибки сети и кэша, таймауты.
Технические метрики доступны на `/metrics` и могут быть собраны **Prometheus**.

---

**Speller** обеспечивает проверку орфографии и подсказки исправлений в **Webim**. Для корректной работы требуется доступ по HTTP на порту **8000**, подключение к кэшу и (при необходимости) к внешнему провайдеру орфографии. Сервис масштабируется горизонтально и публикует метрики и логи для оперативного контроля.

---

Источник: https://webim.ru/kb/devops/services/speller.html