服务器与 Web UI

TensorSharp.Server 是一个 ASP.NET Core 应用，托管单个 GGUF 模型，并在同一端口上暴露浏览器聊天 UI 以及兼容 Ollama 和 OpenAI 的 REST API。连续批处理引擎负责并发。

启动服务器

约 30 秒快速开始（Gemma 4 E4B）

按平台安装 .NET 10 SDK、Git、CMake 与 curl，然后在终端粘贴下面的命令。复制并运行这些命令约需 30 秒；7.48 GiB 的模型下载与首次还原/构建耗时更长，取决于网络速度与机器性能。它会通过原生 GGML 桥接托管仓库基准已验证的 Gemma 4 E4B Q8_0，使用推荐的公开 ggml-org 文件。下面的代码块面向 Linux + NVIDIA（CUDA 构建还需要 CUDA Toolkit）：

git clone https://github.com/zhongkaifu/TensorSharp.git
cd TensorSharp
TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON dotnet build TensorSharp.slnx -c Release -p:TensorSharpSkipMlxNative=true
curl --create-dirs --fail -L "https://huggingface.co/ggml-org/gemma-4-E4B-it-GGUF/resolve/main/gemma-4-E4B-it-Q8_0.gguf?download=true" -o models/gemma-4-E4B-it-Q8_0.gguf
dotnet run --project TensorSharp.Server.Host -c Release --no-build -- --model models/gemma-4-E4B-it-Q8_0.gguf --backend ggml_cuda

Apple Silicon 请省略 CUDA 环境变量并使用 ggml_metal；受支持的 Windows/Linux Vulkan GPU 请改为请求 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=ON 并使用 ggml_vulkan；没有受支持的 GPU 时可省略该环境变量并使用 ggml_cpu。占用内存更低的 gemma-4-E4B-it-Q4_K_M.gguf 位于同一仓库。纯文本不需要投影器；图像、视频或音频还需匹配的 mmproj-gemma-4-E4B-it-Q8_0.gguf，并通过 --mmproj 传入。Windows PowerShell 与完整平台语法见快速开始。

在第二个终端中验证 OpenAI 兼容端点：

curl -s http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma-4-E4B-it-Q8_0.gguf","messages":[{"role":"user","content":"Reply with one short hello."}],"max_tokens":32}'

API 基址是 http://localhost:5000。内置 wwwroot/ 存在且启用时，GET / 会返回其中的 index.html 聊天界面。稳定的纯文本存活检查是 GET /health；只有未启用 Web UI 的无界面部署才会让根路径 / 回退为同一个健康响应。

已构建的源码目录

构建完成后，从仓库根目录运行这些命令。它们会调用 TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll；该输出目录也包含复制好的原生库与 wwwroot/。Releases 页面也附带面向受支持平台的自包含 CLI 与服务器压缩包。

# Apple Silicon / Metal
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model ./models/model.gguf --backend ggml_metal

# NVIDIA / GGML CUDA
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model ./models/model.gguf --backend ggml_cuda

# AMD、Intel 或 NVIDIA / Vulkan；先查看设备索引
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --list-gpus
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model ./models/model.gguf --backend ggml_vulkan --gpu-device 1

# 多模态：投影器始终显式指定
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model ./models/model.gguf --mmproj ./models/mmproj.gguf --backend ggml_cuda

服务器级默认采样

默认值会填补请求未提供的任何字段。你显式配置过的参数还会覆盖客户端为其发来的值 —— 很多聊天客户端（如 VS Code Copilot Chat）会把 temperature/top_p 硬编码进每一次请求。加上 --sampling-precedence request 可把控制权交还给客户端。

dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --model ./models/model.gguf --backend ggml_metal \
    --temperature 0.7 --top-p 0.9 --top-k 40 --repeat-penalty 1.1 \
    --presence-penalty 0.0 --frequency-penalty 0.0 --seed 42 \
    --stop "</s>" --stop "<|endoftext|>"

Web UI 功能

打开 http://localhost:5000/。浏览器界面支持：

