Разделы документации
Функциональные характеристики
Назначение Charo, решаемые задачи, входные и выходные данные, потребляемые ресурсы, полный перечень функций, состав программы и ограничения.
Настоящий раздел описывает функциональные характеристики программы «Charo»: назначение, решаемые задачи, входные и выходные данные, потребляемые ресурсы и перечень функций. Сведения, необходимые для установки и эксплуатации, приведены отдельно — см. «Быстрый старт» и раздел администрирования.
Назначение
Charo предназначена для корпоративного поиска по документам организации и для получения ответов на вопросы в диалоговой форме. Программа подключает корпоративные источники документов, индексирует их содержимое и отвечает на вопрос пользователя связным текстом со ссылками на конкретные документы-источники, по которым ответ построен. Charo разворачивается и работает целиком в инфраструктуре заказчика: документы, поисковый индекс, история переписки и учётные данные источников остаются на серверах организации.
Решаемые задачи
- Подключение корпоративных источников документов и поддержание поискового индекса в актуальном состоянии.
- Поиск по знаниям организации — по смыслу запроса и по ключевым словам одновременно.
- Ответы на вопросы, заданные обычным языком, с обязательной ссылкой на документы, из которых взяты сведения.
- Настройка ассистентов под задачи подразделения: своя область знаний, свои инструкции и свой набор действий.
- Работа с личными файлами и рабочими проектами пользователя.
- Расширение возможностей ассистента внешними действиями по описанию OpenAPI и инструментами внешних MCP-серверов.
- Выдача поиска по знаниям организации внешним программам-клиентам по протоколу MCP.
- Администрирование пользователей, групп и прав доступа; учёт использования и журналирование запросов.
Входные данные
| Вид данных | Источник поступления |
|---|---|
| Документы организации | подключённые источники — опрашиваются по расписанию |
| Файлы пользователя | загрузка в чат или в проект через веб-интерфейс |
| Документы от внешних систем | программный интерфейс приёма документов |
| Запросы и сообщения пользователя | веб-интерфейс, программный интерфейс, MCP-клиент |
| Параметры настройки | задаются администратором в панели администратора |
| Описания внешних действий | схемы OpenAPI 3.x и адреса внешних MCP-серверов |
| Лицензионный ключ | загружается администратором |
К параметрам настройки относятся: подключения к языковым моделям и моделям векторного представления текста, настройки индексации, учётные данные источников, наборы документов, пользователи, группы и права.
Поддерживаемые форматы загружаемых файлов: PDF, DOC, DOCX, PPTX, XLSX, XLSM, EPUB, HTML, EML, изображения JPEG, PNG, TIFF, BMP, GIF и WebP, а также текстовые — TXT, MD, MDX, CONF, LOG, JSON, CSV, TSV, XML, YML, YAML, SQL. В сообщения чата принимаются изображения PNG, JPEG и WebP. Размер одного файла по умолчанию ограничен 100 МБ (предельное значение настройки — 250 МБ), размер одной загрузки — 512 МБ.
Выходные данные
| Вид данных | Форма представления |
|---|---|
| Ответ ассистента | текст в веб-интерфейсе с подставленными ссылками на источники и списком документов, использованных в ответе |
| Результат поиска | ранжированный список документов с фрагментами и фильтрами |
| Поисковый индекс | фрагменты документов и их векторные представления в векторной базе данных |
| Отчёт об использовании | архив ZIP с таблицами CSV (сообщения и пользователи) |
| Выгрузка истории запросов | выгрузка в формате CSV |
| Список пользователей | выгрузка в формате CSV |
| Журнал выполнения хуков | записи об ошибках в панели администратора |
| Ответы программного интерфейса | HTTP-ответы в формате JSON, в том числе ответы MCP-инструментов внешним клиентам |
| Метрики и трассировки | текстовый формат Prometheus и протокол OTLP |
Потребляемые ресурсы
Минимальная конфигурация — установка, в которой языковая модель и модель векторного представления текста внешние.
| Ресурс | Минимум |
|---|---|
| Процессор | 4 ядра |
| Оперативная память | 8 ГБ |
| Свободное место на диске | 40 ГБ |
Значения относятся к ресурсам, выделенным среде контейнеризации. Объём диска растёт вместе с корпусом документов. Графический ускоритель не требуется.
Если модели поднимаются на том же сервере, к минимуму добавляется: для модели векторного представления текста — 2 ядра и 2 ГБ памяти, для языковой модели — не менее 8 ядер и 16 ГБ памяти, а точная величина определяется выбранной моделью.
Программное обеспечение: Docker Engine с плагином Compose версии 2. Программа не зависит от дистрибутива операционной системы, менеджера пакетов и системы инициализации — от узла требуется только рабочая среда контейнеризации. Образы выпускаются под архитектуру x86-64.
Внешние службы: доступ к языковой модели — либо к внешнему провайдеру по сети, либо к модели, запущенной на том же сервере. Система управления базами данных, хранилище очередей, векторная база данных и сервер моделей входят в поставку и отдельной установки не требуют.
Перечень функций
Поиск и ответы на вопросы
| Функция | Описание |
|---|---|
| Гибридный поиск | одновременный поиск по смыслу (векторный) и по ключевым словам (BM25); результаты объединяются ранговым слиянием внутри векторной базы данных |
| Поиск с учётом русской морфологии | полнотекстовая часть поиска приводит слова к основе и отбрасывает стоп-слова русского и английского языков |
| Поисковый конвейер ответа | переформулировка запроса языковой моделью, гибридный поиск, отбор релевантных фрагментов и расширение контекста вокруг них |
| Диалоговый режим | потоковый ответ ассистента с учётом предыдущих сообщений переписки |
| Цитирование источников | в текст ответа подставляются ссылки на документы, из которых взяты сведения; рядом выводится список источников. Отключение цитирования не предусмотрено |
| Режим «Поиск» | выдача документов по запросу с последующим уточнением фильтров (требует лицензии и хотя бы одного подключённого источника) |
| Фильтры выдачи | по типу источника, набору документов, дате обновления и меткам |
| Поиск по документам организации | встроенный инструмент ассистента; доступен, когда настроен провайдер языковой модели |
| Веб-поиск | встроенный инструмент ассистента; поисковая система SearXNG в закрытом контуре или Brave по ключу доступа |
| Чтение страницы по ссылке | встроенный инструмент ассистента; встроенный обходчик страниц либо Firecrawl |
| История переписки | сохранение чатов, поиск по ним, ограничение срока хранения (срок задаётся по лицензии) |
Ассистенты
| Функция | Описание |
|---|---|
| Каталог ассистентов | список доступных ассистентов, создание и редактирование собственных |
| Инструкции ассистента | собственные инструкции, напоминание в конце запроса, замена базового системного текста организации |
| Область знаний | наборы документов, подключённые источники, собственные файлы ассистента, узлы иерархии источника |
| Действия и инструменты | выбор встроенных инструментов, внешних действий OpenAPI и инструментов MCP |
| Параметры ответа | модель по умолчанию, дата отсечки знаний, примеры запросов, метки, имя, описание и изображение |
| Публикация | личный ассистент, доступ выбранным пользователям и группам (доступ группам — по лицензии), публикация на всю организацию |
| Порядок отображения | управление списком, приоритетами показа и признаком «рекомендованный» |
| Статистика ассистента | сведения об обращениях к конкретному ассистенту (по лицензии) |
Проекты и файлы пользователя
| Функция | Описание |
|---|---|
| Проект | объединяет загруженные файлы, привязанные чаты и собственные инструкции проекта |
| Перенос чатов | перемещение переписки в проект и обратно |
| Учёт объёма контекста | подсчёт токенов файлов проекта и текущей сессии |
| Поиск по файлам проекта | если файлы не помещаются в контекст модели, по ним выполняется поиск по индексу |
| Извлечение текста | разбор загруженных документов перечисленных выше форматов |
| Ограничения загрузки | размер файла и размер одной загрузки задаются настройками |
Подключение источников и индексация
| Функция | Описание |
|---|---|
| Подключение источников | восемь типов источников документов, учётные данные хранятся в зашифрованном виде |
| Периодическая индексация | опрос источника по расписанию, дата начала индексации, частота обновления |
| Распознавание текста | текст со сканированных страниц, изображений и картинок внутри документов распознаётся на своей инфраструктуре и индексируется наравне с извлечённым; поддерживаются кириллица и латиница |
| Очистка индекса | удаление из индекса документов, исчезнувших в источнике |
| Наборы документов | группировка подключений в именованные наборы для ограничения области поиска |
| Наследование прав из источника | перенос прав доступа документа из исходной системы (Confluence, BookStack, Google Drive, Jira) |
| Приём документов извне | программный интерфейс приёма документов, который проходит тот же конвейер индексации, что и коннекторы |
| Состояние индексации | статусы подключений, число проиндексированных документов, история попыток и ошибки |
| Обзор документов и отзывы | просмотр проиндексированных документов и оценок ответов (доступно по прямым адресам) |
| Устойчивость к сбойным документам | документ, который не удалось обработать, помечается ошибкой и пропускается, остальные документы пакета индексируются |
Языковые модели и векторные представления
| Функция | Описание |
|---|---|
| Подключение языковых моделей | девять готовых провайдеров: OpenAI, Anthropic, OpenRouter, Azure OpenAI, Ollama, LM Studio, LiteLLM Proxy, Yandex AI Studio и произвольный OpenAI-совместимый интерфейс |
| Свой провайдер | подключение по адресу и ключу для любого сервиса, совместимого с интерфейсом OpenAI |
| Проверка подключения | пробный запрос к провайдеру из панели администратора |
| Выбор моделей | список доступных моделей, модель по умолчанию, ограничение доступа к провайдеру по группам (по лицензии) |
| Локальные модели векторного представления | multilingual-e5-small (384), sergeyzh/BERTA (768), BAAI/bge-m3 (1024) на сервере организации, а также своя модель с ручными параметрами |
| Облачные модели векторного представления | Yandex AI Studio и OpenAI-совместимый интерфейс |
| Смена модели индексации | новый индекс строится в отдельной коллекции, переключение выполняется после того, как переиндексация догнала; предусмотрены режимы «мгновенно», «после переиндексации всех» и «только активных» |
Взаимодействие с внешними системами
| Функция | Описание |
|---|---|
| Charo как MCP-сервер | внешний клиент получает три инструмента (поиск по проиндексированным документам, веб-поиск, чтение страниц по ссылкам) и два справочника (наборы документов, подключённые источники); запрос выполняется в правах владельца токена |
| Charo как MCP-клиент | подключение внешних MCP-серверов и передача их инструментов ассистенту; авторизация — без неё, по токену или по OAuth 2.1 |
| Действия OpenAPI | подключение внешнего интерфейса схемой OpenAPI 3.x; авторизация — без неё, по заголовкам, через OAuth или токеном самого пользователя |
| Хуки расширения | три точки подключения собственной обработки: обработка запроса пользователя, приём документа до индексации, отправка документа после индексации (по лицензии) |
| Программный интерфейс | HTTP-интерфейс продукта для интеграций |
| Ключи для интеграций | ключи сервисных аккаунтов (по лицензии) и персональные токены доступа пользователей; хранятся в виде хеша и показываются один раз |
| Защита от обращений во внутреннюю сеть | обходчик страниц, хуки и MCP-клиент не обращаются к частным и зарезервированным адресам, исключения задаются явным списком |
Учётные записи и разграничение доступа
| Функция | Описание |
|---|---|
| Способы входа | по адресу почты и паролю либо через корпоративный вход по OpenID Connect (по лицензии) |
| Хранение паролей | пароли хранятся в виде хешей argon2id; требования к паролю настраиваются |
| Сессии | сессионный токен с настраиваемым сроком жизни, признаки HttpOnly и SameSite у сессионной куки |
| Роли | Базовый пользователь, Куратор (назначается внутри группы), Глобальный куратор, Администратор, а также служебные роли ограниченного и внешнего пользователя. Куратор и Глобальный куратор назначаются по лицензии |
| Права | набор из 18 именованных прав с картой следования; администратор получает полный набор |
| Группы пользователей | объединение пользователей в группы и назначение кураторов (по лицензии) |
| Разграничение выдачи | поиск возвращает только документы, доступные конкретному пользователю: публичные, доступные его группам и унаследованные из исходной системы |
| Видимость подключения | публичное, приватное по группам либо с наследованием прав из источника (последние два — по лицензии) |
| Пользователи и заявки | приглашение сотрудников, обработка заявок на регистрацию, назначение ролей |
| Синхронизация каталога | провижининг пользователей и групп по SCIM 2.0 (по лицензии) |
Администрирование и учёт
| Функция | Описание |
|---|---|
| Панель администратора | разделы «Агенты и действия», «Документы и знания», «Интеграции», «Права доступа», «Организация», «Использование» и блок базовой настройки: языковые модели, веб-поиск, настройки чата |
| Настройки чата организации | базовый системный текст для всех чатов и ассистентов, набор доступных инструментов, анонимный доступ, срок хранения переписки (по лицензии), ограничения на файлы, режим журналирования запросов (обычный, обезличенный, выключен) |
| Настройки индексации | выбор модели векторного представления и параметры обработки файлов |
| Настройки веб-поиска | выбор и проверка поисковой системы и обходчика страниц |
| Лицензия | загрузка ключа, сведения о сроке действия и числе мест, предупреждения об истечении |
| Лимиты расходов | ограничение потребления токенов языковых моделей (по лицензии) |
| Внешний вид | название, логотип и тексты интерфейса организации (по лицензии) |
| Статистика использования | сводные показатели обращений и активности (по лицензии) |
| История запросов | просмотр и выгрузка заданных вопросов и использованных документов (по лицензии) |
| Пользовательская аналитика | размещение собственного скрипта веб-аналитики (по лицензии) |
| Первичная настройка | мастер начальной настройки: название организации и подключение языковой модели |
| Уведомления | сообщения о необходимости переиндексации и о сроке действия лицензии |
| Сведения о версии | версии веб-интерфейса и серверной части |
Персональные настройки пользователя
| Функция | Описание |
|---|---|
| Профиль | имя, адрес почты, должность, личные предпочтения в свободной форме |
| Оформление | цветовая тема и фон окна переписки |
| Параметры чата | модель по умолчанию, режим по умолчанию, автопрокрутка, плавный вывод, сворачивание длинных вставок, удаление всех чатов |
| Память | личные заметки, которые ассистент учитывает в ответах и дополняет |
| Шаблоны запросов | сохранённые формулировки для повторного использования |
| Токены доступа | личные токены к программному интерфейсу со сроком действия 7, 30, 365 дней или бессрочно |
| Учётная запись | смена пароля |
| Личные учётные данные источников | подключение собственных учётных данных к коннекторам |
Эксплуатационные функции
| Функция | Описание |
|---|---|
| Фоновая обработка | индексация, синхронизация прав, очистка, обслуживание моделей и выгрузки выполняются фоновым процессом по 20 именованным очередям с сохранением состояния на диск |
| Шифрование секретов | учётные данные источников, ключи провайдеров моделей, токены OAuth и секреты хуков хранятся в базе данных в зашифрованном виде |
| Метрики | каждый компонент отдаёт метрики в формате Prometheus |
| Трассировка | трассы передаются в коллектор по протоколу OTLP, если он указан в настройках |
| Локализация | интерфейс полностью на русском языке |
Поддерживаемые источники данных
Программа поддерживает восемь типов источников: Confluence, BookStack, Google Drive, S3-совместимые хранилища, Jira, почтовые ящики по протоколу IMAP, веб-сайты и загрузку файлов. Отдельно доступен приём документов через программный интерфейс.
Требования к учётным данным и параметры настройки каждого источника — в разделе «Коннекторы».
Состав программы
Charo — единая программа. При развёртывании её компоненты запускаются отдельными контейнерами и взаимодействуют по внутренней сети; наружу открыт только обратный прокси-сервер.
| Компонент | Назначение |
|---|---|
| Обратный прокси-сервер | единая точка входа, разведение запросов к веб-интерфейсу, программному интерфейсу и MCP-серверу |
| Веб-интерфейс | окно переписки, поиск, личные настройки и панель администратора |
| Сервер программного интерфейса | вся серверная логика: диалог, поиск, администрирование, коннекторы, ассистенты |
| Фоновый процесс | индексация, синхронизация прав, очистка, обслуживание моделей, выгрузки |
| MCP-сервер | выдача поиска и веб-инструментов внешним программам-клиентам |
| Исполнитель коннекторов | обращения к интерфейсам внешних источников документов |
| Сервер моделей | расчёт векторов для запросов и для индексации, распознавание текста на изображениях и сканах — на своей инфраструктуре |
| Служба миграций схемы | однократное приведение схемы базы данных к нужной версии при запуске |
| Реляционная база данных | пользователи, переписка, настройки, права, метаданные документов и содержимое загруженных файлов |
| Хранилище очередей и кеша | очереди фоновых задач с сохранением на диск и кеш сессий |
| Векторная база данных | фрагменты документов, их векторные представления и полнотекстовый индекс |
Сервер программного интерфейса, фоновый процесс, MCP-сервер и служба миграций — это один и тот же исполняемый образ, запускаемый с разными командами.
Подробное описание компонентов и их взаимодействия — в разделе «Архитектура».
Ограничения
Ниже перечислено то, чего программа не делает. Эти сведения приведены, чтобы состав поставки можно было проверить прямым сопоставлением с развёрнутым экземпляром.
- Выполнение кода. Средства исполнения программного кода в поставку не входят: изолированная среда исключена из всех раскладок, соответствующие инструменты выключены.
- Генерация изображений и голосовой ввод. Такие инструменты в продукте отсутствуют.
- Описание изображений языковой моделью. С изображений считывается только текст; описания того, что на них изображено, не строятся и в индекс не попадают.
- Распознавание при обходе веб-сайтов. Картинки, встреченные при обходе сайта, не распознаются. Не распознаются и изображения внутри книг EPUB, таблиц XLSX и файлов писем EML, а также многокадровые изображения (анимированные GIF, APNG).
- Параллельные ответы нескольких моделей и режим глубокого исследования. Переключатели этих режимов присутствуют в интерфейсе, но серверная часть такие запросы отклоняет.
- Отключение цитирования. Ответ всегда сопровождается ссылками на источники.
- Ограничение частоты попыток входа. Блокировка учётной записи после серии неудачных попыток в программе не реализована — эту защиту следует размещать на внешнем прокси-сервере.
- Объектное хранилище файлов. Загруженные файлы хранятся в реляционной базе данных; попытка настроить S3-совместимое хранилище приводит к отказу запуска.
- Отдельный поисковый механизм. И векторный, и полнотекстовый индекс хранятся в одной векторной базе данных.
- Собственный мониторинг. Компоненты отдают метрики, но система сбора и отображения метрик в поставку не входит.
- Установка без доступа к сети. Готового автономного комплекта нет: образы и модели для закрытого контура переносятся заранее через внутренний реестр и зеркало.
- Защита информации. Charo не является средством защиты информации: собственная модель прав лишь воспроизводит права пользователя в исходных системах.
Кроме того, часть функций работает только при действующей лицензии: группы пользователей и роли кураторов, SCIM, история запросов и переписки, аналитика и отчёты об использовании, лимиты расходов, хуки, ключи сервисных аккаунтов, брендирование, режим «Поиск», приватные подключения и наследование прав из источников. Лицензия одна, без тарифных планов; проверка выполняется локально и доступа в интернет не требует — см. «Лицензия».
Установка и эксплуатация
- Быстрый старт — системные требования, установка, первый вход, подключение языковой модели и первого источника.
- Языковые модели — подключение провайдеров и выбор моделей.
- Настройки индексации — модель векторного представления и параметры обработки документов.
- Права доступа — роли, группы и наследование прав из источников.
- Лицензия — активация ключа и состав лицензируемых функций.
- Коннекторы — подключение источников документов.
- Архитектура — состав компонентов и требования к ресурсам.
- Безопасность — хранение учётных данных, разграничение доступа, работа в закрытом контуре.
- Поддержка — каналы обращения и состав диагностики.