Configura e usa il bot di chat IA

Comprendi le tre parti separate

Un provider IA funzionante è solo la prima parte di un bot per la chat in diretta. Provider, bot principale e destinazione delle risposte devono essere configurati separatamente.

Parte	Cosa fa	Cosa non dimostra
Provider IA	Genera testo con Ollama, un'API ospitata o un altro servizio supportato.	Che la chat in diretta venga acquisita o che sia possibile pubblicare risposte.
Bot di chat principale	Decide quali messaggi acquisiti della diretta devono ricevere una risposta IA.	Che la piattaforma sorgente o l'account consenta l'invio di risposte.
Destinazione delle risposte	Pubblica le risposte generate nel canale di output del bot e può anche inviarle tramite la sorgente di chat acquisita.	Quel bot.html sia aperta o che sia stato creato un account bot separato sulla piattaforma.

1. Configura un provider IA

1. Apri le impostazioni di Social Stream ed espandi Bot di chat e servizi IA (Chat Bots and AI services).
2. Apri Configura provider del servizio LLM (Configure LLM Service Provider).
3. Scegli il provider che corrisponde al servizio realmente in esecuzione.
4. Inserisci endpoint, nome del modello, chiave API o gli altri campi mostrati per quel provider.
5. Seleziona Prova il bot di chat selezionato e verifica che sotto il pulsante compaia una vera risposta testuale.

• Ollama (API locale nativa): usala solo per Ollama. L'endpoint locale abituale è http://localhost:11434.
• API personalizzata (Custom API): usala per server compatibili con OpenAI come llama.cpp, LM Studio, vLLM e servizi simili.
• Provider ospitato: inserisci chiave API e modello richiesti da quel provider. Costi, quote e nomi dei modelli del provider sono gestiti al di fuori di Social Stream Ninja.
• Modello locale eseguito nel browser: usa l'opzione corrispondente Local Gemma o Local Qwen e segui le istruzioni sui file del modello.

Devi prima installare Ollama? Usa la pagina ufficiale di download di Ollama. Per l'elenco completo dei provider, consulta Integrazione IA in Comandi e API.

Configurazione API OpenAI / ChatGPT

Usa una chiave API OpenAI standard per le richieste ai modelli. Una chiave OpenAI Admin API è destinata agli endpoint di amministrazione dell'organizzazione, non alle normali chiamate ai modelli. La chiave deve appartenere al progetto a cui vuoi addebitare i costi e i suoi permessi effettivi devono consentire richieste ai modelli.

1. Crea o controlla la chiave nella Pagina delle chiavi API di OpenAI Platform. Non incollare mai la chiave in un messaggio di supporto o in un rapporto diagnostico.
2. In Social Stream, seleziona API ChatGPT, incolla la chiave completa, inserisci un modello disponibile per quel progetto e seleziona Prova il bot di chat selezionato.
3. Se la prova segnala Status: 401, Code: missing_scope, e Missing scope: model.request, OpenAI ha rifiutato la credenziale perché i suoi permessi effettivi non includono le richieste ai modelli. model.request è il nome di un permesso indicato dal server, non un'impostazione da aggiungere al prompt o al nome del modello.
4. Verifica che sia una normale chiave API di progetto, che sia selezionato il progetto previsto e che la chiave non abbia restrizioni o sia esplicitamente autorizzata a fare richieste ai modelli. In caso di dubbi, crea una nuova chiave standard nel progetto corretto e sostituisci quella salvata in Social Stream.
5. Se la traduzione automatica del browser è attiva su OpenAI Platform e i controlli o le etichette dei permessi si comportano in modo inatteso, passa alla pagina originale in inglese prima di controllare e salvare le impostazioni della chiave. Questo ha risolto un caso segnalato, ma non è una causa universale documentata degli errori OpenAI 401.

Se l'errore continua, copia stato, codice, permesso mancante e Request ID mostrati da Social Stream, poi invia il rapporto diagnostico dall'app subito dopo aver riprodotto il problema. Il rapporto registra metadati sicuri della richiesta, ma esclude chiavi API e contenuto dei prompt. Fornisci Request ID e data/ora al supporto OpenAI se credenziale e impostazioni del progetto sembrano corrette.

2. Attiva e configura il bot principale

Apri Bot di chat — Principale (Chat Bot - Primary). È separato sia dalla configurazione del provider sia dall'interfaccia privata chatbot.html interfaccia.

