Uncensored Endpoint 텔레그램 봇: Python으로 만들기
무검열 엔드포인트 Telegram 봇을 구축하려면 BotFather에서 받은 봇 토큰, API 키, 그리고 각 Telegram 메시지를 채팅 완성 엔드포인트로 전달하는 약 80줄의 Python 코드가 필요합니다. 이 안내서는 전체 코드를 제공한 후 메모리, 스트리밍 및 제한 처리를 추가합니다.
주요 포인트
- 봇은 텔레그램에 python-telegram-bot을 사용하고 모델에는 표준 OpenAI SDK를 사용합니다.
- 채팅당 짧은 기록을 유지하고 다듬어 모든 요청이 작고 저렴하게 유지되도록 하세요.
- 매 토큰마다가 아닌 약 1초마다 하나의 메시지를 편집하여 스트리밍하세요.
- 세마포어를 사용하여 동시 모델 호출을 8개로 제한하고 429 응답을 재시도하세요.

구축할 내용
봇의 유일한 역할은 Telegram 채팅에서 텍스트 메시지를 가져와 해당 채팅의 기록에 추가하고, 기록을 uncensored 모델에 보내고, 답변을 다시 전송하는 것입니다. 각 Telegram 채팅은 자체 메모리를 가지므로, 봇과 대화하는 두 사람이 서로의 컨텍스트를 볼 수 없습니다.
완성된 프로젝트는 다음 부분으로 구성된 단일 파일입니다:
https://api.uncensoredendpoint.com/v1을 가리키는 OpenAI SDK를 사용한 API용 클라이언트입니다.- 무한정 성장하지 않도록 잘라낸 채팅 기록 사전입니다.
- 하나의 텔레그램 메시지를 편집하여 답변을 스트리밍하는 메시지 핸들러입니다.
- 전체 키가 허용하는 8개의 동시 요청을 초과하지 않도록 유지하는 세마포어입니다.
여기에는 데이터베이스가 필요하지 않습니다. 봇이 다시 시작하면 기록이 초기화되는데, 이는 첫 번째 버전에는 적합합니다. 나중에 데이터 지속성을 추가할 위치에 대한 섹션이 다뤄집니다.
사전 준비 사항
Python 3.10 이상이 필요하며 두 가지 인증 정보가 필요합니다.
- Telegram 봇 토큰입니다. Telegram 내에서 BotFather와 채팅을 열고 새 봇 생성 명령을 보내며, 이름과 사용자 이름을 선택한 후 반환된 토큰을 복사합니다. 토큰을 비밀번호처럼 취급하세요.
- API 키입니다. Google 또는 이메일과 비밀번호로 키 페이지에 가입하세요. 신규 사용자는 한 번의 클릭으로 $0.50의 체험 크레딧을 청구할 수 있으며, 이는 이 봇을 여러 번 테스트하기에 충분합니다. 체험 키는 동시 요청 2개와 분당 60개의 요청을 허용합니다.
두 라이브러리를 설치하고 비밀 값을 환경 변수로 내보내어 소스 코드에 남지 않도록 하세요:
pip install "python-telegram-bot>=20" openai
export TELEGRAM_TOKEN="123456:your-bot-token"
export API_KEY="your-api-key"
나중에 체험에서 실제 트래픽으로 전환하면 크레딧은 USDT(TRC20) 또는 USDC(Base)를 사용한 $20에서 $500 사이의 충전에서 나옵니다. 가격 책정 페이지에는 보너스 등급이 나열되어 있습니다.
최소 작동 봇
메시지에 응답하는 가장 작은 버전으로 시작하세요. 아직 스트리밍이나 다듬기가 없으므로 기본 설정을 먼저 확인할 수 있습니다.
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()
실행하고 Telegram에서 봇을 연 다음 인사를 건네세요. answer[:4000] 슬라이스는 Telegram이 단일 메시지를 4096자로 제한하기 때문에 존재합니다. 긴 모델 답변은 그렇지 않으면 보내기 호출을 실패하게 만듭니다. 나중에 잘라내지 않고 긴 답변을 여러 메시지로 나누어 보낼 수 있습니다.
OpenAI SDK는 429 응답을 포함한 일부 실패를 짧은 백오프와 함께 자체적으로 재시도합니다. max_retries=3을 설정하면 재시도 반복문을 작성하지 않아도 약간의 여유를 제공합니다.
무한정 성장하지 않는 메모리
채팅 완성 API는 상태가 없습니다. 모델은 각 요청에서 보낸 내용만 알기 때문에 봇은 매 턴마다 기록을 다시 보냅니다. 이것이 무제한 기록이 주요 비용 및 지연 시간 함정인 이유입니다. 컨텍스트 창은 100,000 토큰으로 많지만, 매 턴마다 모든 입력 토큰에 대해 지불하며 대부분의 채팅 봇은 그 정도가 필요하지 않습니다.
간단한 정책이 잘 작동합니다: 시스템 프롬프트를 유지하고 마지막 N개의 메시지만 유지하세요. 20개의 메시지(사용자 10개, 봇 10개)는 캐주얼 채팅에 적합합니다.
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]
임의 지점에서 잘면 어시스턴트 메시지로 시작하는 기록이 남을 수 있습니다. 이 모델에는 해롭지 않지만 깔끔하게 하려면 첫 번째로 남은 메시지가 사용자에서 온 것이 아닌 경우 하나 더 삭제하세요.
캐릭터나 긴 이야기처럼 모델이 초기의 사실을 기억해야 하는 경우 잘리면 손실됩니다. 일반적인 해결책 두 가지는 고정 메모와 순환 요약입니다. 고정 메모는 이름과 현재 장면과 같은 사실의 짧은 블록으로 시스템 프롬프트에 유지합니다. 순환 요약은 약 30번의 메시지가 있을 때마다 모델에게 기록의 이전 절반을 단락으로 압축하도록 요청하고, 해당 메시지를 대체하여 저장합니다.
/reset 명령어를 추가하여 history[chat_id]를 지우세요. 사람들은 깨끗한 상태의 시작을 좋아하며, 이는 비용이 들지 않습니다.
하나의 메시지 편집으로 응답 스트리밍
긴 답변을 기다리는 10초는 채팅 앱에서 느리게 느껴집니다. 스트리밍은 화면에 응답이 나타나도록 합니다. Telegram은 토큰별로 메시지를 허용하지 않으므로, 트릭은 플레이스홀더를 보내고 텍스트가 도착할 때 편집하는 것입니다. 최대 초당 한 번 편집하세요. Telegram은 봇에 자체적인 플러드 제한을 적용하며, 모든 토큰에 대해 편집 호출을 남발하면 스로틀링되어 스트리밍이 느려집니다.
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
두 가지 세부 사항이 중요합니다. 첫째, 루프 후 항상 마지막 편집을 수행하세요. 마지막 청크는 일반적으로 시간 기반 편집 사이에 도착합니다. 둘째, 텔레그램은 텍스트가 변경되지 않은 편집을 거부하므로 새 내용이 없을 때 호출을 건너뛰세요. 라이브러리는 해당 경우에 오류를 발생시키며 편집 주변의 try/except는 스트림을 유지합니다.
스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 유지한다는 점을 기억하세요. 동시에 많은 채팅에서 대화하는 봇은 스트리밍 시 스트리밍 없이보다 제한에 더 빨리 도달하므로, 이는 다음 섹션으로 이어집니다.
속도 제한 내 유지
전체 키는 8개의 동시 요청과 분당 300개의 요청을 허용합니다. 체험 키는 2개와 분당 60개를 허용합니다. 바쁜 그룹 채팅은 동시에 2개를 쉽게 초과할 수 있으므로, 사용하는 키에 맞게 제한 크기를 조정하세요.
가장 깔끔한 보호 장치는 모델 호출 주변의 세마포어입니다. 캡을 초과하는 요청은 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)
여전히 HTTP 429를 받으면 오류 코드를 읽으세요. concurrency은 동시에 너무 많은 호출을 의미하고, rate_limited은 분당 너무 많은 호출을 의미하며, Retry-After: 5가 있는 429는 일시적인 과부하를 의미합니다. 5초를 기다리세요. SDK 재시도는 이러한 경우 대부분 처리합니다. 실패하거나 거부된 요청은 요금이 부과되지 않으므로 재시도가 청구서에 추가되지 않습니다.
또 다른 보호 장치는 사용자별 페이싱입니다. 한 사람이 10초 동안 10개의 메시지를 보내면 채팅당 잠금을 사용하여 요청을 직렬화하여 답변이 순서대로 도착하고 하나의 채팅이 8개의 슬롯 모두를 사용하지 않도록 하세요.
페르소나, 규칙 및 그룹 채팅
시스템 프롬프트는 봇이 캐릭터를 얻는 곳입니다. 봇이 누구인지, 어떻게 말하는지, 답변 길이는 어느 정도인지, 그리고 무엇을 하지 말아야 하는지 등 짧은 브리프처럼 작성하세요. 성인을 위한 역할극 또는 동반자 봇의 경우 몇 줄로 설정과 어조를 설명하고 사용자가 그 이후로 주도하게 하세요. 구체적인 프롬프트가 긴 프롬프트보다 낫습니다. 모델은 규칙 페이지보다 명확한 5줄짜리 페르소나를 더 잘 따릅니다.
일부 규칙은 프롬프트 외부에 있습니다. 모델은 합법적인 성인 사용에 대해 콘텐츠 거부 없이 답변하지만 미성년자가 관련된 성적인 콘텐츠는 절대 허용되지 않으며 귀하도 이를 강제해야 합니다. 봇이 공개된 경우라면 설명에 명시하고 시작 메시지에 연령 고지를 추가하며 텔레그램에는 봇에 대한 자체 약관이 있음을 기억하세요. 사용자의 대화는 API로 전송되며 프롬프트는 학습에 사용되지 않습니다. 귀하의 봇이 무엇을 저장하는지 사용자에게 알리세요.
그룹 채팅에서는 모든 메시지에 답변하지 마세요. 봇이 언급되었거나 누군가가 봇의 메시지 중 하나에 답할 때만 응답하고, 다른 봇이 보낸 메시지는 무시하세요. python-telegram-bot에서는 update.message.entities을 확인하여 언급을 확인하거나 update.message.reply_to_message.from_user.id을 봇의 자체 ID와 비교할 수 있습니다.
문제가 발생하면 각 호출에 대한 X-Request-Id 응답 헤드를 로그에 기록하세요. SDK의 원시 응답 인터페이스를 통해 읽을 수 있습니다. 지원 페이지는 특정 요청에 대해 문의할 장소입니다.
실제 실행
위에서 사용한 폴링은 작은 봇에는 적합합니다: 프로세스는 루프에서 Telegram에 새 메시지를 요청하며 공개 주소가 필요하지 않습니다. systemd 또는 컨테이너에서 자동 재시작으로 실행하고 두 가지 비밀을 단위 파일의 환경 또는 비밀 저장소에 보관하세요. 웹훅 설정은 유휴 부하를 줄이지만 HTTPS와 공개 URL이 필요하므로 폴링으로 시작하세요.
사람들을 초대하기 전에 비용을 추정하세요. API는 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50을 청구합니다. 입력 토큰 2,000개와 출력 토큰 500개로 다듬은 기록이 있는 일반적인 턴의 비용은 입력의 경우 2,000 x $0.15 / 1M = $0.0003, 출력의 경우 500 x $0.50 / 1M = $0.00025로 합계 $0.00055입니다. 천 번의 턴은 $0.55가 듭니다. 채팅이 턴당 입력 토큰 10,000개로 성장하면 입력 부분만 $0.0015가 되므로, 다듬기가 비용을 상쇄하는 데 빠르게 기여합니다.
지속성이 필요할 때 각 채팅의 기록을 SQLite 또는 Redis에 JSON으로 저장하고, 재시작 후 첫 번째 메시지에서 로드한 후 각 응답 후에 다시 저장하세요. 봇이 공개된 경우 사용자별 일일 메시지 제한을 추가하여 한 명의 열성적인 사용자가 잔액을 고갈시키지 않도록 하세요. API 문서에는 조정할 수 있는 모든 매개변수가 나열되어 있으며, 키 프로덕션 체크리스트에는 키 회전 및 잔액 헤더 모니터링이 포함되어 있습니다.
더 많은 가이드
질문과 답변
Telegram 측에 어떤 라이브러리를 사용해야 하나요?
모델 측이 일반 HTTP API이므로 어떤 라이브러리든 작동합니다. 이 가이드는 python-telegram-bot 버전 20 이상을 사용하며, 이는 비동기식이며 비동기 OpenAI 클라이언트와 잘 맞습니다.
왜 제 봇이 자신이나 그룹의 모든 사람에게 답하나요?
그룹에서는 봇을 언급하거나 봇에 답하는 메시지만 처리하도록 핸들러를 제한하고 봇의 메시지는 무시하세요. 그렇지 않으면 그룹의 모든 메시지가 모델 호출을 트리거합니다.
봇 대화의 비용은 얼마인가요?
입력 토큰 2,000개와 출력 토큰 500개로 구성된 짧은 대화 1회당 비용은 $0.00055이며, 이러한 대화 1,000회의 비용은 $0.55입니다. 긴 대화 기록은 매 턴마다 재전송되므로 비용이 더 많이 듭니다.
봇을 성인 역할극에 사용할 수 있나요?
이 모델은 합법적인 성인 사용에 대해 콘텐츠 거부 없이 답변하도록 조정되었으며, 소설 및 동반자 채팅용 봇이 일반적인 사례입니다. 미성년자가 포함된 성적인 콘텐츠는 절대 허용되지 않으며, Telegram에는 반드시 따라야 할 자체 규칙이 있습니다.
키를 받기까지 양식 하나만 채우면 됩니다
계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.