• 多轮对话，带流式 token 生成（SSE）。
• 每标签页独立的聊天会话 —— 每个标签页拥有自己的跟踪对话历史；请求 KV 块与前缀复用由推理引擎管理。
• 用于多模态推理的图像、视频、音频、PDF 与文本 / 代码上传（最大 500 MB）。
• PDF 文档：原生数字 PDF 会完整抽取文本层并内联到提示词；扫描 PDF 在视觉模型上回退为逐页图像（TS_PDF_MAX_PAGES 限制读取页数）。最终渲染的提示词会根据模型的实际上下文窗口进行检查。
• 思考 / 推理模式开关，以及带函数定义的工具调用。
• 消息编辑与删除，并可从对话中任意位置重新生成。
• 当托管 diffusion-gemma GGUF 时，提供 DiffusionGemma 去噪预览（每步替换整条助手消息，最后定稿）。
• 托管 qwen_image DiT 时提供 Qwen-Image-Edit：上传图像并输入编辑指令后，最多 8 帧实时去噪预览会原位刷新，最终 PNG 提供下载链接。
• 托管视频生成模型（MiniMax-H3 或 Wan）时提供视频生成：输入提示词，附上所加载权重声明支持的条件输入，浏览器通过 SSE 实时显示逐步去噪进度，直到 MP4 出现并提供下载链接。在 MiniMax-H3 上还会同时返回一条 32 kHz 立体声音轨 —— 它与画面出自同一次生成。所有数值仍然来自启动参数 —— 详见下文视频生成。
• 自由滚动 —— 在新 token 流式输出时阅读较早的回复；自动滚动会在回到底部时恢复。

Agentic Work 与代码执行

在能够完整往返工具调用的模型家族上，服务器可让单个模型在进程内执行「生成 → 工具 → 再生成」循环。Agent Skills 可以在不执行脚本的情况下被发现与读取；运维者需另行传入 --skills-allow-exec 才允许运行技能自带脚本。--code-exec 则显式开启由宿主处理的 read_file、edit_file、write_file、apply_patch 与沙箱化 shell 工具。Web UI 聊天会话会在各轮之间保留私有工作区；无状态 API 请求各自获得隔离的请求工作区，并在结束后删除。

视频生成：网页界面能设什么，什么只能靠 API

托管一个视频生成模型（MiniMax-H3 或 Wan），网页界面就变成了一个视频生成器。这些接口判断的是 IVideoGenerationModel 接缝而不是架构字符串，因此其他模型会返回 400 与 The loaded model is not a video-generation model.。有必要清楚地知道浏览器实际控制了请求中多小的一部分：一次视频任务可能跑几分钟，也可能跑几小时，而浏览器在任务开始后无法再改变这一点。

# MiniMax-H3：画面与它的 32 kHz 立体声音轨在同一个潜变量里一起去噪
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll \
    --model ./models/minimax_h3_fl2va_pruned-Q4_K.gguf --backend ggml_cuda \
    --video-width 640 --video-height 384 --video-steps 20 --video-frames 22

# 同样的几何参数，换另一个权重：用身份 / 外观参考生成一个新场景
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll \
    --model ./models/minimax_h3_ref2va_pruned-Q4_K.gguf --backend ggml_cuda \
    --video-width 640 --video-height 384 --video-steps 20 --video-frames 22

FL2VA 与 Ref2VA 是两个权重文件，而不是两档设置：加载哪一个决定了附上的图像被当作关键帧还是参考，/api/models 报给浏览器的也正是这一点。config/minimax-h3-fl2va.json 与 config/minimax-h3-ref2va.json 带的是同一套几何参数，并会在首次运行时下载去噪器、共享的 Qwen3-VL-32B 文本编码器与两个 VAE —— 但不包括分词器，因为它不是一个命令行参数：请把上游 MiniMaxAI/MiniMax-H3 仓库 processor/ 目录下的 vocab.json 与 merges.txt 放到编码器旁边，或让 TS_VIDEO_TOKENIZER 指向存放它们的目录。

进程在启动时就已决定的部分：

Web UI 形态的接口按上述 JSON 字段名接收参数；同一个请求体在 /api/video-generate（返回一个 MP4）与 /api/video-generate/stream（SSE 去噪进度）上都可用。视频生成在进程内串行执行，同一时刻只跑一个任务：

