LoRA 解析器插件¶

此目录包含基于 LoRAResolver 框架构建的 vLLM LoRA 解析器插件。它们可以自动发现并加载来自指定本地存储路径的 LoRA 适配器，无需手动配置或重启服务器。

概述¶

LoRA 解析器插件提供了一种在运行时动态加载 LoRA 适配器的灵活方式。当 vLLM 收到对尚未加载的 LoRA 适配器的请求时，解析器插件将尝试从其配置的存储位置查找并加载该适配器。这实现了

动态 LoRA 加载：按需加载适配器，无需重启服务器
多存储后端：支持文件系统、S3 和自定义后端。内置的 lora_filesystem_resolver 需要一个本地存储路径，而内置的 hf_hub_resolver 将从 Hugging Face Hub 拉取 LoRA 适配器，并以相同的方式处理。通常，可以实现自定义解析器以从任何来源获取数据。
自动发现：与现有的 LoRA 工作流程无缝集成
可扩展部署：跨多个 vLLM 实例的集中式适配器管理

先决条件¶

在使用 LoRA 解析器插件之前，请确保已配置以下环境变量

必需的环境变量¶

VLLM_ALLOW_RUNTIME_LORA_UPDATING：必须设置为 true 或 1 以启用动态 LoRA 加载
```
export VLLM_ALLOW_RUNTIME_LORA_UPDATING=true
```
VLLM_PLUGINS：必须包含所需的解析器插件（逗号分隔列表）
```
export VLLM_PLUGINS=lora_filesystem_resolver
```
VLLM_LORA_RESOLVER_CACHE_DIR：对于文件系统解析器，必须设置为有效的目录路径
```
export VLLM_LORA_RESOLVER_CACHE_DIR=/path/to/lora/adapters
```

可选的环境变量¶

VLLM_PLUGINS：如果未设置，将加载所有可用插件。如果设置为空字符串，则不会加载任何插件。

可用解析器¶

lora_filesystem_resolver¶

文件系统解析器随 vLLM 默认安装，支持从本地目录结构加载 LoRA 适配器。

设置步骤¶

创建 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 token，例如 export HF_TOKEN=xxx235。
```
python -m vllm.entrypoints.openai.api_server \
    --model your-base-model \
    --enable-lora
```

目录结构要求¶

文件系统解析器要求 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 适配器权重文件

使用示例¶

准备您的 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 https://: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
    }'

工作原理¶

当 vLLM 收到针对名为 my_sql_adapter 的 LoRA 适配器的请求时
文件系统解析器会检查 /path/to/lora/adapters/my_sql_adapter/ 是否存在
如果找到，它将验证 adapter_config.json 文件
如果配置与基础模型匹配且有效，则加载适配器
使用新加载的适配器正常处理请求
适配器将保留以供后续请求使用

高级配置¶

多解析器支持¶

您可以配置多个解析器插件，以从不同来源加载适配器

'lora_s3_resolver' 是一个您可能需要实现的自定义解析器示例

export VLLM_PLUGINS=lora_filesystem_resolver,lora_s3_resolver

所有列出的解析器均被启用；在请求时，vLLM 会按顺序尝试它们，直到其中一个成功。

自定义解析器实现¶

要实现您自己的解析器插件

创建一个新的解析器类:

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)

故障排除¶

常见问题¶

"VLLM_LORA_RESOLVER_CACHE_DIR 必须设置为有效目录"
确保目录存在且可访问
检查目录的文件权限
"未找到 LoRA 适配器"
验证适配器目录名称是否与请求的模型名称匹配
检查 adapter_config.json 是否存在且为有效的 JSON
确保 adapter_model.bin 存在于目录中
"无效的适配器配置"
验证 peft_type 是否设置为 "LORA"
检查 base_model_name_or_path 是否与您的基础模型匹配
确保 target_modules 配置正确
"LoRA 等级 (rank) 超过最大值"
检查 adapter_config.json 中的 r 值是否未超过 max_lora_rank 设置

调试技巧¶

启用调试日志:
```
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)
"