Klarify — Руководство по установке и настройке

1. Требования к серверу

2. Установка

Docker Compose (рекомендуемый способ)

Скачайте дистрибутив и распакуйте на сервере:

# Распаковать дистрибутив
tar -xzf klar-latest.tar.gz
cd klar

# Настроить параметры
cp .env.example .env
nano .env

# Запустить все сервисы
docker compose up -d

Конфигурация (.env)

Состав контейнеров

On-Premise LLM (без внешних API)

Для работы без подключения к интернету добавьте контейнер с локальной LLM:

# В .env:
LLM_URL=http://kb-llm:11434/v1/chat/completions
LLM_MODEL=qwen3:14b

# docker compose up добавит контейнер Ollama с моделью

Проверка установки

1. Откройте https://your-server:8002 в браузере
2. Войдите с логином admin и паролем из .env
3. Перейдите в KLAR и загрузите тестовый документ
4. Задайте вопрос по документу в интерфейсе поиска

Обновление

При обновлении заменяется только код приложения внутри контейнеров. Все данные сохраняются:

Вариант 1: С доступом к интернету

# Остановить сервисы
docker compose down

# Загрузить новые образы
docker compose pull

# Запустить (данные на месте)
docker compose up -d

# Миграция БД (если требуется — указано в release notes)
docker compose exec app python3 migrate.py

Вариант 2: Закрытый контур (без интернета)

# На машине с интернетом: сохранить образы в архив
docker save kb-app kb-embed | gzip > klar-update.tar.gz

# Перенести архив на сервер (USB, внутренняя сеть)

# На сервере: загрузить образы и перезапустить
docker load < klar-update.tar.gz
docker compose down
docker compose up -d

3. Подготовка документации

Форматы

KLAR принимает: PDF, DOCX, TXT, MD, HTML, CSV, JSON, XLSX, PPTX, XSD, XML.

Рекомендации по структуре

• Заголовки ## -- используйте заголовки для разделения тем. Система разбивает документы по заголовкам второго уровня.
• Один документ = одна тема. Не смешивайте инструкцию по установке и FAQ в одном файле.
• Конкретика. Включайте конкретные шаги, параметры, значения. LLM лучше отвечает по конкретным данным.
• FAQ-документы. Структура "## Вопрос?\nОтвет" автоматически разбирается в быстрые ответы.

4. Загрузка документов

Загрузка файлов

1. Откройте Открыть KLAR
2. Перетащите файлы в зону загрузки или нажмите для выбора
3. Выберите базу знаний (тенант) в выпадающем списке
4. Прогресс отображается в плавающей панели справа внизу
5. Проверьте документ в таблице "Документы"

Импорт с сайта

1. Введите URL в поле "Импорт с сайта"
2. Система автоматически определит тип сайта (статический HTML, SPA, документация с навигацией)
3. После краулинга откроется превью секций — можно выбрать какие включить
4. Нажмите "Сохранить выбранные" для загрузки в базу

5. Быстрые ответы (FAQ)

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

Автоматическая загрузка

Если документ содержит структуру "## Вопрос?\nОтвет", система автоматически извлечёт пары вопрос/ответ при загрузке.

Ручное добавление

1. KLAR раздел "Быстрые ответы (FAQ)"
2. Введите вопрос, ответ и ключевые слова (через запятую)
3. Ключевые слова используются для нечёткого совпадения

6. Настройка режима LLM

7. Мониторинг

Ключевые метрики

• % с ответом -- доля запросов, на которые система нашла ответ. Цель: >80%
• Ср. время ответа -- среднее время генерации. Норма: 5-15 сек
• Вопросы без ответа -- сигнал о пробелах в документации
• Dislike -- ответы которые пользователи отметили как неточные

Регулярные действия

• Еженедельно: просмотр "Вопросов без ответа" -- добавить документацию или FAQ
• Ежемесячно: просмотр "Dislike" -- улучшить проблемные документы
• Ежеквартально: обновить устаревшие документы

8. Персональный аналитик

Режим "Персональный аналитик" предназначен для глубокой работы со знаниями: аналитика, мониторинг, экспертные оценки.

Цифровые двойники экспертов

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

• Настройка: Настройки → Эксперты → добавить или редактировать
• Максимум 2 эксперта одновременно
• Эксперты используют материалы из базы знаний, а не общие знания LLM

Идея-файл

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

• Активируйте кнопку "Идея-файл" в строке диалога
• Можно комбинировать с экспертами — они прокомментируют идея-файл
• Скачайте результат как .md файл

Мониторинг новостей

Автоматический поиск новостей по заданным направлениям. ИИ фильтрует результаты, учитывая ваши предпочтения (лайки/дизлайки).

• Настройка направлений: Настройки → пространство → Мониторинг
• Расписание: автоматически по будням (настраиваемое)
• Кнопки "Загрузить" / "Не интересно" / "Удалить" на каждой новости

Ежедневные инсайты

Каждую ночь ИИ анализирует всю базу знаний и создаёт аналитический отчёт: паттерны, пробелы, противоречия, неочевидные связи между документами.

• Просмотр: Контент → Инсайты
• Ручной запуск: Настройки → Служебные → Запустить анализ

9. Автоматические задачи

10. MCP Server (для AI-агентов)

KLAR поддерживает Model Context Protocol — стандартный протокол для подключения AI-агентов (Claude Desktop, Claude Code, Cursor) к базе знаний.

Установка

pip install mcp httpx

Запуск

# Через переменные окружения
KLAR_API_URL=https://kb.zaltrix.org KLAR_API_KEY=sk-xxx python3 mcp_server.py

# Или через аргументы
python3 mcp_server.py --api-url https://kb.zaltrix.org --api-key sk-xxx

Подключение к Claude Desktop

Добавьте в ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "klar": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "KLAR_API_URL": "https://kb.zaltrix.org",
        "KLAR_API_KEY": "sk-ваш_ключ"
      }
    }
  }
}

Доступные инструменты

11. REST API