设置和使用 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 模式指南.