Merge branch 'openclaw-exp'

Author: binary-husky

tutorial/opencode_build_openclaw_agent/REWARD_UPDATE.md

@@ -0,0 +1,108 @@
+# OpenClaw奖励模块更新
+
+**项目**: OpenClaw Agent 构建
+**时间范围**: 2026 年 3 月 13 日 — 2026 年 3 月 20 日
+
+---
+
+## 一、之前的奖励模块的问题
+
+之前奖励模块处于最小可行状态：仅依赖语言模型评判回复的外向性（Extraversion）人格特征分数，逻辑简洁但功能单一。在实际训练中，这种单一维度的评估暴露出三类问题：
+
+- **离题回复仍然获得较高奖励**：回复虽然热情洋溢、表达力强，但若与问题无关，仍能得到不错分数，导致模型学会"热情地答非所问"。
+- **批量内回复趋于同质化**：语言模型在生成多个候选回复时，容易产出大量近似重复的内容，这些内容各自获得接近的分数，缺乏多样性信号。
+- **退化输出缺乏惩罚机制**：训练过程中偶尔出现的循环段落、特殊 token 泄露或字符级重复（nonsense generation），因为在 Extraversion 维度上没有明显短板，仍能获得中上奖励，无法被有效压制。
+
+本次更新的核心目标，就是将奖励系统从单一维度扩展为多维度复合架构，以更精细的信号引导模型同时兼顾**相关性**、**多样性**和**输出质量**。
+
+---
+
+## 二、核心升级：从单一维度到四维复合奖励
+
+### 2.1 奖励公式
+
+新的奖励由四个维度加权融合，并通过一个乘法质量门控进行修正：
+
+```
+最终奖励 = 质量分数 × (外向性权重 × 外向性 + 相关性权重 × 相关性 + 多样性权重 × 多样性)
+```
+
+默认权重配置为：外向性 0.5、相关性 0.3、多样性 0.2。三个子维度权重之和为 1.0，质量门控以乘法形式作用于最终得分。
+
+### 2.2 各维度说明
+
+**外向性（Extraversion）**
+
+沿用上一版本的 LLM 评判方案，由语言模型评估回复在热情、活力和表达力方面的表现。评估模式保持两种：pointwise 模式对每个回复独立打分（0–1），listwise 模式在同一批回复中做相对排名（最好 1.0，最差 0.0）。
+
+**相关性（Relevance）**
+
+新增的维度。评判回复是否围绕问题展开、是否切中主题。相关性的加入解决了"热情但跑题"这一问题：即使回复在表达力上得分很高，若相关性不足，综合得分也会被拉低。
+
+**多样性（Diversity）**
+
+新增的维度。鼓励模型在生成多个候选回复时保持差异性，避免同质化输出。多样性评估分为两个层面：
+
+- **批量内多样性**：当前这批候选回复中，各回复之间的相似程度。相似度越高，多样性分越低。
+- **跨请求多样性**：当前回复与近期历史上出现过的回复之间的相似程度。若模型反复产出与历史相似的回复，多样性分也会被压低。
+
+多样性评估采用 n-gram 字符级重叠度（Jaccard 相似度）作为量化指标，无需语言模型调用，完全确定性执行。
+
+**质量门控（Quality Gate）**
+
+新增的维度。作为一个乘法修正项（0–1 之间），质量门控以"硬开关"的方式惩罚两类退化输出：
+
+- **段落级循环**：同一结构化段落（如 `If you have any questions...` 模板段落）被重复多次。
+- **字符级重复与 token 泄露**：连续重复词汇、特殊标记（如 `<|im_start|>`）泄露等。
+
+质量门控采用 OpenJudge 的 NgramRepetitionPenaltyGrader 结合字符串退化检测工具联合判定。当检测到上述退化模式时，质量分数直接压至接近零，无论其他三个维度的得分有多高。
+
+---
+
+## 三、其他变更
+
+### 3.1 查询历史记录
+
+在请求处理环节新增了一个轻量级的查询历史滚动缓冲区（上限 100 条），记录每次提交的请求元信息。其目的不在训练奖励计算，而在于系统层面的可观测性：若同一问题在短时间内高频出现，说明上游数据分发存在问题，需要及时告警，而非归咎于模型。
+
+### 3.2 vLLM 兼容处理
+
+服务端点在转发请求时，自动剥离了上游不支持的字段（如 `strict`、`store`），避免不必要的警告输出。同时，`/requests` 接口的返回值从原始请求记录改为查询历史，提供更清晰的调试视图。
+
+### 3.3 测试体系
+
+原有的两个端到端测试（pointwise 模式、listwise 模式）被扩展为六个专项测试，覆盖复合奖励的各个维度以及质量门控的惩罚效果：
+
+- 外向性复合奖励测试：验证热情回复优于平淡回复
+- 相关性惩罚测试：验证离题回复得分低于切题回复
+- 多样性惩罚测试：验证近似重复回复得分低于独特回复
+- 跨请求多样性测试：验证重复历史回复的代价
+- 退化惩罚测试：验证循环段落和特殊 token 泄露会被质量门控压制
+- listwise 复合测试：验证 listwise 模式下复合奖励同样生效
+
+每个测试在运行时隔离历史状态，确保测试结果不受执行顺序影响。
+
+### 3.4 快速参考文档
+
+新增了一份速查文档（cheatsheet），包含测试运行命令、服务启动命令、所有奖励模式说明和环境变量速查表，方便日常操作时快速查阅。
+
+---
+
+## 四、架构升级概览
+
+| 特性 | 更新前 | 更新后 |
+|------|--------|--------|
+| 奖励维度 | 1 个（外向性） | 4 个（外向性 + 相关性 + 多样性 + 质量门控） |
+| 质量门控 | 无 | 乘法门控，压制退化输出至 ~0 |
+| 批量内多样性 | 无 | n-gram 相似度检测 |
+| 跨请求记忆 | 无 | 25 条回复历史滚动缓冲区 |
+| 相关性评估 | 无 | LLM 评判 |
+| 测试用例数 | 2 个 | 6 个 |
+| 快速参考文档 | 无 | 新增 cheatsheet |
+| 请求可观测性 | 无 | 查询历史记录接口 |
+
+---
+
+## 五、总结
+
+本次更新的本质，是将奖励模块从"外向性评分器"转变为"多维度质量评估系统"。新增的相关性和多样性维度填补了上一版本的盲区，质量门控则为训练稳定性提供了最后一道防线。更新后的系统能够在鼓励热情表达的同时，确保回复切题、不重复、无退化，使模型真正学会在正确方向上发挥外向性人格优势。

