从 C# 使用 TensorSharp

TensorSharp 是一个真正的 .NET 库，而不只是可执行文件。从源码 checkout 引用其项目，即可在不经过 HTTP 的情况下从自己的代码驱动推理。

项目与包边界

仓库按可发布包边界拆分。下方名称是项目/包 ID，但当前 Runtime/Models/Backends/CLI/Server 包尚未发布到 NuGet.org。

典型嵌入场景只需引用 TensorSharp.Models.csproj；它已引用 Core、Runtime 与各后端项目。若你的应用与 TensorSharp checkout 同级：

dotnet add reference ../TensorSharp/TensorSharp.Models/TensorSharp.Models.csproj

最小示例 —— 加载、生成、解码

每个模型都以相同方式加载：ModelBase.Create() 读取 GGUF 元数据并实例化正确的架构。从这里开始你做分词、运行前向、采样并解码。

using System;
using System.Collections.Generic;
using System.Linq;
using TensorSharp.Models;
using TensorSharp.Runtime;

// 1. 加载任意受支持的 GGUF —— 架构从元数据自动识别。
//    按你的构建选择 BackendType：GgmlCuda、GgmlMetal、GgmlVulkan 或 GgmlCpu。
using var model = ModelBase.Create("gemma-4-E4B-it-Q8_0.gguf", BackendType.GgmlCuda);

// 2. 配置采样（默认值与 Ollama 一致：temp 0.8、top_k 40、top_p 0.9）。
var sampling = new SamplingConfig { Temperature = 0.7f, TopP = 0.9f, TopK = 40 };

// 3. 对提示词分词。
var tokens = model.Tokenizer
    .Encode("Explain mixture-of-experts in one sentence.", addSpecial: true)
    .ToList();
var generated = new List<int>();

// 4. 完整提示词只 prefill 一次。
float[] logits = model.Forward(tokens.ToArray());

// 5. 每次只 decode 一个新 token。Forward() 自己维护 KV-cache 位置，
// prefill 后只传刚采样出的 token，不要重复传完整历史。
for (int step = 0; step < 200; step++)
{
    int next = model.Sample(logits, sampling, generated); // 应用惩罚 + 采样
    if (model.Tokenizer.IsEos(next)) break;
    generated.Add(next);
    logits = model.Forward(new[] { next });
}

// 6. 反分词得到结果。
Console.WriteLine(model.Tokenizer.Decode(generated));

要做贪心/确定性解码，请调用 model.SampleGreedy(logits) 而非 Sample。

冒烟测试变体

一次性健全性检查：加载模型、运行一次前向，并打印 top token：

using var model = ModelBase.Create(modelPath, backend);
var tokenIds = model.Tokenizer.Encode("Hello", addSpecial: true);
float[] logits = model.Forward(tokenIds.ToArray());

int topToken = model.SampleGreedy(logits);
Console.WriteLine($"vocab={model.Config.VocabSize}, tokens={tokenIds.Count}, topToken={topToken}");

DiffusionGemma — 文本扩散

DiffusionGemma 是块文本扩散模型，而非自回归模型。ModelBase.Create() 仍可加载它（GGUF 架构为 diffusion-gemma / diffusion_gemma）并返回 DiffusionGemmaModel，但其 Forward(int[]) 会故意抛出异常——生成需通过 DiffusionGemmaSampler，它在 [prompt | canvas] 序列上对定长的 canvas 块迭代去噪。架构详见 DiffusionGemma 模型卡。

using TensorSharp.Models;
using TensorSharp.Models.DiffusionGemma;
using TensorSharp.Runtime;

// 加载 diffusion-gemma GGUF——架构会自动检测。
using var model = (DiffusionGemmaModel)ModelBase.Create("diffusion-gemma.gguf", BackendType.GgmlCuda);

// 用模型的聊天模板渲染 prompt，然后分词。
var messages = new List<ChatMessage> { new() { Role = "user", Content = "Write a haiku about winter." } };
string rendered = PromptRenderer.Render(model.Config.ChatTemplate, messages,
    addGenerationPrompt: true, architecture: model.Config.Architecture);
