命令行 (CLI)

TensorSharp.Cli 是用于本地提示词、多模态实验、提示词检查、JSONL 批处理工作流、交互式 REPL 与内置基准测试的控制台宿主。构建后二进制位于 TensorSharp.Cli/bin/...。

约 30 秒快速开始

请在 TensorSharp 仓库根目录执行，并先按平台安装 .NET 10 SDK。已验证的快速开始会构建原生 GGML 后端，并运行仓库基准已验证的 gemma-4-E4B-it-Q8_0.gguf（7.48 GiB）。复制并运行这些命令约需 30 秒；模型下载与首次 restore/构建耗时更长，取决于网络速度与机器性能。原生源码构建还需要 Git、网络访问、CMake 与可用的 C++ 工具链。

Linux + NVIDIA

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
echo "请用一段话说明本地推理。" > prompt.txt
dotnet run --project TensorSharp.Cli -c Release --no-build -- --model models/gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --max-tokens 128 --backend ggml_cuda

Windows PowerShell + NVIDIA

$env:TENSORSHARP_GGML_NATIVE_ENABLE_CUDA = 'ON'
dotnet build TensorSharp.slnx -c Release -p:TensorSharpSkipMlxNative=true
curl.exe --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
Set-Content -Encoding utf8 prompt.txt "请用一段话说明本地推理。"
dotnet run --project TensorSharp.Cli -c Release --no-build -- --model models\gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --max-tokens 128 --backend ggml_cuda

省略 --input 时，CLI 会退回内置的 What is 1+1? 提示词；若要进行自定义的单次文本推理，请把提示词保存到文件并通过 --input 传入。--prompt 仅用于 Qwen-Image-Edit 的编辑指令。

在其他原生后端上运行 Gemma 4 E4B

Apple Silicon 请省略 CUDA 环境变量并使用 ggml_metal；受支持的 Windows/Linux Vulkan GPU 请改为请求 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=ON 并使用 ggml_vulkan；ggml_cpu 运行原生 CPU 内核，无需 GPU。同一仓库还提供内存占用更低的 gemma-4-E4B-it-Q4_K_M.gguf。纯文本不需要 mmproj；只有图像、视频或音频输入才需要通过 --mmproj 添加匹配的 mmproj-gemma-4-E4B-it-Q8_0.gguf。完整平台语法见快速开始。

示例

请在仓库根目录运行这些源码命令。替换示例路径，并选择构建所支持的原生后端。

# 文本推理（macOS）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --output result.txt \
    --max-tokens 200 --backend ggml_metal

# Windows/Linux + NVIDIA GPU 上的文本推理
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --output result.txt \
    --max-tokens 200 --backend ggml_cuda

# 在任意 Vulkan GPU（AMD / Intel / NVIDIA）上的文本推理
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --output result.txt \
    --max-tokens 200 --backend ggml_vulkan

# 多 GPU 主机：先列出可见的 Vulkan 设备，再按索引选择
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- --list-gpus
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --max-tokens 200 \
    --backend ggml_vulkan --gpu-device 1

# 交互式逐轮聊天（REPL），带 KV 缓存复用与斜杠命令
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal --interactive
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal -i \
    --system "You are a terse assistant." --temperature 0.7 --top-p 0.9 --think

# DSpark 块级投机解码（DeepSeek V4）：--model 指向分片 GGUF 的第一片，
# --draft-model 指向独立的 DSpark 草稿器。需要贪心采样。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <DeepSeek-V4-Flash-...-00001-of-00005.gguf> --backend ggml_cuda \
    --draft-model <DSpark-drafter.gguf> --input prompt.txt --max-tokens 200 --temperature 0

# GLM 5.x：--model 指向第一个分片，同一组的其余分片由 GgufFile 自行找到。
# 权重会按层切分到所有可见 GPU，自报的 1M 上下文则按权重落盘后剩余的显存缩定。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <GLM-5.2-UD-IQ2_XXS-00001-of-00006.gguf> --backend ggml_cuda \
    --input prompt.txt --max-tokens 200 --think

