快速开始

从源码 checkout 到已验证的 CLI 回复或本地 API。快速上手在原生 GGML 后端上运行 Gemma 4 E4B；无法构建原生代码时，仍可使用托管 CPU 路径（无需 CMake 或 GPU 工具链）。

1 · 环境要求

安装 .NET 10 SDK

TensorSharp 面向 net10.0，因此从源码构建必须安装完整的 .NET 10 SDK；只安装 .NET Runtime 或 ASP.NET Core Runtime 并不足够。SDK 已包含运行 CLI 与服务器所需的运行时。请先查看 Microsoft 的 .NET 跨平台安装指南，再按操作系统选择安装方式：

安装后请打开一个新终端，并确认列表中包含 10.0.x SDK：

dotnet --list-sdks

其他前置要求

• git、curl 与网络访问 —— 用于克隆 TensorSharp 与下载模型。完整原生构建还会把 ggml 克隆到 ExternalProjects/ggml/；之后可设置 TENSORSHARP_GGML_NO_UPDATE=1 跳过网络更新。
• 一个 GGUF 模型文件 —— 例如来自 Hugging Face。见模型下载。

各平台工具链（仅 GPU 加速需要）

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/TensorSharp.Server.csproj -c Release

CLI 二进制位于 TensorSharp.Cli/bin/...，服务器位于 TensorSharp.Server/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

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。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 -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --backend ggml_cuda --max-tokens 128
# 打开 http://localhost:5000/index.html

http://localhost:5000/ 返回健康状态；浏览器聊天位于 /index.html。兼容 Ollama 和 OpenAI 的端点使用同一个固定端口。

下一步去哪