LoRA 리졸버 플러그인

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

이 문서는 vLLM의 LoRA 리졸버 플러그인을 소개해요. 이 플러그인들은 LoRAResolver 프레임워크 위에 구축되어, 지정된 로컬 스토리지 경로에서 LoRA 어댑터를 자동으로 발견하고 로드해요. 덕분에 수동 설정이나 서버 재시작이 필요 없어져요.

출처: vLLM 공식 문서 — lora_resolver_plugins

개요 (Overview)

LoRA 리졸버 플러그인은 런타임에 LoRA 어댑터를 동적으로 로드할 수 있는 유연한 방법을 제공해요. vLLM이 아직 로드되지 않은 LoRA 어댑터에 대한 요청을 받으면, 리졸버 플러그인이 설정된 스토리지 위치에서 그 어댑터를 찾아 로드하려고 시도해요. 이를 통해 가능해지는 것들이에요.

동적 LoRA 로딩: 서버 재시작 없이 필요할 때 어댑터를 로드해요.
여러 스토리지 백엔드: 파일시스템, S3, 그리고 커스텀 백엔드를 지원해요. 기본 내장된 lora_filesystem_resolver는 로컬 스토리지 경로가 필요하고, 또 다른 내장 resolver인 hf_hub_resolver는 Huggingface Hub에서 LoRA 어댑터를 가져와 동일한 방식으로 진행해요. 일반적으로 커스텀 resolver를 구현하면 어떤 소스에서든 어댑터를 가져올 수 있어요.
자동 발견: 기존 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: 파일시스템 resolver를 위해 유효한 디렉토리 경로로 설정해야 해요.
```
export VLLM_LORA_RESOLVER_CACHE_DIR=/path/to/lora/adapters
```

선택 환경변수 (Optional Environment Variables)

VLLM_PLUGINS: 설정하지 않으면 사용 가능한 모든 플러그인이 로드돼요. 빈 문자열로 설정하면 아무 플러그인도 로드되지 않아요.

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

lora_filesystem_resolver

파일시스템 resolver는 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를 쓸 수 있어요. 환경변수 export HF_TOKEN=xxx235로 Hugging Face 토큰을 설정했는지 확인하세요.
```
vllm serve your-base-model \
    --enable-lora
```

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

파일시스템 resolver는 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 어댑터에 대한 요청을 받아요.
파일시스템 resolver가 /path/to/lora/adapters/my_sql_adapter/가 존재하는지 확인해요.
존재하면 adapter_config.json 파일을 검증해요.
설정이 기본 모델과 일치하고 유효하면 어댑터를 로드해요.
새로 로드된 어댑터로 요청이 정상 처리돼요.
어댑터는 이후 요청을 위해 계속 사용 가능하게 남아 있어요.

고급 설정 (Advanced Configuration)

여러 리졸버 (Multiple Resolvers)

다른 소스에서 어댑터를 로드하도록 리졸버 플러그인을 여러 개 구성할 수 있어요.

'lora_s3_resolver'는 직접 구현해야 하는 커스텀 resolver의 예시예요.

export VLLM_PLUGINS=lora_filesystem_resolver,lora_s3_resolver

나열된 모든 리졸버가 활성화되고, 요청 시점에 vLLM은 순서대로 시도하다가 하나가 성공하면 멈춰요.

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

자체 리졸버 플러그인을 구현하려면:

새 resolver 클래스를 만들어요:

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

resolver를 등록해요:

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)

LoRA 어댑터 — LoRA 어댑터의 기본 사용법
Plugin System — vLLM 플러그인 시스템 전반