# GLM-5.3（非 Flash）与 GLM-5.2 是同一套 79 块 glm-dsa 结构 —— 256 个路由专家取
# top-8 外加一个共享专家、带 lightning indexer 的 MLA —— 因此它走 GLM-5.2 的加载
# 路径，不需要新代码也不需要新参数，只有文件不同。unsloth/GLM-5.3-GGUF 每个量化
# 各占一个子目录，每个都是多分片的一组（UD-Q2_K_XL 为七个分片、236.4 GiB）；它仅
# 文本：该仓库任何量化都没有发布 mmproj，在 glm-dsa 上传 --mmproj 只会告警并忽略。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <UD-Q2_K_XL/GLM-5.3-UD-Q2_K_XL-00001-of-00007.gguf> --backend ggml_cuda \
    --input prompt.txt --max-tokens 200 --think

多模态

# 图像推理（Gemma 4、Qwen 3.5-family）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --image photo.png --max-tokens 200 --backend ggml_metal

# 视频推理（Gemma 4）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --video clip.mp4 --max-tokens 200 --backend ggml_metal

# 音频推理（Gemma 4）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --audio speech.wav --max-tokens 200 --backend ggml_metal

# PDF 文档问答（--input 是问题；扫描件/纯图像 PDF 需要视觉模型 +
# --mmproj，含文本的 PDF 可使用任意模型）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --pdf report.pdf --input question.txt \
    --max-tokens 400 --backend ggml_metal

推理、工具与采样

# 思考 / 推理模式
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --max-tokens 400 --backend ggml_metal --think

# 工具调用
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --max-tokens 300 --backend ggml_metal \
    --tools tools.json

# 带采样参数（CLI 默认为贪心解码）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --max-tokens 200 --backend ggml_metal \
    --temperature 0.7 --top-p 0.9 --top-k 40 --repeat-penalty 1.2 --seed 42

图像编辑（Qwen-Image-Edit）

# 提示词 + 输入图像 -> 编辑后的图像。VAE + Qwen2.5-VL 文本编码器伴随文件
# 会在 DiT GGUF 旁解析（或用 --qwen-image-vae / --qwen-image-vl /
# --qwen-image-mmproj 指定）。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <qwen-image-edit-DiT.gguf> --image input.png \
    --prompt "Make the sky a dramatic sunset." --output edited.png \
    --backend ggml_cuda --diffusion-steps 30 --cfg 2.5 --diffusion-seed 0

视频生成

MiniMax-H3 在同一个打包潜变量里同时去噪视频与原生 32 kHz 立体声音轨，所以声音和画面来自同一次前向。它经过 CFG 蒸馏，因此必须传 --cfg 1.0（更高的取值会被直接拒绝），默认 20 步，而 4–8 步是它的快速工作点：

# 文本 -> H.264 MP4 外加一个旁挂 WAV。写出 fox.mp4 与 fox.wav。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <minimax_h3_fl2va_pruned-Q4_K.gguf> --backend ggml_metal \
    --prompt "a red fox trotting through falling snow, cinematic" \
    --width 640 --height 384 --video-frames 22 --diffusion-steps 8 --cfg 1.0 \
    --output fox.mp4

# 让一张照片动起来：在 FL2VA 权重上，这张图像就是首帧。
# 再加 --end-image 可以把尾帧也钉住（--video-mode fl2v）。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <minimax_h3_fl2va_pruned-Q4_K.gguf> --backend ggml_metal \
    --image portrait.jpg --video-mode i2v \
    --prompt "the person turns toward the camera and smiles" \
    --width 640 --height 384 --video-frames 22 --diffusion-steps 8 --cfg 1.0 \
    --output animated.mp4

# 参考：保留主体，围绕它构建一个新场景。需要 Ref2VA 权重，
# 最多九个 --ref-image；--ref-video / --ref-audio 则接受片段与音轨。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <minimax_h3_ref2va_pruned-Q4_K.gguf> --backend ggml_metal \
    --ref-image person.jpg --ref-image bottle.png --video-mode ref \
    --prompt "she holds the bottle up to the light on a rooftop at golden hour" \
    --width 640 --height 384 --video-frames 22 --diffusion-steps 20 --cfg 1.0 \
    --output rooftop.mp4

Wan 2.1 / 2.2 只生成视频，而在那里，--model 指向哪个权重决定了整体耗时：

