Аннотация

Документ «Руководство администратора» предназначен для сотрудников эксплуатирующей организации и отражает основную функциональность и порядок действий при выполнении операций, связанных с администрированием системы Kodify.

Перечень терминов

Таблица 1. Термины, используемые в руководстве Kodify.

Перечень сокращений

Таблица 2. Сокращения в руководстве Kodify.

Введение

Настоящий документ представляет собой руководство администратора (далее руководство) системы Kodify.

Руководство описывает:

• общее определение системы;
• функции системы;
• описание взаимодействия сервисов системы;
• требования к уровню подготовки администратора системы;
• программные и аппаратные требования для работы с системой;
• установку и настройку системы.

Назначение системы и ее состав

Назначение системы

Kodify от МWS AI представляет собой AI-ассистента разработчика. Этот инструмент использует искусственный интеллект для автоматизации рутинных процессов и помощи разработчикам в выполнении различных задач при написании программного кода.

Система предназначена для облегчения процесса разработки, предоставляя инструменты для генерации кода, улучшения его качества и автоматизации рутинных задач. Kodify поддерживает различные языки программирования (например, Python, C#, Java, Go, JavaScript) и интеграции с популярными инструментами разработки.

Сервисы Kodify

Система Kodify состоит из следующих сервисов:

Таблица 3. Сервисы Kodify.

Описание взаимодействия сервисов

На следующей схеме показано взаимодействие сервисов Kodify.

Kodify представляет собой LLM и плагин, встраиваемый в IDE от JetBrains (например, PyCharm) и Visual Studio Code. Взаимодействие пользователя с LLM Kodify осуществляется через пользовательский интерфейс (UI) в виде плагина. Плагин содержит набор функций для упрощения и ускорения процесса написания кода за счёт обращения к LLM.

Kodify предоставляет REST API (API сервер), к которому обращается плагин, установленный в IDE. Далее запрос отправляется на обработку LLM-моделью в Model Server.

Краткое описание функций

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

• Автопродление кода с помощью LLM, которая на основе уже написанного пользователем кода генерирует завершение строки.
• Документирование кода
• Поиск ошибок в коде и исправление найденных ошибок.
• Формирование Unit-тестов для кода пользователя.
• Объяснение кода.

Требования к уровню подготовки

Требования к подготовке администратора:

• высокий уровень квалификации;
• наличие практического опыта выполнения работ по установке, настройке и администрированию программных и технических средств.

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

Ниже представлен список пользовательской документации системы:

• Руководство администратора системы Kodify
• Руководство пользователя системы Kodify.

Условия применения системы

Требования к программному обеспечению

Для работы системы необходимо, чтобы выполнялись следующие требования к программному обеспечению:

Таблица 4. Требования к программному обеспечению.

Требования к аппаратному обеспечению

Для работы системы необходимо, чтобы выполнялись следующие требования к аппаратным ресурсам:

Таблица 5. Требования к аппаратному обеспечению.

Установка системы

Для установки системы в собственной инфраструктуре, выполните следующие шаги:

Скачайте файлы и авторизуйтесь в Artifactory

Скачайте файлы docker-compose или compose, ENV-файл и config.yml - при наличии. Вам будут переданы логин и пароль от учетной записи Artifactory.

Перейдите по ссылке https://artifactory.mts.ai/ui/login/ и пройдите аутентификацию, используя полученные учётные данные. Ссылку на папку с вашим образом вам предоставят отдельно.

Поместите скачанные файлы в желаемую директорию.

Проверьте и сконфигурируйте ENV-файл, docker-compose и config.yml файлы

Ознакомьтесь с содержимым ENV-файла, который передан вместе с docker-compose и config.yml файлами. ENV-файл содержит значения переменных окружения. При необходимости, сконфигурируйте переменные.

Подробнее о переменных окружения смотрите в разделе - Проверка и конфигурация ENV-файла.

Также проверьте заполнение docker-compose файла. Все переменные должны быть заполнены как на скриншоте ниже. Редактировать можно только переменную ports, если вы хотите указать иной адрес для приложения.

Файл config.yml необходимо добавить в директорию /opt/mtsai, которую перед этим нужно создать. Вы также можете указать путь до config.yml в текущей директории:
volumes:
./config.yml:/vllm-workspace/config.yml

При использовании пользовательской авторизации (ENV-переменная MTSAI_AUTH=true и AUTH_TYPE=DB), вы можете развернуть базу данных PostgreSQL (работает на версии 16.4, но нет жестких требований к версии) одновременно с сервисом, используя Docker Compose. Для этого добавьте в docker-compose.yml сервис базы данных:

Volume (mtsai_pgdata) обеспечивает сохранность данных базы между перезапусками контейнера. Данные будут храниться в директории /var/lib/postgresql/data внутри контейнера и будут доступны после остановки и удаления контейнера.

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

POSTGRES_PASSWORD=<CHANGE THIS>

При развертывании системы на нескольких видеокартах, добавьте в docker-compose.yml дополнительный параметр:

shm_size: 10g

Где shm_size - размер RAM памяти, которая хранит в себе промежуточные данные работы LLM, используемые в параллельных процессах на разных GPU. Необходимый размер shm_size может варьироваться в зависимости от используемой LLM, количества GPU и других факторов. Рекомендуется установить значение shm_size равным 10g.

Настройка модели для tabby запросов

Для отправки запросов к модели в формате tabby, укажите в config.yml ключ tabby, у которого вы можете указать вложенный ключ model_name. В model_name укажите имя модели.

tabby:
   model_name: tabby_model_name

По умолчанию, запросы в формате tabby обрабатываются первой моделью в списке upstreams в файле config.yml. В случае, когда API-сервер обслуживает несколько моделей и требуется указать какая именно модель будет обрабатывать запросы tabby, вы можете указать имя модели в tabby.model_name.

upstreams:
   http://upstream1:8000:
   http://upstream2:8000:
tabby:
   model_name: tabby_model_name

Залогиньтесь в Artifactory

Залогиньтесь в Artifactory с использованием вашей учетной записи через команду:

docker login artifactory.mts.ai

Мигрируйте БД (опционально)

Актуально в том случае, если планируется использовать журналирование (значение переменной LOGS в ENV-файле - "True"). Если журналирование отключено, то данный этап можно пропустить и перейти к следующему шагу.

Для выполнения миграции БД, установите переменную окружения в ENV-файле RUN_MIGRATIONS в значение "1".

Если приложение эксплуатируется в среде Kubernetes, создайте init-контейнер с тем же образом, что и в основном контейнере сервиса. В нём используйте команду:

alembic -c /vllm-workspace/middleware/gpt_logger/alembic.ini upgrade head

Для подключения к БД укажите переменные окружения. Подробнее о переменных смотрите в разделе - Переменные базы данных.

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

Запустите контейнер с помощью команды:

docker compose up -d 

Убедитесь, что у вас установлен Docker Compose.

Проверьте работу системы

Проверьте, что система работает корректно одним из следующих способов:

1. С помощью API-запроса GET/health.

2. Откройте логи контейнера с помощью команды:

   docker logs CONTAINER_ID 

При успешной установке приложения в логах отобразится следующее:

INFO: Application startup complete/
INFO: Unicorn running on http://. . . . .

Проверка и конфигурация ENV-файла

Вместе с docker-compose файлом вам будет передан ENV-файл, который содержит значения переменных окружения. В файле вы можете задать или изменить переменные, указанные ниже.

Переменные потребления видеопамяти

Переменные потребления видеопамяти (VRAM) используются для контроля за распределением и использованием графической памяти на GPU. Эти переменные устанавливают максимальный объём видеопамяти, доступный для использования.

Таблица 6. Переменные потребления видеопамяти.

Переменные для запуска сервиса на нескольких видеокартах

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

Таблица 7. Переменные окружения для запуска сервиса на нескольких видеокартах.

Дополнительные аргументы для запуска сервиса на нескольких видеокартах

В данном подразделе перечислены дополнительные аргументы tensor-parallel-size и pipeline-parallel-size, которые передаются в строку запуска приложения через переменную окружения ADDITIONAL_ARGS.

Таблица 8. Дополнительные аргументы для запуска сервиса на нескольких видеокартах.

Переменные авторизации

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

Таблица 9. Переменные авторизации

Однотокеновая авторизация (one-token auth) — это авторизация, при которой существует только один токен, способный пройти авторизацию (его значение необходимо задать в рамках конфигурации ENV).
Пользовательская авторизация - это авторизация, при которой каждому пользователю создается уникальный токен. Информация о пользователях хранится в БД.

Переменные базы данных

Переменные базы данных используются для хранения конфигурационных данных, необходимых для подключения и работы с базой данных при включённой пользовательской авторизации (MTSAI_AUTH = true и AUTH_TYPE = DB). Не используются при ином типе авторизации и отсутствуют по умолчанию в ENV-файле. Добавьте их в файл вручную только в том случае, если вам необходима пользовательская авторизация.

Таблица 10. Переменные базы данных.

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

Переменные настройки генерации модели

Переменные настройки генерации модели устанавливают ограничения при обработке запросов POST/v1/chat/completions.

Таблица 11. Переменные настройки генерации модели.

Переменные журналирования

Переменные журналирования используются для настройки журналирования API-запросов и определения таблицы БД, куда будет сохранён журнал обработки пользовательских запросов. Все переменные из данного раздела обязательны к заполнению, кроме переменной LOGS.

Таблица 12. Переменные журналирования.

Переменные движка ядра vLLM

Таблица 13. Переменные движка ядра.

Настройка функции автодополнения

Для работы функции автодополнения кода в плагине, добавьте в ENV-файл переменную COMPLETIONS_PREPROCESSING_CONFIG со следующей настройкой:

COMPLETIONS_PREPROCESSING_CONFIG=preprocess_configs/qwen.json

Примеры заполнения ENV-файла

Однотокеновая авторизация

GPUUTIL: 0.9
MTSAI_AUTH: false
VLLM_API_KEY:<токен авторизации>
USERS_TABLE: <переменная отсутствует>
AUTH_TYPE: <переменная отсутствует>
DB_URL: <переменная отсутствует>
MAX_N: 10

Пользовательская авторизация

GPUUTIL: 0.9
MTSAI_AUTH: true
VLLM_API_KEY: <переменная отсутствует>
USERS_TABLE: <идентификатор таблицы>
AUTH_TYPE: DB
DB_URL:postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
MAX_N: 10

Отключение журналирования

LOGS – переменная отсутствует в ENV-файле
LOGS_DB_HOST: <HOST>
LOGS_DB_POST: <PORT>
LOGS_DB_NAME: <DB_NAME>
LOGS_DB_USERNAME: <USERNAME>
LOGS_DB_PASSWORD: <PASSWORD>

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

Активное журналирование

LOGS: True
LOGS_DB_HOST: <HOST>
LOGS_DB_POST: <PORT>
LOGS_DB_NAME: <DB_NAME>
LOGS_DB_USERNAME: <USERNAME>
LOGS_DB_PASSWORD: <PASSWORD>

При необходимости, скорректируйте значения переменных в ENV-файле.
После внесения изменений, поместите ENV-файл в ту же директорию, где находится docker-compose.yml.