LlamaCpp.Bindings：轻量级C# LLM推理绑定库

一个手工打造的C#绑定库，专注于llama.cpp的核心功能，以极简代码实现本地LLM推理，强调可维护性和快速迭代。

在.NET生态中，LLamaSharp已经成为与llama.cpp交互的主流选择。它功能全面、文档完善，适合大多数生产场景。然而，对于某些开发者来说，LLamaSharp的庞大代码库和复杂架构带来了维护负担。当llama.cpp频繁更新时，跟进这些变化需要投入大量时间。

LlamaCpp.Bindings项目采用了不同的哲学：牺牲功能广度换取维护简洁性。正如项目作者所说，这是一个"小到可以在一个下午理解全貌"的库，更新llama.cpp版本通常只需要"十分钟左右的差异对比和应用工作"。

LlamaCpp.Bindings不追求全面覆盖llama.cpp的C API，而是专注于最核心的使用场景：

包含的功能：

• 加载单个GGUF模型文件
• 通过IAsyncEnumerable实现流式生成
• 现代化的链式采样器配置
• 基于GGUF内嵌Jinja模板的多轮对话支持
• KV缓存生命周期管理

明确排除的功能：

• llama.cpp C API的完整覆盖
• 多用户批处理
• 模型训练功能
• llama-server已经做得很好的功能

这种取舍使得代码库保持精简，开发者可以快速定位和理解任何部分的实现。

LlamaCpp.Bindings采用清晰的三层架构，从底层到高层依次是：

第一层：P/Invoke层

使用.NET 7+的[LibraryImport]属性进行原生函数声明，配合[StructLayout(Sequential)]确保结构体内存布局与C代码完全一致。每个镜像结构体在模块初始化时都会验证字节大小，如果发现ABI漂移，库会拒绝加载而不是默默导致内存损坏。

第二层：SafeHandle层

为每个不透明的原生指针提供SafeHandle包装，确保资源正确释放。这一层防止了内存泄漏和悬挂指针问题。

第三层：公共API层

提供符合.NET习惯的IDisposable类，包括：

• LlamaBackend：进程级初始化和日志路由
• LlamaModel：GGUF模型加载、词表访问、对话模板
• LlamaContext：会话状态管理和KV缓存
• LlamaVocab：分词和解分词
• LlamaSampler：流式采样器构建器
• LlamaGenerator：IAsyncEnumerable生成循环
• LlamaChatTemplate：Jinja模板渲染包装

有趣的是，公共C#方法的命名刻意与C函数名保持一致（如llama_decode而非LlamaDecode）。这种看似反直觉的设计实际上有明确目的：当对比llama.cpp头文件差异时，可以机械地应用变更，减少认知负担和出错概率。

使用LlamaCpp.Bindings进行推理非常直观：

using LlamaCpp.Bindings;

// 初始化后端
LlamaBackend.Initialize();

// 加载模型
using var model = new LlamaModel("/path/to/model.gguf", 
    new LlamaModelParameters
    {
        GpuLayerCount = -1,  // 所有层使用GPU
        UseMmap = true,
    });

// 创建上下文
using var context = new LlamaContext(model, 
    new LlamaContextParameters
    {
        ContextSize = 2048,
    });

// 配置采样器
using var sampler = new LlamaSamplerBuilder()
    .WithTopK(40)
    .WithTopP(0.9f)
    .WithMinP(0.05f)
    .WithTemperature(0.7f)
    .WithDistribution(seed: 42)
    .Build();

// 生成文本
var generator = new LlamaGenerator(context, sampler);
await foreach (var piece in generator.GenerateAsync(
    "Hello, who are you?", maxTokens: 128))
{
    Console.Write(piece);
}

项目包含一套完整的维护工具链，位于tools/目录：

• fetch-binaries.py：从llama.cpp发布页面下载原生二进制文件
• extract-api.py：使用libclang解析llama.h为结构化JSON
• diff-api.py：对比两个JSON快照生成Markdown报告
• xref-bindings.py：将差异与C#源码交叉引用
• check-for-updates.sh：协调整个更新流程
• dump-struct-sizes.{c,sh}：捕获结构体大小和偏移的基准值

这套工具链让跟进llama.cpp更新变得系统化：获取最新版本→生成差异报告→识别需要修改的绑定代码→验证结构体布局→运行测试。

源码组织：

• src/LlamaCpp.Bindings/：核心绑定库
• src/LlamaCpp.Bindings.Tests/：xUnit测试（结构体布局、分词、对话、生成、多轮）
• samples/LlamaChat.Cli/：最小化控制台REPL，推荐入门示例
• samples/LlamaChat/：基于Avalonia MVVM的桌面聊天应用

测试覆盖：

项目实现了85个测试用例，全部通过。其中包括在真实NVIDIA GPU上使用Qwen3 MoE模型进行的端到端生成测试，验证了绑定在实际硬件上的可靠性。