SillyTavern 后端 API 连接 3 条路：云密钥、本地模型与排错教程

SillyTavern 后端 API 连接 3 条路：云密钥、本地模型与排错教程

【免费下载链接】SillyTavernLLM Frontend for Power Users.项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern

想在 SillyTavern 里接上 AI 后端？这篇 API 连接教程按"你实际要做的事"分四步走：先选云 API 还是本地部署，再配密钥、填服务器地址，最后学会看版本号和排查连不上的问题。

先选路：三条接入路径怎么挑 🧭

路径	你要准备的东西	适合谁	详见
云端商业 API	一个 API key + 服务商的服务器 URL	不想折腾硬件，按量付费	云端 API 接入
本地部署（KoboldCpp 等）	本地跑起来的推理服务器 URL	要数据留在本地、按次免费	本地模型接入
聚合平台	平台 API key	一个端点试多家模型	配置方式同云端，只是 URL 换成平台地址

区别只有一点：云服务和聚合平台都走 OpenAI 兼容的 chat completions 格式，本地模型走 KoboldAI 协议。SillyTavern 会在后端帮你把请求翻译成对应格式，你只管填对地址和密钥。所有凭据最终都落在secrets.json里，每个服务商对应一个api_key_*命名的标识，后面会展开讲。


云端 API 接入教程：先配密钥，再对请求格式 ☁️

云 API 密钥快速配置

打开设置面板里的 API 密钥管理区域，选择服务商（OpenAI、Mistral AI、Groq、DeepSeek、Together AI 等），把申请到的 key 粘贴进去保存。保存动作就是往secrets.json写一条记录，例如 OpenAI 对应api_key_openai，Groq 对应api_key_groq。

然后去后端设置里选同一服务商，填入服务器 URL（多数情况用默认地址即可）。点保存时 SillyTavern 会自动发起一次状态探测，能返回模型列表就说明连通了。

请求格式长什么样

所有 OpenAI 兼容服务共用一个约定：向/chat/completions发 POST，请求头带Authorization: Bearer <你的key>。实际发出的请求体大致是这样：

{ "model": "gpt-4o", "messages": [ { "role": "system", "content": "你是有帮助的助手" }, { "role": "user", "content": "你好！" } ], "temperature": 0.7, "max_tokens": 1000 }

你不需要手写这些内容，SillyTavern 按你在预设里的采样参数自动组装。了解格式的价值在于：当某家服务报错时，你知道该检查模型名、消息结构还是认证头。

自定义端点：把请求指向任意 OpenAI 兼容服务

如果你的模型托管在自建网关、内网服务或第三方中转上，后端类型选 Custom 即可，它读取api_key_custom这把密钥（没有 key 的服务填个占位值也行，具体看对方要求）。

Custom 提供三个调节旋钮，都是可选的：

• custom_include_body：往请求体里追加任意参数（比如私有服务特有的开关）
• custom_include_headers：追加自定义请求头
• custom_exclude_body：删掉标准参数里你不想要的字段，如max_tokens

改完先用一条最短对话测试，确认对方能接受你的参数组合，再投入正常使用。

本地模型接入实战：KoboldCpp 从 0 连通 🔌

服务器配置：地址怎么填

先在本地把 KoboldCpp（或其他 KoboldAI 协议服务器）跑起来并加载模型，然后在 SillyTavern 后端设置里选择 KoboldCpp，填入服务器 URL，例如http://127.0.0.1:5001。填localhost也没关系，SillyTavern 会自动帮你改写成127.0.0.1。

保存后系统会并发探测三个接口来判断连接质量：/extra/version拿 KoboldCpp 版本号、/v1/model拿当前加载的模型名、/v1/info/version兼容 Kobold United 的老版本服务器。模型名返回no_connection就说明服务没起来或端口不对，先检查本地控制台日志。

生成参数有哪些可调项

KoboldAI 协议和 OpenAI 的参数名不同，本地模型常用的有：temperature（温度）、top_p、top_k、typical（typical_p）、tfs、min_p、rep_pen（重复惩罚）、rep_pen_range、mirostat及其配套的mirostat_tau、mirostat_eta、sampler_order（采样器顺序）、stop_sequence（停止序列）。这些参数在预设里调整，SillyTavern 会原样转发给服务器。