# 提示词 -> H.264 MP4。UMT5-XXL 文本编码器与视频 VAE 会在 DiT GGUF
# 旁边自动解析（也可用 --video-text-encoder / --video-vae 指定）。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <Wan2.2-TI2V-5B-Q8_0.gguf> \
    --prompt "A red fox trotting through falling snow, cinematic" \
    --video-frames 81 --fps 24 --output out.mp4 --backend ggml_cuda

# 图像 -> 视频：图像作为首帧，提示词驱动运动
# （仅 Wan 2.2 TI2V-5B 与 A14B I2V 支持）。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <Wan2.2-TI2V-5B-Q8_0.gguf> --image first_frame.png \
    --prompt "the camera pushes in as the waves rise" \
    --video-frames 81 --fps 24 --flow-shift 5.0 --output out.mp4 --backend ggml_cuda

# 快车道：把 --model 指向一个步数蒸馏权重。命令的其他部分完全不变；
# 仅凭文件名，这次运行就会切换为 4 次无引导前向。
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <Wan2_2-TI2V-5B-Turbo-Q8_0.gguf> --image first_frame.png \
    --prompt "the camera pushes in as the waves rise" \
    --video-frames 121 --fps 24 --output out.mp4 --backend ggml_metal

DiffusionGemma 与检查

# DiffusionGemma 文本扩散生成
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <diffusion-gemma.gguf> --input prompt.txt --backend ggml_metal \
    --max-tokens 256 --diffusion-steps 48 --diffusion-seed 0

# 检查渲染后的提示词与分词，但不运行推理
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input prompt.txt --dump-prompt

批处理与基准测试

# 批处理（JSONL）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --input-jsonl requests.jsonl \
    --output results.txt --backend ggml_metal

# 带 KV 缓存复用的多轮对话模拟（与 Web UI 行为一致）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --multi-turn-jsonl chat.jsonl \
    --backend ggml_metal --max-tokens 200

# 吞吐基准：best-of-N 的 prefill 与 decode 计时
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal \
    --benchmark --bench-prefill 256 --bench-decode 128 --bench-runs 3

JSONL 格式为每行一个 JSON 对象：

{"id": "q1", "messages": [{"role": "user", "content": "What is 2+3?"}], "max_tokens": 50}
{"id": "q2", "messages": [{"role": "user", "content": "Write a haiku."}], "max_tokens": 100, "temperature": 0.8}

配置文件（--config）

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

# 使用该文件，但本次运行覆盖后端
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --config config/cli-basic.json --backend ggml_cpu

键名与下方长选项名相同（可带或不带前缀 --）。字符串/数字展开为 --key value，true 展开为裸开关 --key，数组展开为重复的标志。

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

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

{
  "variables": { "modelRoot": "C:/models", "hf": "https://huggingface.co" },
  "backend": "ggml_cuda",
  "max-tokens": 256,
  "temperature": 0.7,
  "model": {
    "path": "${modelRoot}/Qwen3.5-9B-Q8_0.gguf",
    "urls": [ "${hf}/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q8_0.gguf" ]
  }
}

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

命令行选项

不带任何参数运行 CLI —— 或使用 --help（也支持 -h、-?、/?）—— 会打印完整的参数参考：逐项列出说明、默认值、取值范围与示例，并在日志与模型机制启动之前退出。未知参数会被忽略，因此请准确复制选项名，否则拼写错误也可能看起来执行成功。

输入 / 输出

运行时

采样

CLI 默认为贪心解码：temperature 0、top-k 0、top-p 1.0、min-p 0、关闭惩罚、seed -1（与默认值匹配 Ollama 的服务端不同）。传入以下参数可启用采样；这些参数也会带入交互式 REPL。

投机解码

默认关闭。草稿器提议接下来的若干 token，主干用一次批量前向完成验证；每个真正输出的 token 仍然取自主干的某一行，并由本次运行自己的采样器抽出，因此这纯粹是一条提速路径 —— 输出序列与普通解码得到的完全一致。它在 --input、--input-jsonl、--multi-turn-jsonl 与 --interactive 上都会生效，而且这些参数必须在模型加载之前出现在命令行上：--spec 正是让 glm-dsa 把约 3 GiB 的 NextN 层调入显存的那个开关（这同时也会挤占上下文的空间），而 --spec-draft 在加载时就决定了原生计算图缓存的大小。→ MTP / NextN · DSpark · docs/speculative_decoding.md

