For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.nvidia.com/dynamo/llms.txt. For full content including API reference and SDK examples, see https://docs.nvidia.com/dynamo/llms-full.txt.

Адаптеры LoRA

LoRA (Low-Rank Adaptation) позволяет эффективно дообучать и обслуживать специализированные варианты моделей без дублирования полных весов модели. Dynamo имеет встроенную поддержку динамической загрузки адаптеров LoRA, кэширования и маршрутизации инференса.

Поддержка backend'ов

Backend	Статус	Примечания
vLLM	✅	Полная поддержка, включая маршрутизацию с учетом KV
SGLang	🚧	В процессе
TensorRT-LLM	❌	Пока не поддерживается

Полные сведения о совместимости см. в Feature Matrix.

Обзор

Реализация LoRA в Dynamo обеспечивает:

Динамическую загрузку: загружать и выгружать адаптеры LoRA во время работы, без перезапуска worker'ов
Несколько источников: загрузка из локальной файловой системы (file://), S3-совместимого хранилища (s3://) или Hugging Face Hub (hf://)
Автоматическое кэширование: загруженные адаптеры кэшируются локально, чтобы избежать повторных загрузок
Интеграцию с discovery: загруженные LoRA автоматически регистрируются и доступны через /v1/models
Маршрутизацию с учетом KV: запросы направляются к worker'ам, на которых загружен нужный адаптер LoRA
Нативную поддержку Kubernetes: декларативное управление LoRA через CRD DynamoModel

Architecture

flowchart TD
    Frontend["Frontend"] --> Router["Router<br/>(LoRA-aware)"]
    Router --> Workers["Workers<br/>(LoRA-loaded)"]
    Workers --> ManagerNode["LoRA Manager"]

    subgraph ManagerGroup["LoRA Manager"]
        Downloader
        Cache
    end

    ManagerNode --> Local["file://<br/>Local"]
    ManagerNode --> S3["s3://<br/>S3/MinIO"]
    ManagerNode --> HF["hf://<br/>(custom)"]

Система LoRA состоит из:

Rust Core (lib/llm/src/lora/): высокопроизводительная загрузка, кэширование и валидация
Python Manager (components/src/dynamo/common/lora/): расширяемая обертка с поддержкой пользовательских источников
Worker Handlers (components/src/dynamo/vllm/handlers.py): API загрузки/выгрузки и интеграция с инференсом

Быстрый старт

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

Dynamo установлен с поддержкой vLLM
Для источников S3: настроены AWS credentials
Адаптер LoRA, совместимый с вашей базовой моделью

Локальная разработка

1. Запустите Dynamo с поддержкой LoRA:

# Запустить worker vLLM с флагами LoRA
DYN_SYSTEM_ENABLED=true DYN_SYSTEM_PORT=8081 \
    python -m dynamo.vllm --model Qwen/Qwen3-0.6B --enforce-eager \
    --enable-lora \
    --max-lora-rank 64

2. Загрузите адаптер LoRA:

curl -X POST http://localhost:8081/v1/loras \
  -H "Content-Type: application/json" \
  -d '{
    "lora_name": "my-lora",
    "source": {
      "uri": "file:///path/to/my-lora"
    }
  }'

3. Выполните инференс с LoRA:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-lora",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

S3-совместимое хранилище

Для промышленного развертывания храните адаптеры LoRA в S3-совместимом хранилище:

# Настроить S3 credentials
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_ENDPOINT=http://minio:9000  # For MinIO
export AWS_REGION=us-east-1

# Загрузить LoRA из S3
curl -X POST http://localhost:8081/v1/loras \
  -H "Content-Type: application/json" \
  -d '{
    "lora_name": "customer-support-lora",
    "source": {
      "uri": "s3://my-loras/customer-support-v1"
    }
  }'

Конфигурация

Переменные окружения

Переменная	Описание	Значение по умолчанию
`DYN_LORA_ENABLED`	Enable LoRA adapter support	`false`
`DYN_LORA_PATH`	Local cache directory for downloaded LoRAs	`~/.cache/dynamo_loras`
`AWS_ACCESS_KEY_ID`	S3 access key (for `s3://` URIs)	-
`AWS_SECRET_ACCESS_KEY`	S3 secret key (for `s3://` URIs)	-
`AWS_ENDPOINT`	Custom S3 endpoint (for MinIO, etc.)	-
`AWS_REGION`	AWS region	`us-east-1`
`AWS_ALLOW_HTTP`	Allow HTTP (non-TLS) connections	`false`

Аргументы vLLM

