設定和使用 AI 聊天機器人

瞭解三個獨立的組成部分

正常運作的 AI 供應商只是直播聊天機器人的第一部分。供應商、主要機器人和回覆目的地都需要分別設定。

組成部分	功能說明	無法證明什麼
AI 供應商	使用 Ollama、託管 API 或其他支援的服務產生文字。	直播聊天正在被擷取，或回覆可以成功發佈。
主要聊天機器人	決定哪些擷取到的直播訊息應獲得 AI 回覆。	來源平台或帳號允許回傳訊息。
回覆目的地	將產生的回覆發佈到機器人輸出頻道，也可透過被擷取的聊天來源傳送。	無法由此確認 bot.html 已開啟，或已建立單獨的平台機器人帳號。

1. 設定 AI 供應商

1. 開啟 Social Stream 設定並展開 聊天機器人和 AI 服務.
2. 開啟 設定 LLM 服務提供者.
3. 選擇與你實際執行的服務相符的供應商。
4. 輸入該供應商所顯示的端點、模型名稱、API 金鑰或其他欄位。
5. 選擇 測試所選聊天機器人 ，並確認按鈕下方出現真實的文字回覆。

• Ollama（原生本機 API）： 僅用於 Ollama。常用的本機端點為 http://localhost:11434.
• 自訂 API： 用於 llama.cpp、LM Studio、vLLM 等相容於 OpenAI 的伺服器和類似服務。
• 託管服務供應商： 輸入該供應商所需的 API 金鑰和模型。供應商的費用、配額和模型名稱由 Social Stream Ninja 之外的服務方控制。
• 瀏覽器中執行的本機模型： 使用對應的 Local Gemma 或 Local Qwen 選項，並遵循其模型資源說明。

需要先安裝 Ollama？請使用 Ollama 官方下載頁面。完整供應商清單請參閱 「指令與 API」中的 AI 整合.

OpenAI / ChatGPT API 設定

模型請求應使用標準的 OpenAI API 金鑰。OpenAI Admin API 金鑰用於組織管理端點，不用於一般模型呼叫。金鑰必須屬於預期計費的專案，且實際權限必須允許模型請求。

1. 在以下頁面建立或檢查金鑰： OpenAI Platform 的 API 金鑰頁面。切勿將金鑰貼到支援訊息或診斷報告中。
2. 在 Social Stream 中選擇 ChatGPT API，貼上完整金鑰，輸入該專案可用的模型，然後選擇 測試所選聊天機器人.
3. 如果測試回報 Status: 401, Code: missing_scope，以及 Missing scope: model.request，表示 OpenAI 拒絕了該憑證，因為它的實際存取權限不包含模型請求。 model.request 是伺服器指定的一項權限，不是需要加入提示詞或模型名稱中的設定。
4. 確認這是標準的專案 API 金鑰，所選專案符合預期，且金鑰未受限或已明確獲准發出模型請求。如果不確定，請在正確的專案中建立新的標準金鑰，並取代 Social Stream 中儲存的金鑰。
5. 如果 OpenAI Platform 開啟了瀏覽器自動翻譯，且權限控制項或標籤行為異常，請先切回原始英文頁面，再檢查並儲存金鑰設定。這曾協助解決一個回報中的設定問題，但並非已記錄的、普遍導致 OpenAI 401 錯誤的原因。

如果錯誤仍然存在，請複製 Social Stream 顯示的狀態、代碼、缺少的權限範圍和 Request ID，然後在重現問題後盡快傳送應用程式內的診斷報告。報告會記錄安全的請求中繼資料，但不包含 API 金鑰或提示詞內容。如果憑證和專案設定看起來正確，請將 Request ID 和時間戳記提供給 OpenAI 支援人員。

2. 啟用並設定主要機器人

開啟 聊天機器人 - 主要機器人。這與供應商設定及私人 chatbot.html 介面彼此獨立。