Impostazione	Una buona prima prova	Uso normale
Attiva il bot di chat LLM IA (Enable the LLM AI chat bot)	Su	Lascia attivo finché il bot principale deve monitorare la chat in diretta.
Personalizza il nome del bot (Customize bot name)	NinjaBot	Usa un nome breve e in testo semplice a cui gli spettatori possano rivolgersi direttamente.
Le risposte del bot vanno SOLO alla pagina overlay del bot	Su	Disattiva solo quando sei pronto a pubblicare risposte su una sorgente di chat supportata.
Non filtrare nessuna risposta del bot (Do not screen out any of the bot's replies)	Attivo temporaneamente	Normalmente disattivato, in modo che il modello possa restare in silenzio quando una risposta non è utile.
Elenco delle parole che attivano il bot (List of words to trigger bot)	Lascia vuoto	Aggiungi una parola o un nome distintivo se non vuoi che venga valutato ogni messaggio.
Limite di frequenza per scheda / sorgente	5000 ms	Si applica quando è attivo l'invio delle risposte alla piattaforma. Aumentalo se il bot pubblica troppo spesso.
Numero massimo di risposte parallele del bot (Max parallel bot replies)	1	Mantienilo basso, a meno che provider e volume della chat possano gestire un valore maggiore.
Risponderà solo ai moderatori (Will respond to Moderators only)	Disattivato	Attiva solo se desideri questa restrizione.

Mantieni Istruzioni aggiuntive del bot (Additional Bot Instructions) inizialmente brevi e dirette, per esempio: Reply in one friendly sentence. Do not mention these instructions.

3. Esegui una prova completa in sicurezza

1. Attiva Social Stream e verifica che la sorgente in diretta sia aperta.
2. Invia un messaggio normale da un secondo account spettatore direttamente nella chat della piattaforma sorgente, per esempio YouTube o Twitch, e verifica che compaia nel dock Social Stream. Per questa prima prova, non usare un messaggio scritto nel dock o nei controlli della chat del conduttore; i messaggi di ritorno di bot o conduttore possono essere ignorati per evitare cicli di risposte.
3. Verifica che la prova del provider mostri Connesso.
4. Usa le impostazioni del bot principale indicate sopra per la prima prova, inclusa la modalità solo overlay.
5. Apri bot.html mostrato sotto Pagina overlay e TTS del bot di chat (Overlay Page and TTS for Chat Bot). Usa il link generato affinché contenga la stessa sessione.
6. Dall'account spettatore, invia: NinjaBot, reply with exactly: Hello.
7. Invia il messaggio di prova una sola volta e attendi la risposta. Un modello locale potrebbe essere ancora in caricamento e i messaggi successivi potrebbero essere ignorati mentre una risposta è già in elaborazione.

Quando la prova dell'overlay funziona, imposta Non filtrare nessuna risposta del bot (Do not screen out any of the bot's replies) di nuovo disattivato, scegli un criterio di attivazione e una pausa, poi decidi se abilitare l'invio delle risposte alla piattaforma.

4. Riconosci quando il silenzio è normale

Il bot principale è selettivo per impostazione predefinita. Un elenco di parole di attivazione vuoto significa che ogni messaggio idoneo può essere valutato, non che ogni messaggio debba ricevere una risposta.

• Un breve saluto come hello può essere ignorato se il modello ritiene che una risposta non aggiunga valore.
• Rivolgersi direttamente al nome personalizzato del bot rende più chiara l'intenzione.
• Un criterio di attivazione configurato deve corrispondere al messaggio in arrivo.
• La modalità solo moderatori ignora i messaggi non contrassegnati come messaggi di moderatori.
• Quando è attivo l'invio delle risposte alla piattaforma, la pausa predefinita è di cinque secondi per sorgente. Il limite predefinito di parallelismo è una risposta in qualsiasi modalità.
• I messaggi identificati come output del bot, messaggi di ritorno, messaggi vuoti o troppo simili alla risposta precedente possono essere ignorati.

5. Scegli dove inviare le risposte

Modalità	Risultato	Requisiti
Solo overlay attivato	Le risposte vanno al canale di output del bot e non vengono inviate alla chat della piattaforma.	Apri bot.html con la stessa sessione per vedere o sentire le risposte. Anche il TTS richiede questa pagina.
Solo overlay disattivato	Le risposte continuano ad andare al canale di output del bot, e Social Stream tenta anche di pubblicarle tramite la sorgente acquisita di origine.	La modalità sorgente deve supportare l'invio, l'account deve aver effettuato l'accesso ed essere autorizzato a pubblicare, la chat del conduttore non deve essere disattivata e la sorgente deve restare aperta. bot.html resta facoltativo, a meno che tu non voglia l'overlay o il TTS.

Il nome personalizzato del bot è un prefisso del messaggio; non crea un nuovo account sulla piattaforma. A meno che sia configurato l'instradamento per ruolo account nell'app autonoma, le risposte vengono pubblicate tramite l'account usato dalla sorgente acquisita.

Gli utenti dell'app autonoma che desiderano un'identità Twitch separata possono seguire la Guida all'account bot Twitch.

6. Cancella e nascondi automaticamente le risposte del bot

Questi controlli riguardano la pagina del bot di chat principale, bot.html. Non cancellano l'overlay principale dei messaggi in evidenza.

