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)
"