Agentic | Twinkle

Agentic 预处理器

Mon, 01 Jan 0001 00:00:00 +0000

Agentic 预处理器模块提供了基于流水线的多轮对话数据质量过滤框架，用于 RLHF / Agentic 微调之前的训练数据清洗和过滤。

QualityPreprocessor

QualityPreprocessor 是一个轻量级流水线运行器，接受过滤器列表并按顺序执行。每个步骤接收行列表，返回 (kept, dropped)，流水线会记录每步统计信息。

from twinkle_agentic.preprocessor import QualityPreprocessor, HardFilter, DeadLoopFilter

pipeline = [
 HardFilter(min_user_chars=10),
 DeadLoopFilter(),
]
preprocessor = QualityPreprocessor(pipeline, dropped_log_path='dropped.jsonl')

# rows 是列格式的字典（Dataset.map 格式）
cleaned = preprocessor(rows)

参数

参数	类型	说明
`pipeline`	`List[Callable]`	有序的过滤步骤列表。每个步骤接收 `List[Dict]`，返回 `(kept, dropped)`。
`dropped_log_path`	`str`	可选的 JSONL 文件路径，用于记录被丢弃的行及步骤名称和原因。

内置过滤器

HardFilter

基于硬规则的过滤器，使用确定性规则移除质量差的行。支持多语言检测（EN/ZH/JA/KO）。

from twinkle_agentic.preprocessor import HardFilter

f = HardFilter(
 min_user_chars=10, # 非 CJK 用户查询最小字符数
 min_user_chars_cjk=6, # CJK 用户查询最小字符数
 min_assistant_chars_2turn=80, # 两轮对话中助手回复最小长度
 min_thinking_chars=200, # 思考链最小长度（可豁免过滤）
 system_deny_keywords=['hack', 'exploit'],
 max_chars_per_round=50000,
 max_total_chars=200000,
 max_rounds=50,
)

丢弃原因： trivial_single_turn（平凡单轮）、shallow_reply（浅回复）、all_empty_assistant（全空助手）、system_deny_keyword（系统拒绝关键词）、round_too_long（单轮过长）、total_too_long（总长过长）、too_many_rounds（轮次过多）

DeadLoopFilter

检测助手消息中的犹豫/死循环模式——重复自我纠正、级联纠正和高 n-gram 重复。

from twinkle_agentic.preprocessor import DeadLoopFilter

f = DeadLoopFilter(
 hesitation_density_threshold=7.0, # 每 1000 字符犹豫标记数（响应）
 cascade_threshold=5, # 窗口内级联标记数
 cascade_window=800, # 窗口大小（字符）
 repetition_threshold=0.45, # N-gram 重复率
 think_hesitation_density_threshold=15.0, # <think> 块更宽松
 think_repetition_threshold=0.65,
)

对 <think> 推理块使用更宽松的阈值（允许自由发散），对可见响应使用更严格的阈值。

DedupFilter

全局最长优先去重。签名由第一个真实用户轮次（首尾）和第一个助手回复推导。

from twinkle_agentic.preprocessor import DedupFilter

f = DedupFilter(prefix_chars=100, asst_chars=100)
kept, dropped = f(all_rows) # 必须在一次调用中传入整个数据集

注意： DedupFilter 需要在单次调用中接收完整数据集。不要将它放入 QualityPreprocessor 中（后者按批处理）。请在流水线之前或之后单独运行。

RefuseFilter

检测第一条助手回复中的自我引用式拒绝（如"我无法帮助您"）。多语言模式匹配（EN/ZH/JA/KO）。

from twinkle_agentic.preprocessor import RefuseFilter

f = RefuseFilter(check_window=600) # 仅检查前 N 个字符

TokenSoupFilter

检测乱码/token-soup 输出，检查替换字符、控制字符、私用区 Unicode、泄漏的特殊 token、单字符重复和脚本混乱。

from twinkle_agentic.preprocessor import TokenSoupFilter

f = TokenSoupFilter(
 replacement_char_ratio=0.02,
 special_token_count=20,
 script_chaos_threshold=0.55,
)

