服务器与 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 --host 127.0.0.1

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

# 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 --host 127.0.0.1

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

• 多轮对话，带流式 token 生成（SSE）。
• 回答按 Markdown 渲染：表格、代码块、列表、标题与链接。页面把它们构建为元素，而不是把模型文本当作 HTML 解析，因此回复无法注入标记或脚本；链接只对 http(s)、mailto 与服务器自身的文件下载保留目标地址。
• 每条回答下方的统计行：本轮生成的 token 数（包括推理与工具调用）、墙钟秒数、解码速度，以及提示词中有多少由 KV cache 提供。
• 每标签页独立的聊天会话 —— 每个标签页拥有自己的跟踪对话历史；请求 KV 块与前缀复用由推理引擎管理。
• 用于多模态推理的图像、视频、音频、PDF 与文本 / 代码上传（默认每个文件最大 500 MB；--upload-max-mb 调整单文件上限，POST /api/upload 的请求体上限会随之调高——见下方上传选项）。
• PDF 文档：原生数字 PDF 会完整抽取文本层并内联到提示词；扫描 PDF 在视觉模型上回退为逐页图像（TS_PDF_MAX_PAGES 限制读取页数）。最终渲染的提示词会根据模型的实际上下文窗口进行检查。
• 思考 / 推理模式开关，以及带函数定义的工具调用。
• 智能体轮次的实时活动行；wait_agent 运行期间会出现可展开的 wait_agent · N sub-agents 列表，每个子智能体一张原位更新的卡片（任务、状态、当前工具、结果）。
• 消息编辑与删除，并可从对话中任意位置重新生成。
• 当托管 diffusion-gemma GGUF 时，提供 DiffusionGemma 去噪预览（每步替换整条助手消息，最后定稿）。
• 托管 qwen_image DiT 时提供 Qwen-Image-2.1：不带附件的提示词会生成图像，附加一张或多张图像则进行编辑；最多 8 帧实时去噪预览会原位刷新，最终 PNG 提供下载链接。浏览器不发送尺寸，因此两者都设置时输出使用 --width / --height，否则使用模型的自动尺寸。
• 托管视频生成模型（LTX 2.5、MiniMax-H3 或 Wan）时提供视频生成：输入提示词，附上所加载权重声明支持的条件输入，浏览器通过 SSE 实时显示逐步去噪进度，直到 MP4 出现并提供下载链接。在 MiniMax-H3 上还会同时返回一条 32 kHz 立体声音轨 —— 它与画面出自同一次生成。所有数值仍然来自启动参数 —— 详见下文视频生成。
• 自由滚动 —— 在新 token 流式输出时阅读较早的回复；自动滚动会在回到底部时恢复。

选区图像编辑：附加照片，在编辑目标上选择选择区域，保存选区并描述修改。Qwen-Image 2.1 保持原始尺寸并保护选区外像素。结果提供比较原图与再次编辑；其他附加照片保留为参考图。选区编辑器与蒙版 API →

可以用 --config 传入一个 JSON 文件，取代冗长的命令行；CLI 读取相同格式。命令行参数始终优先——命令行自己设置了某个单值参数时，文件中该参数的条目会在解析之前被丢弃（不展开、不替换其中的变量、也永远不会发起其下载），因此可以在多台主机上复用同一个文件，只覆盖需要变化的部分。每个被覆盖的参数会在 stderr 上打印一行 [config] --X is set on the command line, so the value from '<file>' is ignored …。--gpu-device 与 --kv-cache-dtype 同样如此。--config 可重复以叠加多个文件（后出现的文件中的条目以同样方式取代先前的条目）。--skills-dir 由获胜来源替换整份根目录列表，获胜来源内部的重复值保留。会累加的参数——--stop、--skill、--lora、--lora-scale、--lora-config、--image 与各个 --ref-* 输入——则保留文件中的值并把命令行的值追加在后面。允许注释与尾随逗号。

# 从文件读取参数；绑定回环地址，并按主机覆盖后端
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --config config/server-basic.json --host 127.0.0.1
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --config config/server-basic.json --backend ggml_cpu --host 127.0.0.1

键名与下方长选项名相同（可带或不带前缀 --）。字符串/数字展开为 --key value，true 展开为裸开关 --key，数组展开为重复的标志（如 "stop": ["</s>", "<|eot|>"]）。false 与 null 不产生任何参数，因此要关闭默认开启的选项，请写它的否定形式（"no-continuous-batching": true）。lora-scale 与 lora-config 不能写成数组，已移除的选项作为键也会被拒绝。由于服务端会拒绝未知选项，仅 CLI 使用的键（如 interactive 或 input）会让它在启动时报错；惩罚窗口在两个宿主上都叫 repeat-last-n。

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

自动下载。 任何文件参数都可以写成带本地 path 与一个或多个 urls（或单个 url）的对象。相对 path 以配置文件所在目录为基准解析。若 path 不存在，则从第一个可用 URL 下载（镜像按顺序尝试），保存到该路径，之后复用；进度打印到 stderr，可选的 sha256 只校验新下载的文件（已存在的文件直接使用）。命令行（或后出现的文件）也设置了同一参数的下载条目，会在解析之前被丢弃，因此在命令行上传 --mmproj none 既会停用已配置的投影器，也会跳过它的下载。