int[] promptTokens = model.Tokenizer.Encode(rendered, addSpecial: true).ToArray();

// 配置 EntropyBound 去噪采样器。
var p = new DiffusionEbParams
{
    MaxDenoisingSteps = 48,   // 每个 canvas 块的精化步数
    Seed = 0,                 // 确定性
    MaxBlocks = 1,            // 块自回归的 canvas 块数
};

var sampler = new DiffusionGemmaSampler(model);

// 生成。可选回调在每个去噪步后触发，参数为
// (blockIndex, step, totalSteps, previewTokens)——适合做实时 UI。
List<int> generated = sampler.Generate(promptTokens, p,
    (block, step, total, preview) => Console.Write($"\rblock {block + 1} step {step + 1}/{total}   "));

Console.WriteLine();
Console.WriteLine(model.Tokenizer.Decode(generated));

DiffusionEbParams 的关键参数：MaxDenoisingSteps（48）、TMin/TMax 温度调度（0.4 / 0.8）、EntropyBound（0.1）、StabilityThreshold / ConfidenceThreshold 早停、Seed 与 MaxBlocks。model.CanvasLength 给出每块的 canvas 大小。

Qwen-Image-Edit — 图像编辑

Qwen-Image-Edit 接收提示词 + 一张输入图像并返回编辑后的图像。所加载的 qwen_image GGUF 仅是 MMDiT 扩散 Transformer；模型还会拉入两个伴随 GGUF（在 DiT 文件同目录解析，或通过 TS_QWEN_IMAGE_VAE / TS_QWEN_IMAGE_TE / TS_QWEN_IMAGE_MMPROJ 环境变量指定）：Qwen-Image VAE 与 Qwen2.5-VL-7B 文本编码器。与 DiffusionGemma 一样，它不是自回归文本模型——自回归入口会抛异常，编辑通过 EditImage() 驱动。

using TensorSharp.Models;
using TensorSharp.Models.QwenImage;
using TensorSharp.Runtime;

// 加载 MMDiT GGUF（架构 = qwen_image）。VAE + Qwen2.5-VL
// 伴随文件从同一目录解析（或用 TS_QWEN_IMAGE_* 环境变量）。
using var model = (QwenImageModel)ModelBase.Create("qwen-image-edit-DiT-Q4_K_M.gguf", BackendType.GgmlCuda);

// 加载输入图像（PNG/JPEG 解码为 RgbImage）。
RgbImage input = ImageIO.Load("input.png");

var p = new QwenImageParams
{
    Steps = 30,               // FlowMatch-Euler 去噪步数
    CfgScale = 4.0f,          // true-CFG 引导；<= 1 关闭负向分支
    NegativePrompt = " ",     // 仅当 CfgScale > 1 时使用
    Seed = 0,
    TargetArea = 1024 * 1024, // ~1 MP；纵横比随输入（尺寸对齐到 /16）
    // Width = 0, Height = 0, // 指定显式输出尺寸可绕过 VRAM 钳制
};

RgbImage output = model.EditImage("Make the sky a dramatic sunset.", input, p);
ImageIO.SavePng("edited.png", output);
Console.WriteLine($"Saved {output.Width}x{output.Height} edited image.");

若要做实时 UI，设置 p.OnStep = (step, total, preview) => { … } 与 p.PreviewCount，即可在节流的步上收到部分去噪潜变量解码出的 RGB 预览。RgbImage 暴露 Width、Height 与平面/交错的 Pixels 缓冲；ImageIO 提供 Load、Decode(byte[])、EncodePng、SavePng 及缩放辅助。

SamplingConfig

采样旋钮与 CLI 参数及 API 选项一一对应。默认值与 Ollama 一致。

关键类型与接口

其他值得了解的运行时契约：IModelArchitecture、IPromptRenderer、IOutputProtocolParser、IMultimodalInjector、IKvBlockCodec（带内置 TurboQuantKvCodec）以及 IKVCachePolicy。