Skip to content

functionality.md

Latest commit

 

History

History
130 lines (101 loc) · 5.87 KB

functionality.md

File metadata and controls

130 lines (101 loc) · 5.87 KB

Функциональность проекта

Главное меню

После запуска python3 run.py пользователь получает три пункта:

1) Offline AI Chat
2) System Analyzer
3) Exit

Сценарий Offline AI Chat

Назначение

Сценарий предназначен для локального запуска GGUF-модели через llama.cpp и последующего интерактивного общения с моделью в консоли.

Этапы работы

1. Выбор модели

Проект читает _work-models/catalog.json и отображает список моделей.

Для каждой модели выводятся:

  • наименование;
  • краткое описание;
  • max_tokens;
  • ориентир по требованиям к хосту;
  • источник;
  • тип разметки GGUF: single-file или sharded.

2. Подготовка файлов модели

После выбора проекта проверяет каталог _work-models/models/<model_key>/.

Логика работы:

  • если файл уже существует, вычисляется SHA256 и сверяется с каталогом;
  • если файл отсутствует, он скачивается по URL из каталога;
  • после загрузки файл повторно проверяется по SHA256;
  • при несовпадении контрольной суммы выполнение прерывается с ошибкой.

Таким образом проект не использует неподтверждённые локальные GGUF-файлы.

3. Сборка Docker-образа

Для сборки создаётся временный build context внутри .runtime/offline-ai-chat/.

Особенности реализации:

  • Dockerfile берётся из apps/offline_llm_chat/docker/Dockerfile;
  • файлы модели добавляются в build context через hardlink, а не копированием;
  • образ собирается с тегами:
    • offline-ai-chat-llm:latest;
    • offline-ai-chat-llm:<model_key>.

4. Запуск контейнера

После сборки проект запускает контейнер с llama.cpp и ожидает появления Unix socket.

В runtime используются параметры из .env:

  • CTX_SIZE;
  • MEM_LIMIT;
  • CPU_LIMIT;
  • PIDS_LIMIT;
  • DEBUG_LOGS.

5. Проверка готовности модели

После появления сокета проект не сразу открывает чат. Сначала выполняются две проверки:

  • опрос /v1/models на готовность API;
  • smoke test с кратким тестовым запросом.

Только после успешного прохождения этих проверок запускается пользовательский чат.

6. Интерактивный режим

В интерактивном режиме поддерживаются команды:

  • /exit — завершить чат;
  • /reset — сбросить текущую историю сообщений.

Дополнительно проект выводит служебную статистику по ответу:

  • число токенов;
  • длительность обработки;
  • скорость prompt/generation;
  • суммарный счётчик токенов с начала сессии.

Сценарий System Analyzer

Назначение

Сценарий предназначен для предварительной оценки ресурсов Linux-хоста и выбора параметров запуска контейнера.

Что анализируется

На основе системных данных проект собирает информацию о:

  • версии ОС;
  • CPU и количестве логических ядер;
  • объёме RAM и swap;
  • файловой системе корня;
  • физических дисках;
  • GPU при наличии поддерживаемых инструментов обнаружения.

Результат работы

По результатам анализа проект формирует профили запуска и предлагает значения для .env:

  • CTX_SIZE;
  • MEM_LIMIT;
  • CPU_LIMIT;
  • PIDS_LIMIT.

При подтверждении пользователя значения записываются в корневой .env.

Ограничения функционала

Проект выполняет строго определённую задачу и не включает дополнительные режимы работы.

В текущей реализации проект:

  • не монтирует пользовательский репозиторий в runtime контейнера;
  • не модифицирует внешний исходный код;
  • не поднимает web-приложение;
  • не предоставляет REST API наружу;
  • не ведёт отдельное файловое хранилище отчётов;
  • не управляет несколькими контейнерами одновременно.

Практический сценарий эксплуатации

Базовый рабочий поток:

Запуск run.py
  -> System Analyzer
  -> оценка профиля и обновление .env
  -> возврат в главное меню
  -> Offline AI Chat
  -> выбор модели
  -> проверка или загрузка GGUF
  -> Docker build
  -> Docker run
  -> smoke test
  -> интерактивный CLI-чат