curl -s http://localhost:5000/api/video-generate \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "a red fox trotting through falling snow, cinematic",
        "width": 640, "height": 384,
        "frames": 22, "fps": 24,
        "steps": 8, "cfg": 1.0, "seed": 42,
        "videoMode": "t2v",
        "generateAudio": true
      }'

返回体是 { ok, url, audioUrl, width, height, frames, fps, seed, codec, elapsedSeconds }；audioUrl 指向旁挂的 WAV，当模型没有产出音轨时为 null。Wan 使用同样的请求体，只是换成它自己的旋钮 —— "flowShift": 5.0、"sampler": "unipc"、"negativePrompt"、"cfgCacheStride": 2 —— 这些 MiniMax-H3 一个都用不上，因为它在 "cfg": 1.0 下无引导运行。

"image" 字段可直接携带 base64 条件帧（允许带 data:…;base64, 前缀）；"imagePath"、"endImage" 以及每一个 reference* 条目都是 Web UI 使用的形式，必须引用 /api/upload 已经返回过的文件 —— 任何解析到上传目录之外的路径都会被拒绝。OpenAI 形态的 POST /v1/videos/generations 接收同样的参数，但尺寸写作 "size": "832x480"、负向提示词写作 "negative_prompt"。完整的请求/响应结构见 HTTP API 页。

配置文件（--config）

可以用 --config 传入一个 JSON 文件，取代冗长的命令行；CLI 读取相同格式。命令行参数始终优先——先应用文件中的值，命令行上再次给出的参数会覆盖它们，因此可以在多台主机上复用同一个文件，只覆盖需要变化的部分。--config 可重复以叠加多个文件（后者优先）。允许注释与尾随逗号。

# 从文件读取全部参数；本次仅覆盖后端
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --config config/server-basic.json
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --config config/server-basic.json --backend ggml_cpu

键名与下方长选项名相同（可带或不带前缀 --）。字符串/数字展开为 --key value，true 展开为裸开关 --key，数组展开为重复的标志（如 "stop": ["</s>", "<|eot|>"]）。

变量。 在 "variables" 中定义一次共享值，用 ${name} 在任意字符串值中引用（未定义的名称回退到同名环境变量）。可以定义任意多个根路径——位于不同目录的模型各用一个。

自动下载。 任何文件参数都可以写成带本地 path 与一个或多个 urls 的对象。若 path 不存在，则从第一个可用 URL 下载（镜像按顺序尝试），保存到该路径，之后复用；进度打印到 stderr，可选的 sha256 用于校验。

{
  "variables": { "modelRoot": "C:/models", "repo": "https://huggingface.co/unsloth/gemma-4-E4B-it-GGUF/resolve/main" },
  "backend": "ggml_cuda",
  "max-tokens": 4096,
  "continuous-batching": true,
  "stop": ["</s>", "<|eot|>"],
  "model":  { "path": "${modelRoot}/gemma-4-E4B-it-Q8_0.gguf", "urls": [ "${repo}/gemma-4-E4B-it-Q8_0.gguf" ] },
  "mmproj": { "path": "${modelRoot}/gemma-4-E4B-mmproj-F16.gguf", "urls": [ "${repo}/mmproj-F16.gguf" ] }
}

开箱即用的示例见仓库 config/ 目录（cli-basic.json、server-basic.json、variables.json、auto-download.json、qwen-image-edit.json）——每个都使用真实、公开、无需授权的 URL，因此在全新机器上也能直接运行。完整说明见 config/README.md。

服务器选项

环境变量

服务器默认监听 http://0.0.0.0:5000；--port、--host 与 --urls（或环境变量 PORT / HOST / ASPNETCORE_URLS）可以改变它，Docker Space 镜像设置的是 PORT=7860。

连续批处理调参

调度器 / 引擎的旋钮在进程启动时读取。通过环境变量（或会被翻译成它们的 --continuous-batching 系列参数）设置。

完整的环境变量面（MLX 调参、MTP 旋钮、扩散）见 API 参考 页与高级页。