Аргумент	Описание
`--enable-lora`	Enable LoRA adapter support in vLLM
`--max-lora-rank`	Maximum LoRA rank (must be >= your LoRA's rank)
`--max-loras`	Maximum number of LoRAs to load simultaneously

Справочник backend API

Загрузка LoRA

Загрузить адаптер LoRA из URI источника.

POST /v1/loras

Запрос:

{
  "lora_name": "string",
  "source": {
    "uri": "string"
  }
}

Ответ:

{
  "status": "success",
  "message": "LoRA adapter 'my-lora' loaded successfully",
  "lora_name": "my-lora",
  "lora_id": 1207343256
}

Список LoRA

Список всех загруженных адаптеров LoRA.

GET /v1/loras

Response:

{
  "status": "success",
  "loras": {
    "my-lora": 1207343256,
    "another-lora": 987654321
  },
  "count": 2
}

Выгрузка LoRA

Выгрузить адаптер LoRA из worker'а.

DELETE /v1/loras/{lora_name}

Response:

{
  "status": "success",
  "message": "LoRA adapter 'my-lora' unloaded successfully",
  "lora_name": "my-lora",
  "lora_id": 1207343256
}

Развертывание в Kubernetes

Для развертываний в Kubernetes используйте пользовательский ресурс DynamoModel для декларативного управления адаптерами LoRA.

CRD `DynamoModel`

apiVersion: nvidia.com/v1alpha1
kind: DynamoModel
metadata:
  name: customer-support-lora
  namespace: dynamo-system
spec:
  modelName: customer-support-adapter-v1
  baseModelName: Qwen/Qwen3-0.6B  # Must match modelRef.name in DGD
  modelType: lora
  source:
    uri: s3://my-models-bucket/loras/customer-support/v1

Как это работает

Когда вы создаете DynamoModel:

Обнаруживает конечные точки: находит все pod'ы, на которых запущен baseModelName
Создает сервис: автоматически создает Kubernetes Service
Загружает LoRA: вызывает API загрузки LoRA на каждой конечной точке
Обновляет статус: сообщает, какие конечные точки готовы

Проверка развертывания

# Проверить статус LoRA
kubectl get dynamomodel customer-support-lora

# Ожидаемый вывод:
# NAME                    TOTAL   READY   AGE
# customer-support-lora   2       2       30s

Полные сведения о развертывании в Kubernetes см.:

Примеры

Пример	Описание
Local LoRA with MinIO	Local development with S3-compatible storage
Kubernetes LoRA Deployment	Production deployment with DynamoModel CRD

Устранение неполадок

LoRA не загружается

Проверьте доступность S3:

# Verify LoRA exists in S3
aws --endpoint-url=$AWS_ENDPOINT s3 ls s3://my-loras/ --recursive

Проверьте каталог кэша:

ls -la ~/.cache/dynamo_loras/

Проверьте журналы worker'ов:

# Look for LoRA-related messages
kubectl logs deployment/my-worker | grep -i lora

Модель не найдена после загрузки

Убедитесь, что имя LoRA совпадает точно, с учетом регистра
Проверьте, что LoRA присутствует в списке: curl http://localhost:8081/v1/loras
Убедитесь, что регистрация discovery прошла успешно (проверьте журналы worker'ов)

Инференс возвращает ответ базовой модели

Убедитесь, что поле model в вашем запросе совпадает с lora_name
Проверьте, что LoRA загружена на worker, обрабатывающий ваш запрос
Для разнесенного serving убедитесь, что LoRA есть и у prefill-, и у decode-worker'ов

Маршрутизация LoRA с учетом KV-кэша

Когда включена маршрутизация с учетом KV, маршрутизатор автоматически учитывает идентичность адаптера LoRA при вычислении хэшей блоков. Это означает:

Отдельные пространства хэшей для каждого адаптера: блоки, закэшированные под адаптером A, никогда не будут перепутаны с блоками под адаптером B или базовой моделью, даже если последовательности токенов одинаковы. Имя адаптера подмешивается в вычисление LocalBlockHash.
Автоматическое совместное использование префиксов внутри одного адаптера: запросы к одному и тому же адаптеру LoRA получают выгоду от сопоставления префиксов в KV-кэше так же, как и запросы к базовой модели.
Никакой настройки не требуется: имя LoRA автоматически передается через KV-события (BlockStored) от engine к маршрутизатору. Маршрутизатор использует поле lora_name в событиях, чтобы направлять запросы LoRA к worker'ам с совпадающими закэшированными блоками.

Это работает end-to-end во всей цепочке: publisher pipeline, KV consolidator (для дедупликации) и путь routing query.

См. также

Feature Matrix - Обзор совместимости backend'ов
vLLM Backend - Конфигурация для vLLM
Dynamo Operator - Обзор Kubernetes-оператора
Routing Concepts - Маршрутизация запросов с учетом LoRA
KV Events for Custom Engines - Публикация KV-событий с учетом LoRA

Поддержка backend'ов​

Обзор​

Architecture​

Быстрый старт​

Предварительные требования​

Локальная разработка​

S3-совместимое хранилище​

Конфигурация​

Переменные окружения​

Аргументы vLLM​

Справочник backend API​

Загрузка LoRA​

Список LoRA​

Выгрузка LoRA​

Развертывание в Kubernetes​

CRD DynamoModel​

Как это работает​

Проверка развертывания​

Примеры​

Устранение неполадок​

LoRA не загружается​

Модель не найдена после загрузки​

Инференс возвращает ответ базовой модели​

Маршрутизация LoRA с учетом KV-кэша​

См. также​