PIIPresidioFilter

基于 Microsoft Presidio + spaCy NER + Faker 的多语言 PII 检测和重写。检测并替换个人身份信息（姓名、邮箱、电话号码、地址等）。

from twinkle_agentic.preprocessor import PIIPresidioFilter

f = PIIPresidioFilter(languages=['en', 'zh'])

IntentClassifier

启发式意图分类器，为每行标注检测到的意图。可插拔的检测器管线。

from twinkle_agentic.preprocessor import IntentClassifier

classifier = IntentClassifier()

意图类别： tool_call（工具调用）、code（代码）、math（数学）、complex_logic（复杂逻辑）、reasoning（推理）、user_dissatisfaction（用户不满）、other（其他）

ScoreFilter

可插拔评分器过滤器，内置字符级指标、语义相似度和代码执行评分器。

from twinkle_agentic.preprocessor import ScoreFilter

f = ScoreFilter()

内置评分器： ChrMinScorer、SIFDScorer、PassNScorer、ParaphraseScorer

ModelFilter

按模型 ID 白名单过滤行。

from twinkle_agentic.preprocessor import ModelFilter

f = ModelFilter(allowed_models=['qwen3.5-4b', 'qwen3.5-32b'])

MessageNormalizer

三遍消息规范化：心跳剥离、工具调用重写、连续同角色消息合并。

from twinkle_agentic.preprocessor import MessageNormalizer

normalizer = MessageNormalizer()

完整流水线示例

from twinkle_agentic.preprocessor import (
 QualityPreprocessor,
 HardFilter,
 DeadLoopFilter,
 RefuseFilter,
 TokenSoupFilter,
 MessageNormalizer,
 DedupFilter,
)

# 第一步：全局去重（必须在完整数据集上运行）
dedup = DedupFilter()
rows, _ = dedup(all_rows)

# 第二步：按批流水线
pipeline = [
 HardFilter(min_user_chars=10, max_rounds=30),
 DeadLoopFilter(),
 RefuseFilter(),
 TokenSoupFilter(),
 MessageNormalizer(),
]
preprocessor = QualityPreprocessor(pipeline, dropped_log_path='dropped.jsonl')
cleaned = preprocessor(rows)

协议（Protocol）

Mon, 01 Jan 0001 00:00:00 +0000

Protocol 模块提供了抽象的 LLM API 客户端接口及其 OpenAI 兼容实现。它将 Twinkle 的 Trajectory / SamplingParams 数据类型与外部 LLM 推理服务连接起来。

API 基类

from abc import ABC, abstractmethod
from twinkle.data_format import Trajectory
from twinkle.data_format.message import Message
from twinkle.data_format.sampling import SamplingParams

class API(ABC):
 """抽象 LLM API 客户端：Trajectory + SamplingParams -> 助手 Message"""

 @abstractmethod
 def __call__(
 self,
 trajectory: Trajectory,
 sampling_params: SamplingParams,
 **kwargs,
 ) -> Union[Message, List[Message]]:
 raise NotImplementedError()

API 类定义了一个简单的契约：给定对话轨迹和采样参数，返回一条或多条助手消息。

OpenAI

OpenAI 是内置实现，兼容任何支持 /v1/chat/completions 协议的端点（OpenAI、Azure OpenAI、vLLM、SGLang、Ollama 等）。

from twinkle_agentic.protocol.openai import OpenAI

api = OpenAI(
 model='qwen3.5-32b',
 base_url='http://localhost:8000/v1',
 api_key='EMPTY',
)

参数

参数	类型	说明
`model`	`str`	API 请求中传递的模型名称。
`api_key`	`str`	API 密钥。默认使用 `OPENAI_API_KEY` 环境变量。
`base_url`	`str`	API 端点的基础 URL（如 `http://localhost:8000/v1`）。
`client_kwargs`	`Dict`	转发给 `openai.OpenAI` 客户端构造函数的额外关键字参数。

使用方法

from twinkle.data_format import Trajectory
from twinkle.data_format.sampling import SamplingParams

trajectory = {
 'messages': [
 {'role': 'user', 'content': '法国的首都是什么？'},
 ]
}

