# caipiao-driver

**Repository Path**: huoyo/caipiao-driver

## Basic Information

- **Project Name**: caipiao-driver
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FD-Driver

> 非自回归、一次前向传播预测全量输出的语言模型

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

FD-Driver 是一种不用自注意力机制的语言模型，采用**膨胀卷积 + 逐层门控注入**的架构。核心创新：**一次前向传播即可预测全部输出 token**，无需逐 token 自回归生成。

> **⚠️ 勘误（caipiao-driver 派生仓库）**：本仓库源自 FD-Driver，已整体移除 BPE 词表体系与
> 预训练链路（`bpe_tokenizer.py` / `pretrain_data.py` / `train_bpe.py` / `pretrain.py` /
> `generate_data.py` 等脚本已删除），分词器改用号码级 `LotteryTokenizer`（排列三
> 000-999，vocab=1004）。本文档其余上游 NLP 场景描述尚未重写，以
> [docs/TRAINING.md](docs/TRAINING.md) 顶部勘误与 scripts/ 实际文件为准。

---

## 架构

```
输入 IDs → Embedding → GII 主干（N 层膨胀卷积 + 逐层门控注入）→ NAR 输出头
                                                               ├→ softmax(长度)
                                                               └→ 输出矩阵（L_out × vocab）
```

- **GII 主干**：N 层膨胀卷积块（dilation 指数递增覆盖长距离依赖），每层门控注入原文（`h_i = F_i(LayerNorm(h_{i-1} + α_i·W^in·E))`）
- **长度预测头**：单 attention 汇聚后回归输出序列长度
- **NAR 输出头**：一次前向并行出全部 `L_out` 个输出位 logits，无自回归
- **无自注意力主干**：不用 Transformer 的自注意力或 RNN

架构设计定稿见 [docs/V9-MINIMAL-GII-DESIGN.md](docs/V9-MINIMAL-GII-DESIGN.md)，
训练流程见 [docs/TRAINING.md](docs/TRAINING.md)。

### 模型定位

FD-Driver 定位为「语言推理器」：模型只负责理解与阅读，知识由外部输入（提示词、
单据、模板、schema、规则），完成理解 → 抽取 → 路由，执行交给确定性工具。
详见 [docs/i-unit.md](docs/i-unit.md)。

## 项目结构

```
fd-driver/
├── src/fd_driver/               # Python 包
│   ├── config.py                # FullDecoderConfig（V9 GII 单模型配置）
│   ├── model/
│   │   ├── gii.py               # GIIModel（Embedding + GII 主干 + NAR 输出头）
│   │   └── layers.py            # GIIBlock 等自定义层
│   ├── tokenizer/
│   │   ├── lottery_tokenizer.py # 号码级分词器（000-999，vocab=1004）
│   │   └── char_tokenizer.py    # 字符级分词器
│   ├── training/
│   │   └── scheduler.py         # CosineWarmupSchedule 学习率调度
│   ├── data/
│   │   ├── dataset.py           # Dataset 构建（build_dataset / load_jsonl）
│   │   ├── schema.py            # 信封协议解析 + schema 描述段
│   │   ├── generators.py        # SFT 任务数据生成器
│   │   ├── domain_generators.py # 垂直领域数据生成器
│   │   ├── backend_generators.py # 后端场景数据生成器
│   │   ├── knowledge_generators.py # 知识问答数据生成器
│   │   ├── chat_generators.py   # 对话数据生成器
│   │   ├── tool_generators.py   # 工具调用数据生成器
│   │   ├── ood_generators.py    # OOD 泛化扰动生成器
│   │   ├── difficulty_generators.py # 难度分层生成器
│   │   └── augmenter.py         # 数据增强
│   ├── runtime/
│   │   └── tool_runtime.py      # 内置 9 工具 + 三级门控运行时（零 TF 依赖）
│   └── evaluation/
│       └── classifier.py        # TaskClassifier 任务分类器
├── scripts/                     # CLI 入口（现行流程见 docs/TRAINING.md）
│   ├── fetch_pls_data.py        # 排列三历史开奖拉取（体彩官方 API）
│   ├── build_pls_corpus.py      # PLS 训练语料构建（滑窗 + 时间序切分）
│   ├── train.py                 # SFT 训练
│   ├── train_visualize.py       # 训练可视化
│   ├── evaluate.py              # 评估
│   ├── repl.py                  # 交互式推理
│   ├── inspect_data.py          # 数据检查
│   ├── mix_external_corpus.py   # 外部语料混合
│   ├── generate_lang_base.py    # 语言底座语料生成
│   ├── generate_corpus.py       # 领域语料生成
│   ├── prepare_structured_docs.py # 结构化文档生成
│   └── generate_scenario_corpus.py # 场景语料生成
├── tests/                       # pytest 测试
│   ├── conftest.py
│   ├── test_gii.py
│   ├── test_data.py
│   └── test_tokenizer.py
├── docs/
│   ├── V9-MINIMAL-GII-DESIGN.md # V9 架构设计定稿
│   ├── TRAINING.md              # 训练指南（唯一维护的训练文档）
│   ├── MODE3_PRETRAIN_TO_SFT.md # 模式三预训练→SFT 流程
│   ├── i-unit.md                # 范式立场：语言推理器
│   ├── 商业/                    # 商业化路线、市场调研、融资与 BP
│   └── archive/                 # 历史设计文档归档
└── data/                        # 原始数据（raw/）与训练语料（jsonl/）
```

