PT ▾
Obter chave de API

Bot Telegram Uncensored Endpoint: Crie-o em Python

Para criar um bot de Telegram com endpoint sem censura, você precisa de três componentes: um token de bot do BotFather, uma chave de API e cerca de 80 linhas de Python que encaminham cada mensagem do Telegram para a rota de conclusões de chat. Este guia fornece o código completo, depois adiciona memória, streaming e tratamento de limites.

Atualizado

Pontos principais

  1. O bot usa python-telegram-bot para o Telegram e o SDK OpenAI padrão para o modelo.
  2. Mantenha um histórico curto por conversa e ajuste-o para que cada requisição permaneça pequena e barata.
  3. Faça streaming editando uma mensagem cerca de uma vez por segundo, não a cada token.
  4. Limite as chamadas simultâneas ao modelo em 8 com um semáforo e tente novamente as respostas 429.
Bolha de chat de avião de papel deixando um terminal em direção a uma fileira de bolhas de fala, representando um bot do Telegram

O que você está construindo

O bot tem uma única função: pegar uma mensagem de texto de um chat do Telegram, adicioná-la ao histórico dessa conversa, enviar o histórico para o modelo uncensored e postar a resposta de volta. Cada chat do Telegram tem sua própria memória, então duas pessoas falando com o bot nunca veem o contexto um do outro.

O projeto finalizado é um arquivo único com estas partes:

  1. Um cliente para a API, usando o SDK OpenAI apontado para https://api.uncensoredendpoint.com/v1.
  2. Um dicionário de históricos de chat, limitado para que nunca cresça indefinidamente.
  3. Um manipulador de mensagens que faz streaming da resposta editando uma mensagem do Telegram.
  4. Um semáforo que mantém você abaixo das 8 requisições simultâneas que uma chave completa permite.

Nada aqui precisa de banco de dados. Quando o bot reinicia, os históricos são resetados, o que é bom para uma primeira versão. Uma seção posterior cobre onde adicionar persistência.

Pré-requisitos

Você precisa do Python 3.10 ou mais recente e de duas credenciais.

  • Um token de bot do Telegram. Abra um chat com o BotFather dentro do Telegram, envie o comando para criar um novo bot, escolha um nome e um nome de usuário, e copie o token que ele retorna. Trate o token como uma senha.
  • Uma chave de API. Entre na página de chaves com Google ou com e-mail e senha. Novos usuários podem reivindicar $0,50 de crédito de teste grátis com um clique, o suficiente para testar este bot várias vezes. A chave de teste permite 2 requisições simultâneas e 60 requisições por minuto.

Instale as duas bibliotecas e exporte os segredos como variáveis de ambiente para que eles nunca apareçam no seu código-fonte:

pip install "python-telegram-bot>=20" openai
export TELEGRAM_TOKEN="123456:your-bot-token"
export API_KEY="your-api-key"

Se você mais tarde migrar do teste para o tráfego real, o crédito vem de um recarregamento de $20 a $500, seja por cripto (USDT na TRC20 ou USDC na Base). A página de preços lista os níveis de bônus.

Um bot funcional mínimo

Comece com a menor versão que responde mensagens. Ela não tem streaming nem corte ainda, então você pode confirmar a infraestrutura primeiro.

import os
from collections import defaultdict

from openai import AsyncOpenAI
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, MessageHandler, filters

client = AsyncOpenAI(
    base_url="https://api.uncensoredendpoint.com/v1",
    api_key=os.environ["API_KEY"],
    max_retries=3,
)

SYSTEM = "You are a friendly, direct assistant. Keep answers short unless asked for detail."
history = defaultdict(list)  # chat_id -> list of messages


async def on_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
    chat_id = update.effective_chat.id
    history[chat_id].append({"role": "user", "content": update.message.text})

    resp = await client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "system", "content": SYSTEM}] + history[chat_id],
        temperature=0.8,
    )
    answer = resp.choices[0].message.content
    history[chat_id].append({"role": "assistant", "content": answer})
    await update.message.reply_text(answer[:4000])


app = ApplicationBuilder().token(os.environ["TELEGRAM_TOKEN"]).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_text))
app.run_polling()

Execute-a, abra seu bot no Telegram e diga olá. A fatia answer[:4000] existe porque o Telegram limita uma única mensagem a 4096 caracteres. Uma resposta longa do modelo faria a chamada falhar. Mais tarde você pode dividir respostas longas em várias mensagens em vez de cortá-las.