{
  "variables": { "modelRoot": "C:/models", "repo": "https://huggingface.co/unsloth/gemma-4-E4B-it-GGUF/resolve/bfc15c382204943c3a8fff0c750b94ae2364d7a3" },
  "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-2.1.json）——每个都使用真实、公开、无需授权的 URL，因此在全新机器上也能直接运行。完整说明见 config/README.md。

默认值会填补请求未提供的任何字段。开箱即用的默认值与 Ollama 一致：temperature 0.8、top-k 40、top-p 0.9、min-p 0、在最近 64 个 token 上的重复惩罚 1.1、存在/频率惩罚 0、seed -1。你显式配置过的参数还会覆盖客户端为其发来的值 —— 很多聊天客户端（如 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 --host 127.0.0.1 \
    --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|>"

使用 --model encoder.gguf --embeddings 托管 Snowflake、MiniLM 或 EmbeddingGemma 2。POST /v1/embeddings 与 POST /api/embed 返回归一化向量；EmbeddingGemma 2 配合 --mmproj 还支持图像/音频/视频与混合内容序列。后端与验证范围依模型而定。 配方、API 与验证 →

托管一个 DiffusionGemma GGUF（例如使用 config/jev-diffusiongemma-q4.json），POST /v1/systemone 就会应答与 Jev 兼容的类型化决策请求：请求体携带状态与类型化问题（noul、choice、score），响应返回在一次去噪步之后读出的概率、选项与期望分数。model 可以写已加载模型的名称，或别名 jev-latest / jev-preview（它们不是独立的权重）。请求只接受 JSON；用 --mmproj 加载视觉塔后，请求还可以在 images 数组中内联最多 8 张图像（base64 或 data: URL）。TS_JEV_MAX_BODY_MB（默认 8，1–64）、TS_JEV_MAX_CANVAS（默认 64，8–4096）与 TS_JEV_MAX_PENDING（默认可接纳 32 个请求，1–1024）限定工作量。字段、限制与状态码 →

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

同一个模型还可以委派任务：在 /v1/chat/completions、/v1/responses、/api/chat/ollama 与 Web UI 的 /api/chat 上，对能渲染工具声明并解析工具调用的家族（Mistral 3、Hunyuan Dense 与 DiffusionGemma 除外），子智能体委派默认开启。是否调用 spawn_agent、wait_agent、send_input、close_agent 与 list_agents 由模型决定；它既不依赖技能，也不依赖 --code-exec。每个子智能体都是同一模型上的独立对话，拥有自己的 KV 状态副本；explorer 与 reviewer 子智能体只读。--no-multi-agent 可关闭委派，下方的 --agents-* 选项为它设定上限，请求也可以用 "multi_agent": false 退出。项目没有发布它的延迟或质量测量数据。→ 子智能体

LTX 2.5: 使用 --config config/ltx-2.5-distilled.json；NVIDIA 用 cuda/ggml_cuda，Apple 用 mlx/ggml_metal（实际为 MLX），CPU 别名选择直接 CPU。默认 1024×1024×17、24 fps，宽高为 64 倍数、帧数 8k+1；8 步半尺寸加 3 步精修，CFG 1。 五文件、音频、条件与限制 →

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

# MiniMax-H3：画面与它的 32 kHz 立体声音轨在同一个潜变量里一起去噪。
# 不设尺寸参数：文生视频为 640×384，上传的关键帧按 MiniMax 的 768p 配方决定画布；
# --video-width/--video-height 会把所有模式固定为同一尺寸
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --host 127.0.0.1 \
    --model ./models/minimax_h3_fl2va_pruned-Q4_K.gguf --backend ggml_cuda \
    --video-steps 20 --video-frames 22

# 换另一个权重：用身份 / 外观参考生成一个新场景，尺寸为 640×384
dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --host 127.0.0.1 \
    --model ./models/minimax_h3_ref2va_pruned-Q4_K.gguf --backend ggml_cuda \
    --video-steps 20 --video-frames 22

FL2VA 与 Ref2VA 是关键帧和参考模式各自使用的独立检查点。唯一配置 config/minimax-h3-fl2va.json 会下载两者、共享的 Qwen3-VL-32B 编码器、两个 VAE 和固定版本的分词器。模型按请求切换去噪器，/api/models 会报告可用模式。配置把输出尺寸交给对应工作流；手动安装分词器时可设置 TS_VIDEO_TOKENIZER。

要让 FL2VA 按 LightX2V 的 8 步或 4 步 Turbo 配方提供服务，加上它的插件配置即可。此后每段片段都按插件的调度采样，所以请不设 --video-steps（或设为插件的步数），请求也不要带 steps，与 Web UI 一样：与之冲突的 --video-steps 会在下载任何文件之前终止启动，冲突的请求返回 400（流式路由则是 {done, error} 事件）。权重（1.38 GB）在首次使用时下载；4 步配方为推断所得。→ Turbo 插件

dotnet TensorSharp.Server.Host/bin/TensorSharp.Server.Host.dll --config config/minimax-h3-fl2va.json --host 127.0.0.1 \
    --lora config/lora/minimax-h3-fl2v-turbo-8step.json

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

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

curl -s http://127.0.0.1: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 下无引导运行（在 Turbo 插件下，与插件不同的 flowShift 或 sampler 会被拒绝）。

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

选项不区分大小写，也接受 --option=value 形式。与 CLI 不同，服务端遇到未知选项或多余的位置参数会拒绝启动；若有已知选项与之相差不超过两处编辑，还会提示最接近的那个。

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

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

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