服务器与 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 -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。内置聊天 UI 位于 http://localhost:5000/index.html；GET / 是存活检查接口，返回 "TensorSharp.Server is running"。

已构建的源码目录

构建完成后，从仓库根目录运行这些命令。它们会调用 TensorSharp.Server/bin/TensorSharp.Server.dll；该输出目录也包含复制好的原生库与 wwwroot/。当前 v3.0.5.0 GitHub Release 没有附带二进制压缩包。

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

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

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

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

服务器级默认采样

默认值会填补请求未提供的任何字段；逐请求的值始终优先。

dotnet TensorSharp.Server/bin/TensorSharp.Server.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/index.html。浏览器界面支持：

• 多轮对话，带流式 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 提供下载链接。
• 自由滚动 —— 在新 token 流式输出时阅读较早的回复；自动滚动会在回到底部时恢复。

配置文件（--config）

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

# 从文件读取全部参数；本次仅覆盖后端
dotnet TensorSharp.Server/bin/TensorSharp.Server.dll --config config/server-basic.json
dotnet TensorSharp.Server/bin/TensorSharp.Server.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；Docker Space 镜像在构建时把该常量改为 7860。

连续批处理调参

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

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