zhongkaifu/TensorSharp

来源：https://github.com/zhongkaifu/TensorSharp

TensorSharp

English | 中文

面向 GGUF 模型的原生 .NET LLM 推理引擎，支持自回归 LLM 和 DiffusionGemma 风格的文本扩散模型。TensorSharp 提供控制台应用程序、基于 Web 的聊天界面，以及 Ollama/OpenAI 兼容的 HTTP API，便于编程访问。

快速开始

从零开始到流式回复，大约需要 30 秒（模型下载完成后）。

1. 先决条件 — .NET 10 SDK (https://dotnet.microsoft.com/download/dotnet/10.0)、git，以及（可选）GPU 工具链：NVIDIA → CUDA Toolkit 12.x；Apple Silicon → Xcode 命令行工具（Metal 内置）。完整列表请查看先决条件。

2. 克隆与构建 — 原生 GGML 库在首次构建时自动编译。

git clone https://github.com/zhongkaifu/TensorSharp.git
cd TensorSharp
dotnet build TensorSharp.slnx -c Release

3. 下载模型 — 一个体积小、经过充分测试的入门模型是来自 ggml-org/gemma-4-E4B-it-GGUF (https://huggingface.co/ggml-org/gemma-4-E4B-it-GGUF) 的 Gemma-4-E4B (Q8_0)。更多选择请参考已验证模型。

4. 运行 — 根据你的硬件选择 --backend（参见选择后端）：

# 单次生成
echo "用一句话解释混合专家模型。" > prompt.txt
./TensorSharp.Cli --model gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend ggml_metal  # macOS
./TensorSharp.Cli --model gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend ggml_cuda  # Windows/Linux + NVIDIA
./TensorSharp.Cli --model gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend cpu        # 可移植 / 调试

# 交互式聊天（REPL）
./TensorSharp.Cli --model gemma-4-E4B-it-Q8_0.gguf -i --backend ggml_metal

更喜欢浏览器 UI 加 HTTP API？启动服务器即可：

./TensorSharp.Server --model gemma-4-E4B-it-Q8_0.gguf --backend ggml_metal
# 打开 http://localhost:5000 — 同时提供 Ollama 和 OpenAI 兼容的端点

CLI 二进制文件位于构建后的 TensorSharp.Cli/bin/...，服务器位于 TensorSharp.Server/bin/...。完整选项请参见：CLI 用法 · [服务器用法](#Web 应用程序)。

选择后端

不确定使用哪个后端？从这里开始。每个后端对于尚未实现的操作都会回退到 CPU，因此所有后端的输出都是正确的。

有关每个后端的完整描述以及每个后端加速的内容，请参见计算后端。

已验证模型

这些架构已实现，并经过测试/基准矩阵的执行。选择适合你硬件的量化格式（例如 Q4_K_M 用于低内存，Q8_0 用于更高质量）。更多尺寸和多模态投影仪文件请参见模型下载 (GGUF)。

亮点

• 与 llama.cpp 一较高下 — 纯 .NET 实现 — 在相同的 GGUF 文件和 GPU 上直接对比，TensorSharp 在关键工作负载上匹配或超越了经过手工调优的 C++ llama.cpp：Gemma 4 26B-A4B MoE 预填充速度 1.32×，首词输出快 1.30×（几何平均；某些场景高达 1.70× / 1.65×），Gemma 4 12B 在每个解码场景均获胜或持平（几何平均 1.17×），流式工具调用解码速度提升 2.37×，Gemma 4 E4B 的结构化输出（JSON）解码速度提升 7.7×（405 vs 52 tok/s）。→ 与 llama.cpp 直接对比

• 连续批处理与分页 KV 缓存 — vLLM 风格的分页 KV 池，带有块哈希前缀共享和迭代级调度器，在服务器中默认开启。→ 深入解读

• MTP / NextN 推测解码 — 多令牌预测草稿头加速 Qwen 3.6（NextN 块嵌入在主干 GGUF 中）和 Gemma 4（单独的 gemma4-assistant 草稿 GGUF）的独立解码。草稿每次提议多个令牌，主干在一次批处理前向中验证它们，由请求自身的采样器驱动草稿和验证。通过 --mtp-spec（+ Gemma 4 的 --mtp-draft-model）选择启用。→ 推测解码

• DiffusionGemma 文本扩散 — 基于 Gemma-4 派生 MoE 主干的块级熵界去噪，提供 CLI 生成标志和 Web UI 去噪预览流。→ DiffusionGemma 卡片

• Qwen-Image-Edit 图像编辑 — 提示 + 输入图像 → 编辑后的图像，驱动包含 60 个块的 MMDiT 扩散变压器，配合 Qwen-Image VAE 和 Qwen2.5-VL-7B 文本编码器。支持 CUDA 图捕获的完整 DiT 前向、FlowMatch-Euler 真 CFG 去噪，以及 Web UI 实时去噪预览。→ Qwen-Image-Edit 卡片

• 多模态 — 图像 / 视频 / 音频输入（Gemma 4）；Gemma 3、Qwen 3.5 系列、Mistral 3 和 Nemotron-H Omni 的图像输入。→ 多模态支持

• 工具调用 / 函数调用 — 三种 API 风格均支持多轮工具调用，并具有架构无关的输出解析。→ 工具调用

• 思考 / 推理模式 — 针对 Qwen 3、Qwen 3.5/3.6 系列、Gemma 4、GPT OSS 和 Nemotron-H 的结构化思维链。→ 思考模式

• Ollama 和 OpenAI 兼容 API — 用于现有工具的即插即用端点，外加浏览器聊天 UI。→ HTTP API

• 原生量化的计算 — Q4_K_M / Q8_0 / MXFP4 / IQ2_XXS 等格式在矩阵乘法中运行，无需反量化到 FP32。

以下内容为详细参考。如果你是新手，只需阅读上述五个部分即可开始运行。

文档地图

当前状态

特性

• 多架构支持 — Gemma 4、Gemma 3、DiffusionGemma、Qwen 3、Qwen 3.5/3.6 系列、GPT OSS、Nemotron-H、Mistral 3 和 Qwen-Image-Edit（图像编辑）
• 多模态推理 — 图像、视频和音频输入（Gemma 4）；Gemma 3 / Qwen 3.5 系列 / Mistral 3 / Nemotron-H Omni 的图像
• 思考 / 推理模式 — 带有 `` / <|channel>thought / <|channel>analysis 标签的结构化思维链输出（Qwen 3、Qwen 3.5/3.6 系列、Gemma 4、GPT OSS、Nemotron-H）
• 工具调用 / 函数调用 — 模型可以调用用户定义的工具；三种 API 风格均支持多轮工具调用对话
• 量化模型支持 — 加载 Q4_K_M、Q8_0、F16、MXFP4 及其他量化格式的 GGUF 文件；执行原生量化矩阵乘法，无需反量化到 FP32，包括针对大型 GGUF 的内存高效纯 C# CPU 加载
• GPU 加速 — macOS 上的 GGML Metal、Windows/Linux 上配合 NVIDIA GPU 的 GGML CUDA、带有 PTX 内核的直接 CUDA/cuBLAS 后端，以及针对 Apple Silicon 的 MLX 后端（mlx-c / Metal），均支持未实现操作的 CPU 回退
• 优化的纯 C# CPU 后端 — 托管 GEMM 快速路径，加上 RMSNorm、RoPE、Softmax、融合激活及其他推理热点的融合 SIMD 内核
• 连续批处理与分页 KV 缓存 — vLLM 风格的分页 KV 池，带有请求间的块哈希前缀共享、可接纳/抢占序列的迭代级调度器、用于非常大的 KV 工作集的可选 SSD 支持层，以及原生的融合分页注意力内核（TSGgml_PagedAttentionForward），该内核在 Metal/CUDA 上驱动 ggml_flash_attn_ext。在 TensorSharp.Server 中默认启用；使用 --no-continuous-batching 选择退出。参见 docs/PAGED_ATTENTION_AND_CONTINUOUS_BATCHING.md。
• MTP / NextN 推测解码 — 多令牌预测草稿头加速独立（非并发）解码。Qwen 3.6 将其 NextN 块融合到主干 GGUF 中；Gemma 4 通过 --mtp-draft-model 加载单独的 EAGLE 风格 gemma4-assistant 草稿 GGUF，其草稿层关注目标的 KV 缓存。草稿每步最多提议 --mtp-draft 个令牌（在草稿置信度 ≥ --mtp-pmin 时保留），主干在单个批处理前向中验证它们；请求自身的采样器（包括惩罚）驱动草稿和验证，因此输出与标准解码相同。通过 --mtp-spec 选择启用（默认关闭）。在 ggml 后端上，融合的多令牌验证/草稿步骤内核使其明显获益；纯 C# cuda 后端运行完全驻留在 GPU 上的逐操作验证/草稿，同样获益。CPU / MLX 保持在标准解码。环境变量：TS_MTP_*（通用）和 TS_GMTP_*（Gemma 4 调优）。
• 批处理 / 并行推理 — Mistral 3、Gemma 4、GPT OSS、Qwen 3、Qwen 3.5/3.6 系列和 Nemotron-H 的 IBatchedPagedModel.ForwardBatch 实现默认运行，将 N 个序列打包到单个前向传播中，具有分页 K/V 散布和通过原生内核的逐序列注意力。每个模型都暴露了 TS__BATCHED=0 的逃生门（例如 TS_GEMMA4_BATCHED=0、TS_QWEN35_BATCHED=0、TS_GPTOSS_BATCHED=0、TS_NEMOTRON_BATCHED=0），用于回退到逐序列 KV 交换路径，以便进行 A/B 比较或回归隔离。
• Ollama 和 OpenAI API 兼容 — 现有工具的即插即用替换端点
• 可配置采样 — 温度、top-k、top-p、min-p、重复/存在/频率惩罚、随机种子、停止序列
• 聊天模板 — 从 GGUF 元数据自动加载（Jinja2），每个架构有硬编码的回退
• 推理引擎 — 新的 InferenceEngine（工作线程调度器 + 分页块池）取代了 TensorSharp.Server 内部的旧单请求 FIFO 队列。旧队列对象现在是一个用于状态/事件形状的兼容性垫片；引擎本身处理并发。
• 批量处理 — 控制台应用程序中的 JSONL 输入支持，以及内置的预填充/解码吞吐量推理基准测试
• 流式传输 — 通过 SSE（Web）或 stdout（控制台）的逐令牌输出，支持正在进行的生成的中止/停止
• 文本扩散生成 — DiffusionGemma 使用迭代熵界去噪采样器，而非自回归的 Forward()。CLI 暴露了 --diffusion-steps、--diffusion-seed 和 --diffusion-blocks；Web UI 流式传输整条消息的 replace 事件，用于实时去噪预览，并通过 DiffusionBatchScheduler 批处理并发扩散请求。
• 图像编辑 (Qwen-Image-Edit) — 提示加输入图像产生编辑后的图像。加载的 qwen_image GGUF 是 MMDiT 扩散变压器；TensorSharp 在它旁边解析两个配套的 GGUF — Qwen-Image VAE（图像 ↔ 16 通道潜在空间）和 Qwen2.5-VL-7B 文本编码器（提示 → 3584 维条件，可选的视觉接地通过 mmproj）。流水线将参考图像进行 VAE 编码，构建文本（以及可选的图像）条