sp = SamplingParams(temperature=0.7, max_tokens=512)
reply = api(trajectory, sp)
# reply 是一个 Message 字典：{'role': 'assistant', 'content': '...'}

特性

工具调用：自动将 trajectory['tools'] 映射到 API 请求，并解析响应中的结构化 tool_calls。
推理内容：保留支持推理的模型返回的 reasoning_content（如 o1 风格推理）。
完成原因：在返回消息中暴露 finish_reason，供多轮驱动器检测长度截断。
多样本：当 sampling_params.num_samples > 1 时，返回消息列表（每个 choice 一条）。

自定义 API 客户端

要集成非 OpenAI API，请继承 API：

from twinkle_agentic.protocol.base import API

class MyCustomAPI(API):

 def __call__(self, trajectory, sampling_params, **kwargs):
 # 调用自定义端点
 response = my_llm_client.chat(
 messages=trajectory['messages'],
 temperature=sampling_params.temperature,
 )
 return {'role': 'assistant', 'content': response.text}

多轮 Rollout

Mon, 01 Jan 0001 00:00:00 +0000

Rollout 模块提供了用于 Agentic RLHF 训练的多轮对话 rollout 引擎。包含两种实现：用于批量 vLLM 采样的 MultiTurnRollout 和用于 OpenAI 兼容 API 端点的 APIMultiTurnRollout。

Rollout 基类

from abc import ABC, abstractmethod
from twinkle.data_format import Trajectory

class Rollout(ABC):

 @abstractmethod
 def __call__(self, trajectories: List[Trajectory], **kwargs) -> List[Trajectory]:
 raise NotImplementedError()

所有 rollout 接受轨迹列表并返回相同数量的轨迹，附带额外字段（messages、turns、stop_reason、truncated）。

MultiTurnRollout

批量多轮 rollout 引擎，使用 vLLM 采样器进行生成。每轮中所有活跃轨迹通过单次批量采样调用并行处理，最大化吞吐量。

每轮循环

将每个轨迹编码为带生成提示的 InputFeature
批量调用 sampler.sample(active_pifs) —— 所有活跃轨迹并行
检查终止条件：stop_reason == 'length'、无工具调用、或达到最大轮次
通过 ToolManager 分发工具调用，追加工具响应
计算桥接 token（工具轮次 + 生成提示），设置 labels = -100
重复直到所有轨迹完成

from twinkle_agentic.rollout.multi_turn import MultiTurnRollout
from twinkle_agentic.tools.tool_manager import ToolManager
from twinkle.data_format.sampling import SamplingParams

rollout = MultiTurnRollout(
 sampler=vllm_sampler,
 template=template,
 tool_manager=tool_manager,
 sampling_params=SamplingParams(temperature=0.7, max_tokens=4096),
 max_turns=6,
 max_trajectory_tokens=8192,
 trace_dir='rollout_traces/',
)

# 运行 rollout
results = rollout(trajectories)

参数

参数	类型	说明
`sampler`	Sampler	用于批量生成的 vLLM 采样器实例。
`template`	`Template`	用于编码/解码的聊天模板。
`tool_manager`	`ToolManager`	工具分发器。也可以按调用传入。
`sampling_params`	`SamplingParams`	默认采样参数。
`max_turns`	`int`	每个轨迹的最大轮次（默认：6）。
`max_trajectory_tokens`	`int`	最大总 token 长度；超出则截断轨迹。
`trace_dir`	`str`	每轨迹 JSON 跟踪文件的目录。
`trace_callback`	`Callable`	决定是否存储轨迹跟踪。
`success_callback`	`Callable`	决定文件名前缀（`ok-` 或 `fail-`）。

输出字段

每个输出轨迹字典包含：

字段	类型	说明
`messages`	`List[Dict]`	包含工具轮次的完整对话。
`input_ids`	`List[int]`	完整序列的 token ID。
`labels`	`List[int]`	训练标签（非可训练 token 为 `-100`）。
`turns`	`int`	执行的轮次数。
`stop_reason`	`str`	`'stop'` / `'length'`
`truncated`	`bool`	轨迹是否被截断。
`logprobs`	`List`	每 token 的对数概率（如有）。

