从 C# 使用 TensorSharp

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

句向量编码器：Snowflake Arctic Embed L v2.0 / all-MiniLM-L6-v2，支持纯 C# CPU 与原生 GGML CPU/Metal/CUDA，通过 --embeddings 提供兼容 OpenAI/Ollama 的 API。 嵌入模型、支持的后端与验证 →

项目与包边界

仓库按可发布包边界拆分。源码树的发布集合是下表的全部 14 个包，由 eng/verify-packages.ps1 校验，并作为发布流水线的门禁。

包版本与内容对应选定的发布标签。个人知识库与回答引导在 v2026.10.10 后合入，需要包含它们的新构建；使用未发布 API 时请引用当前源码项目。发布流程可打包下表项目，不代表已检查某次发行的全部 NuGet 包或安装资产。

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

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

知识库 SDK：KnowledgeStore、KnowledgeOptions、IKnowledgeExtractor 与 IKnowledgeEmbeddingProvider 位于独立项目；Chat 层的 KnowledgeRuntime.CreateStore 接入加载模型、GGUF 编码器与 OCR。应用须显式提供选择范围与认证边界。宿主配置 →

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

每个模型都以相同方式加载：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 System;
using System.Collections.Generic;
using System.Linq;
using TensorSharp.Models;   // DiffusionGemmaModel、DiffusionGemmaSampler、DiffusionEbParams
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." } };
var renderer = new GgufPromptRenderer();
string rendered = renderer.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 大小。

图像输入与类型化决策。model.LoadVisionEncoder(path) 从 mmproj GGUF，或直接从 Hugging Face 分片 model-00011-of-00011.safetensors 加载 Gemma 4 视觉塔；音频与视频会被拒绝。加载视觉塔后，在用户消息上设置 ImagePaths，并在 Generate 之前让分词后的提示词依次经过 model.MultimodalInjector.ProcessPromptTokens(messages, tokens) 与 QueuePromptEmbeddings(0)，做法与 CLI 相同。要做 Jev 风格的类型化决策，请引用 TensorSharp.Chat 并调用 ModelService.JevAsync(JevRequest.Parse(json.RootElement))（命名空间 TensorSharp.Server 与 TensorSharp.Server.Jev）——这正是 POST /v1/systemone 背后经过校验的路径。底层读取是 DiffusionGemmaModel.ReadStructured(promptTokens, seedCanvas, positions, tokenIds)，调用期间需持有 GpuComputeLock。见 docs/models/jev_zh-cn.md。

Qwen-Image-2.1 — 图像生成与编辑

Qwen-Image-2.1 可以把提示词变成图像，也可以把提示词 + 一张或多张参考图变成编辑后的图像。所加载的 qwen_image GGUF 是扩散 Transformer；模型还会在 DiT 文件同目录解析伴随文件（或通过 TS_QWEN_IMAGE_VAE / TS_QWEN_IMAGE_TE / TS_QWEN_IMAGE_MMPROJ 环境变量指定）：专用 2.1 VAE、Qwen3-VL-8B 文本编码器，以及编辑时必需的 mmproj 视觉编码器。与 DiffusionGemma 一样，它不是自回归文本模型——自回归入口会抛异常，图像由 GenerateImage() 与 EditImage() 产生。

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

// 加载 Qwen-Image-2.1 DiT GGUF（架构 = qwen_image）。2.1 VAE 与 Qwen3-VL-8B
// 文本编码器 + mmproj 从同一目录解析（或用 TS_QWEN_IMAGE_* 环境变量）。
// 任意 GGML 后端都可以，BackendType.Cpu（纯 C#）也可以。
using var model = (QwenImageModel)ModelBase.Create("qwen_image_2.1_Q4_K_M.gguf", BackendType.GgmlMetal);

var p = new QwenImageParams
{
    Steps = 0,          // 0 = 模型默认：40 步 FlowMatch-Euler
    CfgScale = 0f,      // 0 = 模型默认：1.0，每步一次 Transformer 预测
    Seed = 42,
    // Width = 1024, Height = 1024, // 显式尺寸，须为 32 的倍数（更快的草图）
};

// 文生图（默认 2048x2048）
RgbImage generated = model.GenerateImage("A small orange cat beside a blue ceramic vase, soft daylight", p);
ImageIO.SavePng("generated.png", generated);

