PL ▾
Pobierz klucz API

Bot Telegram Uncensored Endpoint: Zbuduj go w Pythonie

Aby zbudować bota Telegrama na endpointzie bez cenzury, potrzebujesz trzech elementów: token bota od BotFathera, klucz API i około 80 linii kodu w Pythonie, które przesyłają każdą wiadomość Telegrama do trasy chat completions. Ten poradnik zawiera pełny kod, a następnie dodaje pamięć, strumieniowanie i obsługę limitów.

Zaktualizowano

Kluczowe punkty

  1. Bot używa biblioteki python-telegram-bot do obsługi Telegrama oraz standardowego SDK OpenAI do obsługi modelu.
  2. Przechowuj krótką historię na rozmowę i przycinaj ją, aby każde zapytanie było małe i tanie.
  3. Strumieniuj odpowiedź, edytując jedną wiadomość około raz na sekundę, a nie przy każdym tokenie.
  4. Ogranicz równoległe wywołania modelu do 8 za pomocą semafora i obsłuż odpowiedzi 429.
Dymek czatu w kształcie samolotu papierowego wylatujący z terminala w kierunku rzędu dymków mowy, reprezentujący bota Telegrama

Co budujesz

Bot ma jedno zadanie: przyjąć wiadomość tekstową z czatu Telegram, dodać ją do historii tego czatu, wysłać historię do modelu uncensored i zwrócić odpowiedź. Każdy czat Telegram ma własną pamięć, więc dwie osoby rozmawiające z botem nigdy nie widzą kontekstu drugiej osoby.

Ukończony projekt to pojedynczy plik zawierający te części:

  1. Klient API, używający SDK OpenAI skierowanego do https://api.uncensoredendpoint.com/v1.
  2. Słownik historii czatów, przycinany tak, aby nigdy nie rósł bez ograniczeń.
  3. Handler wiadomości, który strumieniuje odpowiedź poprzez edycję jednej wiadomości Telegrama.
  4. Semafor, który utrzymuje Cię poniżej 8 równoległych zapytań, jakie pozwala pełny klucz.

Nic tutaj nie wymaga bazy danych. Po restarcie bota historie są resetowane, co jest wystarczające dla pierwszej wersji. W kolejnym rozdziale omówiono, gdzie dodać trwałość danych.

Wymagania wstępne

Potrzebujesz Pythona w wersji 3.10 lub nowszej oraz dwóch poświadczeń.

  • Token bota Telegrama. Otwórz czat z BotFatherem w Telegramie, wyślij komendę do utworzenia nowego bota, wybierz nazwę i nazwę użytkownika oraz skopiuj zwrócony token. Traktuj token jak hasło.
  • Klucz API. Zarejestruj się na stronie kluczy za pomocą Google lub e-maila i hasła. Nowi użytkownicy mogą jednym kliknięciem uzyskać $0,50 kredytu próbnego, co wystarczy do wielokrotnego przetestowania tego bota. Klucz próbny pozwala na 2 równoległe zapytania i 60 zapytań na minutę.

Zainstaluj obie biblioteki i wyeksportuj sekrety jako zmienne środowiskowe, aby nigdy nie trafiły do kodu źródłowego:

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

Jeśli później przejdziesz z wersji próbnej na prawdziwy ruch, kredyt pochodzi z doładowania kryptowalutą o wartości od $20 do $500, albo USDT na TRC20, albo USDC na Base. Strona cennika wymienia poziomy bonusów.

Minimalnie działający bot

Zacznij od najmniejszej wersji, która odpowiada na wiadomości. Nie obsługuje jeszcze strumieniowania ani przycinania, więc najpierw możesz potwierdzić poprawność połączeń.

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()

Uruchom go, otwórz bota w Telegramie i powiedz „cześć”. Fragment answer[:4000] istnieje, ponieważ Telegram ogranicza pojedynczą wiadomość do 4096 znaków. Długa odpowiedź modelu w przeciwnym razie spowodowałaby błąd wysyłania. Później możesz dzielić długie odpowiedzi na kilka wiadomości zamiast je obcinać.

SDK OpenAI automatycznie ponawia niektóre błędy, w tym odpowiedzi 429, z krótkim opóźnieniem. Ustawienie max_retries=3 daje Ci margines bezpieczeństwa bez pisania pętli ponawiania.

Pamięć, która nie rośnie w nieskończoność

Uzupełniania czatu są bezstanowe. Model wie tylko to, co wyślesz w każdym zapytaniu, więc bot ponownie wysyła historię przy każdej turze. Dlatego nieograniczona historia to główna pułapka kosztów i opóźnień. Okno kontekstu wynosi 100 000 tokenów, co jest dużo, ale płacisz za każdy token wejściowy przy każdej turze, a większość botów czatu nie potrzebuje aż tak dużo.