Ray 远程支持

MultiTurnRollout 使用 @remote_class() 装饰器，支持作为 Ray actor 透明部署：

# rollout 可以作为 Ray 远程 actor 运行
rollout_actor = MultiTurnRollout.remote(sampler=sampler, template=template, ...)
results = ray.get(rollout_actor.__call__.remote(trajectories))

APIMultiTurnRollout

通过 OpenAI 兼容 chat-completions API 进行多轮 rollout。每个轨迹在线程池中独立运行，实现网络并发。

from twinkle_agentic.rollout.api_multi_turn import APIMultiTurnRollout
from twinkle_agentic.protocol.openai import OpenAI

api = OpenAI(model='qwen3.5-32b', base_url='http://localhost:8000/v1')

rollout = APIMultiTurnRollout(
 api=api,
 tool_manager=tool_manager,
 sampling_params=SamplingParams(temperature=0.7),
 max_turns=6,
 concurrency=8,
 trace_dir='api_traces/',
)

results = rollout(trajectories)

参数

参数	类型	说明
`api`	`OpenAI`	OpenAI 兼容 API 客户端。
`tool_manager`	`ToolManager`	工具分发器（单个或按轨迹的列表）。
`sampling_params`	`SamplingParams`	默认采样参数。
`max_turns`	`int`	每轨迹最大轮次（默认：6）。
`concurrency`	`int`	并行 API 调用的线程池大小（默认：8）。
`extra_body`	`Dict`	API 请求中附加的额外字段。
`trace_dir`	`str`	跟踪文件目录。

停止原因

原因	说明
`stop`	助手回复未包含工具调用（自然结束）。
`length`	API 返回 `finish_reason='length'`（token 限制）。
`max_turns`	达到 `max_turns` 限制。
`api_error`	API 调用或工具执行抛出异常。

选择建议

特性	MultiTurnRollout	APIMultiTurnRollout
后端	vLLM 采样器（本地 GPU）	OpenAI 兼容 API
训练集成	生成 `input_ids` / `labels` 用于 GRPO	仅消息（用于数据收集）
批处理	GPU 级别批量并行	网络级别线程并发
用例	在线 RLHF 训练循环	离线数据生成 / 评估

工具与 ToolManager

Mon, 01 Jan 0001 00:00:00 +0000

Tools 模块提供了抽象工具接口和中央工具分发器（ToolManager），用于 Agentic 多轮 rollout。工具遵循 OpenAI function-calling schema，与 LLM 工具调用能力无缝集成。

Tool 基类

from abc import ABC, abstractmethod
from twinkle.data_format import Tool as ToolInfo

class Tool(ABC):

 @abstractmethod
 def __call__(self, tool_name: str, arguments: Dict[str, Any]) -> str:
 """执行工具并返回字符串结果。"""
 raise NotImplementedError

 @abstractmethod
 def tool_info(self) -> ToolInfo:
 """返回 OpenAI 兼容的工具 schema。"""
 raise NotImplementedError

实现自定义工具

from twinkle_agentic.tools.base import Tool

class SearchTool(Tool):

 def __call__(self, tool_name: str, arguments: dict) -> str:
 query = arguments.get('query', '')
 # 执行搜索逻辑
 return f'搜索结果：{query}'

 def tool_info(self):
 return {
 'type': 'function',
 'function': {
 'name': 'search',
 'description': '搜索网络信息。',
 'parameters': {
 'type': 'object',
 'properties': {
 'query': {
 'type': 'string',
 'description': '搜索查询。',
 },
 },
 'required': ['query'],
 },
 },
 }

ToolManager

ToolManager 是工具的注册中心和分发器。它解析 LLM 结构化输出中的工具调用，并路由到正确的工具实现。

from twinkle_agentic.tools.tool_manager import ToolManager

# 通过 Tool 实例列表初始化
manager = ToolManager([search_tool, calculator_tool])

# 或通过字典初始化
manager = ToolManager({'search': search_tool, 'calc': calculator_tool})

