LoRA 리졸버 플러그인

LoRA 리졸버 플러그인 (LoRA Resolver Plugins)

이 디렉터리에는 LoRAResolver 프레임워크 위에 구축된 vLLM의 LoRA 리졸버 플러그인이 포함돼 있습니다. 지정된 로컬 스토리지 경로에서 LoRA 어댑터를 자동으로 발견·로드하여 수동 구성이나 서버 재시작을 없앱니다.

출처: 문서

본문

개요 (Overview)

LoRA 리졸버 플러그인은 런타임에 LoRA 어댑터를 동적으로 로드하는 유연한 방식을 제공합니다. vLLM이 아직 로드되지 않은 LoRA 어댑터 요청을 받으면 리졸버 플러그인은 구성된 스토리지 위치에서 어댑터를 찾아 로드하려 시도합니다. 이를 통해 다음이 가능합니다:

  • 동적 LoRA 로딩 — 서버 재시작 없이 온디맨드로 어댑터를 로드합니다.
  • 여러 스토리지 백엔드 — 파일시스템, S3, 커스텀 백엔드를 지원합니다. 내장 lora_filesystem_resolver는 로컬 스토리지 경로가 필요하고, 내장 hf_hub_resolver는 Huggingface Hub에서 LoRA 어댑터를 가져와 동일한 방식으로 진행합니다. 일반적으로 커스텀 리졸버를 구현해 어떤 소스에서든 가져올 수 있습니다.
  • 자동 발견 — 기존 LoRA 워크플로와 원활하게 통합됩니다.
  • 확장 가능한 배포 — 여러 vLLM 인스턴스에서 중앙 집중식 어댑터 관리를 제공합니다.

사전 준비 (Prerequisites)

LoRA 리졸버 플러그인을 사용하기 전에 다음 환경 변수를 구성하세요.

필수 환경 변수 (Required Environment Variables)

  • VLLM_ALLOW_RUNTIME_LORA_UPDATING: 동적 LoRA 로딩을 활성화하려면 true 또는 1로 설정해야 합니다.
export VLLM_ALLOW_RUNTIME_LORA_UPDATING=true
  • VLLM_PLUGINS: 원하는 리졸버 플러그인을 포함해야 합니다(콤마로 구분된 목록).
export VLLM_PLUGINS=lora_filesystem_resolver
  • VLLM_LORA_RESOLVER_CACHE_DIR: filesystem 리졸버의 경우 유효한 디렉터리 경로로 설정해야 합니다.
export VLLM_LORA_RESOLVER_CACHE_DIR=/path/to/lora/adapters

선택적 환경 변수 (Optional Environment Variables)

  • VLLM_PLUGINS: 설정하지 않으면 사용 가능한 모든 플러그인이 로드됩니다. 빈 문자열로 설정하면 플러그인이 로드되지 않습니다.

사용 가능한 리졸버 (Available Resolvers)

lora_filesystem_resolver

filesystem 리졸버는 vLLM과 함께 기본 설치되며 로컬 디렉터리 구조에서 LoRA 어댑터를 로드할 수 있게 합니다.

설정 단계 (Setup Steps)

  • LoRA 어댑터 스토리지 디렉터리를 생성합니다:
mkdir -p /path/to/lora/adapters
  • 환경 변수를 설정합니다:
export VLLM_ALLOW_RUNTIME_LORA_UPDATING=true
export VLLM_PLUGINS=lora_filesystem_resolver
export VLLM_LORA_RESOLVER_CACHE_DIR=/path/to/lora/adapters
  • vLLM 서버를 시작합니다. 베이스 모델은 meta-llama/Llama-2-7b-hf일 수 있습니다. 환경 변수에 Hugging Face 토큰을 설정했는지 확인하세요(export HF_TOKEN=xxx235).
vllm serve your-base-model \
    --enable-lora

디렉터리 구조 요구 사항 (Directory Structure Requirements)

filesystem 리졸버는 LoRA 어댑터가 다음 구조로 구성돼 있어야 합니다:

/path/to/lora/adapters/
├── adapter1/
│   ├── adapter_config.json
│   ├── adapter_model.bin
│   └── tokenizer files (if applicable)
├── adapter2/
│   ├── adapter_config.json
│   ├── adapter_model.bin
│   └── tokenizer files (if applicable)
└── ...