Prosta polityka działa dobrze: zachowaj prompt systemowy i zachowaj tylko ostatnie N wiadomości. Dwadzieścia wiadomości, dziesięć od użytkownika i dziesięć od bota, pasuje do luźnej rozmowy.

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]

Obcięcie w arbitralnym punkcie może pozostawić historię zaczynającą się od wiadomości asystenta. To nie szkodzi dla tego modelu, ale jeśli chcesz to uporządkować, usuń jedną dodatkową wiadomość, gdy pierwsza pozostała nie pochodzi od użytkownika.

W przypadku postaci lub długich opowieści, gdzie model musi pamiętać fakty z wczesnych partii, przycinanie je traci. Dwa powszechne rozwiązania to przypięta notatka i tocząca się podsumowanie. Przypięta notatka to krótki blok faktów, który utrzymujesz w promptcie systemowym, taki jak imiona i obecna scena. Toczące się podsumowanie prosi model, co około trzydzieści wiadomości, o skompresowanie starszej połowy historii do akapitu, który następnie przechowujesz w miejscu tych wiadomości.

Dodaj komendę /reset, która czyści history[chat_id]. Ludzie lubią mieć czystą kartę, a nic Cię to nie kosztuje.

Strumieniowanie odpowiedzi przez edycję jednej wiadomości

Czekanie dziesięć sekund na długą odpowiedź wydaje się wolne w aplikacji czatu. Strumieniowanie pozwala odpowiedzi rosnąć na ekranie. Telegram nie akceptuje wiadomości token po tokenie, więc sztuczka polega na wysłaniu symbolu zastępczego, a następnie jego edycji, gdy napływa tekst. Edytuj najwyżej raz na sekundę. Telegram stosuje własne limity natężenia ruchu do botów, a wysyłanie wywołania edycji przy każdym tokenie powoduje throttling i spowalnia strumieniowanie.

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

Ważne są dwie kwestie. Po pierwsze, zawsze wykonaj końcową edycję po pętli, ponieważ ostatnie fragmenty zwykle przychodzą między edycjami czasowymi. Po drugie, Telegram odrzuca edycję, która nie zmienia tekstu, więc pomiń wywołanie, gdy nic nowego nie ma. Biblioteka zgłasza błąd dla tego przypadku, a try/except wokół edycji utrzymuje strumień.

Pamiętaj, że żądanie strumieniowe zajmuje slot współbieżności do końca strumienia. Bot z wieloma rozmowami jednocześnie osiągnie limit szybciej ze strumieniowaniem niż bez niego, co prowadzi do kolejnego rozdziału.

Pozostawanie w ramach limitów zapytań

Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Klucz próbny pozwala na 2 i 60. Zajęty czat grupowy może łatwo przekroczyć 2 jednocześnie, więc dostosuj limit do używanego klucza.

Najczystszą ochroną jest semafor wokół wywołania modelu. Zapytania poza limitem czekają w kolejce w Twoim procesie zamiast odbijać się od 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)

Jeśli nadal otrzymujesz HTTP 429, przeczytaj kod błędu. concurrency oznacza zbyt wiele wywołań naraz, rate_limited oznacza zbyt wiele na minutę, a 429 z Retry-After: 5 oznacza tymczasowe przeciążenie; odczekaj pięć sekund. Obsługa ponownych prób przez SDK rozwiązuje większość tych przypadków. Nieudane lub odrzucone żądania nie są rozliczane, więc ponowne próby nie zwiększają rachunku.

Kolejną ochroną jest tempo na użytkownika. Jeśli jedna osoba wyśle dziesięć wiadomości w ciągu dziesięciu sekund, serializuj ich zapytania za pomocą blokady na rozmowę, aby odpowiedzi przychodziły w kolejności i jedna rozmowa nie zużywała wszystkich ośmiu slotów.

Persona, zasady i czaty grupowe

Prompt systemowy to miejsce, gdzie bot zyskuje swoją charakterystykę. Napisz go jak krótki brief: kim jest bot, jak mówi, jak długie powinny być odpowiedzi i czego nie powinien robić. Dla bota roleplay lub towarzyskiego dla dorosłych opisz ustawienie i ton w kilku liniach i pozwól użytkownikowi prowadzić od tego miejsca. Konkretne prompty są lepsze niż długie; model lepiej podąża za jasną personą z pięciu linii niż stroną zasad.

