内容
# Anvil
**开源LoRA优先的训练后** — SFT和RL，拥有简洁的四动词API，诚实的配方，以及 **实时RL调试器**。
为 **两类用户群体设计**:
| 模式 | 对象 | 感受 |
|------|-----|----------------|
| **个人** | 研究人员/机器人专家 + 自有GPU | 配方，网页UI，运行循环，观察曲线和探针 |
| **代理** | 操作代理（您提供模型） | 通过 **HTTP + MCP** 实现同样的功能 — 监控指标/探针，暂停，调整参数，切换方法 |
Anvil拥有 **控制平面，MCP工具，可选的适配器和可移植的提示**。您提供 **智能代理核心**（前沿或本地），GPU和数据。如果您不使用我们的适配器，提示包也可以接入 **您的适配器**。
> Anvil最初的灵感来自Thinking Machines的Tinker API（四个低级别的训练/采样动词 + LoRA）的产品形态。Anvil是独立的开源软件；无关联，无线路兼容。
| 文档 | 角色 |
|-----|------|
| **[docs/product.md](docs/product.md)** | 产品理念（曲线，RSI形目标，双模式） |
| **[docs/agentic-control.md](docs/agentic-control.md)** | MCP/适配器 vs 用户核心；采用路径A/B/C |
| **[prompts/agent/](prompts/agent/)** | 插入式操作提示 |
| **[docs/roadmap.md](docs/roadmap.md)** | 阶段性目标 |
| **[start.md](start.md)** | 人类和编码代理的会话入口 |
## 为什么
通过降低系统税率，使训练后民主化：您保留 **数据，损失，奖励，环境**；Anvil处理 **训练，采样，和导出** 的稳定合约 — 并呈现通常只有在评估失败后才会出现的信号。
不同方法（**DPO**，**GRPO**，**LoRA SFT**，…）会遇到不同的 **瓶颈**。产品的任务是使这些瓶颈 **可见且可操作** — 由人类 *或* 可以实时更改配方/方法的代理。
核心动词：
```text
forward_backward · optim_step · sample · save_state
```
## 产品界面
| 界面 | 描述 |
|---------|------------|
| **四动词客户端** | 类型训练/采样API；`fake://`，`local://`（torch+PEFT），远程HTTP，vLLM采样工作器 |
| **网页控制平面** | `anvil-web` (:7600) — 配方，参数，运行，关口，观察图表 |
| **RL可观察性** | `metrics.jsonl`（奖励，组标准差 / 优势崩溃，IS比率，损失）+ SSE |
| **实时推理探针** | 当前策略的固定提示每K步 — 在最终评估前观察 |
| **采样/训练分离** | 本地训练；使用LoRA热交换在vLLM上采样 |
| **代理控制** | `AnvilControlClient`，实时暂停/恢复/调整参数， **`anvil mcp`**， **`anvil agent`** |
| **视觉（第三阶段）** | 媒体CAS，轨迹，VLM渲染器，图像模态， `vlm_smoke` |
## 状态
**第二阶段/2.5核心完成 · 第三阶段视觉进行中 · 代理控制平面v0已上线。**
已交付的亮点：
- 类型客户端 + `fake://` / `local://`（手写的torch+PEFT动词，无HF训练器）
- `HFChatRenderer` / `HFVLMRenderer`；训练/采样一致性路径
- HTTP `anvil serve` + `RemoteBackend`；GRPO + IS/PPO；动词队列
- vLLM采样工作器 + 适配器热交换
- 指标，探针， `/observe/{run_id}`；配方关口 + 审计
- 视觉基础 + 图像模态训练路径； `scripts/vlm_smoke.py`
- 代理：控制HTTP客户端，MCP服务器（ `[mcp]` 额外），适配器 + 提示包
J-Lens残余读数（雅各比透镜）是 **可选的研究工具，不是承载负载**：模式 + 评分在 `anvil/observe/jlens.py`， `log_jlens` → `jlens.jsonl`， `GET /api/observe/{run_id}/jlens`，-forge CLI `scripts/jlens_spike.py` (+ `scripts/run_jlens_7b_mixed.sh`隔夜恢复)。 Spike **停放** 2026-07-19 在1.5B/7B数学顺序门控失败J2入口（参见 `docs/spikes/jlens-math.md`）。混合语料库拟合需要实验室主机上的 `datasets` 包。 RL调试器通过指标，探针和瓶颈发货，无需它。
## 快速开始
### 人类 / 个人
```bash
pip install -e ".[web,dev]"
anvil-web --host 0.0.0.0 --port 7600
# 打开 http://localhost:7600
# 实时RL调试器： http://localhost:7600/observe/<run_id>
```
GPU遥测： [spark-dashboard](https://github.com/niklasfrick/spark-dashboard) 在实验室主机上（:3000）。 Anvil拥有 *训练* 信号；spark-dashboard拥有 *硬件* 信号。
```python
from anvil import ServiceClient, Datum, ModelInput, AdamParams
svc = ServiceClient() # fake:// — 无GPU
tc = svc.create_lora_training_client(base_model="toy/TinyLM", rank=8)
datum = Datum(
model_input=ModelInput.from_ints([1, 2, 3, 4]),
loss_fn_inputs={"target_tokens": [2, 3, 4, 5], "weights": [1, 1, 1, 1]},
)
print(tc.forward_backward([datum], "cross_entropy").result().loss)
tc.optim_step(AdamParams(learning_rate=1e-4)).result()
```
### 代理 / MCP
```bash
# 终端A — 控制平面（与UI相同）
anvil-web --port 7600
# 终端B — MCP标准输入输出用于Cursor / Claude Desktop / 自定义主机
pip install -e ".[mcp]"
anvil mcp --url http://127.0.0.1:7600
# 或：anvil-mcp --url http://127.0.0.1:7600
```
```bash
# 仅限可移植提示（粘贴到您的适配器中）
anvil agent --print-prompts
# 可选的Anvil适配器 — 您提供核心
export ANVIL_AGENT_API_KEY=… # 或OPENAI_API_KEY
export ANVIL_AGENT_MODEL=gpt-4o-mini # 任何OpenAI兼容模型
# 可选：ANVIL_AGENT_BASE_URL=https://…/v1
anvil agent "列出运行并暂停正在运行的运行"
```
实时控制HTTP（也用于MCP）：
```http
POST /api/runs/{id}/pause
POST /api/runs/{id}/resume
PATCH /api/runs/{id}/knobs {"knobs": {"learning_rate": 5e-5}}
GET /api/observe/{id}/metrics?tail=50
GET /api/audit
```
### 使用指标 + 探针的RL
```python
from anvil.recipes.grpo import run_grpo
run_grpo(
endpoint="local://…",
sample_endpoint="http://forge:8741", # 空 → 0级进程中
sync_every=5,
run_dir="runs/demo",
probes=[[…token ids…]],
probe_every=10,
)
```
观察 **优势崩溃** (`group_reward_std_mean → 0`)，IS比率漂移和探针文本 — 负面回报的点通常首先在这里显示。
### 视觉烟雾
```bash
PYTHONPATH=. python scripts/vlm_smoke.py --endpoint fake:// --steps 2
# forge: --endpoint local:// --model /mnt/data/models/Qwen2.5-VL-3B-Instruct
```
## 文档
| 文档 | 何时 |
|-----|------|
| **[start.md](start.md)** | 会话入口（人类 + 编码代理） |
| **[docs/product.md](docs/product.md)** | 产品理念 |
| **[docs/agentic-control.md](docs/agentic-control.md)** | MCP / 适配器 / 提示包分割 |
| **[prompts/agent/](prompts/agent/)** | 操作提示（Anvil或外部适配器） |
| [docs/design.md](docs/design.md) | 架构 |
| [docs/roadmap.md](docs/roadmap.md) | 阶段（当前：第三阶段视觉 + 代理v0） |
| [docs/phase3-vision.md](docs/phase3-vision.md) | 视觉切片 |
| [docs/datasets-robotics.md](docs/datasets-robotics.md) | OXE / Bridge / LeRobot / … |
| [docs/governance.md](docs/governance.md) | 决策 & 贡献 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | PR卫生（您合并；代理打开PR） |
## 布局
```text
anvil/
client/ # ServiceClient / TrainingClient / SamplingClient / futures / remote
protocol/ # Datum, ModelInput, 消息，轨迹，序列化
agent/ # AnvilControlClient, MCP服务器，可选适配器
control/ # 会话，适配器注册，门控审计
observe/ # metrics.jsonl + probes.jsonl (+ jlens模式)
render/ # ToyTextRenderer, HFChatRenderer, HFVLMRenderer
media/ # 内容寻址的LocalMediaStore
data/ # JSONL / 路径导入用于VLM和机器人行
backends/ # FakeBackend; LocalBackend（torch+PEFT，图像模态）
workers/ # VLLMSampleBackend
serve/ # anvil serve — 四动词HTTP
web/ # anvil-web控制平面 + /observe
recipes/ # 架构 → 模式 → 计划； GRPO/SFT/VLM
losses/ # 命名的损失注册表
export/ # peft / gguf / onnx / trt标签
docs/ # 产品，设计，路线图，agentic-control，…
prompts/agent/ # 可移植的操作提示包
scripts/ # pull_base_model, vlm_smoke, jlens_spike, run_jlens_7b_mixed, …
tests/
```
## 快速原则
1. **四动词** 在大型 `train()` 之前。
2. **LoRA优先** — 小型工件，热交换，导出。
3. **相同的渲染器** 用于训练和采样（对于RL至关重要）。
4. **边训练边观察** — 标量 + 实时探针捕获负面回报和奖励黑客。
5. **双客户端** — 人类UI和代理MCP/API共享一个SSOT。
6. **您提供智能代理核心** — Anvil封装工具，适配器形状和提示。
7. **视觉和边缘** 在数据模型中是一等公民（不是事后补充）。
8. **审计力度** — 架构门控和方法切换留下痕迹。
## 关键词
训练后 · SFT · RL · GRPO · PPO · DPO · LoRA · PEFT · vLLM · 可观察性 · RL调试器 · 实时探针 · 代理控制 · MCP · 配方门控 · 视觉语言 · 机器人 · Jetson · 边缘AI · 微调 · 大型语言模型训练
## 许可证
[Apache-2.0](LICENSE)
## 移交
在 **此目录** 中打开Grok（或您的代理），输入 `read start.md`，然后一行：
`结果： …`
