# RuntimeError: 检查点中未找到 PEFT 适配器 'my_adapter'。可用适配器：['base', 'lora_v1']

- **ID:** `huggingface/peft-adapter-not-found-in-checkpoint`
- **领域:** huggingface
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 92%

## 根因

请求的 PEFT 适配器名称与检查点目录或合并模型中存储的任何适配器不匹配。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| huggingface/peft 0.9.0 | active | — | — |
| huggingface/peft 0.10.0 | active | — | — |
| huggingface/transformers 4.38.0 | active | — | — |

## 解决方案

1. ```
   List available adapters and load the correct one: `model.load_adapter('lora_v1')` or `PeftModel.from_pretrained(model, 'path/to/checkpoint', adapter_name='lora_v1')`
   ```
2. ```
   If loading a single adapter, use `PeftModel.from_pretrained(model, 'path/to/checkpoint')` without specifying adapter_name, which defaults to 'default'.
   ```

## 无效尝试

- **Rename the adapter folder to 'my_adapter' manually** — PEFT uses internal metadata to track adapter names; renaming the folder without updating the metadata file (adapter_config.json) causes a mismatch. (80% 失败率)
- **Set `load_in_8bit=True` to bypass adapter loading** — Loading in 8-bit doesn't skip adapter loading; it still tries to find the adapter and fails with the same error. (90% 失败率)