CodeSprite 是一个代码结构分析与转换工具，基于框架无关的 IR（中间表示）架构。
核心分析层（
ir/）不依赖任何计算框架（PyTorch/NumPy），计算由可插拔的backends/后端提供。 同一套分析逻辑可以：用 PyTorch 训练，用 NumPy 纯 CPU 推理，导出为 GGUF/ONNX 格式。
约 3800 万参数的计算核心，Transformer Decoder 架构，支持 Python 及主流编程语言的代码结构分析，支持中英文双语处理。 集成 RoPE 旋转位置编码、SwiGLU 门控前馈网络、GQA 分组查询注意力等现代技术。支持 KV-Cache 推理加速，CPU 即可流畅运行。
| 项目 | 最低要求 | 推荐 |
|---|---|---|
| Python | 3.10+ | 3.12 |
| PyTorch | 2.0+ | 2.8+ (CUDA 12.x) |
| GPU 显存 | - | >= 2 GB（训练时约需 0.5 GB） |
| 操作系统 | Windows / Linux / macOS | - |
| CUDA | - | 11.8+（GPU 加速） |
设备策略：训练优先 GPU，自动回退 CPU（可通过
--no-cpu-fallback禁用回退）；推理默认 CPU，可按需切换 GPU。CPU 线程数可通过config.yaml的system.cpu_threads控制（老电脑建议设为 2）。
先安装与你系统匹配的 PyTorch 版本，参考官网：https://pytorch.org/get-started/locally/
# Linux + CUDA 12.x（推荐）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
# Windows + CUDA 12.x
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
# macOS（MPS 加速）
pip install torch torchvision
# CPU only（无 GPU）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpugit clone https://github.com/bthitzepw/codesprite.git
cd codesprite
pip install -r requirements.txtrequirements.txt 包含以下依赖：
torch>=2.0.0
numpy>=1.24.0
tqdm>=4.65.0
pyyaml>=6.0
tensorboard>=2.14.0
flask>=2.0.0
# 1. 安装依赖
pip install -r requirements.txt
# 2. 准备数据（见下一节），然后训练
python train.py
# 3. 训练完成后，交互式生成
python generate.py如果你有训练好的 best_model.pt 文件：
# 将权重文件放入 checkpoints 目录
mkdir -p checkpoints
cp your_best_model.pt checkpoints/best_model.pt
# 直接开始对话
python generate.py训练数据放在 data/raw/ 目录下，需要三个文件：
data/raw/
├── train.txt # 训练集（必需）
├── val.txt # 验证集（必需）
└── test.txt # 测试集（评估时使用）
每行一条训练样本，支持中英文混合文本。本项目聚焦代码编程领域，建议使用以下类型的数据：
def fibonacci(n):
"""计算斐波那契数列第n项"""
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
# 快速排序算法
def quicksort(arr):
if len(arr) <= 1:
return arr
pivot = arr[len(arr) // 2]
left = [x for x in arr if x < pivot]
middle = [x for x in arr if x == pivot]
right = [x for x in arr if x > pivot]
return quicksort(left) + middle + quicksort(right)
function binarySearch(arr, target) {
let left = 0, right = arr.length - 1;
while (left <= right) {
let mid = Math.floor((left + right) / 2);
if (arr[mid] === target) return mid;
if (arr[mid] < target) left = mid + 1;
else right = mid - 1;
}
return -1;
}
- 训练集：建议 1000 条以上，越多越好
- 验证集：建议 50-100 条，用于监控过拟合
- 测试集：建议 30-50 条，用于最终评估
- 质量：优先数据质量而非数量，确保代码正确、格式规范
- 多样性：覆盖多种编程语言（Python / JavaScript / Java / C++ / Go / Rust / SQL 等）
本项目使用内置的 SimpleTokenizer（字符级 BPE，词表大小 4268），支持 ASCII 字符、CJK 汉字和常见代码符号。无需额外预训练分词器，开箱即用。
如需调整词表大小，修改 config/config.yaml 中的 vocab_size。
python train.py使用 config/config.yaml 中的默认配置开始训练。
# 启用 EMA（推荐用于追求推理稳定性）
python train.py --use-ema
# 禁用混合精度（调试时使用，或显存不足时）
python train.py --no-amp
# 启用梯度检查点（用计算换显存）
python train.py --use-checkpointing
# 禁用 RoPE 或 SwiGLU（用于消融实验）
python train.py --no-rope
python train.py --no-swiglu
# 自定义超参数
python train.py --lr 0.001 --epochs 20 --batch-size 32
# 设置标签平滑值
python train.py --label-smoothing 0.1| 参数 | 默认值 | 说明 |
|---|---|---|
--mode |
standard |
训练模式：standard / auto / find-lr |
--lr |
0.0003 | 学习率（覆盖配置文件） |
--epochs |
10 | 训练轮数 |
--batch-size |
16 | 批量大小 |
--device |
auto |
设备选择：auto / cuda / cpu |
--no-cpu-fallback |
- | GPU 不可用时直接报错，不静默回退 CPU |
--no-amp |
False | 禁用混合精度训练 |
--no-rope |
False | 禁用 RoPE 位置编码 |
--no-swiglu |
False | 禁用 SwiGLU 前馈网络 |
--use-ema |
False | 启用指数移动平均 |
--use-checkpointing |
False | 启用梯度检查点 |
--label-smoothing |
0.05 | 标签平滑系数 |
训练过程中会输出每个 epoch 的训练损失和验证指标：
Epoch 6/10 Summary:
Train Loss: 4.2698
Val Loss: 3.2807
Perplexity: 26.60
Learning Rate: 6.00e-05
Epoch Time: 15.5s
Total Time: 94.1s
>> New best model! Val Loss: 3.2807
- Train Loss：训练集上的平均损失，越低越好
- Val Loss：验证集上的损失，用于判断是否过拟合
- Perplexity：困惑度（PPL = e^loss），数值越低表示预测越准确
- < 10：优秀
- < 30：良好
- < 100：一般
-
500：需要更多训练
- Early Stopping：验证损失连续 5 个 epoch 没有改善时自动停止训练
训练完成后，权重文件保存在 checkpoints/ 目录：
checkpoints/
├── best_model.pt # 验证损失最低的权重（推荐使用这个）
├── checkpoint_epoch_8.pt # 第 8 轮检查点
├── checkpoint_epoch_9.pt # 第 9 轮检查点
└── checkpoint_epoch_10.pt # 第 10 轮检查点
注意：
checkpoints/目录和.pt文件已在.gitignore中排除，不会上传到 GitHub。如需分享权重文件，建议使用 Hugging Face Hub、Google Drive 等平台。
将 best_model.pt 放入 checkpoints/ 目录后，直接运行 python train.py 即可自动加载并继续训练。
自动寻找最优学习率：
python train.py --find-lr程序会绘制 loss-lr 曲线并建议最佳学习率。
# PyTorch 后端（默认）
python generate.py
# NumPy 后端（纯 CPU，无需 PyTorch）
python generate.py --backend numpy
# 指定 GPU 设备
python generate.py --device cuda进入交互模式后：
You: def fibonacci(n):
Model: def fibonacci(n):
"""计算斐波那契数列第n项"""
if n <= 1:
return n
...
You: :temp 0.5
Temperature set to 0.5
You: quit
Goodbye!
| 命令 | 说明 |
|---|---|
<文本> |
输入提示，生成续写 |
:temp <n> |
设置温度（0.1-2.0，越低越确定性） |
:topk <n> |
设置 Top-K（1-200） |
:topp <n> |
设置 Top-P（0.0-1.0，nucleus 采样） |
:len <n> |
设置最大生成长度（10-500） |
:info |
显示模型信息 |
quit / exit / q |
退出 |
python evaluate.py输出包含：
- Perplexity（困惑度）：核心指标
- Token-level Loss：平均损失
- 生成质量抽检：对 8 个预设代码提示进行生成测试
- 质量评级：根据 PPL 自动评级
python web_app.py浏览器打开 http://localhost:5000
- 代码分析控制台（带反馈按钮）
- 输出内容安全过滤
- 自动化输出标识
- 用户协议与隐私政策页面
- 学习状态控制面板
| 系统 | 命令 |
|---|---|
| Linux / macOS | ./start_web.sh |
| Windows | 双击 start_web.bat |
启动后访问 http://localhost:5000 即可使用。
# Linux/macOS 高级选项
./start_web.sh --port 8080 # 指定端口
./start_web.sh --debug # 调试模式
./start_web.sh --help # 查看帮助所有配置集中在 config/config.yaml：
model:
vocab_size: 4268 # 词表大小
hidden_size: 512 # 隐藏层维度
num_layers: 8 # Transformer 层数
num_heads: 8 # 注意力头数
intermediate_size: 2048 # FFN 中间层维度
dropout: 0.1 # Dropout 比率
max_seq_length: 512 # 最大序列长度
tie_weights: true # Embedding 与 LM Head 权重共享
use_rope: true # RoPE 旋转位置编码
use_swiglu: true # SwiGLU 前馈网络
training:
batch_size: 16 # 批量大小
learning_rate: 0.0003 # 学习率
num_epochs: 10 # 训练轮数
warmup_steps: 500 # 预热步数
gradient_accumulation_steps: 4 # 梯度累积步数（等效 batch = 16×4 = 64）
max_grad_norm: 1.0 # 梯度裁剪
weight_decay: 0.01 # 权重衰减
use_amp: true # 混合精度（FP16 加速 + 节省显存）
label_smoothing: 0.05 # 标签平滑（防止过拟合）
use_ema: false # EMA（指数移动平均）
early_stopping_patience: 5 # 早停耐心值
save_total_limit: 3 # 最多保留 N 个检查点
system:
device: "auto" # 设备策略: auto(自动最优) / cuda / cpu
seed: 42 # 随机种子
checkpoint_dir: "checkpoints"
log_dir: "logs"Web 服务启动后（python web_app.py），可通过 API 调用分析服务。
curl -X POST http://localhost:5000/api/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "def hello():", "max_new_tokens": 100, "temperature": 0.8}'响应：
{
"success": true,
"text": "def hello():\n print('Hello, World!')\n...",
"session_id": "xxx",
"interaction_id": "xxx"
}curl http://localhost:5000/api/infocurl http://localhost:5000/api/healthcurl -X POST http://localhost:5000/api/feedback \
-H "Content-Type: application/json" \
-d '{"interaction_id": "xxx", "feedback": 1}'feedback 值：1（赞）、-1（踩）、0（无反馈）
| 端点 | 方法 | 说明 |
|---|---|---|
/api/generate |
POST | 代码分析 |
/api/info |
GET | 引擎信息 |
/api/health |
GET | 健康检查 |
/api/feedback |
POST | 提交反馈（赞/踩） |
/api/learning-status |
GET | 自动学习状态 |
/api/learning/start |
POST | 手动触发增量学习 |
/api/learning/config |
GET/POST | 学习配置管理 |
/api/user-rights |
GET | 用户权利概览 |
/api/data-export |
GET | 数据导出 |
/api/data-delete |
POST | 数据删除 |
编辑 config/config.yaml：
auto_learning:
enabled: true # 启用自动学习
min_feedback_samples: 20 # 积累 20 条反馈后触发学习
incremental_epochs: 3 # 增量训练 3 轮
incremental_lr: 0.00005 # 使用更小的学习率
augmentation_enabled: true # 启用数据增强- 用户通过 Web 界面提交代码分析请求
- 对分析结果点赞/点踩，系统自动记录反馈
- 当正面反馈样本达到阈值时，自动触发增量训练
- 也可以通过 API 手动触发：
POST /api/learning/start
# PyTorch 后端（GPU 推理）
python generate.py --backend pytorch --device cuda
# NumPy 后端（CPU 推理，无需安装 PyTorch）
python generate.py --backend numpy# GGUF 导出（用于 llama.cpp）
from export.gguf import export_gguf
export_gguf(model, "codesprite.gguf")
# ONNX 导出
from export.onnx import export_onnx
export_onnx(model, "codesprite.onnx")python tools/convert_checkpoint.py --old checkpoints/best_model.pt --new checkpoints/best_model_v2.pt前几个 epoch 出现 inf 通常是因为 warmup 阶段学习率极小，模型输出数值不稳定。训练几个 epoch 后学习率上升，Val Loss 会自动恢复正常。如果持续为 inf，尝试：
- 增大学习率：
--lr 0.001 - 减小 warmup 步数：修改
config.yaml中warmup_steps - 禁用混合精度：
--no-amp
可以。程序默认允许 CPU 回退（CODESPRITE_ALLOW_CPU_FALLBACK=true），但会打印警告。CPU 训练速度约为 GPU 的 1/10~1/50，建议：
- 减小
batch_size - 减小
num_epochs - 使用 Google Colab（免费 GPU）等平台
如果不希望静默回退，使用 --no-cpu-fallback 参数让程序在 GPU 不可用时直接报错。
将数据按行写入 data/raw/train.txt、data/raw/val.txt、data/raw/test.txt，每行一条样本，然后直接运行 python train.py。
checkpoints/ 目录已在 .gitignore 中排除。如需分享权重，推荐：
- Hugging Face Hub（推荐，免费）
- Google Drive
- 百度网盘
修改 config/config.yaml：
model:
hidden_size: 256 # 减小隐藏层（更轻量）
num_layers: 4 # 减少层数
num_heads: 4 # 减少注意力头
# 或增大以获得更强能力
hidden_size: 768
num_layers: 12
num_heads: 12注意：修改架构参数后，旧的检查点将不兼容，需要重新训练。
不支持，也不建议用于仓颉代码分析。
仓颉语言的开源训练语料几乎为零，3800 万参数的小型引擎对此类低资源语言产生严重幻觉 — 引擎会把它见过的 C/C++/Rust 语法"缝合"成看似合理但实际上完全错误的仓颉代码。
如果你正在学习仓颉，建议将本工具定位为**"语法翻译参考"**（例如把 Python 代码的大致逻辑转成仓颉代码骨架，然后自行修正），而非"代码输出工具"。同理也适用于其他小众编程语言（Haskell、COBOL 等）。
更多语言支持的风险评估见 RISKS.md。
本项目不依赖 npm/Node.js，纯 Python 项目，不受影响。
chmod +x start_web.sh
./start_web.shpython3 -c "import torch; print(torch.cuda.is_available())"
# 应输出: True
# 查看 GPU 型号
python3 -c "import torch; print(torch.cuda.get_device_name(0))"codesprite/
├── ir/ # 核心分析层定义（零框架依赖）
│ ├── config.py # ModelConfig 数据类
│ ├── layers.py # 抽象层定义（Linear/Attention/FFN等）
│ ├── transformer.py # 完整 Transformer 结构
│ └── graph.py # 计算图（预留）
├── backends/ # 计算后端实现
│ ├── base.py # Backend 抽象接口
│ ├── pytorch.py # PyTorch 后端（训练用）
│ └── numpy.py # NumPy 后端（纯CPU推理）
├── training/ # 训练模块
│ ├── trainer.py # 后端无关训练器
│ └── optimizer.py # 优化器工具
├── inference/ # 推理接口
│ └── engine.py # 推理引擎（自动选后端）
├── export/ # 跨平台导出
│ ├── gguf.py # GGUF 格式导出（llama.cpp兼容）
│ └── onnx.py # ONNX 格式导出
├── tools/ # 工具脚本
│ ├── convert_checkpoint.py # 旧权重转换工具
│ └── build_nuitka.py # Nuitka 打包脚本（Windows 64-bit）
├── config/
│ └── config.yaml # 引擎和训练配置
├── data/
│ └── raw/ # 训练数据
├── src/ # 核心组件
│ ├── tokenizer.py # 分词器 + 数据集（框架无关）
│ ├── device.py # 统一设备管理（检测/回退/资源隔离）
│ ├── model.py # CodeSprite 核心计算类
│ ├── moderator.py # 内容审核
│ ├── compliance.py # 安全合规
│ ├── auto_learner.py # 自动增量学习
│ └── trainer.py # 训练器
├── templates/ # Web 前端
├── train.py # 训练入口
├── generate.py # 交互式分析
├── evaluate.py # 引擎评估
├── web_app.py # Flask Web 服务
├── start_web.sh # 启动脚本 (Linux/macOS)
├── start_web.bat # 启动脚本 (Windows)
├── requirements.txt # Python 依赖
├── .gitattributes # Git 换行符统一规则
├── LICENSE # MIT
├── RISKS.md # 风险与隐患登记册
├── ROADMAP.md # 路线图
├── INVISIBILITY.md # 隐形架构设计规范
└── README.md
┌──────────────────────┐
│ ir/ (核心分析层) │
│ 零框架依赖，纯结构描述 │
└──────────┬───────────┘
│ delegate
┌───────────────┼───────────────┐
↓ ↓ ↓
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PyTorch后端 │ │ NumPy后端 │ │ (MLX后端) │
│ 训练+GPU推理 │ │ CPU纯推理 │ │ Apple芯片 │
└─────────────┘ └─────────────┘ └─────────────┘
↓ ↓
┌─────────────┐ ┌─────────────┐
│ GGUF导出 │ │ ONNX导出 │
│ llama.cpp │ │ ONNX Runtime │
└─────────────┘ └─────────────┘
核心思想：核心分析逻辑与计算框架完全解耦。ir/ 中的代码不 import torch，不 import numpy，只描述"有哪些层、长什么样"。具体怎么算由 backends/ 决定。
Transformer Decoder (LLaMA 风格)
┌──────────────────────────────────┐
│ Token Embedding │
│ Dropout │
├──────────────────────────────────┤
│ TransformerBlock × 8 │
│ ├── RMSNorm (Pre-Norm) │
│ ├── Self-Attention (GQA) │
│ │ ├── RoPE Position Encoding │
│ │ ├── Rotating KV-Cache │
│ │ └── Causal Masking │
│ ├── Residual │
│ ├── RMSNorm (Pre-Norm) │
│ ├── SwiGLU FeedForward │
│ └── Residual │
├──────────────────────────────────┤
│ Final RMSNorm │
│ LM Head (Tied Weights) │
└──────────────────────────────────┘
Parameters: ~37.9M | Hidden: 512 | Heads: 8 | Layers: 8
Vocab: 4268 | Context: 512 tokens | Activation: SwiGLU
Position: RoPE | Norm: RMSNorm | Attention: GQA
详见 ROADMAP.md — 涵盖 IR 架构增强、输出能力优化、工程化与生态建设。
MIT License