각 어댑터 디렉터리는 다음을 포함해야 합니다:

  • adapter_config.json: 다음 구조의 필수 구성 파일:
{
  "peft_type": "LORA",
  "base_model_name_or_path": "your-base-model-name",
  "r": 16,
  "lora_alpha": 32,
  "target_modules": ["q_proj", "v_proj"],
  "bias": "none",
  "modules_to_save": null,
  "use_rslora": false,
  "use_dora": false
}
  • adapter_model.bin: LoRA 어댑터 가중치 파일

사용 예 (Usage Example)

  • LoRA 어댑터를 준비합니다:
# Assuming you have a LoRA adapter in /tmp/my_lora_adapter
cp -r /tmp/my_lora_adapter /path/to/lora/adapters/my_sql_adapter
  • 디렉터리 구조를 확인합니다:
ls -la /path/to/lora/adapters/my_sql_adapter/
# Should show: adapter_config.json, adapter_model.bin, etc.
  • 어댑터를 사용해 요청을 보냅니다:
curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "my_sql_adapter",
        "prompt": "Generate a SQL query for:",
        "max_tokens": 50,
        "temperature": 0.1
    }'

동작 방식 (How It Works)

  • vLLM이 my_sql_adapter라는 LoRA 어댑터 요청을 받습니다.
  • filesystem 리졸버가 /path/to/lora/adapters/my_sql_adapter/가 존재하는지 확인합니다.
  • 발견되면 adapter_config.json 파일을 검증합니다.
  • 구성이 베이스 모델과 일치하고 유효하면 어댑터가 로드됩니다.
  • 요청은 새로 로드된 어댑터로 정상 처리됩니다.
  • 어댑터는 이후 요청에서도 계속 사용 가능합니다.

고급 구성 (Advanced Configuration)

여러 리졸버 (Multiple Resolvers)

여러 리졸버 플러그인을 구성해 서로 다른 소스에서 어댑터를 로드할 수 있습니다:

'lora_s3_resolver'는 직접 구현해야 하는 커스텀 리졸버의 예입니다.

export VLLM_PLUGINS=lora_filesystem_resolver,lora_s3_resolver

나열된 모든 리졸버가 활성화되며, 요청 시 vLLM은 하나가 성공할 때까지 순서대로 시도합니다.

커스텀 리졸버 구현 (Custom Resolver Implementation)

나만의 리졸버 플러그인을 구현하려면:

  • 새 리졸버 클래스를 만듭니다:
from vllm.lora.resolver import LoRAResolver, LoRAResolverRegistry
from vllm.lora.request import LoRARequest

class CustomResolver(LoRAResolver):
    async def resolve_lora(self, base_model_name: str, lora_name: str) -> Optional[LoRARequest]:
        # Your custom resolution logic here
        pass
  • 리졸버를 등록합니다:
def register_custom_resolver():
    resolver = CustomResolver()
    LoRAResolverRegistry.register_resolver("Custom Resolver", resolver)

문제 해결 (Troubleshooting)

흔한 문제 (Common Issues)

  • "VLLM_LORA_RESOLVER_CACHE_DIR must be set to a valid directory"
    • 디렉터리가 존재하고 접근 가능한지 확인합니다.
    • 디렉터리의 파일 권한을 확인합니다.
  • "LoRA adapter not found"
    • 어댑터 디렉터리 이름이 요청한 모델 이름과 일치하는지 확인합니다.
    • adapter_config.json이 존재하고 유효한 JSON인지 확인합니다.
    • 디렉터리에 adapter_model.bin이 존재하는지 확인합니다.
  • "Invalid adapter configuration"
    • peft_type이 "LORA"로 설정됐는지 확인합니다.
    • base_model_name_or_path가 베이스 모델과 일치하는지 확인합니다.
    • target_modules가 올바르게 구성됐는지 확인합니다.
  • "LoRA rank exceeds maximum"
    • adapter_config.json의 r 값이 max_lora_rank 설정을 초과하지 않는지 확인합니다.

디버깅 팁 (Debugging Tips)

  • 디버그 로깅을 활성화합니다:
export VLLM_LOGGING_LEVEL=DEBUG
  • 환경 변수를 확인합니다:
echo $VLLM_ALLOW_RUNTIME_LORA_UPDATING
echo $VLLM_PLUGINS
echo $VLLM_LORA_RESOLVER_CACHE_DIR
  • 어댑터 구성을 테스트합니다:
python -c "
import json
with open('/path/to/lora/adapters/my_adapter/adapter_config.json') as f:
    config = json.load(f)
print('Config valid:', config)
"

더 알아보기 (Learn more)