1. 从一次 Agentic RL 训练卡死说起如果你正在用 verl 跑多轮 Agent 任务大概率遇到过这种场景rollout 阶段 GPU 利用率忽高忽低训练日志里response_mask长度对不上或者 PPO loss 里混进了工具返回的 token导致模型开始“背诵”环境输出而不是学决策。Uni-Agent 这套框架之所以值得拆就是因为它把“Agent 怎么和环境交互并产出 token-level 训练数据”这件事从零散补丁变成了可复用的工程骨架。这篇聚焦三个东西ReAct 执行范式、verl 训练框架、rollout_cache 增量状态载体。目标很明确——给你一份能直接抄的config.toml/settings.json配置骨架跑通一次调用验证再顺手把接入通道统一到 TaoToken 的 Key/API 上省得每个模型后端都维护一套鉴权。适合谁已经在跑 verl、想上多轮 Agent 的算法工程师以及想理解 Agentic RL 数据流长什么样的后端同学。我试过把 rollout_cache 的 mask 逻辑单独抽出来做单元测试发现只要边界 token 探测错一个整个 trajectory 的 loss 就废了。所以下面会重点讲配置和验证而不是泛泛谈架构。2. TaoToken 前置统一 Key/API 通道在讲配置之前先把调用通道理清楚。Uni-Agent 的推理侧走的是OpenAICompatibleChatModel也就是说它需要一个 OpenAI 兼容的base_url和api_key。TaoToken 提供的正是这个统一入口——你不用为每个模型单独申请 Key也不用在训练脚本里塞一堆环境变量。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意这个不带 UTM直接填进配置即可。你需要做的只有两步在控制台生成一个 API Key然后把它写进settings.json的api_key字段。模型对话验证可以走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentmodel_chat 长期跑编码/Agent 任务建议看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentcoding_plan 。Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdoc 。注意不要把 Key 硬编码进config.toml提交到仓库。用环境变量注入下面配置里我会用${TAOTOKEN_API_KEY}占位。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文最干的部分。Uni-Agent 的配置分两层verl 侧的 Hydra 配置config.toml风格和 Agent 侧的settings.json。两者通过agent_loop_config_path桥接。3.1 verl 侧 config.toml[rollout] mode async n_resp_per_prompt 8 [rollout.agent] num_workers 8 agent_loop_config_path configs/uni_agent_loop.yaml default_agent_loop uni_agent [rollout.multi_turn] enable true max_parallel_calls 1 max_user_turns 1 max_assistant_turns 12 [async_training] staleness_threshold 0.5 partial_rollout true trigger_parameter_sync_step 4 require_batches 2 [actor_rollout_ref.actor] clip_ratio 4e-4几个关键点解释一下。rollout.multi_turn.enable true是硬前置Uni-Agent 的UniAgentLoop依赖它才会被调度。max_parallel_calls 1和当前 Uni-Agent 的硬编码一致别乱改。staleness_threshold 0.5配合trigger_parameter_sync_step 4意味着参数最多滞后 4 步、样本最多滞后 1.5 倍这是 Fully Async 模式下控制 off-policy 偏差的第一层防御。3.2 Agent 侧 uni_agent_loop.yaml- name: uni_agent target: uni_agent.agent_loop.UniAgentLoop max_turns: 12 max_model_len: 32768 tools: - execute_bash - str_replace_editor - search - finish env: deployment: type: local timeout: 300 reward: type: swebench fail_to_pass_only: truetarget这一行是 verl 发现 Uni-Agent 的桥梁——hydra.utils.instantiate会动态创建UniAgentLoop实例完全不需要register()装饰器。这就是“零代码级耦合”的落地方式。3.3 settings.json模型后端与 TaoToken 接入{ model: { backend: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_name: claude-sonnet-4, max_tokens: 4096, temperature: 0.7 }, rollout_cache: { enable_boundary_probe: true, mask_abnormal_exit_traj: true, max_prompt_length: 8192, max_response_length: 24576 }, logging: { log_tool_timing: true, log_query_timing: true } }enable_boundary_probe打开后message_boundary_tokens的差分探测会在初始化时跑一次把|im_end|这类胶水 token 缓存下来。mask_abnormal_exit_traj决定异常退出的 trajectory 是否全 mask 掉——环境崩溃和超时建议 mask格式错误建议保留让模型学会正确格式。4. 验证请求从一次调用到 mask 对齐配置写完先别急着上大规模训练。用最小代价验证三件事模型能通、rollout_cache 能累积、mask 能对齐。4.1 模型连通性验证export TAOTOKEN_API_KEYsk-你的key curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 16 }返回里能看到choices[0].message.content就说明通道通了。这一步别跳过很多“训练卡住”其实是 Key 或 base_url 写错。4.2 rollout_cache 增量验证写一个最小脚本模拟 QUERY → APPEND 一轮打印 mask 长度import asyncio from uni_agent.model import AgentChatModel async def probe(): model AgentChatModel( clientNone, # 推理侧用 OpenAICompatibleChatModel tokenizertokenizer, max_model_len32768, sampling_params{temperature: 0.7}, ) cache await model.prepare_rollout_cache([ {role: user, content: 列出当前目录} ]) print(初始 prompt_ids:, len(cache[prompt_ids])) print(初始 mask:, len(cache[response_mask])) # 应为 0 # 模拟一次 QUERY cache[prompt_ids] [101, 102, 103] cache[response_mask] [1, 1, 1] cache[response_logprobs] [0.1, 0.2, 0.3] # 模拟一次 APPEND工具返回 cache[prompt_ids] [201, 202] cache[response_mask] [0, 0] cache[response_logprobs] [0.0, 0.0] assert len(cache[prompt_ids]) len(cache[response_mask]) assert len(cache[response_mask]) len(cache[response_logprobs]) print(对齐校验通过mask 分布:, cache[response_mask]) asyncio.run(probe())跑通后你会看到 mask 是[1,1,1,0,0]——模型生成的 3 个 token 参与 loss工具返回的 2 个 token 不参与。这就是 rollout_cache 最核心的不变量。4.3 成功结果长什么样一次完整的UniAgentLoop.run()结束后convert_to_agent_output()会产出AgentLoopOutput里面response_mask的长度应该等于response_ids的长度且extra_fields[traj_exit_reason]是finished。如果看到traj_maskedTrue说明这条轨迹被异常退出逻辑 mask 掉了需要去查exit_reason。5. 本篇常见错排查5.1 mask 长度对不上最常见的原因是message_boundary_tokens探测失败。表现是len(prompt_ids) ! len(response_mask)。排查方法打印_get_new_message_ids()的返回值看边界 token 是否为空。如果为空说明差分对比法在你的 tokenizer 上没找到 EOS 之后的部分——检查apply_chat_template是否带了add_generation_promptTrue。5.2 工具返回混进 loss如果发现 PPO loss 异常高且response_mask里工具返回位置是 1 而不是 0检查append_messages_to_rollout_cache的断言是否被绕过。Uni-Agent 只允许追加user和tool角色其他角色会直接 assert 失败。5.3 Fully Async 下 staleness 爆表日志里如果出现staleness_samples max_required_samples频繁触发 pause说明trigger_parameter_sync_step设太大了。把它从 4 降到 2或者把staleness_threshold从 0.5 降到 0.3。代价是 GPU 利用率会降一点但 off-policy 偏差可控。5.4 TaoToken 调用 401先确认base_url是https://taotoken.net/api而不是带/v1的完整路径——OpenAI 兼容客户端会自动拼/v1/chat/completions。如果还是 401去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 重新生成一个 Key确认没有多余空格。5.5 环境启动超时env.start()卡住通常是 deployment 配置问题。本地调试用type: local容器测试用type: docker生产再切modal或vefaas。从本地到生产只改 YAML 一行但别在本地用生产后端超时时间对不上。6. 接入通道与后续动作配置骨架和验证动作都跑通之后下一步就是把调用通道固定下来。排障和接入相关的文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdoc Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 。如果你要长期跑编码类 Agent 任务Coding Plan 的额度模型比按次调用更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentcoding_plan 。模型对话快速验证走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentmodel_chat 。最后留一个实操建议把rollout_cache的四个不变量写成 pytest 断言每次改配置后跑一遍。我踩过的坑是改了max_response_length之后忘了同步max_model_len结果 QUERY 阶段直接抛MaxTokenExceededError整批 rollout 报废。断言比日志快。
Uni-Agent 深度技术分析（2）：关键技术拆解——从 verl 到 rollout_cache 的 Agentic RL 配置骨架
1. 从一次 Agentic RL 训练卡死说起如果你正在用 verl 跑多轮 Agent 任务大概率遇到过这种场景rollout 阶段 GPU 利用率忽高忽低训练日志里response_mask长度对不上或者 PPO loss 里混进了工具返回的 token导致模型开始“背诵”环境输出而不是学决策。Uni-Agent 这套框架之所以值得拆就是因为它把“Agent 怎么和环境交互并产出 token-level 训练数据”这件事从零散补丁变成了可复用的工程骨架。这篇聚焦三个东西ReAct 执行范式、verl 训练框架、rollout_cache 增量状态载体。目标很明确——给你一份能直接抄的config.toml/settings.json配置骨架跑通一次调用验证再顺手把接入通道统一到 TaoToken 的 Key/API 上省得每个模型后端都维护一套鉴权。适合谁已经在跑 verl、想上多轮 Agent 的算法工程师以及想理解 Agentic RL 数据流长什么样的后端同学。我试过把 rollout_cache 的 mask 逻辑单独抽出来做单元测试发现只要边界 token 探测错一个整个 trajectory 的 loss 就废了。所以下面会重点讲配置和验证而不是泛泛谈架构。2. TaoToken 前置统一 Key/API 通道在讲配置之前先把调用通道理清楚。Uni-Agent 的推理侧走的是OpenAICompatibleChatModel也就是说它需要一个 OpenAI 兼容的base_url和api_key。TaoToken 提供的正是这个统一入口——你不用为每个模型单独申请 Key也不用在训练脚本里塞一堆环境变量。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意这个不带 UTM直接填进配置即可。你需要做的只有两步在控制台生成一个 API Key然后把它写进settings.json的api_key字段。模型对话验证可以走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentmodel_chat 长期跑编码/Agent 任务建议看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentcoding_plan 。Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdoc 。注意不要把 Key 硬编码进config.toml提交到仓库。用环境变量注入下面配置里我会用${TAOTOKEN_API_KEY}占位。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文最干的部分。Uni-Agent 的配置分两层verl 侧的 Hydra 配置config.toml风格和 Agent 侧的settings.json。两者通过agent_loop_config_path桥接。3.1 verl 侧 config.toml[rollout] mode async n_resp_per_prompt 8 [rollout.agent] num_workers 8 agent_loop_config_path configs/uni_agent_loop.yaml default_agent_loop uni_agent [rollout.multi_turn] enable true max_parallel_calls 1 max_user_turns 1 max_assistant_turns 12 [async_training] staleness_threshold 0.5 partial_rollout true trigger_parameter_sync_step 4 require_batches 2 [actor_rollout_ref.actor] clip_ratio 4e-4几个关键点解释一下。rollout.multi_turn.enable true是硬前置Uni-Agent 的UniAgentLoop依赖它才会被调度。max_parallel_calls 1和当前 Uni-Agent 的硬编码一致别乱改。staleness_threshold 0.5配合trigger_parameter_sync_step 4意味着参数最多滞后 4 步、样本最多滞后 1.5 倍这是 Fully Async 模式下控制 off-policy 偏差的第一层防御。3.2 Agent 侧 uni_agent_loop.yaml- name: uni_agent target: uni_agent.agent_loop.UniAgentLoop max_turns: 12 max_model_len: 32768 tools: - execute_bash - str_replace_editor - search - finish env: deployment: type: local timeout: 300 reward: type: swebench fail_to_pass_only: truetarget这一行是 verl 发现 Uni-Agent 的桥梁——hydra.utils.instantiate会动态创建UniAgentLoop实例完全不需要register()装饰器。这就是“零代码级耦合”的落地方式。3.3 settings.json模型后端与 TaoToken 接入{ model: { backend: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_name: claude-sonnet-4, max_tokens: 4096, temperature: 0.7 }, rollout_cache: { enable_boundary_probe: true, mask_abnormal_exit_traj: true, max_prompt_length: 8192, max_response_length: 24576 }, logging: { log_tool_timing: true, log_query_timing: true } }enable_boundary_probe打开后message_boundary_tokens的差分探测会在初始化时跑一次把|im_end|这类胶水 token 缓存下来。mask_abnormal_exit_traj决定异常退出的 trajectory 是否全 mask 掉——环境崩溃和超时建议 mask格式错误建议保留让模型学会正确格式。4. 验证请求从一次调用到 mask 对齐配置写完先别急着上大规模训练。用最小代价验证三件事模型能通、rollout_cache 能累积、mask 能对齐。4.1 模型连通性验证export TAOTOKEN_API_KEYsk-你的key curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 16 }返回里能看到choices[0].message.content就说明通道通了。这一步别跳过很多“训练卡住”其实是 Key 或 base_url 写错。4.2 rollout_cache 增量验证写一个最小脚本模拟 QUERY → APPEND 一轮打印 mask 长度import asyncio from uni_agent.model import AgentChatModel async def probe(): model AgentChatModel( clientNone, # 推理侧用 OpenAICompatibleChatModel tokenizertokenizer, max_model_len32768, sampling_params{temperature: 0.7}, ) cache await model.prepare_rollout_cache([ {role: user, content: 列出当前目录} ]) print(初始 prompt_ids:, len(cache[prompt_ids])) print(初始 mask:, len(cache[response_mask])) # 应为 0 # 模拟一次 QUERY cache[prompt_ids] [101, 102, 103] cache[response_mask] [1, 1, 1] cache[response_logprobs] [0.1, 0.2, 0.3] # 模拟一次 APPEND工具返回 cache[prompt_ids] [201, 202] cache[response_mask] [0, 0] cache[response_logprobs] [0.0, 0.0] assert len(cache[prompt_ids]) len(cache[response_mask]) assert len(cache[response_mask]) len(cache[response_logprobs]) print(对齐校验通过mask 分布:, cache[response_mask]) asyncio.run(probe())跑通后你会看到 mask 是[1,1,1,0,0]——模型生成的 3 个 token 参与 loss工具返回的 2 个 token 不参与。这就是 rollout_cache 最核心的不变量。4.3 成功结果长什么样一次完整的UniAgentLoop.run()结束后convert_to_agent_output()会产出AgentLoopOutput里面response_mask的长度应该等于response_ids的长度且extra_fields[traj_exit_reason]是finished。如果看到traj_maskedTrue说明这条轨迹被异常退出逻辑 mask 掉了需要去查exit_reason。5. 本篇常见错排查5.1 mask 长度对不上最常见的原因是message_boundary_tokens探测失败。表现是len(prompt_ids) ! len(response_mask)。排查方法打印_get_new_message_ids()的返回值看边界 token 是否为空。如果为空说明差分对比法在你的 tokenizer 上没找到 EOS 之后的部分——检查apply_chat_template是否带了add_generation_promptTrue。5.2 工具返回混进 loss如果发现 PPO loss 异常高且response_mask里工具返回位置是 1 而不是 0检查append_messages_to_rollout_cache的断言是否被绕过。Uni-Agent 只允许追加user和tool角色其他角色会直接 assert 失败。5.3 Fully Async 下 staleness 爆表日志里如果出现staleness_samples max_required_samples频繁触发 pause说明trigger_parameter_sync_step设太大了。把它从 4 降到 2或者把staleness_threshold从 0.5 降到 0.3。代价是 GPU 利用率会降一点但 off-policy 偏差可控。5.4 TaoToken 调用 401先确认base_url是https://taotoken.net/api而不是带/v1的完整路径——OpenAI 兼容客户端会自动拼/v1/chat/completions。如果还是 401去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 重新生成一个 Key确认没有多余空格。5.5 环境启动超时env.start()卡住通常是 deployment 配置问题。本地调试用type: local容器测试用type: docker生产再切modal或vefaas。从本地到生产只改 YAML 一行但别在本地用生产后端超时时间对不上。6. 接入通道与后续动作配置骨架和验证动作都跑通之后下一步就是把调用通道固定下来。排障和接入相关的文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentdoc Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentapi_keys 。如果你要长期跑编码类 Agent 任务Coding Plan 的额度模型比按次调用更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentcoding_plan 。模型对话快速验证走 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_contentmodel_chat 。最后留一个实操建议把rollout_cache的四个不变量写成 pytest 断言每次改配置后跑一遍。我踩过的坑是改了max_response_length之后忘了同步max_model_len结果 QUERY 阶段直接抛MaxTokenExceededError整批 rollout 报废。断言比日志快。