# 或动态注册
manager = ToolManager()
manager.register(search_tool)
manager.register(calculator_tool)

核心方法

方法	说明
`register(tool)`	注册工具（名称从 `tool_info()` 提取）。
`unregister(name)`	按名称移除工具。
`names()`	列出所有已注册的工具名称。
`copy()`	创建管理器的浅拷贝。
`tool_infos()`	返回所有工具 schema 列表（用于 API 请求）。
`__call__(tool_call)`	分发工具调用并返回结果字符串。

分发工具调用

ToolManager 接受 OpenAI 格式的工具调用字典：

tool_call = {
 'id': 'call_1',
 'type': 'function',
 'function': {
 'name': 'search',
 'arguments': '{"query": "Python 教程"}',
 },
}

result = manager(tool_call)
# result: '搜索结果：Python 教程'

错误处理： 如果工具名未知、参数是无效 JSON 或工具抛出异常，ToolManager 返回描述性错误字符串而不是抛出异常——这保证了 rollout 循环的持续运行。

与 Rollout 集成

from twinkle_agentic.rollout.multi_turn import MultiTurnRollout

rollout = MultiTurnRollout(
 sampler=sampler,
 template=template,
 tool_manager=manager, # 传入工具管理器
 max_turns=6,
)

Rollout 引擎对模型生成的每个工具调用执行 manager(tool_call)，并将结果作为 {'role': 'tool', 'content': result} 消息追加。

执行环境（Envs）

Mon, 01 Jan 0001 00:00:00 +0000

Envs 模块提供了用于 Agentic 训练的 RL 执行环境抽象。环境可以在多轮 rollout 中交互式参与，也可以批量评估已完成的轨迹。

Env 基类

from twinkle_agentic.envs.base import Env, StepResult

class Env(ABC):

 def reset(self, trajectory=None) -> StepResult:
 """重置环境，开始新一轮。"""

 @abstractmethod
 def step(self, tool_name: str, arguments: dict) -> StepResult:
 """执行单个动作，返回观测 + 奖励 + 完成标志。"""

 def tools(self) -> List[ToolInfo]:
 """返回此环境中可用的工具定义。"""

 def evaluate(self, trajectories, **kwargs) -> List[float]:
 """批量评估已完成的轨迹，返回奖励列表。"""

 def close(self) -> None:
 """释放资源。"""

StepResult

@dataclass
class StepResult:
 observation: str = '' # 动作执行后的环境观测
 reward: float = 0.0 # 此步骤的标量奖励
 done: bool = False # 是否终止
 info: Dict[str, Any] = field(default_factory=dict) # 额外元数据

两种使用模式

交互模式（多轮 rollout）—— 逐步执行：

env = MyEnv()
env.reset(trajectory)
result = env.step('search', {'query': 'Python'})
# ... 重复直到 result.done

批量评估模式 —— 评估已完成的轨迹：

rewards = env.evaluate(completed_trajectories)

EnvTool

EnvTool 将 Env 包装为 Tool，连接环境与 ToolManager 和 MultiTurnRollout。

from twinkle_agentic.envs.env_tool import EnvTool
from twinkle_agentic.tools.tool_manager import ToolManager

env = MyEnv()

# 为环境中定义的每个工具创建一个 EnvTool
env_tools = EnvTool.from_env(env)

# 注册到 ToolManager
manager = ToolManager(env_tools)

核心特性

特性	说明
`from_env(env)`	工厂方法：为 `env.tools()` 中的每个工具创建一个 `EnvTool`。
`last_result`	存储最近一次 `StepResult` 供调用方检查。
`done`	属性：最后一步是否终止了回合。
`episode_reward`	属性：来自 `info['episode_reward']` 的累计奖励。

手动构造

env_tool = EnvTool(
 env=my_env,
 tool_name='execute_code',
 description='在沙箱中执行 Python 代码。',
 parameters={
 'type': 'object',
 'properties': {
 'code': {'type': 'string', 'description': '要执行的 Python 代码。'},
 },
 'required': ['code'],
 },
)

OpenEnv