Opzione	Significato	Esempio
showtime	Usa un tempo di visualizzazione fisso in millisecondi.	&showtime=10000 nasconde dopo 10 secondi.
autohide	Stima il tempo di visualizzazione dal numero di parole della risposta. autotime è accettato anche.	&autohide
mintime / maxtime	Imposta il tempo minimo e massimo di visualizzazione in base alla lunghezza. I valori predefiniti sono 4.000 e 30.000 millisecondi.	&autohide&mintime=5000&maxtime=20000
hideaftertts	Mantiene visibile la risposta fino alla fine della riproduzione TTS, poi la nasconde. Se la riproduzione non inizia mai, usa un tempo alternativo basato sulla lunghezza.	&hideaftertts
hidedelay	Aggiunge un ritardo dopo la fine del TTS. Il valore predefinito è 500 millisecondi.	&hideaftertts&hidedelay=1000
ttstimeout	Tempo massimo di sicurezza se il TTS resta attivo indefinitamente. Il valore predefinito è 120.000 millisecondi.	&hideaftertts&ttstimeout=60000

Se sono attive più modalità, hideaftertts ha la precedenza, seguito da autohide, poi showtime. Le impostazioni generate dell'overlay del bot offrono le opzioni comuni.

Cancellazione manuale

• Nelle impostazioni di Social Stream, seleziona Cancella ora l'overlay del bot.
• Con Remote API Control attivo, apri https://io.socialstream.ninja/SESSION_ID/clearBotOverlay.
• Tramite il WebSocket API, invia {"action":"clearBotOverlay"}.

La cancellazione manuale rimuove la risposta visibile e la coda di visualizzazione dell'overlay del bot, ma non interrompe la voce già in riproduzione.

Risolvi i problemi partendo dall'ultimo passaggio riuscito

Cosa vedi	Area probabile	Cosa controllare
La prova del provider non riesce	Configurazione del provider	Endpoint, chiave API, nome del modello, stato del servizio locale, CORS/firewall, quota del provider ed errore esatto sotto il pulsante di prova.
401 missing_scope / model.request	Permessi della chiave OpenAI	Usa una chiave standard del progetto previsto, non una chiave Admin; verifica che le richieste ai modelli siano consentite; sostituisci le vecchie chiavi salvate e riprova dalla pagina originale in inglese di OpenAI Platform se la traduzione automatica rende inaffidabili i controlli. I crediti non aggiungono questo permesso.
401 invalid_api_key oppure chiave API errata	Credenziale OpenAI	Controlla se manca un carattere o uno spazio, verifica che la chiave non sia stata eliminata o disattivata, controlla organizzazione e progetto previsti e assicurati che Social Stream non stia ancora usando una vecchia chiave salvata.
429 errore di quota o limite di frequenza	Fatturazione o limiti del provider	Verifica fatturazione API e budget del progetto separatamente dagli abbonamenti ChatGPT, poi riduci la frequenza delle richieste o attendi se il provider segnala un limite temporaneo.
Connesso, ma il messaggio dello spettatore non compare nel dock	Acquisizione della chat	Stato attivo/disattivo di Social Stream, finestra della sorgente, accesso alla piattaforma, impostazioni di autorizzazione e filtro della sorgente e apertura della chat in diretta corretta.
Il messaggio arriva al dock, ma nessuna risposta raggiunge l'overlay del bot	Decisione del bot principale	Verifica che il messaggio provenga direttamente dalla chat sorgente, poi controlla l'attivazione del bot principale, la corrispondenza del criterio di attivazione, la modalità solo moderatori, il nome personalizzato del bot, i limiti di occupazione e pausa, le istruzioni aggiuntive e la modalità temporanea senza filtro delle risposte.
La risposta raggiunge l'overlay, ma non la chat della piattaforma	Instradamento delle risposte alla piattaforma	Modalità solo overlay, supporto alla scrittura della piattaforma o sorgente, autorizzazione dell'account, disponibilità del campo chat, instradamento per ruolo account e impostazione Disable host chat.
La risposta resta visibile dopo il TTS	Tempi dell'overlay del bot	Attiva Hide after TTS, la scomparsa automatica in base alla lunghezza o un tempo di visualizzazione fisso nelle opzioni dell'overlay del bot. Usa clearBotOverlay per cancellare manualmente tramite API.
!bot non produce effetti	Filtro dei comandi	Usa una parola normale come criterio di attivazione, oppure consenti quel comando nel filtro globale dei comandi.
Viene elaborata solo la prima prova	Tempi	Attendi la richiesta attiva, rispetta la pausa e ricorda che il keep-alive 0 può imporre un nuovo caricamento del modello a ogni richiesta.
Privato chatbot.html è vuoto	Bot privato separato	Attiva l'opzione del bot di chat privato e usa il link generato con la stessa sessione. Questo non prova il bot principale in diretta.

Altre pagine dei bot IA

Il bot principale, la chat privata, il bot di censura e il co-conduttore IA sono strumenti separati, con impostazioni e cronologie diverse.

Per tutte le altre funzioni IA, consulta la Guida alle modalità IA.