微调模型

框架无关

Weaver 本身是框架无关的训练 API。你可以直接用 SDK 写训练循环，也可以接入 NexRL、verl 或自定义 RL 框架。NexRL 是 Nex-AGI 生态中与 Weaver 集成最深的参考实现，本页以 NexRL 为主线。

NexRL 是什么?

NexRL 是面向大语言模型 post-training 的分布式 RL 框架。它负责组织数据、rollout、reward、轨迹池和训练算法；Weaver 作为 training-service 后端，负责实际的远端训练、权重保存和 sampler 权重同步。

在 Weaver 模式下，一个典型链路是：

DataLoader -> RolloutWorker -> TrajectoryPool -> Trainer -> Weaver Training API
                    |                                      |
                    v                                      v
                 Rewards                         Updated / Exported Weights

核心组件

组件	作用
DataLoader	提供 prompts、questions、环境状态或任务样本。
RolloutWorker	调用模型或 Agent 生成轨迹，并计算 reward。
TrajectoryPool	收集、分组和批量化 trajectories。
Trainer	实现 GRPO、PPO、SFT 或自定义算法，并调用 Weaver API。
WeightSyncController	在训练和推理/rollout 服务之间同步更新后的权重。

通常你主要自定义两部分：

• RolloutWorker：如何从任务生成轨迹、提取答案、计算 reward。
• Trainer：如何从轨迹计算 advantage，并选择 Weaver loss。

安装 NexRL

git clone git@github.com:nex-agi/NexRL.git
cd NexRL

# 完整安装，包含训练相关依赖
pip install -e ".[core]"

# 或仅安装轻量 CLI 和配置提交能力
pip install -e .

配置 Weaver API key：

export WEAVER_API_KEY=<your-api-key>

运行 Weaver Recipe

NexRL 使用 recipe 组织训练任务。一个 recipe 通常包含：

• 训练配置 YAML。
• 可选环境初始化脚本。
• 数据路径、rollout worker、trainer、service backend 和日志配置。

以 Pig Latin 为例：

nexrl -m training-service \
  -c recipe/pig_latin/weaver.yaml \
  --run-nexrl \
  --tag pig-latin-v1

也可以使用脚本入口：

python scripts/run.py \
  --mode training-service \
  --train-config recipe/pig_latin/weaver.yaml \
  --run-nexrl \
  --tag pig-latin-v1

常用参数：

参数	说明
-m / --mode	运行模式；Weaver 通常使用 training-service。
-c / --train-config	recipe YAML 路径。
--run-nexrl	资源启动后自动开始训练。
--tag	实验标签，便于区分多次运行。

Recipe 示例

SFT: Pig Latin

位置：NexRL/recipe/pig_latin/weaver.yaml

这个示例演示如何通过 NexRL 调用 Weaver 做监督微调：

rollout_worker:
  type: "pig_latin"
  need_llm_inference: false

trainer:
  type: "remote_api_cross_entropy"

service:
  train_service:
    backend: weaver
    config:
      loss_fn: "cross_entropy"
      learning_rate: 1e-4

特点：

• rollout worker 直接使用 ground-truth label，不需要模型推理。
• trainer 把样本转换成 cross_entropy 所需的 target_tokens 和 weights。
• Weaver 负责 LoRA 或 full fine-tuning 的远端训练。

Full Fine-Tuning: Math

位置：NexRL/recipe/math/weaver_full_ft.yaml

该 recipe 展示 Weaver full fine-tuning 模式。适合 LoRA 容量不足、需要更深行为迁移或长期训练的任务。

关键配置通常包含：

service:
  weaver_service:
    training_mode: "full_ft"

  train_service:
    backend: weaver

Agent Training: NexAU

位置：

• NexRL/recipe/nexau_deepsearch/weaver.yaml
• NexRL/recipe/nexau_news/weaver.yaml

这些 recipe 展示如何把 NexAU Agent 的多轮工具调用轨迹接入 NexRL，再通过 Weaver 更新模型。

自定义 RolloutWorker

RolloutWorker 负责把输入任务变成可训练轨迹。一个简化示例：

from nexrl.rollout_worker import BaseRolloutWorker
from nexrl.nexrl_types import Trajectory


class MyTaskWorker(BaseRolloutWorker):
    def rollout(self, task: dict) -> str | None:
        prompt = task["prompt"]
        answer = task.get("answer", "")

        completion = self._inference_client.completion(prompt)
        prompt_tokens = completion["prompt_tokens"]
        response_tokens = completion["response_tokens"]
        response = completion["response"]

        reward = 1.0 if self._extract_answer(response) == answer else 0.0

        trajectory = Trajectory(
            tokens=prompt_tokens + response_tokens,
            loss_mask=[0] * len(prompt_tokens) + [1] * len(response_tokens),
            reward=reward,
            extra_fields={
                "response": response,
                "answer": answer,
            },
        )
        return self._put_trajectory(trajectory)

在 recipe 中引用：

rollout_worker:
  type: "custom"
  custom_rollout_worker_module_path: "recipe/my_task/rollout_worker.py"
  custom_rollout_worker_class_name: "MyTaskWorker"

自定义 Trainer

Trainer 负责把 trajectories 转成 Weaver 可训练的 Datum，并选择 loss。你可以继承 NexRL 的 remote API trainer，在 _prepare_trajectories() 中实现 advantage 计算：

from nexrl.trainer import RemoteApiTrainer


class MyAlgorithmTrainer(RemoteApiTrainer):
    def _prepare_trajectories(self, trajectories, metrics):
        for traj in trajectories:
            traj.advantage = traj.reward
        return trajectories

在 recipe 中引用：

trainer:
  type: "custom"
  custom_trainer_module_path: "recipe/my_task/trainer.py"
  custom_trainer_class_name: "MyAlgorithmTrainer"

Weaver 集成要点

• SFT 通常使用 remote_api_cross_entropy 和 loss_fn: "cross_entropy"。
• RL 通常使用 importance_sampling、ppo_clip、grpo 或 OPD 相关 loss。
• 使用 Weaver 做 full fine-tuning 时，在 recipe 的 Weaver service 配置中设置 training_mode: "full_ft"。
• rollout 阶段需要频繁同步权重时，优先使用 sampler 权重导出和 TTL，而不是永久 checkpoint。
• 长实验建议定期 save_state(checkpoint_type="weight_and_optimizer")，以便恢复 optimizer 状态。

下一步

• 构建与微调 Agent：用 NexAU 定义工具调用 Agent。
• 损失函数：了解 Weaver loss 输入约定。
• 保存与加载：规划 checkpoint 和 sampler 权重生命周期。