建议的起步值：temperature1.0、top_p0.9、rep_pen1.1。想要输出更稳就提高rep_pen；想要更有创意就调高温度但注意重复率会上升。

流式生成与版本兼容：先看版本号 ⚠️

这是本地接入最容易踩的坑。不同版本的 KoboldCpp 支持的功能不一样，SillyTavern 会根据探测到的版本号决定是否放出对应选项，门槛如下：

功能	最低版本（KoboldCpp / United）
停止序列 stop_sequence	United ≥ 1.2.2
流式生成	KoboldCpp ≥ 1.30
Mirostat	KoboldCpp ≥ 1.35
语法约束 grammar	KoboldCpp ≥ 1.44
min_p 采样	KoboldCpp ≥ 1.48

流式生成开启后，SillyTavern 向/extra/generate/stream发请求，服务端以事件流逐段回传文本，前端边收边渲染，长回答的体验明显更好。旧版本只能走/v1/generate一次性返回，耐心等即可。

另外 KoboldCpp 还支持语音转录（/api/extra/transcribe）和向量嵌入（/api/extra/embeddings），需要在对应扩展里单独填同一个服务器地址。

进阶配置：自定义后端与多模态能力 🧩

自定义端点除了上一节说的三个调节项，还有一个组合技巧：当你的私有服务既改了模型名又要求额外头时，custom_include_body管请求体、custom_include_headers管请求头，两者互不干扰，可以同时生效。

多模态能力取决于你选的后端：

• 图像描述：OpenAI、OpenRouter 等支持在 chat completions 的content里混入image_url条目，SillyTavern 的附件功能会替你拼装
• 语音转录：OpenAI 走专用音频接口；本地用户可用 KoboldCpp 的转录端点
• 文本转语音：OpenAI、Azure TTS（对应api_key_azure_tts）都提供，TTS 扩展里单独配置

原则是：先用纯文本跑通对话，再逐项开启多模态，出问题时容易定位是哪一环。

密钥安全与常见故障排查 🔐

secrets.json 是怎么保管你的 key 的

secrets.json位于每个用户数据根目录下，写入走原子操作（write-file-atomic），中途断电或崩溃也不会把文件写坏成半截 JSON。较新版本里，同一把 key 支持存多个带标签的凭据，/rotate接口让你在服务端一键切换激活哪一把，适合定期轮换密钥时不停机交接。

默认情况下界面只能看到掩码后的 key（中间打星号、保留末尾 3 位）。如果你确实需要完整查看，把config.yaml里的allowKeysExposure设为true——注意这会让密钥出现在页面数据里，局域网多人使用时慎开。此外 SillyTavern 内置 CSRF token 机制（/csrf-token接口下发），防止跨站伪造请求改你的配置。

连接测试与故障对照

保存后端配置时会自动发起状态探测，这就是内置的连接测试。如果对话时出问题，按这个顺序查：

• 403 / 503 反复出现：KoboldAI 类服务器在忙，SillyTavern 会每 2.5 秒自动重试（上限 50 次）。持续重试到上限说明服务器真的卡住了，去本地看是不是上下文太长或显存不足
• 保存时探测不到模型：URL 少了端口、服务器只绑定了 127.0.0.1 而你从别的机器访问、或者防火墙拦了
• key 保存后不生效：确认界面里这把 key 的状态是"已激活"，同 key 多凭据时只有 active 那条会被使用
• 401 / 认证错误：先回密钥管理区确认凭据没过期，再检查服务商后台的用量与权限

密钥轮换的正确姿势：在密钥管理里新增一把新 key（旧的暂时保留），测试新 key 连通后，用 rotate 切到新的，再删掉旧的——全程不用改secrets.json文件。

写在最后

三条路的核心差异只有协议格式，配置思路完全一致：填地址、给 key、保存时看探测结果。给日常使用几个小建议：云 API 和聚合平台优先测短对话再放量；本地模型把 KoboldCpp 升过 1.44，能解锁的功能多一半；密钥轮换用内置的 rotate 接口完成，别手改文件。跑通之后，你就可以在预设里安心调采样参数了。

【免费下载链接】SillyTavernLLM Frontend for Power Users.项目地址: https://gitcode.com/GitHub_Trending/si/SillyTavern