API 参考
所有参数、变量、端点与公共类型集于一处。在输入框中键入即可即时过滤下方全部表格 —— 或按 / 进行全站搜索。
· 匹配的行会在所有区块中实时高亮。
CLI 参数 —— TensorSharp.Cli
| 参数 | 说明 |
|---|---|
--model <path> | GGUF 模型文件路径（必需）。 |
--input <path> | 包含用户提示词的文本文件。 |
--input-jsonl <path> | 含批量请求的 JSONL 文件（每行一个 JSON）。 |
--multi-turn-jsonl <path> | 带 KV 缓存复用的多轮对话模拟 JSONL。 |
--output <path> | 将生成文本写入此文件。 |
--image / --video / --audio <path> | 用于视觉 / 视频 / 音频推理的媒体。 |
--pdf <path> | PDF 文档单次输入：数字 PDF 内联为文本；扫描 PDF 转为页面图像交给视觉模型（页数上限：TS_PDF_MAX_PAGES）。 |
--mmproj <path> | 多模态投影器 GGUF。建议显式传入；CLI 自动检测只识别少数旧伴随文件名。 |
--max-tokens <N> | 最大生成 token 数（默认 100）。 |
--backend <type> | cpu、cuda、mlx、ggml_cpu、ggml_metal、ggml_cuda、ggml_vulkan。 |
--gpu-device <N> | ggml_vulkan 在多 GPU 主机上使用的 Vulkan 设备索引（默认 0；环境变量 TS_GGML_VULKAN_DEVICE）。 |
--list-gpus | 列出可见的 Vulkan 设备（索引 + 显卡名称）后退出。 |
--kv-cache-dtype <type> | KV 缓存精度：f32、f16、q8_0、q4_0（默认按后端/模型自动选择；q4_0 约为 f32 的 1/7；量化档位需原生 GGML flash-attention 路径）。 |
--interactive / -i | 启动交互式 REPL。 |
--system <text> / --system-file <path> | 设定系统提示。 |
--think | 启用思考 / 推理模式。 |
--tools <path> | 含工具 / 函数定义的 JSON 文件。 |
--temperature / --top-k / --top-p / --min-p | 采样控制。 |
--repeat-penalty / --presence-penalty / --frequency-penalty | 惩罚（1.0 / 0 = 关闭）。 |
--seed <N> / --stop <string> | 随机种子（-1 = 随机） / 停止序列（可重复）。 |
--dump-prompt | 渲染提示词 + 分词后退出。 |
--diffusion-steps / --diffusion-seed / --diffusion-blocks <N> | DiffusionGemma 生成控制。 |
--prompt <text> | Qwen-Image-Edit 编辑指令（与 --image 一起；编辑后的 PNG 写入 --output）。 |
--cfg <F> | Qwen-Image-Edit true-CFG 引导尺度（自动：2.5，使用 Lightning LoRA 时为 1.0；<= 1 关闭负向分支）。 |
--qwen-image-vae / --qwen-image-vl / --qwen-image-mmproj <path> | 覆盖解析到的 Qwen-Image-Edit 伴随 GGUF（VAE / Qwen2.5-VL 文本编码器 / mmproj）。 |
--qwen-image-lora <path> | 合并进 DiT 的 Lightning 蒸馏 LoRA（.safetensors）；自动推导步数（如 4 或 8），并将 CFG 切换为 1.0。 |
--paged-kv-quant-bits <0|2|4|8> | TurboQuant 分页 KV 块压缩（0 = 关闭）。 |
--benchmark / --bench-prefill / --bench-decode / --bench-runs | 合成吞吐基准。 |
--bench-kvcache / --bench-kv-turns <N> | 多轮 KV 缓存复用基准。 |
--warmup-runs <N> | 计时前丢弃的前向次数（默认 0）。 |
--test / --test-templates <dir> | 内置分词器/模板测试；对照 GGUF Jinja2 校验模板。 |
--tp <N> | 张量并行度 —— 在单个进程内把模型切分到 N 张 GPU 上（默认 1；需要 --backend cuda、ggml_cuda 或 ggml_vulkan）。TensorSharp.Server 同样支持该参数。 |
--tp-node-id <N> / --tp-peers <list> | 多节点分布式 TP：本节点的 0 起始编号，以及所有节点共用的逗号分隔 host:port 列表。 |
--log-level / --log-dir / --log-file / --log-console | 日志级别、目录，以及文件/控制台开关。 |
服务器参数 —— TensorSharp.Server
| 参数 | 说明 |
|---|---|
--model <path> | 启动时要托管的 GGUF 文件（必需）；无模型进程不能通过 /api/models/load 选择 GGUF。 |
--mmproj <path> | 显式多模态投影器 GGUF；none 可禁用。服务端不会自动检测。 |
--backend <type> | 计算后端；macOS 默认 ggml_metal，其他平台默认 ggml_cpu。 |
--gpu-device <N> / --list-gpus | ggml_vulkan 的 Vulkan 设备选择 / 列出可见 Vulkan 设备后退出。 |
--help | 打印参数说明后退出（不带任何参数启动时也会显示）。 |
--max-tokens <N> | 请求未指定时的默认生成上限（默认 20000）。 |
--temperature / --top-k / --top-p / --min-p | 默认采样值。 |
--repeat-penalty / --presence-penalty / --frequency-penalty / --seed | 默认惩罚与随机种子。 |
--stop <string> | 默认停止序列（可重复）；逐请求会替换该列表。 |
--continuous-batching / --no-continuous-batching | 启用（默认） / 禁用迭代级分页批处理。别名 --paged-batching。 |
--mtp-spec / --no-mtp-spec | 启用 / 禁用 NextN/MTP 推测解码（默认关闭）。 |
--mtp-draft <N> | 每个推测步草拟的最大 token 数（默认 8）。 |
--mtp-pmin <f> | 保留某 token 所需的草稿头最低置信度（默认 0.75）。 |
--mtp-draft-model <path> | 独立的 MTP 草稿 GGUF（Gemma 4 gemma4-assistant）。 |
--prefill-chunk-size <N> | 每个调度步的最大 prefill token 数（设置 TS_SCHED_PREFILL_CHUNK）。 |
--kv-cache-dtype <type> | KV 缓存精度：f32、f16、q8_0、q4_0（默认按后端/模型自动选择；环境变量 KV_CACHE_DTYPE）。 |
--qwen-image-vae / --qwen-image-vl / --qwen-image-mmproj <path> | 覆盖解析到的 Qwen-Image-Edit 伴随 GGUF。 |
--qwen-image-lora <path> | 合并进 DiT 的 Qwen-Image-Edit Lightning LoRA（更少去噪步数，CFG 1.0）。 |
--paged-kv* / --paged-kv-quant-bits | 遗留的独立分页 KV 参数（KV 状态现由引擎管理）。 |
环境变量
| 变量 | 说明 |
|---|---|
BACKEND | 默认后端（macOS 上为 ggml_metal，其他平台为 ggml_cpu）。 |
MAX_TOKENS | 默认最大生成长度（20000）。 |
TS_PDF_MAX_PAGES | PDF 上传与 CLI --pdf 读取的最大页数；0 = 全部（默认）。 |
VIDEO_SAMPLE_FPS / VIDEO_MAX_FRAMES | 视频抽帧速率 / 上限。 |
TENSORSHARP_TEMPERATURE / _TOP_K / _TOP_P / _MIN_P | 默认采样值。 |
TENSORSHARP_REPEAT_PENALTY / _PRESENCE_PENALTY / _FREQUENCY_PENALTY / _SEED | 默认惩罚与随机种子。 |
TENSORSHARP_LOG_LEVEL / _LOG_DIR / _LOG_FILE | 日志级别、目录、文件开关（CLI + 服务器）。 |
DIFFUSION_STEPS / DIFFUSION_MAX_BATCH | DiffusionGemma 每块步数 / 最大批处理请求数。 |
KV_CACHE_DTYPE | CLI + 服务端 KV 缓存精度：f32、f16、q8_0、q4_0；默认自动（= --kv-cache-dtype）。 |
TS_SCHED_DISABLE_BATCHED | 1 强制逐序列 KV 交换（= --no-continuous-batching）。 |
TS_SCHED_MAX_BATCHED_TOKENS | 每步 token 预算（4096）。 |
TS_SCHED_MAX_RUNNING_SEQS | 最大在飞序列数（16）。 |
TS_SCHED_PREFILL_CHUNK | 每步最大 prefill token 数（1024）。 |
TS_SCHED_SOLO_PREFILL_CHUNK | 独占 / 无竞争请求的 prefill 分块（8192）。 |
TS_SCHED_DECODE_QUANTUM | 切换序列前的 decode token 数（256 = 块大小）。 |
TS_SCHED_NUM_BLOCKS / TS_SCHED_BLOCK_SIZE | 引擎块池大小（256） / 每块 token 数（256）。 |
TS_SCHED_PREFIX_CACHE | 0 禁用块哈希前缀共享。 |
TS_<FAMILY>_BATCHED | 0 强制某家族走逐序列路径（如 TS_GEMMA4_BATCHED、TS_QWEN35_BATCHED）。 |
TS_MTP_SPEC / TS_MTP_DRAFT / TS_MTP_PMIN / TS_MTP_DRAFT_MODEL | MTP 推测解码旋钮（对应 --mtp-* 参数）。 |
TS_GMTP_NO_FUSED / TS_GMTP_NO_FAST_ROLLBACK / TS_GMTP_BATCHED_TRUNK | Gemma 4 MTP 草稿路径 A/B 开关。 |
TS_QWEN_IMAGE_VAE / TS_QWEN_IMAGE_TE / TS_QWEN_IMAGE_MMPROJ | Qwen-Image-Edit 伴随文件路径（VAE / Qwen2.5-VL 文本编码器 / mmproj）。 |
TS_QWEN_IMAGE_LORA / TS_QWEN_IMAGE_LORA_SCALE | 合并进 DiT 的 Lightning LoRA .safetensors / 缩放覆盖。 |
TS_QWEN_DIT_CACHE / TS_QWEN_DIT_CACHE_MODE | 整步 DiT 缓存：0 禁用 / 模式 easycache、fbc、both、off。 |
TENSORSHARP_TP_DEGREE | 本地张量并行度 —— 模型切分到多少张 GPU（= CLI 与服务端的 --tp）。 |
TENSORSHARP_TP_DEVICES | 各 TP rank 使用的 GPU 序号，例如 0,2（默认 0..tp-1）。用于 GGML 后端。 |
TENSORSHARP_TP_NODE_ID / TENSORSHARP_TP_PEERS | 多节点分布式 TP：0 起始的节点编号与所有节点共用的 host:port 列表（= --tp-node-id / --tp-peers）。 |
TENSORSHARP_TP_CONNECT_TIMEOUT_SECONDS / _RECV_TIMEOUT_SECONDS | 分布式 TP 网格的 peer 连接重试窗口（120 秒）与单次接收超时（300 秒）。 |
TENSORSHARP_TP_DISABLE_P2P / TENSORSHARP_TP_HOST_ALLREDUCE | 1 强制跨 GPU 拷贝 / 本地 AllReduce 走主机内存，而非 CUDA P2P（诊断用）。 |
TS_KV_CACHE_REDIS_URL / TS_KV_CACHE_REDIS_TTL_MINUTES | Redis 支撑的共享 KV 缓存层及其条目 TTL（默认 1440 分钟；0 = 不过期）。 |
TS_RESPONSES_STORE_REDIS_URL | Redis 支撑的 OpenAI Responses API 存储（取代内存存储）。 |
TS_GGML_VULKAN_DEVICE | ggml_vulkan 使用的 Vulkan 设备索引（= --gpu-device）。 |
TS_FUSED_QKNORM_ROPE | 0 禁用 direct cuda 后端中 Qwen 3.5/3.6 文本 prefill 的融合 QK-Norm + RoPE kernel（默认开启）。 |
TS_JSON_FORCE_OPEN | 0 关闭结构化输出的首 token { 约束（json_object / json_schema 默认开启）。 |
TS_MLX_* | MLX 后端调参：流水线 decode、mlock GGUF、融合 KV 写、批量 MoE decode、内存上限。 |
TENSORSHARP_MLX_LIBRARY / _LIBRARY_DIR | 覆盖 libmlxc 的搜索路径。 |
TENSORSHARP_GGML_NO_UPDATE / _GGML_GIT_REF | 在原生构建时跳过 / 固定 ggml 源码克隆。 |
TENSORSHARP_GGML_NATIVE_ENABLE_VULKAN | 在原生构建时强制开启/关闭 GGML Vulkan 后端（ON/OFF = 构建脚本 --vulkan/--no-vulkan）。检测到 Vulkan 运行时时自动启用；显式选择会在重复构建中保持。 |
HTTP 端点
| 方法与路径 | 风格 | 用途 |
|---|---|---|
GET / | 工具 | 纯存活响应。 |
GET /index.html | Web UI | 浏览器聊天应用。 |
POST /api/generate | Ollama | 单提示补全（流式或非流式）。 |
POST /api/chat/ollama | Ollama | 多轮对话，可选 think / tools / images。 |
GET /api/tags | Ollama | 列出托管模型。 |
POST /api/show | Ollama | 模型信息。 |
POST /v1/chat/completions | OpenAI | Chat Completions（流式、工具、response_format）。 |
GET /v1/models | OpenAI | 列出模型。 |
POST /api/chat | Web UI | 带会话 + KV 复用字段的 SSE 聊天流。 |
POST /api/sessions · DELETE /api/sessions/{id} | Web UI | 创建 / 销毁每标签页会话。 |
POST /api/upload | Web UI | 上传图像 / 音频 / 视频 / PDF / 文本文件。 |
POST /api/image-edit | Web UI | Qwen-Image-Edit 单次编辑（multipart 或 JSON）。 |
POST /api/image-edit/stream | Web UI | 带实时去噪预览的 SSE 图像编辑。 |
GET /api/models | Web UI | 托管模型、支持的后端、默认值。 |
POST /api/models/load | Web UI | 重新加载启动模型（可切换后端，但不能选择任意新文件）。 |
GET /api/version · GET /api/queue/status | 工具 | 服务器版本 / 遗留队列快照。 |
采样参数
Ollama（options） | OpenAI（顶层） | 默认 | 含义 |
|---|---|---|---|
num_predict | max_tokens | 200 | 兼容 API 省略时的最大生成 token 数（Web UI 默认使用 --max-tokens / 20000）。 |
temperature | temperature | 0.8 | 采样温度（0 = 贪心）。 |
top_k | — | 40 | Top-K 过滤（0 = 禁用）。 |
top_p | top_p | 0.9 | 核采样阈值（1.0 = 禁用）。 |
min_p | — | 0 | 最小概率过滤。 |
repeat_penalty | — | 1.1 | 重复惩罚（1.0 = 关闭）。 |
presence_penalty / frequency_penalty | presence_penalty / frequency_penalty | 0 | 存在 / 频率惩罚。 |
seed | seed | -1 | 随机种子（-1 = 随机）。 |
stop | stop | null | 停止序列。 |
| — | response_format | null | text、json_object 或 json_schema。 |
C# 公共 API
| 成员 | 签名 / 取值 | 说明 |
|---|---|---|
ModelBase.Create | static ModelBase Create(string ggufPath, BackendType backend) | 从 GGUF 元数据自动识别架构。 |
ModelBase.Forward | float[] Forward(int[] tokens) | 返回下一 token 的 logits（长度 = 词表大小）。 |
ModelBase.Sample | int Sample(float[] logits, SamplingConfig config, IList<int> generated = null) | 应用惩罚 + 采样。 |
ModelBase.SampleGreedy | int SampleGreedy(float[] logits) | 确定性 argmax。 |
ModelBase.Config / .Tokenizer | ModelConfig / ITokenizer | Config.VocabSize、上下文长度等。 |
BackendType | Cpu, GgmlCpu, GgmlMetal, GgmlCuda, Cuda, Mlx | 后端选择枚举。 |
ITokenizer.Encode | Encode(string text, bool addSpecial) | 文本 → token id。 |
ITokenizer.Decode | string Decode(List<int> ids) | token id → 文本。 |
ITokenizer.IsEos / .EosTokenIds | bool IsEos(int id) / int[] EosTokenIds | 序列结束检测。 |
SamplingConfig | Temperature、TopK、TopP、MinP、惩罚、Seed、StopSequences、MaxTokens | 见 C# 库。 |
IBatchedPagedModel.ForwardBatch | 批量/分页前向 | 多数架构为连续批处理而实现。 |
REPL 命令
| 命令 | 说明 |
|---|---|
/help、/? | 显示所有交互命令。 |
/exit、/quit | 离开会话。 |
/reset、/new | 清空对话历史与 KV 缓存。 |
/history · /save <file> | 打印 / 追加记录。 |
/system <text> | 设置系统提示（重置 KV 缓存）。 |
/think on|off · /multiline on|off | 切换推理模式 / 多行输入。 |
/info、/status | 显示模型、后端、架构、上下文/词表、投影器、深度。 |
/model <path> · /backend <name> · /mmproj <path> | 热切换模型、后端或投影器。 |
/sampling、/show | 打印当前采样配置。 |
/max · /temp · /topk · /topp · /minp | 设置回复长度 / 温度 / top-k / top-p / min-p。 |
/repeat · /presence · /frequency · /seed | 设置惩罚与随机种子。 |
/stop <text> · /clearstop | 添加 / 清除停止序列。 |
/image · /audio · /video · /text <path> · /clearattach | 为下一轮附加媒体 / 文本；丢弃待发送附件。 |