OpenEnv 将基于 WebSocket 的环境服务器适配为同步的 Twinkle Env。

from twinkle_agentic.envs.openenv import OpenEnv

env = OpenEnv(
 base_url='http://localhost:8000',
 env_cls='coding_env.CodingEnv', # 可选的类型化客户端
 env_kwargs={'message_timeout_s': 30},
 tool_schema=[...], # 可选的工具定义
)

参数

参数	类型	说明
`base_url`	`str`	运行中的 OpenEnv 服务器 URL。
`env_cls`	`str` 或 class	类型化客户端的点分导入路径或类。`None` 使用 `GenericEnvClient`。
`env_kwargs`	`Dict`	传递给客户端构造函数的额外参数。
`tool_schema`	`List[ToolInfo]`	通过 `tools()` 暴露的工具定义。
`action_mapper`	`Callable`	自定义函数，将 `(tool_name, args)` 映射为发送给服务器的动作字典。

与 Rollout 集成使用

from twinkle_agentic.envs.openenv import OpenEnv
from twinkle_agentic.envs.env_tool import EnvTool
from twinkle_agentic.tools.tool_manager import ToolManager
from twinkle_agentic.rollout.api_multi_turn import APIMultiTurnRollout

# 设置环境
env = OpenEnv(base_url='http://localhost:8000', tool_schema=[...])
env.reset()

# 桥接到 ToolManager
env_tools = EnvTool.from_env(env)
manager = ToolManager(env_tools)

# 在 rollout 中使用
rollout = APIMultiTurnRollout(api=api, tool_manager=manager, max_turns=10)
results = rollout(trajectories)

实现自定义环境

from twinkle_agentic.envs.base import Env, StepResult

class CodeExecutionEnv(Env):

 def reset(self, trajectory=None):
 self._sandbox = create_sandbox()
 return StepResult(observation='沙箱已就绪。')

 def step(self, tool_name, arguments):
 code = arguments.get('code', '')
 output = self._sandbox.run(code)
 return StepResult(
 observation=output,
 reward=1.0 if 'error' not in output.lower() else 0.0,
 done=False,
 )

 def tools(self):
 return [{
 'type': 'function',
 'function': {
 'name': 'execute_code',
 'description': '运行 Python 代码。',
 'parameters': {
 'type': 'object',
 'properties': {
 'code': {'type': 'string'},
 },
 },
 },
 }]

 def close(self):
 self._sandbox.cleanup()

多轮工具使用指南

Mon, 01 Jan 0001 00:00:00 +0000

本指南介绍如何在 Twinkle 中设置和运行带工具调用的多轮 Agentic rollout。

架构概览

Agentic rollout 管线由四个核心组件组成：

Tool —— 实现特定能力（搜索、代码执行等）
ToolManager —— 注册工具并分发 LLM 工具调用
Env（可选）—— RL 环境，通过 EnvTool 暴露工具
Rollout —— 驱动多轮对话循环

快速开始：基于 API 的 Rollout

使用 OpenAI 兼容 API 运行多轮工具使用 rollout 的最简方式：

from twinkle_agentic.protocol.openai import OpenAI
from twinkle_agentic.tools.base import Tool
from twinkle_agentic.tools.tool_manager import ToolManager
from twinkle_agentic.rollout.api_multi_turn import APIMultiTurnRollout
from twinkle.data_format.sampling import SamplingParams

# 1. 定义工具
class WeatherTool(Tool):
 def __call__(self, tool_name, arguments):
 city = arguments.get('city', '未知')
 return f'{city}的天气：晴，25°C。'

 def tool_info(self):
 return {
 'type': 'function',
 'function': {
 'name': 'get_weather',
 'description': '获取城市的当前天气。',
 'parameters': {
 'type': 'object',
 'properties': {
 'city': {'type': 'string', 'description': '城市名称。'},
 },
 'required': ['city'],
 },
 },
 }

# 2. 设置 ToolManager
manager = ToolManager([WeatherTool()])

# 3. 创建 API 客户端
api = OpenAI(model='qwen3.5-32b', base_url='http://localhost:8000/v1')