O SDK da OpenAI tenta novamente algumas falhas por conta própria, incluindo respostas 429, com uma breve pausa. Definir max_retries=3 dá a você uma margem de segurança sem precisar escrever um loop de tentativa ainda.

Memória que não cresce para sempre

Completions de chat são stateless. O modelo só sabe o que você envia em cada requisição, então o bot reenvia o histórico a cada turno. É por isso que histórico ilimitado é a principal armadilha de custo e latência. A janela de contexto é de 100.000 tokens, o que é muito, mas você paga por cada token de entrada em cada turno, e a maioria dos bots de chat não precisa de tanto assim.

Uma política simples funciona bem: mantenha o prompt do sistema e mantenha apenas as últimas N mensagens. Vinte mensagens, dez do usuário e dez do bot, adequam-se ao chat casual.

MAX_MESSAGES = 20


def remember(chat_id, role, content):
    h = history[chat_id]
    h.append({"role": role, "content": content})
    if len(h) > MAX_MESSAGES:
        del h[: len(h) - MAX_MESSAGES]

Cortar em um ponto arbitrário pode deixar um histórico que começa com uma mensagem do assistente. Isso é inofensivo para este modelo, mas se você quiser que fique organizado, remova mais uma mensagem quando a primeira restante não for do usuário.

Para personagens ou histórias longas onde o modelo deve lembrar fatos desde o início, o corte os perde. Duas correções comuns são uma nota fixa e um resumo móvel. Uma nota fixa é um bloco curto de fatos que você mantém no prompt do sistema, como nomes e a cena atual. Um resumo móvel pede ao modelo, a cada trinta mensagens ou mais, para comprimir a metade mais antiga do histórico em um parágrafo, que você então armazena no lugar dessas mensagens.

Adicione um comando /reset que limpa history[chat_id]. As pessoas gostam de ter uma folha limpa, e isso não custa nada para você.

Streaming da resposta editando uma mensagem

Esperar dez segundos por uma resposta longa parece lento em um app de chat. O streaming permite que a resposta cresça na tela. O Telegram não aceita um token de mensagem por token, então o truque é enviar um texto de marcador, depois editá-lo conforme o texto chega. Edite cerca de uma vez por segundo no máximo. O Telegram aplica seus próprios limites de flood aos bots, e martelar a chamada de edição em cada token faz você ser limitado e desacelera o streaming.

import time


async def stream_answer(update, chat_id):
    msg = await update.message.reply_text("...")
    stream = await client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "system", "content": SYSTEM}] + history[chat_id],
        stream=True,
    )
    text, last_edit = "", 0.0
    async for chunk in stream:
        if not chunk.choices:
            continue
        piece = chunk.choices[0].delta.content or ""
        text += piece
        if time.monotonic() - last_edit > 1.0 and text.strip():
            await msg.edit_text(text[:4000])
            last_edit = time.monotonic()
    if text.strip():
        await msg.edit_text(text[:4000])
    return text

Dois detalhes importam. Primeiro, sempre faça uma edição final após o loop, porque os últimos pedaços geralmente chegam entre edições temporizadas. Segundo, o Telegram rejeita uma edição que não muda o texto, então pule a chamada quando nada é novo. A biblioteca levanta um erro para esse caso, e um try/except em torno da edição mantém o streaming vivo.

Lembre-se de que uma solicitação em streaming mantém seu slot de concorrência até que o streaming termine. Um bot com muitos chats conversando ao mesmo tempo atingirá o limite mais cedo com streaming do que sem, o que leva à próxima seção.

Mantendo-se dentro dos limites de requisições

Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 e 60. Um grupo de chat ocupado pode facilmente exceder 2 ao mesmo tempo, então dimensione seu limite para a chave que você está usando.

A proteção mais limpa é um semáforo em torno da chamada do modelo. Requisições além do limite aguardam na fila dentro do seu processo em vez de bater na API:

import asyncio

slots = asyncio.Semaphore(8)  # use 2 with a trial key


async def on_text(update, context):
    chat_id = update.effective_chat.id
    remember(chat_id, "user", update.message.text)
    async with slots:
        text = await stream_answer(update, chat_id)
    remember(chat_id, "assistant", text)

Se você ainda receber um HTTP 429, leia o código de erro. concurrency significa muitas chamadas ao mesmo tempo, rate_limited significa muitas por minuto, e um 429 com Retry-After: 5 significa sobrecarga temporária; espere os cinco segundos. O retry do SDK lida com a maioria desses casos. Requisições falhas ou recusadas não são cobradas, então as tentativas não somam à conta.