tutorial/opencode_build_openclaw_interactive_train/README.md

@@ -0,0 +1,197 @@
+# OpenClaw Agent Training - Extraversion Personality
+
+Train an LLM agent to exhibit more extraverted personality traits using reinforcement learning.
+
+## Overview
+
+This training program uses GRPO (Group Relative Policy Optimization) to train Qwen2.5-7B-Instruct to respond with more extraverted characteristics:
+- Outgoing, energetic, enthusiastic tone
+- Social engagement and excitement
+- Positive, upbeat language
+- Action-oriented expressions
+
+## Architecture
+
+```
+User Query → fake_vllm_endpoint.py → Swarm Server (8 GPUs)
+                ↓
+        Generate N=4 responses in parallel
+                ↓
+        Evaluate with ExtraversionGrader (OpenJudge)
+                ↓
+        Compute rewards & update model (GRPO)
+                ↓
+        Return best response to user
+```
+
+## Prerequisites
+
+```bash
+pip install py-openjudge datasets
+```
+
+## Setup
+
+### 1. Download Dataset
+
+```bash
+cd tutorial/opencode_build_openclaw_agent
+python download_dataset.py
+```
+
+This downloads the `holistic-ai/personality_manipulation` dataset and extracts extraversion examples.
+
+### 2. Configure API Key
+
+Edit `on_compute_relative_reward.py` and set your API key for the judge model:
+
+```python
+model = OpenAIChatModel(
+    model="qwen-plus",
+    api_key="YOUR_API_KEY_HERE",  # Change this
+    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+)
+```
+
+## Training
+
+### Step 1: Start Swarm Server
+
+On your GPU server (with 8 GPUs available):
+
+```bash
+ajet-swarm start
+```
+
+Or with monitoring:
+
+```bash
+(ajet-swarm start &> ajet-swarm-server.log) & (ajet-swarm overwatch)
+```
+
+### Step 2: Start Fake vLLM Endpoint
+
+In a new terminal:
+
+```bash
+cd tutorial/opencode_build_openclaw_agent
+
+# Option 1: Use OpenJudge pointwise grading (default)
+export AJET_SWARM_URL="http://localhost:10086"
+export NUM_REPEAT=4
+export REWARD_MODE=pointwise
+export DASHSCOPE_API_KEY=your_api_key_here
+python fake_vllm_endpoint.py
+
+# Option 2: Use OpenJudge listwise ranking
+export AJET_SWARM_URL="http://localhost:10086"
+export NUM_REPEAT=4
+export REWARD_MODE=listwise
+export DASHSCOPE_API_KEY=your_api_key_here
+python fake_vllm_endpoint.py
+```
+
+This starts the training proxy on `http://localhost:8090`.
+
+### Step 3: Configure OpenClaw to Use Training Endpoint
+
+OpenClaw needs to connect to the fake vLLM endpoint.
+
+Configure it to use `http://localhost:8090` as the LLM backend.
+
+### Step 4: Send Training Requests
+
+Option A - Manual testing via OpenClaw Web / Cli:
+
+```bash
+openclaw agent --message "What are your thoughts on Paris?" --thinking high
+```
+
+Option B - Automated dataset iteration:
+
+```bash
+python mock_user_request.py
+```
+
+This will iterate through the personality_manipulation dataset and send each question via OpenClaw CLI.
+
+## Configuration
+
+Key parameters in `fake_vllm_endpoint.py`:
+
+- `n_gpu=8` - Number of GPUs for training
+- `batch_size=32` - Training batch size
+- `num_repeat=4` - GRPO N parameter (responses per query)
+- `model` - Base model path
+
+Environment variables for reward computation:
+
+- `REWARD_MODE` - Reward computation mode: `pointwise` (default) or `listwise`
+- `DASHSCOPE_API_KEY` - API key for OpenJudge LLM grader
+- `JUDGE_BASE_URL` - Base URL for judge model API (default: DashScope)
+- `JUDGE_MODEL` - Judge model name (default: `qwen-plus`)
+
+## Reward Function
+
+Two OpenJudge-based reward modes are available:
+
+### 1. Pointwise Mode (Default)
+
+Uses OpenJudge LLM grader to evaluate each response independently:
+- Evaluates extraversion traits on 1-10 scale
+- Provides detailed reasoning for each score
+- Scores normalized to [-1, 1] for GRPO training
+
+```bash
+export REWARD_MODE=pointwise
+export DASHSCOPE_API_KEY=your_api_key_here
+```
+
+### 2. Listwise Mode
+
+Uses OpenJudge to rank all responses together:
+- Compares responses directly against each other
+- Produces relative rankings
+- Best for capturing subtle differences
+
+```bash
+export REWARD_MODE=listwise
+export DASHSCOPE_API_KEY=your_api_key_here
+```
+
+## Monitoring
+
+Check training progress:
+
+```bash
+# View swarm status
+ajet-swarm overwatch
+
+# Check request history
+curl http://localhost:8090/requests
+
+# Health check
+curl http://localhost:8090/health
+```
+
+## Files
+
+- `fake_vllm_endpoint.py` - Main training server
+- `on_compute_relative_reward.py` - Extraversion reward function
+- `on_user_submit_new_requests.py` - Request handler
+- `download_dataset.py` - Dataset downloader
+- `mock_user_request.py` - Automated testing client
+
+## Troubleshooting
+
+**Import errors**: LSP warnings about unresolved imports are normal - dependencies will be available at runtime.
+
+**Connection refused**: Ensure swarm server is running on port 10086.
+
+**All episodes failed**: Check GPU availability and swarm server logs.
+
+## Notes
+
+- Training is passive - the endpoint waits for requests rather than iterating a dataset
+- Each request generates N=4 responses, evaluates them, and trains on the best
+- The model gradually learns to produce more extraverted responses over time