# 4. 创建 rollout
rollout = APIMultiTurnRollout(
 api=api,
 tool_manager=manager,
 sampling_params=SamplingParams(temperature=0.7, max_tokens=2048),
 max_turns=6,
 concurrency=8,
)

# 5. 准备轨迹
trajectories = [
 {
 'messages': [
 {'role': 'user', 'content': '北京今天天气怎么样？'},
 ],
 },
]

# 6. 运行 rollout
results = rollout(trajectories)
for r in results:
 print(f"轮次: {r['turns']}, 停止原因: {r['stop_reason']}")
 for msg in r['messages']:
 print(f" [{msg['role']}] {msg.get('content', '')[:100]}")

训练集成：基于 vLLM 的 Rollout

用于 RLHF 训练时，使用 MultiTurnRollout，它会生成 input_ids 和 labels：

from twinkle_agentic.rollout.multi_turn import MultiTurnRollout
from twinkle.data_format.sampling import SamplingParams

rollout = MultiTurnRollout(
 sampler=vllm_sampler, # vLLMSampler 实例
 template=template, # 聊天模板
 tool_manager=manager,
 sampling_params=SamplingParams(temperature=0.7, max_tokens=4096),
 max_turns=6,
 max_trajectory_tokens=8192,
 trace_dir='rollout_traces/',
)

# 在 GRPO 训练循环中
results = rollout(batch_trajectories)
# results 包含 input_ids、labels、logprobs 用于训练

将环境用作工具

将 RL 环境桥接到工具管线中：

from twinkle_agentic.envs.base import Env, StepResult
from twinkle_agentic.envs.env_tool import EnvTool
from twinkle_agentic.tools.tool_manager import ToolManager

# 定义环境
class CodeEnv(Env):
 def step(self, tool_name, arguments):
 code = arguments.get('code', '')
 # 在沙箱中执行代码
 result = execute_in_sandbox(code)
 return StepResult(observation=result, reward=1.0, done=False)

 def tools(self):
 return [{
 'type': 'function',
 'function': {
 'name': 'run_python',
 'description': '执行 Python 代码。',
 'parameters': {
 'type': 'object',
 'properties': {
 'code': {'type': 'string'},
 },
 'required': ['code'],
 },
 },
 }]

# 桥接 Env -> Tool -> ToolManager
env = CodeEnv()
env_tools = EnvTool.from_env(env)
manager = ToolManager(env_tools)

# 照常在 rollout 中使用 manager
rollout = APIMultiTurnRollout(api=api, tool_manager=manager, max_turns=10)

使用 OpenEnv 环境

连接远程 OpenEnv WebSocket 服务器：

from twinkle_agentic.envs.openenv import OpenEnv
from twinkle_agentic.envs.env_tool import EnvTool

env = OpenEnv(
 base_url='http://localhost:8000',
 env_cls='coding_env.CodingEnv',
 tool_schema=[{
 'type': 'function',
 'function': {
 'name': 'submit',
 'description': '提交代码解决方案。',
 'parameters': {
 'type': 'object',
 'properties': {
 'code': {'type': 'string'},
 },
 },
 },
 }],
)

env.reset()
env_tools = EnvTool.from_env(env)
manager = ToolManager(env_tools)

每轨迹独立 ToolManager

当每个轨迹需要独立工具集时（例如，轨迹绑定的状态）：

# 创建每轨迹的 manager
managers = []
for traj in trajectories:
 env = create_env_for(traj)
 env_tools = EnvTool.from_env(env)
 managers.append(ToolManager(env_tools))

# 传入列表（与轨迹 1:1 对齐）
results = rollout(trajectories, tool_manager=managers)

跟踪调试

两种 rollout 实现都支持跟踪文件输出用于调试：

rollout = APIMultiTurnRollout(
 api=api,
 tool_manager=manager,
 trace_dir='traces/',
 trace_callback=lambda t: t['turns'] > 1, # 仅存储多轮对话
 success_callback=lambda t: t.get('stop_reason') == 'stop',
)

跟踪文件以 {step}-{ok|fail}-{id}.json 格式保存，包含完整对话和元数据。