Configurar e usar o bot de chat com IA

Entenda as três partes separadas

Um provedor de IA funcionando é apenas a primeira parte de um bot de chat ao vivo. O provedor, o bot principal e o destino das respostas precisam ser configurados separadamente.

Parte	O que faz	O que isso não comprova
Provedor de IA	Gera texto com Ollama, uma API hospedada ou outro serviço compatível.	Que o chat ao vivo está sendo capturado ou que respostas podem ser publicadas.
Bot principal de chat	Decide quais mensagens ao vivo capturadas devem receber uma resposta da IA.	Que a plataforma ou conta da fonte permite enviar respostas.
Destino da resposta	Publica respostas geradas no canal de saída do bot e também pode enviá-las pela fonte de chat capturada.	Esse resultado bot.html está aberta ou que uma conta separada de bot da plataforma foi criada.

1. Configure um provedor de IA

1. Abra as configurações do Social Stream e expanda Bots de chat e serviços de IA.
2. Abrir Configurar provedor de serviço LLM.
3. Escolha o provedor que corresponde ao serviço que você realmente está executando.
4. Insira endpoint, nome do modelo, chave de API ou outros campos mostrados para esse provedor.
5. Selecione Testar bot de chat selecionado e confirme que uma resposta real de texto aparece abaixo do botão.

• Ollama (API local nativa): use apenas para Ollama. O endpoint local comum é http://localhost:11434.
• API personalizada: use para servidores compatíveis com OpenAI, como llama.cpp, LM Studio, vLLM e serviços semelhantes.
• Provedor hospedado: insira a chave de API e o modelo exigidos pelo provedor. Custos, cotas e nomes de modelos são controlados fora do Social Stream Ninja.
• Modelo local executado no navegador: use a opção correspondente Local Gemma ou Local Qwen e siga as instruções de arquivos do modelo.

Precisa instalar o Ollama primeiro? Use a página oficial de download do Ollama. Para a lista completa de provedores, veja Integração de IA em Comandos e API.

Configuração da API OpenAI / ChatGPT

Use uma chave padrão da API OpenAI para requisições a modelos. Uma chave Admin API da OpenAI é destinada a endpoints administrativos da organização, não a chamadas normais de modelos. A chave deve pertencer ao projeto que você quer faturar e suas permissões efetivas precisam permitir requisições a modelos.

1. Crie ou revise a chave na página de chaves de API da OpenAI Platform. Nunca cole a chave em uma mensagem de suporte ou relatório de diagnóstico.
2. No Social Stream, selecione ChatGPT API, cole a chave completa, insira um modelo disponível para esse projeto e selecione Testar bot de chat selecionado.
3. Se o teste informar Status: 401, Code: missing_scope, e Missing scope: model.request, a OpenAI rejeitou a credencial porque o acesso efetivo dela não inclui requisições a modelos. model.request é uma permissão indicada pelo servidor, não uma configuração para adicionar ao prompt ou ao nome do modelo.
4. Confirme que esta é uma chave de API padrão de projeto, que o projeto esperado está selecionado e que a chave não tem restrições ou está explicitamente autorizada a fazer requisições a modelos. Em caso de dúvida, crie uma nova chave padrão no projeto correto e substitua a chave salva no Social Stream.
5. Se a tradução automática do navegador estiver ativa na OpenAI Platform e os controles ou rótulos de permissões se comportarem de forma inesperada, mude para a página original em inglês antes de revisar e salvar as configurações da chave. Isso ajudou em uma configuração relatada, mas não é uma causa universal documentada de erros 401 da OpenAI.

Se o erro continuar, copie o status, o código, o escopo ausente e o Request ID mostrados pelo Social Stream e envie o relatório de diagnóstico pelo aplicativo logo depois de reproduzir. O relatório registra metadados seguros da requisição, mas exclui chaves de API e conteúdo dos prompts. Forneça o Request ID e o horário ao suporte da OpenAI se as configurações de credencial e projeto parecerem corretas.

2. Ative e configure o bot principal

Abrir Bot de chat - Principal. Isso é separado tanto da configuração do provedor quanto da interface privada chatbot.html interface.

