Grok 接入酒馆教程:SillyTavern 配置 xAI API 与 400/403 报错全流程

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,但卡在“连不上 / 加载不出模型 / 一发消息就报错”的玩家。

前置准备

分步教程

三种接入方式怎么选?

接入方式适合谁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 直连,酒馆里该填什么?

  1. 打开酒馆,点击顶部或左侧的插头图标 / “API 连接”。
  2. API 类型选 Chat Completion(聊天补全)。
    • 注意:不要选 Text Completion,否则后面的自定义地址填了也用不上。
  3. API 来源 / 聊天补全来源选 Custom (OpenAI-compatible),也就是“自定义(兼容 OpenAI)”。酒馆列表里通常没有单独的“xAI / Grok”选项,社区的统一答案就是走这个兼容项。
  4. **自定义端点(基础 URL)**填:https://api.x.ai/v1。
  5. 自定义 API 密钥填你自己的 xAI Key(一般以 sk- 开头)。
  6. 点击 Connect(连接)。连接成功后,模型列表会被拉取出来,选一个可用模型(例如社区实测用过的 grok-3-mini-beta),点发送测试消息。
  7. 如果测试消息报 400,见方式一下方的“400 修复”小节;如果报 403 / forbidden,不要继续调参数,直接看方式二或方式三。
  8. 测试通过后即可正常开聊。

400 修复:排除不兼容参数

  1. 在 API 连接页往下找到“请求设置”里的 Exclude Parameters from payload(从负载中排除参数) 输入框。
  2. 填入:presence_penalty,frequency_penalty
    • 用英文逗号分隔,不要用中文逗号。
  3. 保存,重连 API,再发一次测试消息。

原理说明:酒馆在“兼容 OpenAI”模式下会把 presence_penalty、frequency_penalty 这类扩展参数一起塞进请求体(哪怕 UI 里没手动设置,也会以 0 传入),而 x.ai 的接口不接受这些参数,会直接返回 400,报文大意是“该模型不支持 presencePenalty”。把这两个参数从负载里剔除即可。

方式二:腾讯云/阿里云服务器被拒,怎么用 Hugging Face Space 做反代?

现象:本地酒馆用同一个 Key 能连上,部署在腾讯云或阿里云海外服务器的酒馆却一直 forbidden;换新加坡、美西等区域依旧报同样的错。这属于 IP 归属被拒,与区域无关,换机房解决不了,需要中转。

  1. 打开并登录 Hugging Face。

  2. 点右上角菜单,选择 New Space,填写 Space 名称,创建后记住你的 owner 名称和 space 名称(拼 URL 要用)。

  3. 进入新 Space 页面,点 Files → + Contribute → Upload files。

  4. 上传两个文件:

    • requirements.txt:声明依赖,包含 fastapi、uvicorn、requests、pydantic、python-multipart;
    • app.py:一个转发脚本,把 /v1/chat/completions 与 /v1/models 请求转发到 https://api.x.ai/v1,并透传 Authorization 头、支持流式返回。

    两个文件的完整代码请以上述社区原帖为准(帖中已给出可直接使用的版本),本文不复刻大段代码。

  5. 上传后点 Commit changes to main,等待 Space 构建完成,点页面中的 App 按钮查看,日志显示服务启动即成功(末尾出现 404 Not Found 不影响使用)。

  6. 拼出你的代理地址:https://<owner>-<space>.hf.space/v1/

    • 注意:用 Cherry Studio 之类工具测试时,v1 后面要带斜杠,否则模型加载不出来。
  7. 回到酒馆的 API 连接页:

    • API 类型:聊天补全;
    • 来源:自定义(兼容 OpenAI);
    • 基础 URL:https://<owner>-<space>.hf.space/v1(这里不要带斜杠);
    • API 密钥:你自己的 xAI Key。
  8. 点连接,模型列表应能正常加载;选一个模型(如 grok-3-mini-beta),发送测试消息验证。

  9. 通过后即可使用。若后续公网地址突然打不开,先尝试重启该 Space。

如果你有自己的服务器和 Nginx,也可以直接写一条反向代理规则把请求转发到 https://api.x.ai/v1,效果等价,且多个 AI 服务可以用不同路径分流,维护成本更低。

方式三:用第三方中转 API,国内怎么直连?

  1. 在提供 Grok 中转的服务商处注册账号,进入 API 管理 / API Token 页面生成密钥,复制 sk- 开头的那串。
  2. 打开酒馆 API 连接页:
    • API 类型:Chat Completion(聊天补全);
    • API 来源:Custom (OpenAI-compatible);
    • API URL:填服务商公布的中转地址,例如 https://llm-api.mmchat.xyz/v1;
    • API Key:粘贴上一步复制的密钥。
  3. 点 Connect,看到绿色的 Valid 即连接成功。
  4. 在 Model ID 里手动输入或选择服务商给出的 Grok 模型名(有教程示例用 grok-4-1-fast)。
  5. 发送测试消息验证。

注意点:走中转意味着你的请求内容和 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 看对应的教程索引,按自己的服务器情况选一条路线照做即可。

Sources

这篇有帮助吗?