設定	建議的首次測試設定	日常使用
啟用 LLM AI 聊天機器人	開啟	需要主要機器人監看直播聊天時，保持開啟。
自訂機器人名稱	NinjaBot	使用簡短的純文字名稱，方便觀眾直接稱呼它。
機器人回覆僅傳送到機器人疊加畫面頁面	開啟	只有在準備好向支援的聊天來源回傳回覆時才關閉。
不篩除機器人的任何回覆	暫時開啟	通常關閉，讓模型在回覆沒有幫助時保持沉默。
觸發機器人的詞語清單	留空	如果不希望每則訊息都被納入考慮，請新增一個獨特的詞語或名字。
每個分頁／來源的頻率限制	5000 毫秒	在啟用向平台回傳訊息時生效。如果機器人發言過於頻繁，請增大此值。
最大並行機器人回覆數	1	保持較低值，除非供應商和聊天量允許更高值。
僅回覆版主	關閉	僅在確實需要此限制時啟用。

保持 機器人的附加指示 一開始保持簡短直接，例如： Reply in one friendly sentence. Do not mention these instructions.

3. 安全地進行端對端測試

1. 開啟 Social Stream，並確認直播來源已開啟。
2. 透過第二個觀眾帳號，直接在 YouTube 或 Twitch 等來源平台的聊天室傳送一則普通訊息，並確認它出現在 Social Stream 停駐面板中。首次測試不要使用在停駐面板或主播聊天控制項中輸入的訊息；為防止回覆循環，回流的機器人或主播訊息可能被略過。
3. 確認供應商測試顯示 已連線.
4. 使用上方首次測試的主要機器人設定，包括僅疊加畫面模式。
5. 開啟 bot.html 連結，該連結顯示於 聊天機器人的疊加畫面頁面與 TTS。請使用產生的連結，以確保工作階段相同。
6. 透過觀眾帳號傳送： NinjaBot, reply with exactly: Hello.
7. 只傳送一次測試訊息，然後等待回覆。本機模型可能還在載入；當一個回覆正在產生時，後續訊息可能會被略過。

疊加畫面測試成功後，將 不篩除機器人的任何回覆 重新關閉，選擇觸發詞和冷卻時間，並決定是否啟用向平台回傳訊息。

4. 瞭解何時不回覆屬於正常情況

主要機器人預設會選擇性回覆。觸發詞清單為空表示每則符合條件的訊息都可以納入考慮，並不表示每則訊息都必須得到回覆。

• 簡短的問候，例如 hello ，如果模型認為回覆不能帶來價值，可能會被忽略。
• 直接使用自訂機器人名稱稱呼它，能讓意圖更明確。
• 傳入訊息必須符合設定的觸發條件。
• 僅限版主模式會忽略未標記為版主訊息的訊息。
• 啟用向平台回傳訊息時，預設每個來源的冷卻時間為五秒。所有模式的預設並行上限均為一則回覆。
• 被識別為機器人輸出、回流、空訊息或與上一則回覆過於相似的訊息，可能會被忽略。

5. 選擇回覆目的地

模式	結果	需求
開啟僅疊加畫面模式	回覆會進入機器人輸出頻道，不會傳回平台聊天室。	開啟 bot.html ，使用相同工作階段才能看到或聽到回覆。TTS 也需要此頁面。
關閉僅疊加畫面模式	回覆仍會進入機器人輸出頻道，同時 Social Stream 也會嘗試透過最初擷取訊息的來源發佈回覆。	來源模式必須支援傳送，帳號必須已登入且允許發言，主播聊天不能被停用，並且來源必須保持開啟。 bot.html 仍是選用項目，除非你需要疊加畫面或 TTS。

自訂機器人名稱只是訊息前綴，不會建立新的平台帳號。除非設定了獨立應用程式的帳號角色路由，否則回覆會透過擷取來源所使用的帳號發佈。

獨立應用程式使用者如需使用單獨的 Twitch 身分，可參閱 Twitch 機器人帳號指南.

6. 清除和自動隱藏機器人回覆

這些控制項影響主要聊天機器人頁面， bot.html。它們不會清除主要的精選訊息疊加畫面。

