Chiave API LLM per bot Discord: guida alla configurazione

A cosa serve una chiave API LLM per un bot Discord

Se vuoi una chiave API LLM per bot Discord, le parti in gioco sono semplici. Discord invia un messaggio al tuo codice tramite il suo gateway bot. Il tuo codice invia la conversazione recente a un endpoint LLM, riceve testo e lo pubblica di nuovo nel canale. La chiave API è ciò che prova al provider LLM che la richiesta è tua e lo addebita al tuo saldo.

Questo servizio è compatibile con OpenAI, quindi il bot utilizza il pacchetto Python openai standard. Modifichi due impostazioni, l'URL di base e l'ID del modello uncensored, e tutto il resto è normale completamento della chat. I nuovi utenti possono provarlo prima: dopo la registrazione, la pagina chiave API offre $0,50 di credito di prova gratuito, valido per 7 giorni, senza bisogno di carta.

Un limite onesto fin da subito. Questo è un modello di testo. Non può generare immagini, voce o video e non legge gli allegati da solo. Il tuo bot può inoltrare il testo da un messaggio, ma qualsiasi cosa oltre il testo è al di fuori di ciò che fa questa API.

Prima di scrivere il codice

1. Ottieni una chiave API. Registrati con Google o email, crea una chiave nella pagina delle chiavi e tienila in una variabile d'ambiente.
2. Crea un'applicazione Discord. Nel portale per gli sviluppatori di Discord, aggiungi un bot, copia il suo token e abilita l'intent Message Content in modo che il bot possa leggere il testo dei messaggi. Invitalo nel tuo server con i permessi per leggere e inviare messaggi.
3. Installa le librerie. Ti servono discord.py e openai.

Copypython3 -m venv .venv
source .venv/bin/activate
pip install discord.py openai
export API_KEY="your-llm-key"
export DISCORD_TOKEN="your-discord-bot-token"

Non fare mai il commit di questi segreti. Se un token viene esposto, reimpostalo nel rispettivo dashboard. Per il lato LLM, la documentazione quickstart mostra la stessa chiamata in curl e Node se preferisci un'altra lingua.

Un bot funzionante in circa 50 righe

Questo bot risponde quando qualcuno lo menziona. Mantiene gli ultimi 20 messaggi per canale, chiama il modello con un prompt del personaggio e divide le risposte lunghe per adattarsi al limite di 2.000 caratteri di Discord.

Copyimport os
import asyncio
from collections import defaultdict, deque

import discord
from openai import AsyncOpenAI, RateLimitError

ai = AsyncOpenAI(
    base_url="https://api.getaiapikey.com/v1",
    api_key=os.environ["API_KEY"],
)

SYSTEM = (
    "You are Mara, the resident storyteller of a community server for adult "
    "fiction writers. Keep replies under 150 words unless asked for more. "
    "Stay in character, write in plain prose, and ask one question at the end."
)

history = defaultdict(lambda: deque(maxlen=20))
gate = asyncio.Semaphore(6)

intents = discord.Intents.default()
intents.message_content = True
bot = discord.Client(intents=intents)


@bot.event
async def on_message(message):
    if message.author.bot or bot.user not in message.mentions:
        return

    text = message.clean_content.replace("@" + bot.user.display_name, "").strip()
    if not text:
        return

    log = history[message.channel.id]
    log.append({"role": "user", "content": message.author.display_name + ": " + text})

    async with gate:
        async with message.channel.typing():
            try:
                resp = await ai.chat.completions.create(
                    model="uncensored",
                    messages=[{"role": "system", "content": SYSTEM}, *log],
                    temperature=0.8,
                    max_tokens=500,
                )
            except RateLimitError:
                await message.reply("I am busy right now. Try again in a few seconds.")
                return

    reply = resp.choices[0].message.content or ""
    log.append({"role": "assistant", "content": reply})

    for i in range(0, len(reply), 1900):
        await message.reply(reply[i:i + 1900])


bot.run(os.environ["DISCORD_TOKEN"])

Esegui con python bot.py, menziona il bot in un canale e dovresti vedere una risposta. L'indicatore di digitazione appare mentre la richiesta è in corso, il che fa sembrare l'attesa più breve.

Scrivi un prompt di sistema che mantenga un personaggio

Il prompt di sistema fa la maggior parte del lavoro in un bot chat. Uno buono è breve e specifico: chi è il bot, quanto durano le sue risposte e cosa dovrebbe fare quando la conversazione devia. Confronta due versioni.

Un prompt debole dice "sii un assistente utile". Uno più forte dà un ruolo, un limite di lunghezza e un'abitudine: "Sei Mara, una narratrice. Rispondi in meno di 150 parole. Finisci con una domanda che fa avanzare la scena". Il secondo dà al modello qualcosa a cui aggrapparsi attraverso una dozzina di turni, e il limite di lunghezza mantiene anche i tuoi costi prevedibili.

Alcuni punti pratici dall'esecuzione di chat bot:

