LoRA 解析器插件¶

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

概述¶

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

动态 LoRA 加载：按需加载适配器，无需重启服务器
多个存储后端：支持文件系统、S3 和自定义后端。内置的 lora_filesystem_resolver 需要本地存储路径，但可以实现自定义解析器以从任何源获取。
自动发现：与现有 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。请确保在您的环境变量 export HF_TOKEN=xxx235 中设置 Hugging Face token。
```
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 秩超出最大值"
检查 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)
"