## 安装

```bash
git clone <repo-url>
cd fd-driver
uv sync          # 安装依赖
uv sync --dev    # 安装开发依赖（含 pytest）
```

## 快速开始

### 1. 准备 PLS 训练数据

```bash
# 拉取排列三历史开奖（体彩官方 API → data/raw/pls_history.txt；首次全量，后续增量）
uv run python scripts/fetch_pls_data.py

# 构建训练语料（滑窗 10 期输入 + 时间序切分 → data/jsonl/pls/{train,valid}.jsonl）
uv run python scripts/build_pls_corpus.py
```

> 防泄漏口径：滑窗输入仅含目标期之前的历史；训练/验证按时间序切分，禁止随机打乱。
> 官方 API 不可用时，参考 500.com 爬取脚本（`C:\project\analyze\pls\getpls.py`）。

### 2. 训练模型

```bash
# 可视化训练（推荐主入口）：Web 实时仪表盘，默认端口 6008
# 浏览器访问 http://127.0.0.1:6008（实时曲线 / 在线调参 / 交互测试）
uv run python scripts/train_visualize.py --train data/jsonl/pls/train.jsonl \
    --valid data/jsonl/pls/valid.jsonl --preset medium \
    --max_input_len 16 --max_output_len 4 \
    --epochs 60 --batch_size 64 --version pls1

# CLI 训练（无仪表盘）
uv run python scripts/train.py --train data/jsonl/pls/train.jsonl \
    --valid data/jsonl/pls/valid.jsonl --preset medium \
    --max_input_len 16 --max_output_len 4 \
    --epochs 60 --batch_size 64 --version pls1
```

常用参数（完整列表见 `python scripts/train.py --help`）：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--train` / `--valid` | 必填 / 空 | 训练 / 验证 JSONL |
| `--preset` | medium | 模型尺寸预设（small / medium / large） |
| `--decoder` | ar | 输出解码器（ar=自回归 / nar=并行输出头） |
| `--epochs` | 30 | 训练轮数 |
| `--batch_size` | 32 | 批次大小 |
| `--lr` | 3e-4 | 峰值学习率 |
| `--max_input_len` / `--max_output_len` | 0（取预设 256） | 输入 / 输出长度上限 |
| `--early_stop_patience` | 5 | val_token_acc 早停（0=关闭，需 `--valid`） |
| `--version` | 1 | 存档版本（→ `checkpoints/gii_v{version}.*`） |

> **GPU 训练说明：** 代码内置了 GPU 自动检测、显存按需增长（memory_growth）和混合精度（mixed_float16）支持。
> 依赖默认 `tensorflow[and-cuda]==2.21.0`（RTX 5090 / sm_120 亦可直接训练；首次运行打印
> `compute capability 12.0a` / `jit-compiled from PTX` 属正常提示，kernel 首次编译有一次性开销）。
> TensorFlow >= 2.11 在原生 Windows 上不支持 GPU，请使用 WSL2。

训练产物保存在 `checkpoints/`（V9 存档格式）：
```
checkpoints/
├── gii_v{version}.weights.h5     # 模型权重
├── gii_v{version}.config.json    # 模型配置
└── gii_v{version}.tokenizer.json # 词表
```

### 3. 评估模型

```bash
uv run python scripts/evaluate.py --version pls1 \
    --eval_file data/jsonl/pls/valid.jsonl
```

输出完全匹配率等整体指标。模型结论必须与随机基线数值对比验证——排列三全猜固定号码的
Top-1 基线为 1/1000。

### 4. 交互式推理

```bash
uv run python scripts/repl.py --version <gii_vN>
```

加载存档进行交互式对话测试。

## 模型配置

```python
from fd_driver.config import FullDecoderConfig

config = FullDecoderConfig(
    vocab_size=1004,               # 词表大小（1000 号码 token + 4 特殊 token）
    embed_dim=320,                 # Embedding 维度 d_emb
    hidden_dim=512,                # GII 主干卷积维度 d_hidden
    num_layers=8,                  # GII 主干层数 N
    dilations=[1, 2, 4, 8, 16, 1, 2, 4],  # 每层膨胀率
    conv_kernel_size=3,            # 卷积核大小
    dropout_rate=0.1,              # Dropout 比例
    max_input_len=256,             # 最大输入长度
    max_output_len=256,            # 最大输出长度
    max_history_len=256,           # 多轮历史最大字符数
    length_weight=10.0,            # 长度回归损失权重
    label_smoothing=0.0,           # 标签平滑
    structure_loss_weight=2.5,     # 数字/JSON 结构符 token 提权
    weight_decay=1e-5,             # L2 权重衰减
)
```

## 运行测试

```bash
uv run pytest tests/ -v
```

## 与 Transformer 对比

| 特性 | Transformer（自回归） | FD-Driver |
|------|----------------------|-----------|
| 生成方式 | 逐 token，N 次前向 | 一次前向，全量输出 |
| 推理复杂度 | O(N) | O(1) |
| 核心组件 | 自注意力 + FFN | 膨胀卷积 + 门控注入 |
| KV Cache | 需要 | 不需要 |
| 推理速度 | 随输出长度线性增长 | 恒定 |
| 边缘部署 | 困难（显存大） | 友好（轻量） |

## 许可证

[MIT](LICENSE)