• Anticipa ogni turno utente con il nome dell'autore, come fa il codice. In un canale condiviso il modello altrimenti non può distinguere le persone.
• Metti le regole del tuo server nel prompt di sistema, come gli argomenti da evitare o uno stile specifico. Il modello è ottimizzato per rispondere senza rifiuti di contenuto per uso adulto legale, quindi i limiti che vuoi devono provenire dal tuo prompt e dalla tua moderazione, non dal modello.
• Mantieni il personaggio costante. Se lo cambi spesso, i vecchi turni nella cronologia contraddiranno le nuove istruzioni.

Contesto, cronologia e la finestra da 100.000 token

La finestra di contesto è di 100.000 token, prompt più completamento. Una cronologia rotativa di 20 messaggi è di gran lunga inferiore, ed è intenzionale. L'API è stateless: ogni richiesta deve contenere l'intera conversazione che vuoi che il modello veda, quindi ogni turno extra che mantieni è pagato di nuovo su ogni chiamata successiva.

Scegli una lunghezza della cronologia in base alla memoria di cui ha bisogno il bot. Un bot chat occasionale funziona con 10-20 messaggi. Un roleplay a lungo termine potrebbe averne bisogno di più, e per quello un approccio comune è riassumere i turni vecchi in una breve nota tenuta vicino all'inizio del prompt, quindi scartare gli originali. Usa una seconda chiamata al modello per scrivere il riassunto quando la cronologia supera una dimensione che scegli.

La cronologia per canale, come nel codice, mantiene le conversazioni separate. Se vuoi anche memoria per utente tra i canali, archivia le note in un database e aggiungile al prompt di sistema per quell'utente. Questa parte è compito della tua applicazione, poiché l'API stessa non mantiene nulla tra le chiamate. Per la privacy, nota che i prompt inviati a questa API non sono usati per l'addestramento; vedi la pagina privacy per i dettagli.

Limiti di richiesta su un server affollato

Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. Una chiave di prova permette 2 e 60. Un server tranquillo non se ne accorge, ma un canale popolare può inviare un burst di menzioni tutte insieme.

L'asyncio.Semaphore(6) nel codice limita il bot a 6 chiamate in corso, così non raggiunge mai il limite di 8 e lascia spazio a un secondo script che usa la stessa chiave. Su una chiave di prova, impostalo a 2. Se superi un limite, l'API restituisce HTTP 429: rate_limited per richieste al minuto, concurrency per troppe contemporaneamente. Il sovraccarico temporaneo dà anche 429 con Retry-After: 5. Il client OpenAI ritenta alcuni di questi per impostazione predefinita, e il codice sopra risponde con un messaggio educato se i ritentativi terminano.

Lo streaming merita una nota. Se modifichi il messaggio Discord mentre arrivano i token, la richiesta mantiene il suo slot di concorrenza fino alla fine dello stream, e Discord limita la velocità con cui puoi modificare i messaggi. Per la maggior parte dei bot una singola risposta dopo la risposta completa è più semplice e affidabile.

Quanto costa far funzionare un bot Discord

La tariffazione è $0,15 per 1M token di input e $0,50 per 1M token di output, da credito prepagato. Calcola prima una risposta. Supponi che il prompt di sistema più 20 messaggi di cronologia arrivino a 1.500 token di input, e la risposta sia 200 token.

• Input: 1.500 / 1.000.000 x $0,15 = $0,000225
• Output: 200 / 1.000.000 x $0,50 = $0,0001
• Totale: $0,000325 per risposta, quindi 1.000 risposte costano $0,325

Ora un caso più pesante con 3.000 input e 300 token di output: $0,00045 + $0,00015 = $0,0006 per risposta, o $0,60 per 1.000 risposte. Un server che riceve 500 risposte al giorno di quella dimensione spende circa $0,30 al giorno, circa $9 in 30 giorni.

Il minimo ricarico è $20 (qualsiasi importo intero fino a $500), con un bonus del 5% da $50, 10% da $100 e 15% da $200. Il credito non scade mai, e le richieste fallite o rifiutate non sono addebitate. Paga con carta (Visa, Mastercard, Apple Pay, Google Pay) o cripto (USDT su TRC20, USDC su Base). Maggiori informazioni nella pagina prezzi.

Regole e sicurezza per comunità per adulti

Il modello serve l'uso adulto legale, e il limite rigido è che i contenuti sessuali che coinvolgono minorenni non sono mai permessi. Se il tuo server ospita fiction o roleplay per adulti, mantieni tutto per adulti: limita l'accesso ai canali nelle impostazioni di Discord, dichiara le tue regole nell'argomento del canale e modera. Leggi le attuali politiche developer e community di Discord prima di lanciare, poiché si applicano al tuo bot indipendentemente da cosa scriverà il modello.

Registra gli ID di richiesta. Ogni risposta API include X-Request-Id, che aiuta quando contatti il supporto per una chiamata specifica. L'intestazione X-Balance-USD permette al bot di avvisarti in un canale admin quando il credito è basso, così non va mai in silenzio senza preavviso.

Altre guide

• Chiave API LLM gratuita: cosa copre il credito di prova
• Come installare un LLM in Python: Locale o API
• AI API Checklist