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 名稱核驗與使用教程