LLaMA-Factory 插件开发指南，扩展你的微调能力

2600_96323174

2人浏览 · 2026-06-29 11:31:00

2600_96323174 · 2026-06-29 11:31:00 发布

为什么你需要为 LLaMA-Factory 写插件？

在大模型微调的实战中，我们常会遇到一种尴尬：手里的数据格式独特，或者想验证一个冷门的评估指标，但现有的开源框架似乎总差那么“最后一公里”。很多人第一反应是去改框架的核心源码，但这不仅风险大，还容易在后续更新中丢失自己的修改。其实，LLaMA-Factory 早就为我们预留了优雅的扩展接口——插件机制。

作为一个在 ROCm 生态里摸爬滚打过的开发者，我深刻体会到，好的工具链不应该是个黑盒。LLaMA-Factory 的模块化设计非常出色，它允许我们在不触碰主逻辑的前提下，像搭积木一样注入新功能。这不仅降低了开发门槛，更让社区贡献变得简单可行。今天，我就结合自己在 AMD GPU 上的实践，聊聊如何动手写一个轻量级插件，让你的微调流程真正“量身定制”。

拆解插件机制：从注册到加载

在动手之前，得先搞清楚 LLaMA-Factory 是怎么识别插件的。它的核心逻辑基于 Python 的动态导入和注册表模式。框架启动时，会扫描特定的配置项或目录，寻找用户定义的类或函数，并将其挂载到预定的钩子（Hook）上。

对于想要定制数据集或评估流程的开发者来说，最关键的两个入口通常是 DatasetLoader 和 Evaluator。你不需要重新实现整个训练循环，只需关注数据如何被读取，或者结果如何被计算。这种设计思路与 ROCm 生态中其他工具（如 vLLM 的后端抽象）异曲同工，都是为了让上层应用与底层硬件解耦。

在代码结构上，LLaMA-Factory 通常支持通过配置文件指定插件路径，或者在代码中直接注册。推荐的做法是建立一个独立的 plugins 目录，将你的扩展代码与官方源码物理隔离。这样即使框架升级，只要接口不变，你的插件就能无缝复用。

实战演练：自定义数据集格式支持

假设你手头有一份特殊的 JSONL 数据，其中包含嵌套的对话历史和额外的元数据标签，标准加载器无法直接解析。这时候，编写一个自定义 Dataset 插件就派上用场了。

首先，我们需要定义一个继承自基类的加载器。以下是一个简化的代码骨架，展示了如何处理非标准格式：

from typing import List, Dict, Any
from llamafactory.data import BaseDatasetLoader

class CustomJsonlLoader(BaseDatasetLoader):
    def __init__(self, path: str, **kwargs):
        super().__init__(path, **kwargs)
        # 初始化特定参数，例如元数据过滤规则
        self.filter_tags = kwargs.get("filter_tags", [])

    def load_data(self) -> List[Dict[str, Any]]:
        data = []
        with open(self.path, "r", encoding="utf-8") as f:
            for line in f:
                item = json.loads(line)
                # 自定义解析逻辑：提取嵌套字段
                messages = item.get("conversation", {}).get("history", [])
                metadata = item.get("meta", {})
                
                # 应用过滤逻辑
                if self.filter_tags and metadata.get("tag") not in self.filter_tags:
                    continue
                
                data.append({
                    "messages": messages,
                    "system": metadata.get("system_prompt", "")
                })
        return data

这段代码的核心在于 load_data 方法。你完全可以根据自己的数据结构调整解析逻辑，比如处理多轮对话的特殊分隔符，或者清洗特定的噪声字段。

接下来是注册环节。在你的项目入口脚本或配置文件中，需要将这个类告知框架。如果是通过配置方式，通常在 YAML 文件中添加类似如下内容：

dataset_loader:
  name: custom_jsonl
  class_path: plugins.custom_loader.CustomJsonlLoader
  args:
    filter_tags: ["tech", "coding"]

如果是代码式注册，则可能在初始化 Trainer 前调用注册函数。一旦注册成功，LLaMA-Factory 在读取数据时就会自动调用你的 CustomJsonlLoader，而无需修改任何核心代码。我在 MI300X 上测试过这种模式，加载效率与原生支持的数据集几乎没有差别，且能充分利用 ROCm 优化的数据管道。

扩展评估指标：不仅仅是 Loss

除了数据输入，输出端的评估同样重要。默认的评估指标往往只有 Loss 和 Perplexity，但在实际业务中，我们可能更关心回复的准确性、安全性或是特定领域的得分。

编写自定义评估插件的思路与数据集类似。你需要实现一个评估函数，接收模型生成的文本和参考文本，返回计算后的分数。

from llamafactory.eval import BaseEvaluator

class KeywordMatchEvaluator(BaseEvaluator):
    def evaluate(self, predictions: List[str], references: List[str]) -> float:
        match_count = 0
        total_keywords = 0
        
        for pred, ref in zip(predictions, references):
            # 假设参考文本中包含必须出现的关键字列表
            keywords = ref.split("|")[1:] 
            total_keywords += len(keywords)
            
            for kw in keywords:
                if kw.strip() in pred:
                    match_count += 1
                    
        return match_count / total_keywords if total_keywords > 0 else 0.0