Configuração	Bom primeiro teste	Uso normal
Ativar o bot de chat com IA LLM	Ligado	Mantenha ligado enquanto o bot principal deva monitorar o chat ao vivo.
Personalizar nome do bot	NinjaBot	Use um nome curto em texto simples que os espectadores possam chamar diretamente.
As respostas do bot vão SOMENTE para a página de sobreposição do bot	Ligado	Desative somente quando estiver pronto para publicar respostas de volta em uma fonte de chat compatível.
Não filtrar nenhuma resposta do bot	Ligado temporariamente	Normalmente desligado para que o modelo possa ficar em silêncio quando uma resposta não for útil.
Lista de palavras para acionar o bot	Deixe vazio	Adicione uma palavra ou nome característico se não quiser que todas as mensagens sejam consideradas.
Limite de frequência por aba / fonte	5000 ms	Aplica-se quando o envio de respostas à plataforma está ativado. Aumente se o bot publicar com muita frequência.
Máximo de respostas paralelas do bot	1	Mantenha baixo, a menos que o provedor e o volume do chat comportem mais.
Responder somente a moderadores	Desligado	Ative somente quando essa restrição for intencional.

Mantenha Instruções adicionais do bot curtas e diretas no início, como: Reply in one friendly sentence. Do not mention these instructions.

3. Faça um teste completo com segurança

1. Ligue o Social Stream e confirme que a fonte ao vivo está aberta.
2. Envie uma mensagem normal de uma segunda conta de espectador diretamente no chat da plataforma de origem, como YouTube ou Twitch, e confirme que ela aparece no dock do Social Stream. Não use uma mensagem digitada no dock ou nos controles de chat do anfitrião neste primeiro teste; ecos de mensagens do bot ou anfitrião podem ser ignorados para evitar ciclos de respostas.
3. Confirme que o teste do provedor mostra Conectado.
4. Use as configurações de primeiro teste do bot principal acima, incluindo o modo somente sobreposição.
5. Abra: bot.html mostrado em Página de sobreposição e síntese de voz do bot de chat. Use o link gerado para que tenha a mesma sessão.
6. Pela conta de espectador, envie: NinjaBot, reply with exactly: Hello.
7. Envie o teste uma vez e espere a resposta. Um modelo local ainda pode estar carregando, e mensagens posteriores podem ser ignoradas enquanto uma resposta já está em andamento.

Depois que o teste da sobreposição funcionar, desative Não filtrar nenhuma resposta do bot novamente, escolha um gatilho e um tempo de espera e decida se o envio de respostas à plataforma deve ser ativado.

4. Saiba quando o silêncio é normal

O bot principal é seletivo por padrão. Uma lista de gatilhos vazia significa que toda mensagem elegível pode ser considerada; não significa que toda mensagem deva receber uma resposta.

• Uma saudação curta, como hello pode ser ignorada se o modelo não achar que uma resposta agrega valor.
• Chamar o bot diretamente pelo nome personalizado deixa a intenção mais clara.
• Um gatilho configurado precisa corresponder à mensagem recebida.
• O modo somente moderadores ignora mensagens que não estejam marcadas como mensagens de moderador.
• Quando o envio à plataforma está ativado, o tempo de espera padrão é de cinco segundos por fonte. O limite paralelo padrão é uma resposta em todos os modos.
• Mensagens identificadas como saída de bot, ecos, mensagens vazias ou muito semelhantes à resposta anterior podem ser ignoradas.

5. Escolha para onde vão as respostas

Modo	Resultado	Requisitos
Somente sobreposição ativado	As respostas vão para o canal de saída do bot e não são enviadas de volta ao chat da plataforma.	Abrir bot.html com a mesma sessão para vê-las ou ouvi-las. A síntese de voz também exige essa página.
Somente sobreposição desativado	As respostas continuam indo para o canal de saída do bot, e o Social Stream também tenta publicá-las pela fonte capturada de origem.	O modo da fonte precisa permitir envio, a conta deve estar conectada e autorizada a publicar, o chat do anfitrião não pode estar desativado e a fonte precisa permanecer aberta. bot.html continua opcional, a menos que você queira a sobreposição ou síntese de voz.

O nome personalizado do bot é um prefixo de mensagem; não cria uma nova conta na plataforma. A menos que o encaminhamento por função de conta do aplicativo independente esteja configurado, as respostas são publicadas pela conta usada pela fonte capturada.

Usuários do aplicativo independente que desejam uma identidade separada no Twitch podem seguir o guia de conta de bot do Twitch.

6. Limpe e oculte automaticamente as respostas do bot

Estes controles afetam a página do Bot principal de chat, bot.html. Elas não limpam a sobreposição principal de mensagens em destaque.