DiffusionGemma、基准测试与日志

视频生成（MiniMax-H3 · Wan 2.1 / 2.2）

以下参数在 --model 为视频生成 DiT（MiniMax-H3 或 Wan）时生效。--prompt 提供文本，--image 提供条件帧，--output 指定 MP4 文件名（默认 video.mp4；若扩展名写成 .png，则改为把各帧写成 PNG）。除非用 --diffusion-steps / --cfg 覆盖，去噪步数与引导强度都来自模型自身的配方。

在视频家族中，Wan 可运行于 ggml_cuda、ggml_vulkan、ggml_metal、ggml_cpu、cuda 与 cpu —— 它是唯一会直接拒绝 --backend mlx 的模型族。Wan 与 MiniMax-H3 都不支持 --tp。→ MiniMax-H3 实测数据 · Wan 后端耗时与成本模型

完整参考（含 --test、--test-templates 与分块 prefill 正确性检查）见 API 参考 页。

Agent Skills（智能体技能）

一个技能就是一份 SKILL.md 加上脚本、参考文档与素材。CLI 先展示名称与描述；对于能调用工具的模型，即使显式选中技能，启动时也只放元数据，模型决定使用后再通过 skills_read 读取说明。无法完成工具往返的家族才会把选中技能正文内联。→ 功能概览 · 通过 HTTP 使用 · 在 C# 中使用 · 智能体架构

# 查看注册了哪些技能、来自哪里，以及是否有加载告警
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --skills-dir ~/skills --list-skills

# 选中一个技能的一次性推理
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal \
    --skills-dir ~/skills --skill pdf --input prompt.txt --max-tokens 600

# 两个技能，且关闭发现：模型只看得到这两个，别的都看不到
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_cuda --skills-dir ~/skills \
    --skill pdf --skill xlsx --skills-no-discovery --input prompt.txt

# 交互式，并允许执行脚本（自己的机器、自己的技能）
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal --skills-dir ~/skills \
    --skills-allow-exec -i

同样的参数拼写在配置文件（"skills-dir": ["/srv/skills"]）和 TensorSharp.Server 上都成立，因此一份配置文件可以同时驱动两个宿主。多个目录按优先级顺序扫描，安装目录排在最前；两个目录之间的重名会直接报错，而不是靠自动改名解决。在 REPL 里，/skills 与 /skill <name> 对单次会话起同样的作用——见交互式 REPL 命令。可直接取用的开源技能：github.com/anthropics/skills；完整参考见 docs/agent_skills.md。

智能体工作与代码执行

--code-exec 启用有界的单助手模型 / 工具循环。TensorSharp 声明并执行五个内置工具：read_file、edit_file、write_file、shell 与原子化的 apply_patch；通过 --tools 提供的调用方工具仍回传调用方处理。这里没有子智能体运行时，也没有逐命令审批提示；下列启动参数就是运维授权。→ 智能体工作

# 持久交互工作区；命令仍默认离线
dotnet run --project TensorSharp.Cli/TensorSharp.Cli.csproj -- \
    --model <model.gguf> --backend ggml_metal --code-exec -i

CLI 会在整段聊天中保留同一个工作区、当前目录、允许保留的导出环境状态与安装的软件包；技能脚本也与代码工具共用它。PATH 会在每次调用时刻意重建，因此靠修改 PATH 激活虚拟环境不会跨调用保留。每条命令仍是一个新的受约束进程。Linux bubblewrap 0.12+ 会约束写入、主目录读取、网络与后代进程；macOS Seatbelt 约束写入 / 主目录 / 网络，但会报告故意脱离的子进程可能比请求活得更久；Windows 只提供进程树限制，因此在 required 模式下拒绝执行。生成文件以本地路径报告。当前无法返回工具调用的模型——qwen4exp，以及不声明工具的 Mistral 3——不会得到代码工具。

交互式 REPL 命令

用 --interactive / -i 启动。任何不以 / 开头的内容都是一轮用户输入；输入 /help 查看列表。提示头显示当前模型、后端、架构、上下文长度、投影器、对话深度与待发送附件。生成时按 Ctrl+C 中断；在提示符处按 Ctrl+C 退出。

对话

Agent Skills

模型与运行时

采样（实时）与上传（下一轮）