Grok 接入酒馆教程:SillyTavern 配置 xAI API 与 400/403 报错全流程
Grok 接入酒馆教程:SillyTavern 配置 xAI API 与 400/403 报错全流程
Contents
接入 Grok 的核心三步:API 类型选“聊天补全”,来源选“自定义(兼容 OpenAI)”,基础 URL 填 https://api.x.ai/v1,并填入你自己的 xAI API Key。若报 400,就在负载中排除 presence_penalty 与 frequency_penalty;若报 403/forbidden,多半是服务器 IP 被 xAI 拒绝,需要走反向代理或第三方中转。
简介
这篇教程讲的是把 Grok(x.ai)的 API 接进 SillyTavern(俗称“酒馆”)并稳定跑起来:从填什么地址、选什么 API 类型,到官方直连、自建反代、第三方中转三种路线怎么选,以及 400、403、404 这些高频报错怎么修。适合已经装好酒馆、手里有 Grok API Key,但卡在“连不上 / 加载不出模型 / 一发消息就报错”的玩家。
前置准备
- SillyTavern(酒馆):能正常打开界面,并且能进入左侧“API 连接”页面。
- 一个 Grok / xAI 的 API Key:在 xAI 官方控制台申请。社区经验里,有人是通过充值 5 美元完成验证后拿到了每月额度(额度、价格与验证方式以 xAI 官方当时的规则为准,不要照抄别人的数字)。
- API 基础地址:官方直连用
https://api.x.ai/v1;用中转服务时,以服务商公布的地址为准。 - 一台跑酒馆的机器:本地电脑可以,云服务器也可以,但需要确认公网 IP 归属——腾讯云、阿里云的公网 IP 会被 xAI 拒绝(多个社区帖都指向这一点)。
- 可选工具:
- Hugging Face 账号(用 Space 做一个 API 反向代理);
- 一台能配 Nginx 的机器(自己写反向代理,思路和前者一样,只是更可控);
- 或者一个第三方中转 API 服务(无需海外网络,直接用)。
- 排错意识:“兼容 OpenAI”只是客户端协议适配,不等于服务端完全兼容,参数差异是很多 400 错误的根源。
分步教程
三种接入方式怎么选?
| 接入方式 | 适合谁 | API 基础 URL 示例 | 优点 | 注意点 |
|---|---|---|---|---|
| 官方 API 直连 | 本地电脑,或 IP 未被拒的服务器 | https://api.x.ai/v1 | 链路最短、配置最少 | 腾讯云、阿里云公网 IP 会被拒,表现为 forbidden / 403 |
| 自建反向代理(Hugging Face Space 或 Nginx) | 酒馆就跑在腾讯云、阿里云等被拒 IP 上 | https://<owner>-<space>.hf.space/v1 | 仍然用自己的 Key,请求链路自己掌握 | Space 需要维护;测试时末尾要带斜杠,填进酒馆时不要带 |
| 第三方中转 API | 没有海外网络、不想自建 | 以服务商公布为准,例如 https://llm-api.mmchat.xyz/v1 | 国内可直连、上手快 | 请求会经过第三方,模型名与计费以平台为准 |
方式一:官方 API 直连,酒馆里该填什么?
- 打开酒馆,点击顶部或左侧的插头图标 / “API 连接”。
- API 类型选 Chat Completion(聊天补全)。
- 注意:不要选 Text Completion,否则后面的自定义地址填了也用不上。
- API 来源 / 聊天补全来源选 Custom (OpenAI-compatible),也就是“自定义(兼容 OpenAI)”。酒馆列表里通常没有单独的“xAI / Grok”选项,社区的统一答案就是走这个兼容项。
- **自定义端点(基础 URL)**填:
https://api.x.ai/v1。 - 自定义 API 密钥填你自己的 xAI Key(一般以
sk-开头)。 - 点击 Connect(连接)。连接成功后,模型列表会被拉取出来,选一个可用模型(例如社区实测用过的
grok-3-mini-beta),点发送测试消息。 - 如果测试消息报 400,见方式一下方的“400 修复”小节;如果报 403 / forbidden,不要继续调参数,直接看方式二或方式三。
- 测试通过后即可正常开聊。
400 修复:排除不兼容参数
- 在 API 连接页往下找到“请求设置”里的 Exclude Parameters from payload(从负载中排除参数) 输入框。
- 填入:
presence_penalty,frequency_penalty- 用英文逗号分隔,不要用中文逗号。
- 保存,重连 API,再发一次测试消息。
原理说明:酒馆在“兼容 OpenAI”模式下会把 presence_penalty、frequency_penalty 这类扩展参数一起塞进请求体(哪怕 UI 里没手动设置,也会以 0 传入),而 x.ai 的接口不接受这些参数,会直接返回 400,报文大意是“该模型不支持 presencePenalty”。把这两个参数从负载里剔除即可。
方式二:腾讯云/阿里云服务器被拒,怎么用 Hugging Face Space 做反代?
现象:本地酒馆用同一个 Key 能连上,部署在腾讯云或阿里云海外服务器的酒馆却一直 forbidden;换新加坡、美西等区域依旧报同样的错。这属于 IP 归属被拒,与区域无关,换机房解决不了,需要中转。
-
打开并登录 Hugging Face。
-
点右上角菜单,选择 New Space,填写 Space 名称,创建后记住你的 owner 名称和 space 名称(拼 URL 要用)。
-
进入新 Space 页面,点 Files → + Contribute → Upload files。
-
上传两个文件:
requirements.txt:声明依赖,包含fastapi、uvicorn、requests、pydantic、python-multipart;app.py:一个转发脚本,把/v1/chat/completions与/v1/models请求转发到https://api.x.ai/v1,并透传 Authorization 头、支持流式返回。
两个文件的完整代码请以上述社区原帖为准(帖中已给出可直接使用的版本),本文不复刻大段代码。
-
上传后点 Commit changes to main,等待 Space 构建完成,点页面中的 App 按钮查看,日志显示服务启动即成功(末尾出现 404 Not Found 不影响使用)。
-
拼出你的代理地址:
https://<owner>-<space>.hf.space/v1/- 注意:用 Cherry Studio 之类工具测试时,
v1后面要带斜杠,否则模型加载不出来。
- 注意:用 Cherry Studio 之类工具测试时,
-
回到酒馆的 API 连接页:
- API 类型:聊天补全;
- 来源:自定义(兼容 OpenAI);
- 基础 URL:
https://<owner>-<space>.hf.space/v1(这里不要带斜杠); - API 密钥:你自己的 xAI Key。
-
点连接,模型列表应能正常加载;选一个模型(如
grok-3-mini-beta),发送测试消息验证。 -
通过后即可使用。若后续公网地址突然打不开,先尝试重启该 Space。
如果你有自己的服务器和 Nginx,也可以直接写一条反向代理规则把请求转发到 https://api.x.ai/v1,效果等价,且多个 AI 服务可以用不同路径分流,维护成本更低。
方式三:用第三方中转 API,国内怎么直连?
- 在提供 Grok 中转的服务商处注册账号,进入 API 管理 / API Token 页面生成密钥,复制
sk-开头的那串。 - 打开酒馆 API 连接页:
- API 类型:Chat Completion(聊天补全);
- API 来源:Custom (OpenAI-compatible);
- API URL:填服务商公布的中转地址,例如
https://llm-api.mmchat.xyz/v1; - API Key:粘贴上一步复制的密钥。
- 点 Connect,看到绿色的 Valid 即连接成功。
- 在 Model ID 里手动输入或选择服务商给出的 Grok 模型名(有教程示例用
grok-4-1-fast)。 - 发送测试消息验证。
注意点:走中转意味着你的请求内容和 Key 会经过第三方,价格、可用模型、限流都以该平台公布为准;中转地址和模型名随时可能变化,别把它当永久配置。
配置完怎么确认速度和效果?
用同一段提示词做前后对比最直观:社区实测里,同等输出量在 Gemini 上大约要等 60 秒左右,且流式偶尔出问题;换成 Grok 反代方案后,通常 10 秒内就开始持续出字。如果你测下来仍然很慢,先排查是不是中转层或代理层在排队,而不是模型本身的问题。
常见问题排查
| 现象 | 常见原因 | 处理办法 |
|---|---|---|
点连接后模型列表为空 / 测试消息报 400,报文提到 does not support parameter presencePenalty | 酒馆默认带上了 presence_penalty、frequency_penalty | 在“从负载中排除参数”里填 presence_penalty,frequency_penalty,保存后重连 |
| 报 403 / forbidden,但同一个 Key 在本地酒馆能用 | 服务器公网 IP 属于腾讯云/阿里云,被 xAI 拒绝 | 换用方式二(Space 反代 / Nginx 反代)或方式三(第三方中转) |
| 报 404 / 页面找不到 | URL 拼写错误;Space 的 v1 斜杠位置不对;实例未启动完成 | 逐一核对:测试工具里 /v1/ 带斜杠,酒馆里 /v1 不带斜杠;确认 Space 日志正常 |
| 换了新加坡、美西等区域仍然报同样错误 | 不是区域问题,是 IP 归属问题 | 不要反复换区,直接上反代或中转 |
| 云服务器内存占用高、越跑越高 | 酒馆日志里堆积了大量历史对话 | 重启实例;必要时扩容内存后再观察 |
| 公网地址突然进不去 | 实例异常或服务未拉起 | 重启实例,仍不行就重建 |
| 连接成功但回复很慢 | 中转层排队、模型选错、或走了慢速通道 | 换模型测试,观察是否为特定中转节点问题 |
排查顺序建议:先验密钥(用官方或第三方调试工具确认 Key 有效)→ 再验网络层(403 基本都是 IP 问题)→ 最后验请求参数(400 基本都是参数兼容问题)。按这个顺序走,能少绕很多弯路。
关于模型名称的冲突说明
不同时间点的来源给出的模型名并不一致:较早的帖子中出现的是 grok-3-beta、grok-3-mini-beta、grok-3-fast-beta、grok-3-mini-fast-beta;另一篇报错案例的报文里出现了 grok-4;还有中转教程推荐的是 grok-4-1-fast。这些差异来自发布时间和接入渠道不同,并非某一方写错。实际以你连接成功后 /v1/models 返回的列表、以及服务商后台标注的可用模型为准。
FAQ
Q:酒馆的 API 列表里根本没有 xAI 或 Grok 选项,怎么办?
A:不需要专门选项。API 类型选“聊天补全”,来源选“自定义(兼容 OpenAI)”,手动填 https://api.x.ai/v1 和你的 Key 即可,这是社区的统一做法。
Q:为什么本地酒馆能连 Grok,放到云服务器就不行? A:问题出在公网 IP 的归属上,并非配置写错。x.ai 会拒绝腾讯云、阿里云的公网 IP,同一个 Key 在本地能通、在云上就报 forbidden,正是这个原因。解决方式是加一层反向代理或改用中转。
Q:一定要用 VPS 才能玩酒馆吗? A:不一定。本地电脑同样可以部署酒馆,云服务器的主要价值是常驻在线、方便从多设备访问。只有当你的本地网络无法直连模型服务,或需要 24 小时挂机时,才需要考虑上云。
Q:报 400 时改来改去都没用,最可能漏了什么? A:最常见的是排除参数时用了中文逗号,或者改完没有重新连接 API。请确认输入的是英文逗号,然后保存、重连、再发测试消息。
Q:Grok 的回复速度真的比 Gemini 快吗? A:按社区实测体感,同样输出量下 Gemini 大约要等 60 秒,Grok 通常 10 秒内开始流式输出。这个对比受网络、中转层和模型版本影响,仅作参考。
Q:Grok 在角色扮演里配合度如何? A:社区普遍反馈它对抗审查的难度较低、语言风格更口语化。但请务必遵守 x.ai 的使用条款与当地法律法规,保持 SFW 内容,不要用它生成违规内容。
Q:用 Hugging Face Space 做反代安全吗? A:请求会经过你自建的 Space,Key 由你自己填写、不落到第三方手上,比公共中转更可控;但 Space 是公开托管服务,别在代码里硬编码密钥,也不要上传敏感数据。
Q:中转服务和官方直连该怎么选? A:能直连就直连,链路短、问题少;IP 被拒且不想维护反代时再用中转。中转胜在开箱即用,代价是请求经过第三方、模型与计费受平台约束。
Q:角色卡格式需要注意什么? A:酒馆常用的角色卡是 V2/V3 规范,内嵌在 PNG 图片里或单独的 JSON 文件中,导入时直接拖入或从菜单选择导入即可。
CTA
如果你想把 Grok 接入酒馆的配置项、报错对照和版本变化集中放在一处随时查阅,可以到 tuniang.ai 看对应的教程索引,按自己的服务器情况选一条路线照做即可。
Related guides
- agnai 本地部署与使用教程
- Illustrious 模型是什么、怎么用:从版本差异到出图的完整教程
- Janitor AI 中文版怎么用:tuniang reviews 整合教程
- KoboldAI 使用教程
- nalang 模型是什么:SillyTavern/酒馆AI 名称核验与使用教程