Opção	Significado	Exemplo
showtime	Usa um tempo fixo de exibição em milissegundos.	&showtime=10000 oculta após 10 segundos.
autohide	Estima o tempo de exibição pela quantidade de palavras da resposta. autotime também é aceito.	&autohide
mintime / maxtime	Define os tempos mínimo e máximo de exibição baseados no tamanho. Os padrões são 4.000 e 30.000 milissegundos.	&autohide&mintime=5000&maxtime=20000
hideaftertts	Mantém a resposta visível até a síntese de voz terminar, depois a oculta. Se a reprodução nunca começar, usa uma alternativa baseada no tamanho.	&hideaftertts
hidedelay	Adiciona um atraso depois que a síntese de voz termina. O padrão é 500 milissegundos.	&hideaftertts&hidedelay=1000
ttstimeout	Tempo limite de segurança se a síntese de voz permanecer ativa indefinidamente. O padrão é 120.000 milissegundos.	&hideaftertts&ttstimeout=60000

Se vários modos estiverem ativados, hideaftertts tem prioridade, seguido de autohide, depois showtime. As configurações do link gerado da sobreposição do bot oferecem as opções comuns.

Limpar manualmente

• Nas configurações do Social Stream, selecione Limpar sobreposição do bot agora.
• Com Controle remoto por API ativado, abra https://io.socialstream.ninja/SESSION_ID/clearBotOverlay.
• Pelo WebSocket da API, envie {"action":"clearBotOverlay"}.

Limpar manualmente remove a resposta visível e a fila de exibição pendente da sobreposição do bot, mas não interrompe a fala já em reprodução.

Investigue a partir da última etapa que funcionou

O que você vê	Área provável	O que verificar
O teste do provedor falha	Configuração do provedor	Endpoint, chave de API, nome do modelo, status do serviço local, CORS/firewall, cota do provedor e o erro exato abaixo do botão de teste.
401 missing_scope / model.request	Permissões da chave OpenAI	Use uma chave padrão do projeto pretendido, não uma chave Admin; verifique se requisições a modelos são permitidas; substitua qualquer chave salva antiga; e tente novamente pela página original em inglês da OpenAI Platform se a tradução automática tiver tornado os controles pouco confiáveis. Créditos não adicionam essa permissão.
401 invalid_api_key ou chave de API incorreta	Credencial da OpenAI	Procure um caractere ausente ou espaço, confirme que a chave não foi excluída nem desativada, confira a organização/projeto pretendido e garanta que o Social Stream não continue usando uma chave salva antiga.
429 erro de cota ou limite de requisições	Faturamento ou limites do provedor	Confirme o faturamento da API e o orçamento do projeto separadamente das assinaturas do ChatGPT; depois reduza a frequência de requisições ou aguarde se o provedor informar um limite temporário.
Conectado, mas a mensagem do espectador não aparece no dock	Captura de chat	Estado ligado/desligado do Social Stream, janela da fonte, login na plataforma, configurações de permissão/filtro da fonte e se o chat ao vivo correto está aberto.
A mensagem chega ao dock, mas nenhuma resposta chega à sobreposição do bot	Decisão do bot principal	Confirme que a mensagem veio diretamente do chat da fonte e confira a ativação do bot principal, a correspondência do gatilho, o modo somente moderadores, o nome personalizado do bot, os limites de ocupado/tempo de espera, as instruções adicionais e o modo temporário de respostas sem filtragem.
A resposta chega à sobreposição, mas não ao chat da plataforma	Encaminhamento de respostas	Modo somente sobreposição, suporte de escrita da plataforma/fonte, autorização da conta, disponibilidade de entrada de chat, encaminhamento por função de conta e a configuração Desativar chat do anfitrião.
A resposta continua visível após a síntese de voz	Temporização da sobreposição do bot	Ative Ocultar após síntese de voz, ocultação automática baseada no tamanho ou um tempo fixo de exibição nas opções da sobreposição do bot. Use clearBotOverlay para limpeza manual pela API.
!bot não faz nada	Filtragem de comandos	Use um gatilho de palavra simples ou permita esse comando no filtro global de comandos.
Somente o primeiro teste é processado	Temporização	Espere a requisição ativa, respeite o tempo de espera e lembre-se de que keep-alive 0 pode adicionar uma inicialização a frio a cada requisição.
Privado chatbot.html está vazio	Bot privado separado	Ative a opção de bot de chat privado e use o link gerado com a mesma sessão. Isso não testa o bot principal ao vivo.

Outras páginas de bots de IA

O bot principal, o chat privado, o bot de censura e o coapresentador de IA são ferramentas separadas com configurações e históricos diferentes.

Para o conjunto mais amplo de recursos de IA, veja o Guia de modos de IA.