// 编辑：这里只有一张参考图；多张参考图按顺序传入 IReadOnlyList<RgbImage>
RgbImage input = ImageIO.Load("generated.png", preserveAlpha: true);
RgbImage edited = model.EditImage("Change the blue vase to a red vase.", input, p);
ImageIO.SavePng("edited.png", edited);
Console.WriteLine($"Saved {edited.Width}x{edited.Height} edited image.");

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

LoRA 插件。model.SetLoras(new[] { new LoraSpec("config/lora/qwen-image-2.1-viggle-turbo.json") }) 替换之后每个请求所用的插件组；LoraSpec(Path, Scale, ConfigPath) 接受与 --lora / --lora-scale / --lora-config 相同的三个值，空列表表示移除插件组。适配器会立即针对 Transformer 校验，失败时保留原来的插件组。当 Steps / CfgScale 为 0 时，由插件的采样配方提供步数与 CFG。见 LoRA 插件。

局部编辑：在 EditImage() 之前设置 p.Mask = ImageIO.Load("selection.png", preserveAlpha: true)，并按需设置 MaskMode、MaskInvert、MaskFeather、MaskCrop 与 MaskCropPadding。QwenImageMaskMode.Grayscale（默认）中白色表示编辑；Alpha 使用透明度。蒙版匹配第一张输入图，结果保留其画布与保护像素。蒙版语义 →

保持源图尺寸：设置 p.KeepSourceSize = true，编辑结果即为第一张输入图的精确宽高，采样面积约为图片自身面积，至少 1 百万像素、至多 TargetArea（或自动面积）。它不能与 Width/Height 同时使用，GenerateImage() 也不接受它。

音视频与嵌入模型

LTX 2.5 通过注册的 Ltx25Model 实现 IVideoGenerationModel，MiniMax-H3 与 Wan 使用同一视频接口；参数按模型契约校验。LTX 默认完整两阶段配方与 48 kHz 立体声。嵌入文本使用 EmbeddingModel.Load，EmbeddingGemma 2 媒体使用 EmbeddingGemma2MultimodalEncoder 与有序输入部分。 LTX 2.5 · 嵌入集成

SamplingConfig

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

Agent Skills —— SkillsChatClient

Agent Skill（智能体技能）是一个面向模型的说明文件夹——一份 SKILL.md，外加它引用的脚本、参考文档与素材——模型只在任务需要时才加载它。SkillsChatClient（命名空间 TensorSharp.AgentHost.Skills，位于 TensorSharp.AgentHost 项目）就是 .NET 应用取用技能的入口。它通过 HTTP 调用兼容 OpenAI 的聊天端点，而不是在进程内加载 GGUF，因此与本页其余内容不同：它既不需要后端，也不需要引用 TensorSharp.Models。

在 TensorSharp 支持工具的聊天格式上，已选择和发现到的技能最初都只披露元数据；模型按需读取说明与随附文件。若模型没有可用的工具解析器，TensorSharp 会改为内联已选择技能的正文并隐藏内置技能/代码工具，使请求仍然有用，而不会假装工具往返能工作。

它覆盖实际会遇到的两种情形，由 SkillsChatClientOptions.Delivery 选择。

面向 TensorSharp 服务端（TensorSharp.Server.Host）—— SkillDelivery.Server

只需点名技能，其余全部由服务端在模型旁边完成，渐进式披露的循环也在那里跑。每次请求不上传任何东西，技能文件也从不离开服务端。

using System;
using System.Threading.Tasks;
using TensorSharp.AgentHost.Skills;

using var client = new SkillsChatClient(new SkillsChatClientOptions
{
    Endpoint = "http://localhost:5000",           // 带不带结尾的 /v1 都可以
    DefaultModel = "gemma-4-E4B-it-Q8_0.gguf",
    Delivery = SkillDelivery.Server,
});

// 单轮场景的便捷写法：提示词 + 要使用的技能。
SkillsChatResponse reply = await client.CompleteAsync(
    SkillsChatRequest.User("Extract the tables from report.pdf", "pdf"));

Console.WriteLine(reply.Content);
Console.WriteLine($"{reply.Rounds} 轮，prompt {reply.PromptTokens} + completion {reply.CompletionTokens} token");

服务端交付模式下，渐进式披露的循环跑在服务端内部，因此 reply.SkillInvocations 返回为空，reply.Rounds 为 1 —— 本客户端恰好只发出了一次请求。

面向任意其他兼容 OpenAI 的端点 —— SkillDelivery.Local

