快速开始
从源码 checkout 到已验证的 CLI 回复或本地 API。快速上手在原生 GGML 后端上运行 Gemma 4 E4B；无法构建原生代码时，仍可使用托管 CPU 路径（无需 CMake 或 GPU 工具链）。
正在沿着 Gemma 4 E4B 路径动手实践？《From Tensors to Tokens》把这份快速开始扩展成一条从零出发的系统讲解，带你理解每一步背后的推理引擎。了解 TensorSharp 配套图书 →
1 · 环境要求
安装 .NET 10 SDK
TensorSharp 面向 net10.0，因此从源码构建必须安装完整的 .NET 10 SDK；只安装 .NET Runtime 或 ASP.NET Core Runtime 并不足够。SDK 已包含运行 CLI 与服务器所需的运行时。请先查看 Microsoft 的 .NET 跨平台安装指南，再按操作系统选择安装方式：
| 平台 | 安装 SDK | 官方说明 |
|---|---|---|
| Windows | 打开 PowerShell 或命令提示符，运行 winget install Microsoft.DotNet.SDK.10。 | 在 Windows 上安装 .NET |
| macOS | 下载与处理器匹配的 .NET 10 SDK 安装程序：Apple Silicon 选择 Arm64，Intel Mac 选择 x64。 | 在 macOS 上安装 .NET |
| Linux | 按对应发行版的说明配置软件源（若需要），再安装 dotnet-sdk-10.0。在 Ubuntu 上完成当前版本所需的软件源设置后，先运行 sudo apt-get update，再运行 sudo apt-get install -y dotnet-sdk-10.0。 | 选择 Linux 发行版（例如 Ubuntu） |
安装后请打开一个新终端，并确认列表中包含 10.0.x SDK：
dotnet --list-sdks其他前置要求
git、curl与网络访问 —— 用于克隆 TensorSharp 与下载模型。完整原生构建还会把 ggml 克隆到ExternalProjects/ggml/；之后可设置TENSORSHARP_GGML_NO_UPDATE=1跳过网络更新。- 一个 GGUF 模型文件 —— 例如来自 Hugging Face。见模型下载。
各平台工具链（仅 GPU 加速需要）
| 平台 | 用于 | 安装 |
|---|---|---|
| macOS（Metal） | ggml_metal / mlx | CMake 3.20+ 与 Xcode 命令行工具。MLX 还会额外构建 libmlxc。 |
| Windows | ggml_cuda / cuda | CMake 3.20+、Visual Studio 2022 C++ 构建工具、NVIDIA 驱动 + CUDA Toolkit 12.x（含 cuBLAS）。 |
| Linux | ggml_cuda / cuda | CMake 3.20+、NVIDIA 驱动 + CUDA Toolkit 12.x（含 cuBLAS）。 |
| Windows / Linux（任何 Vulkan GPU） | ggml_vulkan | 当主机存在 Vulkan 运行时（loader 已安装）时自动启用；用 --no-vulkan（或 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=OFF）退出。Windows 上未安装 SDK 时会自动准备便携 Vulkan 工具链；Linux 上请安装如 libvulkan-dev glslc spirv-headers。运行时需要 Vulkan 1.3 驱动。 |
| 任意（仅 CPU） | cpu | 除 .NET SDK 外无需任何东西。ggml_cpu 更快，但属于原生构建。 |
2 · 克隆并选择构建路径
git clone https://github.com/zhongkaifu/TensorSharp.git
cd TensorSharp托管 CPU 路径（无需原生工具链）
若要跳过所有原生构建，请同时传入两个跳过属性并使用托管 cpu 后端；首次运行自动 restore 并构建托管项目。
-p:TensorSharpSkipGgmlNative=true -p:TensorSharpSkipMlxNative=true -- --backend cpu完整原生 / GPU 路径
需要 GGML CPU、Metal、CUDA、Vulkan 或 MLX 时构建整个解决方案。首次构建会编译原生桥接，可能需要数分钟；后续为增量构建。
dotnet build TensorSharp.slnx -c Release或只构建其中一个应用：
# 控制台应用
dotnet build TensorSharp.Cli/TensorSharp.Cli.csproj -c Release
# Web 应用
dotnet build TensorSharp.Server.Host/TensorSharp.Server.Host.csproj -c ReleaseCLI 二进制位于 TensorSharp.Cli/bin/...，服务器位于 TensorSharp.Server.Host/bin/...。如需启用 CUDA 或 Vulkan 的原生构建、手动原生构建或 MLX，见构建原生库。
3 · 下载模型
快速上手请从公开的 ggml-org/gemma-4-E4B-it-GGUF 仓库下载推荐的、经基准验证的 gemma-4-E4B-it-Q8_0.gguf（7.48 GiB）。同一仓库还提供更省内存的 gemma-4-E4B-it-Q4_K_M.gguf，更多选项见模型页。
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多模态模型还需下载匹配的投影器（mmproj），并用 --mmproj 传入精确路径。服务端不会自动检测投影器，CLI 也只识别少数旧文件名；显式路径最可靠。
要生成图像或视频？在下载阶段就选好那条快路。下面几个模型族各有一条，差距非常大：
- MiniMax-H3 视频 + 音频 —— 这里唯一连声音一起产出的模型族：画面与原生 32 kHz 立体声音频在同一个打包潜变量里一起去噪，一次运行写出一个
.mp4和一个独立的.wav。它是两个仓库里的四个文件 —— FL2VA 去噪器（10.64 GiB）、共用的 Qwen3-VL-32B 文本编码器（16.97 GiB）、视频 VAE（5.21 GB）和音频 VAE（0.61 GB），合计约 33.5 GB —— 也可以只写一个--config config/minimax-h3-fl2va.json，首次运行时会把四个文件全部下载好。该权重出厂即为 CFG 蒸馏版，因此必须用--cfg 1.0（更高的取值 TensorSharp 会直接拒绝），相对 20 步的默认值，4–8 步是常用的快速工作点。有一处自动下载填不上：文本编码器的 GGUF 不带分词器，需要自己从 MiniMaxAI/MiniMax-H3 取vocab.json和merges.txt放到编码器旁边（或用TS_VIDEO_TOKENIZER指向它们所在的目录）。 - Wan 视频，只有画面 —— 基础的
Wan2.2-TI2V-5B走官方配方 50 步 × 2 次 CFG = 100 次 DiT 前向；Turbo / Lightning / FastWan 权重在训练时就不使用引导，只需 4 次。TensorSharp 会从 DiT 文件名自动识别，不需要额外参数。在 M5 Pro 上，一段 1088×832 × 121 帧的图生视频，基础权重约需 3 h 30 m，Turbo 只需 17 m 30 s —— 命令完全相同，只是--model指向了不同的文件。 - Qwen-Image-Edit —— 用
--qwen-image-lora加载 Lightning 蒸馏 LoRA，可把默认的 30 步 / CFG 2.5（60 次 DiT 前向）降到 4 步或 8 步。
Gemma 4 E4B 后端与平台说明
下一节的首次运行命令面向 Linux + NVIDIA。Windows + NVIDIA 请先在 PowerShell 中设置 $env:TENSORSHARP_GGML_NATIVE_ENABLE_CUDA='ON'，再运行不带 Bash 赋值前缀的相同命令。Apple Silicon 请省略 CUDA 环境变量并改用 ggml_metal。Windows/Linux 上使用 Vulkan 时，请设置 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=ON（PowerShell：$env:TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN='ON'）并使用 ggml_vulkan。没有 GPU 时使用 ggml_cpu（原生 CPU 内核）。纯文本不需要投影器；图像、视频或音频输入需从同一仓库下载 mmproj-gemma-4-E4B-it-Q8_0.gguf，并添加 --mmproj models/mmproj-gemma-4-E4B-it-Q8_0.gguf。
4 · 首次运行
一次性提示词通过 --input 从文件读取；--prompt 属于生成类模型族 —— Qwen-Image-Edit 的编辑指令，以及 MiniMax-H3 与 Wan 的视频提示词。CLI 默认使用 ggml_cpu、贪心解码和 100 个生成 token。环境变量赋值用于启用 CUDA 原生构建；首次运行会编译它，可能需要数分钟，后续为增量构建。
方式 A —— 一次性生成（CLI）
echo "简短回答：TensorSharp 是什么？" > prompt.txt
TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON dotnet run --project TensorSharp.Cli -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --max-tokens 128 --backend ggml_cuda方式 B —— 交互式聊天（REPL）
dotnet run --project TensorSharp.Cli -c Release --no-build -- --model models/gemma-4-E4B-it-Q8_0.gguf -i --max-tokens 128 --backend ggml_cuda逐轮输入消息；用 斜杠命令（如 /reset、/think on 或 /image photo.png）控制会话。
方式 C —— 浏览器 UI + HTTP API（服务器）
TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON dotnet run --project TensorSharp.Server.Host -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --backend ggml_cuda --max-tokens 128
# 打开 http://localhost:5000/index.htmlhttp://localhost:5000/ 返回健康状态；浏览器聊天位于 /index.html。兼容 Ollama 和 OpenAI 的端点使用同一个固定端口。
省去冗长的命令行。 把参数写进一个 JSON 文件，用 --config config/server-basic.json（或 config/cli-basic.json）传入。配置项甚至可以在首次运行时自动下载模型，因此全新机器无需手动下载。仓库的 config/ 目录提供了开箱即用的示例。→ 配置文件