快速上手

先得到一次文本回复：选择界面与平台 → 安装 → 下载一个模型 → 发出提示 → 检查结果。图像、视频、多 GPU 与技能在完成这一步后再选。

1 · 选择界面

桌面路径：从发布页选择 Mac Apple Silicon DMG 或 Windows x64 MSI，安装并打开，在 ☰ → 模型 → 下载 → 使用 后发送消息。也有 PKG/ZIP；Windows 可能需要 WebView2。内置目录从 12 GB 系统内存起步，权重另下；较早发布可能没有桌面资产。具体包校验与限制见桌面安装与首次聊天。

CLI/服务端也有 自包含发布归档，适用于 Windows/Linux x64 CPU/CUDA 和 macOS arm64。发布包对应自己的标签，不能据此假定包含当前源码的全部功能；下文命令是源码构建，不是对下载归档的验证。

2 · 安装并匹配平台

源码构建需要 .NET 10 SDK

需要完整 SDK，只有 .NET Runtime 不足以构建。安装后打开新终端，确认列表中有 10.0.x：

dotnet --list-sdks

为这台机器选择后端

示例默认使用 ggml_cpu；把运行命令的后端改成表中的一个值即可。CUDA 构建前设置 TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON；Vulkan 使用 TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN=ON。Windows PowerShell 的写法是 $env:TENSORSHARP_GGML_NATIVE_ENABLE_CUDA="ON"；macOS/Linux 是 export TENSORSHARP_GGML_NATIVE_ENABLE_CUDA=ON。Metal 不需要 CUDA 开关。完整安装、Vulkan 工具链自动配置与 MLX 的额外依赖见后端与原生构建指南。

取得源码

git clone https://github.com/zhongkaifu/TensorSharp.git
cd TensorSharp

只运行下面的应用项目即可；首次运行会还原与构建，不必先构建包含桌面应用的整个解决方案。Git、curl 与网络访问用于下载源码、依赖及模型；首次原生构建会取得上游 ggml。

3 · 下载一个文本模型

本例使用公开的 Gemma 4 E4B Q8_0，文件为 7.48 GiB。磁盘文件大小不是运行内存需求：还要为 KV 缓存与执行预留内存。同仓库有较小的 Q4_K_M；换量化或模型前核对Gemma 4 模型卡与其他模型下载。这次只输入文本，不需要 mmproj。

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

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

4 · 得到第一条文本回复

在仓库根目录执行，按上表替换 ggml_cpu。CLI 的一次性文本提示来自 --input 文件；--prompt 是生成图像/视频的参数。下例使用贪心采样，最多输出 32 token，首次构建可能需要数分钟。

'What is 2+2? Reply with only the number.' | Set-Content -Encoding utf8 prompt.txt
dotnet run --project TensorSharp.Cli -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend ggml_cpu --temperature 0 --max-tokens 32

printf '%s\n' 'What is 2+2? Reply with only the number.' > prompt.txt
dotnet run --project TensorSharp.Cli -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend ggml_cpu --temperature 0 --max-tokens 32

想用浏览器或 HTTP？改为启动同一模型的服务端，在运行命令中选择相同后端，并让这个终端保持运行：

dotnet run --project TensorSharp.Server.Host -c Release -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --backend ggml_cpu --host 127.0.0.1 --port 8080 --max-tokens 32

打开 http://127.0.0.1:8080/，发送同一个算术问题。这里显式使用本机回环与 8080 端口；默认其实是 0.0.0.0:5000，macOS 的 5000 常被 AirPlay 占用。服务端没有内置鉴权或 TLS；对外部署需自己的鉴权 HTTPS 边界。

5 · 验证这条路径

在另一个终端检查；Windows PowerShell 将 curl 改为 curl.exe：

curl --fail http://127.0.0.1:8080/health
curl --fail http://127.0.0.1:8080/v1/models

把下面内容保存为 request.json；若模型 ID 不同，使用 /v1/models 返回的值：

{
  "model": "gemma-4-E4B-it-Q8_0",
  "messages": [
    {
      "role": "user",
      "content": "What is 2+2? Reply with only the number."
    }
  ],
  "temperature": 0,
  "max_tokens": 32,
  "stream": false
}

curl --fail http://127.0.0.1:8080/v1/chat/completions -H "Content-Type: application/json" --data-binary "@request.json"

检查 JSON 中的 choices[0].message.content 有文本。正常 Web UI 部署中 / 打开聊天；加 --no-webui 或没有 Web UI 文件时，/ 才返回存活文本。稳定的存活路由始终是 /health。 想继续终端多轮聊天，可用 CLI 的 --interactive；完整格式见CLI 参考与HTTP API 示例。

卡住时，按阶段排查

dotnet run --project TensorSharp.Cli -c Release -p:TensorSharpSkipGgmlNative=true -p:TensorSharpSkipMlxNative=true -- --model models/gemma-4-E4B-it-Q8_0.gguf --input prompt.txt --backend cpu --temperature 0 --max-tokens 32

回复成功后，再选择下一项任务

可用 JSON 配置文件复用参数；文件可以下载资源，所以先检查配置内容。分支源码可能领先于发布包，选择功能前查看项目状态。

高级设置与参考

• 桌面源码构建：TensorAgent 构建与验证保留 MAUI 工作负载、平台应用头、TensorSharpSkipTensorAgentApp 与缺失依赖跳过规则；构建测试项目不会运行测试。
• 嵌入：独立服务指南保留 MiniLM/Snowflake 下载、--embeddings、纯 C#/原生后端及 /v1/embeddings、/api/embed 示例；与聊天服务使用不同端口。
• 知识：知识库指南保留 TS_KNOWLEDGE_DIRECTORY、knowledgeCollections、BM25/可选嵌入、Reindex 与媒体提取限制；上传后仍需选择“在此聊天使用”。
• 多模态输入：Gemma 4 模型卡保留匹配 mmproj 文件名与显式 --mmproj 用法；服务端不会自动发现投影器。MiniMax-H3 的专门指南保留约 46 GB 配置下载、Turbo 1.38 GB、采样器约束与 TS_VIDEO_TOKENIZER。
• DGX Spark / GB10：实验性 CUDA 13 / Linux ARM64 构建面向单 GB10，不能使用 x64 CUDA 包；历史硬件检查不能证明当前上游重集成，托管 CI 只检查 CPU/归档路径。

# RunPod Ubuntu 24.04 images using this CUDA compatibility directory:
export LD_LIBRARY_PATH=/usr/local/cuda-12.6/compat:$LD_LIBRARY_PATH
# Older Ubuntu releases needing the .NET backports package source:
add-apt-repository ppa:dotnet/backports
apt update && apt install dotnet-sdk-10.0