解决Olive项目中ONNX适配器转换后的形状错误问题

问题背景

在使用微软Olive项目进行大语言模型适配时，开发者可能会遇到一个典型的形状错误问题。具体表现为：在完成适配器转换后运行模型时，系统提示输入维度不匹配的错误，特别是在处理自注意力机制中的投影层权重时。

错误现象

当尝试加载并运行转换后的适配器时，系统会抛出如下错误信息：

Got invalid dimensions for input: model.layers.25.self_attn.v_proj.lora_B.weight
index: 1 Got: 4096 Expected: 1024

这个错误表明，在模型第25层的自注意力机制中，值投影层(V_proj)的LoRA适配器权重B的维度与预期不符。系统期望的是1024维，但实际得到的是4096维。

问题根源

经过分析，这个问题通常由以下两种情况引起：

1. 模型路径混淆：在转换适配器时使用了与基础模型不匹配的模型路径，导致适配器权重与模型结构不兼容。

2. 缓存污染：之前的转换过程可能留下了不完整的缓存文件，这些残留文件影响了后续的转换过程。

解决方案

要彻底解决这个问题，可以按照以下步骤操作：

1. 清理工作目录：删除所有之前生成的模型文件和缓存文件夹，确保从一个干净的环境开始。

2. 统一模型路径：确保在capture-onnx-graph、generate-adapter和convert-adapters三个步骤中使用完全一致的模型路径。

3. 完整转换流程：

   # 1. 捕获ONNX图
   olive capture-onnx-graph -m meta-llama/Llama-2-7b-chat-hf \
     --adapter_path wsvn53/Llama-2-7b-chat-lora-tricky_math \
     -o models/Llama-2-7b-chat-LoRA \
     --torch_dtype float32 \
     --use_ort_genai
   
   # 2. 生成适配器
   olive generate-adapter -m models/Llama-2-7b-chat-LoRA/model \
     -o models/Llama-2-7b-chat-LoRA/adapted \
     --log_level 1
   
   # 3. 转换适配器
   olive convert-adapters \
     --adapter_path wsvn53/Llama-2-7b-chat-lora-tricky_math \
     --output_path adapters/Llama-2-7b-chat-lora-tricky_math.onnx_adapter \
     --dtype float32
   

技术要点

1. 维度一致性检查：在转换适配器时，系统会验证LoRA权重矩阵的维度是否与基础模型的对应层匹配。特别是对于自注意力机制中的Q/K/V投影层，需要确保LoRA的A/B矩阵的维度正确。

2. 缓存管理：Olive在转换过程中会生成中间缓存文件，这些文件如果损坏或不完整，可能导致后续步骤出现维度不匹配的问题。

3. 路径规范：建议使用绝对路径或确保相对路径的一致性，避免因路径问题导致的模型加载错误。

最佳实践

1. 每次开始新的转换前，清理工作目录中的旧文件和缓存。

2. 使用版本控制工具跟踪模型和适配器的版本，确保一致性。

3. 在转换完成后，先进行小规模测试验证适配器是否能正常工作。

4. 对于大型模型转换，建议分阶段进行并记录每个阶段的输出日志。

通过遵循这些步骤和最佳实践，开发者可以有效地避免适配器转换后的形状维度错误问题，确保模型能够正确加载和运行。