Перейти к содержанию

Миграция на v1.6.0 — слияние LLM-сервисов

В версии v1.6.0 два сервиса (vul-explainer для Ollama и vul-explainer-cloud для облачных LLM) объединены в единый llm-service с поддержкой адаптеров обоих протоколов.

Что изменилось

Внутренне

  • Один Docker-контейнер llm-service вместо двух (vul-explainer + vul-explainer-cloud).
  • Размер образа уменьшен с ~3,5 ГБ до ~500 МБ (выкинуты неиспользовавшиеся transformers, numpy, scipy, scikit-learn, pyarrow, pandas — относились к мёртвой XAI-инфраструктуре, которая никогда не подключалась к LLM-промптам).
  • Per-protocol routing per-request: для каждого запроса llm-service выбирает адаптер по полю protocol из каталога (ollama / openai_compatible / auto).

Для администратора

  • Управление провайдерами через UI — Settings → LLM-провайдеры — без изменений (catalog CRUD появился ещё в v1.5.x).
  • Прогрев и тест соединения работают как раньше, но теперь дают единый 6-шаговый диагностический trace для обоих протоколов: healthcheck → validation → reachability → simple_chat_probe → full_chat_probe → parse_response.
  • Playground работает для всех провайдеров (раньше — только cloud). Customer с локальной Ollama теперь может играть с prompt'ами через UI.
  • llm_request_log теперь пишется и для Ollama-режима (раньше — только cloud).

Для пользователя

  • Никаких видимых изменений. Кнопки, страницы, поведение — те же.

Шаги миграции

1. Backup

Перед обновлением сделайте backup:

ssh <ваш-стенд>
sudo mkdir -p /opt/copilot-backups/backup-pre-1.6.0-$(date +%Y%m%d-%H%M%S)
sudo cp /opt/copilot/docker-compose.yml /opt/copilot-backups/backup-pre-1.6.0-*/
sudo docker exec postgresql pg_dumpall > /opt/copilot-backups/backup-pre-1.6.0-*/pg_dumpall.sql

2. Обновление через Helm

helm repo update
helm upgrade copilot appsec/copilot --version 1.6.0 -f values.yaml

В выводе helm появится WARNING о том, что ключи vulExplainerCloud: устарели — это нормально, они продолжат работать в течение 1-2 минорных версий благодаря backwards-compat mapping.

3. (Опционально) Обновление values.yaml

Можно обновить ключи в своём values.yaml:

# Было:
vulExplainerCloud:
  enabled: true
  image:
    tag: 1.5.0
  llmApiKey: "sk-..."

# Стало:
llmService:
  enabled: true
  image:
    repository: registry.appsec.global/copilot/llm-service
    tag: 1.6.0
  llmApiKey: "sk-..."

# Старая секция vulExplainer полностью удалена — её функциональность
# теперь доступна через UI Settings → LLM-провайдеры (добавьте
# Ollama-провайдера с protocol=ollama).

Если у вас был включён vulExplainer (Ollama-режим):

  1. Установите vulExplainer.enabled: false (Helm выдаст fail-fast если оставить true).
  2. После старта откройте UI → Settings → LLM-провайдеры → Add Provider.
  3. Заполните: name=Ollama Local, protocol=ollama, endpoint=URL вашего Ollama (например, http://ollama-internal:11434), auth_type=none или x_api_key (если за nginx-proxy с X-API-Key).
  4. Назначьте провайдера на роль Explanation в той же странице.

4. Особенность для customer'ов с Ollama-за-nginx-proxy

Если ваш Ollama стоит за nginx-прокси с ограничением client_max_body_size, увеличьте лимит до 64K:

# /etc/nginx/conf.d/ollama.conf
location /api/chat {
    client_max_body_size 64K;
    proxy_pass http://ollama-upstream:11434;
    # ...
}

Это нужно потому что unified prompt в llm-service может достигать ~10-15 KB на сложных explain-запросах. Дефолтный лимит nginx — 1 MB, но некоторые customer'ы выставляли 1-10 KB защитно.

5. Verification

После старта:

sudo docker ps | grep llm-service
# Ожидается: copilot-llm-service ... Up

curl https://<your-stand>/api/settings/providers/info
# Ожидается: { "explanation": { "statusV2": "ready" }, ... }

Откройте UI Settings → LLM-провайдеры — каталог должен показать ваших провайдеров со статусом ready. Нажмите Test connection на каждом — должен зажечься зелёный badge с 6-шаговым trace в модалке.

Откат (rollback)

Если что-то критическое:

helm rollback copilot <previous-revision>

Старые образы vul-explainer-dev и vul-explainer-cloud-dev сохранены в Container Registry — rollback восстановит их автоматически.

Breaking changes

Минимальные:

  • API-поля ProviderInfoResponse.type и ProviderInfoResponse.explanationModel удалены. Frontend обновлён в той же версии — не читает их. Сторонние интеграции, читавшие эти поля, должны мигрировать на per-role поля (ProviderInfoResponse.explanation.*).
  • Контейнер vul-explainer (старый Ollama-сервис) больше не запускается. Миграция настроек — через UI Settings.

Поддержка

Issues/вопросы: https://code.appsec.ru/appsec-ai/llm-service/-/issues