Niektóre zasady znajdują się poza promptem. Model odpowiada bez odrzuceń treści dla użytku dorosłego, ale treści erotyczne z udziałem nieletnich są zawsze zabronione, a Ty powinienś egzekwować to po swojej stronie. Jeśli Twój bot jest otwarty dla publiczności, powiedz o tym w jego opisie, dodaj informację o wieku w wiadomości powitalnej i pamiętaj, że Telegram ma własne warunki dla botów, które również musisz stosować. Rozmowy Twoich użytkowników trafiają do API, a prompty nie są używane do szkolenia; powiedz swoim użytkownikom, co przechowuje Twój własny bot.

W czatach grupowych nie odpowiadaj na każdą wiadomość. Odpowiadaj tylko wtedy, gdy bot jest wspomniany lub gdy ktoś odpowiada na jedną z jego wiadomości, i ignoruj wiadomości wysłane przez inne boty. W python-telegram-bot możesz sprawdzić update.message.entities pod kątem wzmianki lub porównać update.message.reply_to_message.from_user.id z własnym ID bota.

Kiedy coś pójdzie nie tak, zaloguj nagłówek odpowiedzi X-Request-Id dla każdego wywołania; możesz go odczytać przez interfejs surowej odpowiedzi w SDK. Strona wsparcia to miejsce, w którym możesz zapytać o konkretne zapytanie.

Uruchomienie w praktyce

Pollowanie, jak użyto powyżej, jest wystarczające dla małego bota: proces pyta Telegrama o nowe wiadomości w pętli i nie wymaga publicznego adresu. Uruchom go pod systemd lub kontenerem z automatycznym restartem i przechowuj dwa sekrety w środowisku pliku jednostki lub w magazynie sekretów. Konfiguracja webhook zmniejsza obciążenie w spoczynku, ale wymaga HTTPS i publicznego URL, więc zacznij od pollowania.

Oszacuj koszt przed zaproszeniem ludzi. API pobiera $0,15 za 1M tokenów wejściowych i $0,50 za 1M tokenów wyjściowych. Typowa tura z przyciętą historią 2000 tokenów wejściowych i 500 tokenów wyjściowych kosztuje 2000 x $0,15 / 1M = $0,0003 za wejście plus 500 x $0,50 / 1M = $0,00025 za wyjście, co daje $0,00055. Tysiąc tur kosztuje $0,55. Jeśli rozmowa wzrośnie do 10 000 tokenów wejściowych na turę, sama część wejściowa wyniesie $0,0015, więc przycinanie zwraca się szybko.

Kiedy potrzebujesz trwałości, przechowaj historię każdej rozmowy jako JSON w SQLite lub Redis, załaduj ją przy pierwszej wiadomości po restarcie i zapisz z powrotem po każdej odpowiedzi. Dodaj dzienny limit wiadomości na użytkownika, jeśli bot jest publiczny, aby jeden entuzjastyczny użytkownik nie wyczerpał salda. Dokumentacja API wymienia każdy parametr, który możesz dostosować, a lista kontrolna produkcji kluczy obejmuje rotację kluczy i śledzenie nagłówka salda.

Pytania i odpowiedzi

Którą bibliotekę wybrać do obsługi Telegrama?

Działa dowolna biblioteka, ponieważ strona modelu to zwykłe API HTTP. W tym przewodniku używamy python-telegram-bot w wersji 20 lub nowszej, która jest asynchroniczna i dobrze współpracuje z asynchronicznym klientem OpenAI.

Dlaczego mój bot odpowiada sam sobie lub do wszystkich w grupie?

W grupach ogranicz handler do wiadomości, które zawierają wzmiankę o bocie lub są na nie odpowiedzią, oraz ignoruj wiadomości od botów. W przeciwnym razie każda wiadomość w grupie wywoła zapytanie do modelu.

Ile kosztuje rozmowa z botem?

Krótka wymiana 2000 tokenów wejściowych i 500 tokenów wyjściowych kosztuje $0,00055, więc tysiąc takich rozmów kosztuje $0,55. Długie historie kosztują więcej, ponieważ są przesyłane ponownie w każdej turze.

Czy bot może być używany do roleplayu dla dorosłych?

Model jest dostrojony do odpowiadania bez odrzucania treści dla prawnego użytku dorosłych, a boty do czatu fabularnego i towarzyskiego to typowy przypadek. Treści seksualne z udziałem nieletnich są zawsze zabronione, a Telegram ma własne zasady, które musisz przestrzegać.

Twój klucz jest o jeden formularz stąd

Utwórz konto, skopiuj klucz, zmień bazowy URL. To cała konfiguracja.

Pobierz klucz APIPrzeczytaj dokumentację