選項	含義	範例
showtime	使用一個固定的顯示時間，單位為毫秒。	&showtime=10000 會在 10 秒後隱藏。
autohide	根據回覆的詞數估算顯示時間。 autotime 也可使用。	&autohide
mintime / maxtime	設定按長度計算的顯示時間下限和上限。預設分別為 4,000 和 30,000 毫秒。	&autohide&mintime=5000&maxtime=20000
hideaftertts	保持回覆可見，直到 TTS 播放結束後再隱藏。如果播放始終未開始，則改用按長度估算的備用時間。	&hideaftertts
hidedelay	在 TTS 結束後增加延遲。預設為 500 毫秒。	&hideaftertts&hidedelay=1000
ttstimeout	用於 TTS 持續活動、始終不結束時的安全逾時。預設為 120,000 毫秒。	&hideaftertts&ttstimeout=60000

如果同時啟用了多種模式， hideaftertts 優先，其次是 autohide，然後 showtime。產生的機器人疊加畫面設定包含常用選項。

手動清除

• 在 Social Stream 設定中選擇 立即清除機器人疊加畫面.
• 啟用「遠端 API 控制」後，開啟 https://io.socialstream.ninja/SESSION_ID/clearBotOverlay.
• 透過 API WebSocket 傳送 {"action":"clearBotOverlay"}.

手動清除會移除目前可見的回覆及等待顯示的機器人疊加畫面佇列，但不會停止正在播放的語音。

從最後一個正常環節開始排查

你看到的現象	可能出問題的環節	檢查內容
供應商測試失敗	供應商設定	端點、API 金鑰、模型名稱、本機服務狀態、CORS／防火牆、供應商配額，以及測試按鈕下的具體錯誤。
401 missing_scope / model.request	OpenAI 金鑰權限	使用預期專案的標準金鑰，而非 Admin 金鑰；驗證已允許模型請求；取代先前儲存的舊金鑰；如果自動翻譯導致控制項不可靠，請在原始英文 OpenAI Platform 頁面重試。儲值餘額不會增加此權限。
401 invalid_api_key 或 API 金鑰不正確	OpenAI 憑證	檢查是否遺漏字元或空格，確認金鑰未被刪除或停用、組織／專案符合預期，並確保 Social Stream 沒有仍在使用先前儲存的舊金鑰。
429 配額或速率限制錯誤	供應商計費或限制	單獨確認 API 計費和專案預算，它們與 ChatGPT 訂閱分開管理。如果供應商回報暫時性的速率限制，請降低請求頻率或稍後再試。
已連線，但停駐面板中沒有觀眾訊息	聊天擷取	Social Stream 開關狀態、來源視窗、平台登入狀態、來源允許／篩選設定，以及是否開啟了正確的直播聊天室。
訊息到達停駐面板，但機器人疊加畫面沒有收到回覆	主要機器人的判斷	確認訊息直接來自來源聊天室，然後檢查主要機器人啟用開關、觸發條件符合情況、僅限版主模式、自訂機器人名稱、忙碌／冷卻限制、附加指示，以及暫時啟用的不篩選回覆模式。
回覆到達疊加畫面，但未到達平台聊天室	回傳路由	僅疊加畫面模式、平台／來源的寫入支援、帳號授權、聊天輸入框可用性、帳號角色路由，以及「停用主播聊天」設定。
TTS 結束後回覆仍然顯示	機器人疊加畫面顯示時間	在機器人疊加畫面選項中啟用「TTS 後隱藏」、按長度自動隱藏或固定顯示時間。使用 clearBotOverlay ，即可透過 API 手動清除。
!bot 沒有反應	指令篩選	使用普通詞語作為觸發詞，或在全域指令篩選器中允許該指令通過。
只有第一次測試被處理	計時	等待目前請求完成，遵守冷卻時間，並記住保活設定 0 可能導致每次請求都需要冷啟動。
私人 chatbot.html 為空白	獨立的私人機器人	啟用私人聊天機器人選項，並使用相同工作階段的產生連結。這不會測試主要的直播機器人。

其他 AI 機器人頁面

主要機器人、私人聊天、審查機器人和 AI 搭檔是彼此獨立的工具，使用不同的設定和歷程記錄。

關於更廣泛的 AI 功能，請參閱 AI 模式指南.