命令行 (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

多模态

# 图像推理（Gemma 3/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

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。

DiffusionGemma、基准测试与日志

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

交互式 REPL 命令

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

对话

模型与运行时

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