把客户端指向一个本地 SkillRegistry，它就会在本进程内构造提示词块、声明技能工具并运行整个循环，于是一个从没听说过技能的端点表现得就像原生支持一样。代价是模型每读一个文件多一次网络往返。

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using TensorSharp.Runtime;          // ChatMessage
using TensorSharp.AgentHost.Skills;

var registry = new SkillRegistry(new SkillRegistryOptions
{
    Roots = new[] { "/srv/skills" },   // 最深扫描 MaxDepth（3）层
});

using var client = new SkillsChatClient(new SkillsChatClientOptions
{
    Endpoint = "https://api.example.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("EXAMPLE_API_KEY"),
    DefaultModel = "some-hosted-model",
    Delivery = SkillDelivery.Local,
    Registry = registry,
    Discovery = true,                  // 同时展示本次请求没有点名的技能
});

SkillsChatResponse reply = await client.CompleteAsync(new SkillsChatRequest
{
    Messages = { new ChatMessage { Role = "user", Content = "Fill in this AcroForm and tell me what you set." } },
    Skills = { "pdf" },
    MaxTokens = 800,
});

Console.WriteLine(reply.Content);

// 模型读过的每一个技能文件，按顺序排列。
foreach (SkillToolInvocation call in reply.SkillInvocations)
    Console.WriteLine($"round {call.Round}: {call.Tool} {call.SkillId}/{call.ResourcePath} ok={call.Ok}");

默认值 SkillDelivery.Auto 会探测一次 /v1/skills，并把结果缓存到该客户端的整个生命周期：端点有响应就走服务端交付，没有响应且本客户端带了注册表就走本地交付。await client.ResolveDeliveryAsync() 会告诉你最终选了哪一种；await client.ListServerSkillsAsync() 则向端点询问它有哪些技能，端点没有实现技能 API 时返回空列表而不是抛异常。

SkillsChatClientOptions

SkillsChatRequest 与 SkillsChatResponse

SkillRegistry 与 SkillRegistryOptions

注册表负责发现（在配置的目录中查找 SKILL.md）、安装与查找；它是唯一接触技能存储的组件，因此边界约束规则集中在一处。CLI 与服务端也正是用 --skills-dir 构造出它。

完整参考（frontmatter 字段、提示词预算与安全模型）见 docs/agent_skills.md。可直接取用的开源技能：github.com/anthropics/skills。

AgentHost 运行时层

TensorSharp.AgentHost 是构建在 TensorSharp.Runtime 之上的可选智能体层；Runtime 不反向依赖它。CodeExecOptions、ShellRunner 与 CodeRunnerAdapter 实现宿主拥有的四个工具：read_file、write_file、shell、apply_patch。只有宿主提供持久工作区时才声明文件工具；没有工作区的直接调用方只获得 shell。

SkillAgentLoop 运行有界循环，只执行 TensorSharp 自有的技能/代码调用，并把应用自身工具的调用放入 SkillLoopResult.PendingClientToolCalls 返回。同时设置 SkillAgentLoopOptions.MultiAgent 与 SubagentGeneratorFactory（一个为每个子智能体返回独立生成器的 Func<string, SkillTurnGenerator>）后，循环会通过 spawn_agent、wait_agent、send_input、close_agent 与 list_agents 协调一棵请求级的子智能体树；设置了已启用的 MultiAgent（其 Enabled 默认为 true）却没有工厂时会抛出 ArgumentException。MultiAgentOptions（位于 TensorSharp.AgentHost.Agents）限定这棵树：MaxConcurrentAgents 3、MaxAgents 8、MaxDepth 2、MaxRoundsPerAgent 8、MaxTotalChildGenerations 48、AgentTimeoutSeconds 180、MaxResultCharacters 8000、MaxTaskCharacters 16000，AllowWorkerTools 默认关闭。回调携带 SkillToolInvocation.AgentId。宿主默认最多生成 8 轮；提供代码工具时提升为 24，除非运维方显式设定。SessionWorkspaceManager 为每个服务器会话提供私有工作区；仅请求调用方则在一次请求内共享。工作文件、允许导出的环境状态与已安装包会在该作用域内保留，而 PATH 每次 shell 调用都会重建。

关键类型与接口

其他值得了解的运行时契约：IModelArchitecture、IPromptRenderer（由 GgufPromptRenderer 实现）、IOutputProtocolParser 以及 IMultimodalInjector。