概览与架构
TensorSharp 是面向 GGUF 模型的原生 .NET 大模型推理引擎 —— 既支持自回归大模型，也支持 DiffusionGemma 式的文本扩散模型。它提供控制台应用、基于 Web 的聊天机器人，以及兼容 Ollama / OpenAI 的 HTTP API。
它到底是什么 —— 通俗讲解
大语言模型（LLM）是一种预测文本的神经网络。要使用它，你需要一个推理引擎：负责加载模型权重、运行数学运算，把你的提示词变成回复的软件。TensorSharp 就是这样一个引擎，用现代 C# / .NET 10 编写，专注于本地大模型生态广泛使用的 GGUF 模型格式。
它用同一套二进制为你提供三种使用模型的方式：
- 命令行 —— 运行一条提示词、一张图片、一批问题，或一次基准测试。→ CLI
- 服务器 —— 浏览器聊天机器人，外加模仿 Ollama 与 OpenAI 的 REST 接口。→ 服务器
- 库 —— 引用源码项目，从你自己的 .NET 代码调用引擎。→ C# 库
商业价值
对评估本地推理的决策者而言，核心权衡是用运行自己的硬件换取掌控力与成本。
🔒
数据隐私与合规
提示词与文档永不离开你的基础设施 —— 适合受监管、私有部署或离网环境。
💸
成本可预测
没有按 token 计费的 API。容量受限于你本就已预算的硬件。
🧩
无供应商锁定
来自 Hugging Face 的开放 GGUF 模型，以及现有工具已支持的 OpenAI / Ollama 兼容接口。
🏗️
.NET 原生集成
将推理嵌入现有 C# 服务，而非桥接到外部运行时。
📈
单机即可扩展
连续批处理用单个托管模型服务大量并发用户。
🔁
轻松迁移
把现有 OpenAI SDK 代码指向 http://localhost:5000/v1，应用无需改动。
架构
TensorSharp 是一个分层系统。每一层都是可独立打包的项目，因此源码使用者只需引用自己需要的部分。当前 Runtime/Models/Backends/CLI/Server 包 ID 尚未发布到 NuGet.org。
| 层 | 职责 |
|---|---|
| TensorSharp.Core | 核心 Tensor 类型、存储抽象、设备抽象，以及可扩展的运算注册表（Ops）。CPU 实现使用 System.Numerics.Vectors 做 SIMD。 |
| TensorSharp.Runtime | GGUF 解析、分词器（SentencePiece / BPE）、聊天模板渲染、采样、输出解析、分页 KV 缓存，以及连续批处理的调度器 / 引擎。 |
| TensorSharp.Models | ModelBase 以及具体架构与多模态编码器。模型通过 ModelBase.Create() 加载，会从 GGUF 元数据自动识别架构。 |
| TensorSharp.Backends.GGML | 通过原生 C++ 桥接（libGgmlOps）链接 ggml 实现加速运算 —— macOS 上用 Metal，Windows/Linux 上用 CUDA 与 Vulkan，以及原生 CPU。 |
| TensorSharp.Backends.Cuda | 直接 CUDA 路径：CUDA Driver API、cuBLAS GEMM，以及热点运算的 PTX 内核，并带 CPU 回退。 |
| TensorSharp.Backends.MLX | Apple Silicon 的 MLX 路径，封装 mlx-c，提供量化、融合与编译内核。 |
| TensorSharp.Server | HTTP / 应用层：兼容 Ollama 与 OpenAI 的 REST API、浏览器聊天 UI、上传处理，以及每模型的连续批处理引擎宿主。 |
| TensorSharp.Cli | 控制台宿主，用于本地提示词、多模态实验、提示词检查、JSONL 批处理工作流、交互式 REPL 与基准测试。 |
💡
对于任何尚未实现的运算，每个后端都会回退到 CPU，因此在所有后端上输出都保持正确 —— 你牺牲的只是速度，绝不是正确性。
一次请求如何流转
- 加载 ——
ModelBase.Create(path, backend)读取 GGUF 元数据、选择架构，并把量化权重映射到所选后端。 - 渲染 —— 提示词（以及任何系统消息、图像、音频、工具）经由架构的聊天模板和分词器转成 token。
- Prefill（预填充） —— 提示词 token 在一次批量前向中处理，填充 KV 缓存。
- Decode（解码） —— 逐 token 生成（可借助推测解码一次生成多个），按你的设置采样并流式返回。
- 服务 —— 在服务器中，连续批处理引擎将多个请求交错运行于同一模型之上，并在它们之间共享 KV 缓存前缀。
项目结构
仓库按上述分层组织。最有用的入口：
| 路径 | 内容 |
|---|---|
TensorSharp.Core/ | 张量库、运算、内存、设备抽象、CPU SIMD / 量化内核。 |
TensorSharp.Runtime/ | GGUF、分词器、模板、采样；Paged/ KV 原语与 Scheduling/ 推理引擎 + MTP 核心。 |
TensorSharp.Models/Models/<Family>/ | 每个架构一个文件夹（Gemma3/4、Qwen3/35、GptOss、Nemotron、Mistral3、DiffusionGemma、QwenImage），各含一个 legacy 与一个批量前向。 |
TensorSharp.GGML.Native/ | 到 ggml 的原生 C++ 桥接（matmul、融合 transformer 内核、分页注意力、MoE、Mamba2、GatedDeltaNet、扩散）。 |
TensorSharp.Server/ | ASP.NET Core 服务器：程序引导、模型服务、推理引擎宿主、聊天流水线、遥测。 |
docs/ | 各模型架构卡、分页注意力深入解析、环境变量矩阵、基准矩阵。 |
当前状态与能力
| 领域 | 状态 |
|---|---|
| 模型家族 | Gemma 3/4、DiffusionGemma、Qwen 3、Qwen 3.5/3.6-family（qwen35、qwen35moe、qwen3next）、GPT OSS、Nemotron-H（含 Nemotron 3 Nano Omni）、Mistral 3，以及 Qwen-Image-Edit（qwen_image 图像编辑）。 |
| 推理宿主 | CLI、交互式 REPL、ASP.NET Core Web UI、Ollama 式 API、OpenAI Chat Completions 式 API。 |
| 后端 | 纯 C# CPU、直接 CUDA/cuBLAS（cuda）、MLX Metal（mlx）、GGML CPU、GGML Metal、GGML CUDA、GGML Vulkan。 |
| 多模态 | Gemma 4 图像/视频/音频；Gemma 3、Qwen 3.5-family、Mistral 3 与 Nemotron-H Omni 图像输入。PDF 文档可经 Web UI 上传或 CLI --pdf 传入（提取文本并内联；扫描页渲染为图像交给视觉模型）。 |
| 连续批处理 | vLLM 式分页 KV 缓存、块哈希前缀共享、迭代级调度器（默认开启；可用 --no-continuous-batching 关闭）。 |
| 推测解码 | Qwen 3.6（内嵌）与 Gemma 4（独立草稿 GGUF）的 MTP / NextN 草稿头；默认关闭，通过服务器的 --mtp-spec 参数（环境变量 TS_MTP_SPEC）启用。 |
| 张量并行 | Direct cuda 后端与 GGML CUDA / Vulkan 后端上的 Megatron-LM 列/行并行 TP（--tp N / TENSORSHARP_TP_DEGREE，CLI 与服务端均支持），以及基于点对点 TCP 网格的多节点分布式 TP（--tp-node-id / --tp-peers），覆盖全部自回归架构。融合的按 rank 计算图与 MoE 专家并行让 Gemma 4 上 --tp 2 的 decode 快于单卡。可选 Redis 支撑的共享 KV 缓存与 Responses API 存储。→ 多 GPU 与多节点 |
| 可观测性 | 结构化的逐轮日志、队列状态，以及跨 Web UI、Ollama 与 OpenAI 响应形态的 KV 缓存复用指标。 |