构建与微调 Agent

与 Weaver 的关系

NexAU 负责定义和运行 Agent，NexRL 负责把 Agent 轨迹组织成 RL 训练数据，Weaver 负责远端模型训练和权重同步。三者可以一起使用，也可以替换其中任意一层。

NexAU 是什么?

NexAU 是面向工具调用 LLM Agent 的框架。它支持用 YAML 声明 Agent、配置工具、选择 LLM backend、接入 tracing，并把运行轨迹交给训练框架使用。

典型用途：

• Web research、news search、SQL agent 等工具调用任务。
• 多轮推理和长上下文任务。
• 需要把 Agent 行为轨迹转成 RL signal 的训练任务。

构建一个 Web Research Agent

下面是一个简化版 deep research Agent 配置：

type: agent
name: deep_research_agent
max_context_tokens: 100000

system_prompt: |
  Date: {{date}}
  You are a research agent. Search for information using web_search and web_read.

system_prompt_type: jinja
tool_call_mode: openai

llm_config:
  temperature: 0.7
  max_tokens: 4096
  api_type: openai_chat_completion

tools:
  - name: web_search
    yaml_path: ./tools/WebSearch.yaml
    binding: nexau.archs.tool.builtin.web_tool:web_search
  - name: web_read
    yaml_path: ./tools/WebRead.yaml
    binding: nexau.archs.tool.builtin.web_tool:web_read

运行：

from datetime import datetime
import os

from nexau import Agent, AgentConfig, LLMConfig


agent_config = AgentConfig.from_yaml("deep_research_agent.yaml")
agent_config.llm_config = LLMConfig(
    model=os.getenv("LLM_MODEL"),
    base_url=os.getenv("LLM_BASE_URL"),
    api_key=os.getenv("LLM_API_KEY"),
)

agent = Agent(agent_config)
response = agent.run(
    "What are the latest developments in quantum computing?",
    context={"date": datetime.now().strftime("%Y-%m-%d")},
)
print(response)

接入 NexRL 训练

为了让 NexRL 读取 Agent 配置、运行 Agent、收集轨迹并计算 reward，建议按 workspace 组织任务文件：

recipe/my_task/agent_workspace/
├── agent_config.yaml
├── evaluator.py
├── custom_worker.py
└── tools/

文件	作用
agent_config.yaml	NexAU Agent 定义。
evaluator.py	reward 计算和答案判定。
custom_worker.py	可选，自定义数据格式、prompt 或轨迹转换。
tools/	自定义工具定义和实现。

为 RL 打开 Tracing

NexRL 需要从 Agent 运行中拿到 token、工具调用和响应轨迹。Agent 配置里通常需要启用 tracing：

llm_config:
  temperature: 0.7
  max_tokens: 8192
  api_type: openai_chat_completion

  logprobs: true
  extra_body:
    train_mode: true
    include_stop_str_in_output: true
    skip_special_tokens: false
    return_tokens_as_token_ids: true

tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer

这些设置让 rollout 结果可以转成 Weaver 训练所需的 token、old logprobs、mask 和 reward/advantage。

在 NexRL Recipe 中引用 Agent

rollout_worker:
  type: "nexau"
  nexau_agent_config_path: "recipe/my_task/agent_workspace/agent_config.yaml"
  evaluator_module_path: "recipe/my_task/agent_workspace/evaluator.py:MyEvaluator"
  nexau_agent_workspace: "recipe/my_task/agent_workspace"
  task_name: "my_task"

service:
  train_service:
    backend: weaver

现有 Weaver + NexAU 示例：

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

Evaluator 示例

Evaluator 把 Agent 运行结果转换成 reward。具体接口以 NexRL 当前版本为准，常见形态如下：

from typing import Any

from nexrl.rollout_worker import EvaluationRunResult, Evaluator, NexAUEvaluationTarget


class MyEvaluator(Evaluator):
    def evaluate(
        self,
        data: Any,
        evaluation_target: NexAUEvaluationTarget,
    ) -> EvaluationRunResult:
        response = evaluation_target.response
        expected = data.get("answer", "")
        reward = 1.0 if expected and expected in response else 0.0

        return EvaluationRunResult(
            reward=reward,
            extra_info={
                "expected": expected,
                "response": response,
            },
        )

训练流程

nexrl -m training-service \
  -c recipe/nexau_deepsearch/weaver.yaml \
  --run-nexrl \
  --tag deepsearch-weaver-v1

训练期间：

1. NexAU 执行任务并生成工具调用轨迹。
2. Evaluator 为轨迹打 reward。
3. NexRL 聚合 trajectories，计算 advantage。
4. NexRL Trainer 调用 Weaver 的 forward_backward() 和 optim_step()。
5. Weaver 导出 sampler 权重，NexRL 同步到 rollout 服务继续采样。

实践建议

• 先用少量任务验证 Agent 配置、工具 schema 和 evaluator。
• reward 尽量从可验证信号开始，例如 exact match、unit test、SQL execution 或网页检索命中。
• 对长上下文 Agent 控制 max response length，避免 rollout 成本不可控。
• 训练早期保留调试日志和轨迹样本，重点检查 mask、reward 和 old logprobs 是否对齐。
• 长实验配合 Weaver checkpoint，避免只依赖短期 sampler 权重。

下一步

• 微调模型：理解 NexRL recipe、RolloutWorker 和 Trainer。
• 损失函数：查看 RL loss 的输入字段。
• 训练与采样：直接使用 Weaver SDK 构建自定义流程。