AgentTrajLab

Train task-specialized agents with LoRA on consumer GPUs.

从真实 Agent 执行采集经验，在一张 RTX 4090 上训练 LoRA，再让同一个 harness 运行独立任务，检查模型究竟学到了什么。

本机工程验收：Qwen3.5-4B、rank 8 LoRA、实际最长 2201 tokens，加载/一次更新/保存合计 18.2 秒；PyTorch 峰值 allocated 10.45 GiB、reserved 11.95 GiB。仅一条任务的训练通路验证，详见 实测配置。

主参考 harness：DeepSeek Harness。模型与 harness 分开：DeepSeek Harness 编排工具和上下文，本地 Qwen3.5-4B 是当前学生模型；模型请求经过独立 recording proxy。教师轨迹也可从兼容服务采集。

任务与公开环境
    ↓
DeepSeek Harness + 本地学生 / 教师模型
    ↓ 独立代理记录实际请求、输出、工具结果与摘要调用
独立验收 → 成功轨迹 → 压缩分段 → 显式监督目标
    ↓ 学生自己的 chat template / tokenizer
SFT tokens / labels → 单张 4090、LoRA
    ↓ 加载 adapter，保持 harness 与评测预算一致
独立任务上的 base / adapter 对比

当前状态： 核心采集、SFT 和单设备 LoRA 通路已实现；DeepSeek 集成使用官方 Python SDK 的 sdk-minimal profile。主任务场景仍在选择，候选与验收方法见 SCENARIOS。账单任务用于工程调试；现有少量任务结果不代表能力提升。

先看懂数据，再使用 GPU

git clone https://github.com/kirie123/AgentTrajLab.git
cd AgentTrajLab
uv sync --extra tokenize --extra dev
uv run agenttrajlab demo --output runs/demo

打开 runs/demo/report.html。离线 demo 使用明确标记的确定性 fixture，展示多轮工具调用、压缩与 loss mask；无需 API、模型或显卡，不能用于真实训练。

训练数据保留每个新输出的原始调用出处。压缩后回放的旧 assistant 属于输入，labels 为 -100；段内多次新输出可以同时监督。摘要生成调用单独记录，提供“包含摘要目标”和“只监督行动”两种导出。

官方 DeepSeek Harness 接本地模型

准备带 CUDA PyTorch、Transformers 5、PEFT 的 Python 环境，安装本项目的 train、tokenize、deepseek extras。官方 SDK 带匹配的原生运行时，不需要构建整个 DeepSeek 仓库。

# 在已配置 CUDA PyTorch 的环境中安装；保留你的 CUDA wheel 来源配置。
uv pip install -e '.[train,tokenize,deepseek]'
python -m agentic_sft deepseek-demo --model-path /path/to/Qwen3.5-4B --output runs/deepseek-first

SDK 也可以安装在另一个 Python 环境，用 --harness-python /path/to/python 指定。deepseek-demo 使用官方原生 read/write 与自动压缩；调低压缩阈值便于在短任务上观察分段。采集、模型服务、代理和离线编译都有独立入口，详见 DeepSeek 接入与调试。

在 4090 上训练 LoRA

python -m agentic_sft train --model /path/to/Qwen3.5-4B --tokenizer /path/to/Qwen3.5-4B `
  --data runs/deepseek-first/sft-actions/train.tokens.jsonl --output runs/adapter `
  --lora --lora-rank 8 --batch-size 1 --accumulation 4 --max-tokens 4096 `
  --learning-rate 0.00002 --steps 100 --no-thinking-template --supervised-logits

这是 4B BF16 + LoRA 的起步配置，使用梯度检查点和按监督 token 归一化的梯度累积。--supervised-logits 只在有效监督位置计算完整词表输出头，保留全部因果上下文；已验证 loss 和参数梯度等价。单次演示数据很少，以上命令用于检查训练；正式实验需先准备足够的、独立验收通过的任务轨迹。

training_manifest.json 保存 GPU、训练参数量、序列预算、训练耗时与 PyTorch 显存峰值。具体可容纳的长度依赖模型和算子；4B 的验证不能推导为 30B 在单张 4090 上可训。当前未实现量化加载或 QLoRA。

训练后用 deepseek-evaluate --adapter-path runs/adapter 在同一官方 harness 中运行独立任务；省略 adapter 参数运行基座。先固定模型服务、工具、解码、压缩与步数预算，再比较 base / adapter。本轮同一组 4 个独立合成任务上，基座与 adapter 均为 3/4；没有测得训练收益，正式场景尚待确定。

代码与调试入口

阶段	源码	独立入口
任务与私有验收	tasks.py, environment.py	factory, check-tasks
本地模型与 LoRA 推理	local_model.py, model_service.py	probe-model, serve-model
独立模型 I/O 采集	proxy.py, recording.py, messages_sse.py	proxy-serve, proxy-audit
官方 DeepSeek Agent 执行	integrations/deepseek.py, scripts/deepseek_runner.py	deepseek-collect, deepseek-demo
原始记录转 SFT	proxy_export.py, dataset.py	proxy-export, prepare, deepseek-prepare
模板、token 与 loss mask	tokenize.py, debugging.py	encode, debug-render, audit
单设备 LoRA / 全参 SFT	training.py	train, loss-smoke
完整轨迹审计报告	report.py	report

核心代理不导入 harness、工具环境或训练框架。Chat Completions 与 Messages 文本/工具轨迹支持 SFT 导出；Responses 当前仅记录。模型输入中的 tool result、thinking 与协议格式处理见 数据契约；Python list / PyTorch / loss 的中文走读见 WALKTHROUGH。

其他文档：分阶段调试 · 独立代理 · 模型与蒸馏 · 本机实测。

开发

uv run ruff check .
uv run pytest -q
uv build

项目与仓库名 AgentTrajLab；包和 CLI 为 agenttrajlab，Python 导入路径为 agentic_sft。核心 MIT，第三方依赖与参考来源见 THIRD_PARTY_NOTICES。权重、密钥、运行记录和 checkpoint 默认不进入 Git。