# agnesLlm

**Repository Path**: zhongjack/agnes-llm

## Basic Information

- **Project Name**: agnesLlm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agnes LLM / llm-engine

双轨引擎：**Native**（Rust 手写反传，CPU 从零训 tiny/small/medium）+ **HF/Candle**（GPU 加载开源 Instruct 小模型推理）。

## 能力一览

| 能力 | 状态 |
|------|------|
| Causal Attention + CE + AdamW + Checkpoint V2 | ✅ Native |
| 真实 BPE（train / save / load）+ `tiny`/`small`/`medium` | ✅ |
| ChatML（`--chat` / `--system`） | ✅ |
| 文本 / 目录 / 网站 / 数据库 / 图片 / 视频 / 音频 语料 | ✅ |
| HuggingFace Qwen2-0.5B-Instruct（GGUF）via Candle | ✅ `--features gpu` |
| CUDA | ✅ `--features cuda`（需本机 CUDA） |
| Go CGO + gRPC（native / hf） | ✅ |
| 手写 CUDA 训练 / 亿级预训练 | ❌ 不在本仓库范围 |

| Preset | 结构 | vocab | seq | 约参数 | 用途 |
|--------|------|-------|-----|--------|------|
| `tiny` | 2L/d=32/4H | 256 | 8 | ~0.11M | 冒烟 |
| `small` | 4L/d=64/4H | 1024 | 64 | ~1M+ | 小语料 + BPE |
| `medium` | 6L/d=256/8H | 8192 | 256 | ~20M | CPU 短训验证 |

---

## 环境

```powershell
cd e:\work\ems\code\ai\agnes-llm
$env:PATH = "C:\Users\zhongguoxin\.cargo\bin;D:\mingw64\bin;" + $env:PATH

cargo +stable-x86_64-pc-windows-gnu test --lib
# 通用推理（Candle，可 CPU）
cargo +stable-x86_64-pc-windows-gnu test --features gpu --lib
# 有 NVIDIA CUDA 时
cargo +stable-x86_64-pc-windows-gnu build --release --features cuda
```

---

## 阶段 A — BPE + medium（Native 训练）

```powershell
# small：从语料现场训词表，保存到 checkpoints/small.tok.json
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-trainer -- `
  --model small --data data/tiny.txt --steps 200

# medium（CPU 较慢，建议先减步数）
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-trainer -- `
  --model medium --data data/tiny.txt --steps 50 --seq-len 128

# 复用已有词表
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-trainer -- `
  --model small --data data/tiny.txt --tokenizer checkpoints/small.tok.json --resume --steps 100

# Native 推理（必须带同一 tokenizer）
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-infer -- "Hello!" `
  --checkpoint checkpoints/small.ckpt `
  --tokenizer checkpoints/small.tok.json `
  --temperature 0 --max-tokens 48
```

`tiny` 仍可走字节词表（无 BPE）。`small`/`medium` 默认会训/写 `.tok.json`。

---

## 阶段 C — 对话格式（ChatML）

```powershell
# 训练：纯文本行 → user/assistant 对；或 JSONL messages
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-trainer -- `
  --model small --data data/tiny.txt --chat --steps 200

# 推理
cargo +stable-x86_64-pc-windows-gnu run --release --bin llm-infer -- "用一句话介绍你自己" `
  --checkpoint checkpoints/small.ckpt `
  --tokenizer checkpoints/small.tok.json `
  --chat --system "你是简洁助手" `
  --temperature 0 --max-tokens 64
```

JSONL 示例：

```json
{"messages":[{"role":"user","content":"1+1?"},{"role":"assistant","content":"2"}]}
```

---

## 阶段 B — GPU / HF 通用推理（Candle）

首次运行会从 HuggingFace 拉取 GGUF（需网络）。默认模型：`Qwen/Qwen2-0.5B-Instruct`。

```powershell
# CPU Candle
cargo +stable-x86_64-pc-windows-gnu run --release --features gpu --bin llm-infer -- `
  "用一句话介绍 Rust" `
  --backend hf --device cpu `
  --system "你是助手" `
  --max-tokens 64 --temperature 0.7

# CUDA（需 --features cuda + 本机 CUDA）
cargo +stable-x86_64-pc-windows-gnu run --release --features cuda --bin llm-infer -- `
  "你好" --backend hf --device cuda --max-tokens 64
```

也可传本地 `.gguf` 路径：`--hf-model D:\models\qwen2-0_5b-instruct-q4_k_m.gguf`。

Go / gRPC（DLL 需带 `gpu` 编过）：

```powershell
$env:CARGO_TARGET_DIR = "$PWD\target"
cargo +stable-x86_64-pc-windows-gnu build --release --features gpu

cd go
go run ./cmd/server -addr 127.0.0.1:50051 -checkpoint ../checkpoints/small.ckpt
# 另一终端
go run ./cmd/client -addr 127.0.0.1:50051 -prompt "你好" -backend hf -max-tokens 64
go run ./cmd/client -addr 127.0.0.1:50051 -prompt "Hello!" -chat -system "be brief" -temperature 0
```

---

## 其它语料入口（与通用大模型轨共用 trainer）

```powershell
# 目录 / 网站 / 数据库 / 图片 / 视频 / 音频 —— 详见历史用法
--dir PATH | --url URL | --db taos|influx|postgres | --image | --video | --audio
```

数据源互斥规则见 `llm-trainer --help` 风格 Usage 输出。

---

## 参数速查

**llm-trainer**：`--model tiny|small|medium`、`--tokenizer`、`--chat`、`--data/--dir/--url/--db/...`、`--resume`、`--steps/--seq-len/--batch-size/--lr`

**llm-infer**：`--backend native|hf`、`--checkpoint`、`--tokenizer`、`--chat`、`--system`、`--hf-model`、`--device cuda|cpu`、`--max-tokens`、`--temperature`

中间产物：`checkpoints/<model>.ckpt`、`checkpoints/<model>.tok.json`、`data/last_*.txt`

## 从 1-bmo-e 对齐的优化

参考同目录 [`1-bmo-e`](../1-bmo-e)（Llama 风格解码器 + ChatML SFT + 端侧部署）已落地：

| 能力 | 说明 |
|------|------|
| 词表绑定 | 新模型 `tie_embeddings`：`lm_head = wte^T`（旧 ckpt 仍 untied） |
| RoPE | native 默认 `use_rope`（θ=10000）；旧 V2 ckpt 无字段时仍用 learned `wpe` |
| KV-cache decode | `generate` 预填 + 增量解码；`Tensor::concat` 保证 contiguous |
| 残差初始化 | `c_proj` / `ffn.w3` 按 `0.02/√(2L)` 缩放 |
| ChatML SFT mask | `--chat` 时仅对 assistant 段计 CE（`LABEL_IGNORE=-100`） |
| 重复惩罚 | native 推理默认 `repetition_penalty=1.15` |
| AdamW | norm / emb / lm_head 不做 weight decay |
| SpikeGuard + metrics | 训练写 `*.metrics.jsonl`，暴涨 step 告警 |

尚未移植（工作量大 / 属另一训练栈）：真 GQA、稀疏 MoE、Encoder→多 LoRA 路由。GPU 通用对话继续走 Candle `--backend hf`。