v2.0.0 — 重大重构

发布日期: 2026年3月9日
完整变更: v1.0.0 → v2.0.0

⚠️ 破坏性变更

KVCache API 重新设计

问题: 之前的 appendKV() 实现存在脆弱的层序依赖，如果层以不同顺序调用可能导致错误的缓存写入。

解决方案: 新的无状态设计，显式推进长度。

之前 (v1.x)

class="highlight">
1
2
3

// 第 0 层会更新 current_len，其他层需要补偿
// 如果层序改变会崩溃
kv_cache.appendKV(seq_id, layer_idx, k, v, num_tokens);

之后 (v2.0+)

class="highlight">
1
2
3
4
5
6

// appendKV 无状态 - 所有层都写入 current_len
for (int i = 0; i < num_layers; i++) {
    layers[i]->forward(hidden_states, kv_cache, seq_id, position, stream);
}
// 所有层完成后显式推进长度
kv_cache.advanceSeqLen(seq_id, num_tokens);

迁移: 任何直接使用 KVCacheManager 的代码都需要更新。参见下方的 迁移指南。

🟢 新增

CI/CD 改进

  • GitHub Actions 持续集成工作流
  • 自动 clang-format 检查
  • Pull Request 格式验证

CMake 现代化

特性 之前 之后
版本 1.0.0 2.0.0
CUDA 架构 手动 自动检测（原生或回退）
Include 全局 target_include_directories()
Target 导出 无 tiny_llm::tiny_llm 别名
警告 基础 -Wall -Wextra (GCC/Clang)
IDE 支持 手动 compile_commands.json 生成

新的使用方式:

class="highlight">
1
2

find_package(tiny_llm)
target_link_libraries(myapp tiny_llm::tiny_llm)

🟡 变更

构建系统

  • 最低 CMake 版本：3.18
  • CUDA 架构自动检测，带常见架构回退
  • 改进的编译器警告标志

测试覆盖

  • 使用 RapidCheck 添加基于属性的测试
  • 扩展 kernel 测试覆盖
  • 端到端工作流集成测试

🔄 迁移指南

更新 KVCache 使用

如果代码中直接使用 KVCacheManager：

class="highlight">
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// v1.x 代码
void generateStep() {
    for (int i = 0; i < num_layers; i++) {
        // appendKV 内部管理长度
        kv_cache.appendKV(seq_id, i, k_data[i], v_data[i], 1);
    }
}

// v2.0+ 代码
void generateStep() {
    for (int i = 0; i < num_layers; i++) {
        // appendKV 无状态
        kv_cache.appendKV(seq_id, i, k_data[i], v_data[i], 1, stream_);
    }
    // 必须显式推进
    kv_cache.advanceSeqLen(seq_id, 1);
}

标准用例中 InferenceEngine 类自动处理此逻辑。

📊 性能

指标 v1.0.0 v2.0.0 变化
构建时间 45s 38s -15%
测试运行时间 2.1s 1.8s -14%
显存 (KV 缓存) 相同 相同 仅正确性修复
吞吐 相同 相同 无影响

✅ 验证

class="highlight">
1
2
3
4
5

$ ctest --output-on-failure
100% tests passed, 0 tests failed

$ clang-format --dry-run --Werror src/*.cpp tests/*.cpp kernels/*.cu
$ # 无输出 = 无格式问题

📚 文档

新的文档结构：

  • 多语言支持 (EN/ZH)
  • 带示例的 API 参考
  • 架构文档
  • 贡献指南

← 返回更新日志

Back to top

Quick Links