Mais uma proteção é o ritmo por usuário. Se uma única pessoa enviar dez mensagens em dez segundos, serialize suas requisições com um lock por chat para que as respostas cheguem em ordem e um chat não use todos os oito slots.

Persona, regras e chats em grupo

O prompt do sistema é onde o bot ganha sua personalidade. Escreva-o como um breve resumo: quem é o bot, como ele fala, quão longas devem ser as respostas e qualquer coisa que ele não deve fazer. Para um bot de roleplay ou de companhia para adultos, descreva o cenário e o tom em algumas linhas e deixe o usuário guiar a partir daí. Prompts específicos batem longos; o modelo segue uma persona clara de cinco linhas melhor do que uma página de regras.

Algumas regras ficam fora do prompt. O modelo responde sem recusas de conteúdo para uso adulto legal, mas conteúdo sexual envolvendo menores de idade nunca é permitido, e você deve impor isso do seu lado também. Se o seu bot é aberto ao público, diga isso na descrição dele, adicione um aviso de idade na mensagem de início, e lembre-se de que o Telegram tem seus próprios termos para bots que você também deve seguir. As conversas dos seus usuários vão para a API, e prompts não são usados para treinamento; diga aos seus usuários o que seu próprio bot armazena.

Em chats de grupo, não responda a cada mensagem. Responda apenas quando o bot for mencionado ou quando alguém responder a uma de suas mensagens, e ignore mensagens enviadas por outros bots. No python-telegram-bot você pode verificar update.message.entities para uma menção ou comparar update.message.reply_to_message.from_user.id com o próprio ID do bot.

Quando algo dá errado, registre o cabeçalho de resposta X-Request-Id para cada chamada; você pode lê-lo através da interface de resposta bruta do SDK. A página de suporte é o lugar para perguntar sobre uma requisição específica.

Executando-o na prática

Polling, como usado acima, é bom para um bot pequeno: o processo pergunta ao Telegram por novas mensagens em um loop e não precisa de endereço público. Execute-o sob systemd ou um container com reinício automático, e mantenha os dois segredos no ambiente do arquivo da unidade ou em um armazenamento de segredos. Uma configuração de webhook reduz a carga ociosa, mas precisa de HTTPS e uma URL pública, então comece com polling.

Estime o custo antes de convidar pessoas. A API cobra $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída. Um turno típico com um histórico ajustado de 2.000 tokens de entrada e 500 tokens de saída custa 2.000 x $0,15 / 1M = $0,0003 para entrada mais 500 x $0,50 / 1M = $0,00025 para saída, o que é $0,00055. Mil turnos custam $0,55. Se um chat crescer para 10.000 tokens de entrada por turno, a parte de entrada sozinha se torna $0,0015, então o ajuste paga a si mesmo rapidamente.

Quando você precisa de persistência, armazene o histórico de cada chat como JSON no SQLite ou Redis, carregue-o na primeira mensagem após uma reinicialização e grave-o novamente após cada resposta. Adicione um limite diário de mensagens por usuário se o bot for público, para que um usuário entusiástico não esgote o saldo. A documentação da API lista todos os parâmetros que você pode ajustar, e a lista de verificação de produção de chaves cobre a rotação de chaves e o monitoramento do cabeçalho de saldo.

Perguntas e respostas

Qual biblioteca devo usar para o lado do Telegram?

Qualquer biblioteca funciona porque o lado do modelo é uma API HTTP simples. Este guia usa python-telegram-bot versão 20 ou mais recente, que é assíncrono e combina bem com o cliente OpenAI assíncrono.

Por que meu bot responde a si mesmo ou a todos em um grupo?

Em grupos, restrinja o manipulador a mensagens que mencionam o bot ou respondem a ele, e ignore mensagens de bots. Caso contrário, cada mensagem no grupo aciona uma chamada ao modelo.

Quanto custa uma conversa com um bot?

Uma troca curta de 2.000 tokens de entrada e 500 tokens de saída custa $0,00055, então mil delas custam $0,55. Histórico longos custam mais porque são reenviados a cada turno.

O bot pode ser usado para roleplay adulto?

O modelo é ajustado para responder sem recusas de conteúdo para uso adulto legal, e bots para ficção e bate-papo de companhia são um caso típico. Conteúdo sexual envolvendo menores de idade nunca é permitido, e o Telegram tem suas próprias regras que você deve seguir.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de APILer a documentação