Uncensored Endpoint Telegram Bot: Xây dựng bằng Python
Để xây dựng bot Telegram Uncensored Endpoint, bạn cần ba thứ: token bot từ BotFather, khóa API và khoảng 80 dòng Python chuyển từng tin nhắn Telegram đến endpoint /chat/completions. Hướng dẫn này cung cấp toàn bộ mã nguồn, sau đó thêm bộ nhớ, truyền phát và xử lý giới hạn.
Điểm chính
- Bot sử dụng python-telegram-bot cho Telegram và SDK OpenAI tiêu chuẩn cho mô hình.
- Giữ một lịch sử ngắn cho mỗi cuộc trò chuyện và cắt bớt sao cho mỗi yêu cầu luôn nhỏ và rẻ.
- Truyền phát bằng cách chỉnh sửa một tin nhắn khoảng một lần mỗi giây, không phải trên mỗi token.
- Giới hạn các cuộc gọi mô hình đồng thời ở mức 8 bằng một semaphore và thử lại các phản hồi 429.

Những gì bạn đang xây dựng
Bot có một nhiệm vụ: nhận một tin nhắn văn bản từ một cuộc trò chuyện Telegram, thêm vào lịch sử của cuộc trò chuyện đó, gửi lịch sử đến mô hình uncensored và đăng lại câu trả lời. Mỗi cuộc trò chuyện Telegram có bộ nhớ riêng, vì vậy hai người nói chuyện với bot không bao giờ thấy ngữ cảnh của nhau.
Dự án hoàn chỉnh là một tệp duy nhất với các phần sau:
- Một client cho API, sử dụng SDK OpenAI trỏ đến
https://api.uncensoredendpoint.com/v1. - Một từ điển chứa lịch sử hội thoại, được cắt bớt để không phát triển vô hạn.
- Một trình xử lý tin nhắn truyền phát câu trả lời bằng cách chỉnh sửa một tin nhắn Telegram.
- Một semaphore giữ số lượng yêu cầu của bạn dưới 8 yêu cầu đồng thời mà khóa đầy đủ cho phép.
Không có gì ở đây cần cơ sở dữ liệu. Khi bot khởi động lại, lịch sử được đặt lại, điều này ổn cho phiên bản đầu tiên. Một phần sau đề cập nơi thêm tính bền vững.
Yêu cầu tiên quyết
Bạn cần Python 3.10 trở lên và hai thông tin xác thực.
- Một token bot Telegram. Mở một cuộc trò chuyện với BotFather trong Telegram, gửi lệnh để tạo bot mới, chọn tên và tên người dùng, rồi sao chép token mà nó trả về. Hãy coi token như một mật khẩu.
- Một khóa API. Đăng ký trên trang khóa bằng Google hoặc bằng email và mật khẩu. Người dùng mới có thể nhận $0,50 tín dụng dùng thử miễn phí chỉ với một cú nhấp chuột, đủ để kiểm tra bot này nhiều lần. Khóa dùng thử cho phép 2 yêu cầu đồng thời và 60 yêu cầu mỗi phút.
Cài đặt hai thư viện và xuất các bí mật dưới dạng biến môi trường để chúng không bao giờ nằm trong mã nguồn của bạn:
pip install "python-telegram-bot>=20" openai
export TELEGRAM_TOKEN="123456:your-bot-token"
export API_KEY="your-api-key"
Nếu sau này bạn chuyển từ dùng thử sang lưu lượng thực, tín dụng đến từ việc nạp tiền bằng tiền mã hóa (USDT trên TRC20 hoặc USDC trên Base) từ $20 đến $500. Trang giá liệt kê các bậc thưởng.
Một bot hoạt động tối thiểu
Bắt đầu với phiên bản nhỏ nhất trả lời các tin nhắn. Nó không có truyền phát và không có cắt bớt, vì vậy bạn có thể xác minh đường ống trước.
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()
Chạy nó, mở bot của bạn trong Telegram và chào hỏi. Cắt đoạn answer[:4000] tồn tại vì Telegram giới hạn một tin nhắn đơn lẻ ở 4096 ký tự. Một câu trả lời dài của mô hình sẽ khiến lệnh gọi gửi thất bại. Sau này bạn có thể chia các câu trả lời dài thành nhiều tin nhắn thay vì cắt chúng.
SDK OpenAI tự động thử lại một số lỗi, bao gồm phản hồi 429, với thời gian chờ ngắn. Đặt max_retries=3 cho bạn một chút dư lượng mà không cần viết vòng lặp thử lại ngay.
Bộ nhớ không tăng mãi
Hoàn tất hội thoại không có trạng thái. Mô hình chỉ biết những gì bạn gửi trong mỗi yêu cầu, vì vậy bot gửi lại lịch sử ở mỗi lượt. Đó là lý do tại sao lịch sử không giới hạn là bẫy chi phí và độ trễ chính. Cửa sổ ngữ cảnh là 100.000 token, điều đó rất nhiều, nhưng bạn trả tiền cho mọi token đầu vào ở mỗi lượt, và hầu hết các bot trò chuyện không cần nhiều như vậy.
Một chính sách đơn giản hoạt động tốt: giữ prompt hệ thống và chỉ giữ N tin nhắn cuối cùng. Hai mươi tin nhắn, mười từ người dùng và mười từ bot, phù hợp với trò chuyện thông thường.
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]
Cắt ở một điểm tùy ý có thể để lại lịch sử bắt đầu bằng một tin nhắn trợ lý. Điều đó vô hại cho mô hình này, nhưng nếu bạn muốn nó gọn gàng, hãy bỏ một tin nhắn nữa khi tin nhắn còn lại đầu tiên không phải từ người dùng.
Đối với các nhân vật hoặc câu chuyện dài nơi mô hình phải nhớ các sự kiện từ đầu, việc cắt bớt sẽ làm mất chúng. Hai giải pháp phổ biến là ghi chú ghim và tóm tắt cuộn. Một ghi chú ghim là một khối ngắn các sự kiện bạn giữ trong prompt hệ thống, chẳng hạn như tên và cảnh hiện tại. Một tóm tắt cuộn yêu cầu mô hình, cứ sau ba mươi tin nhắn hoặc hơn, nén nửa lịch sử cũ hơn thành một đoạn văn, sau đó bạn lưu trữ nó thay thế cho các tin nhắn đó.
Thêm lệnh /reset để xóa history[chat_id]. Mọi người thích có một trang trắng, và nó không tốn gì của bạn.
Truyền phát phản hồi bằng cách chỉnh sửa một tin nhắn
Chờ mười giây cho một câu trả lời dài cảm thấy chậm trong ứng dụng chat. Truyền phát cho phép câu trả lời xuất hiện dần trên màn hình. Telegram không chấp nhận một token tin nhắn một token, nên mẹo là gửi một bản giữ chỗ, sau đó chỉnh sửa nó khi văn bản đến. Chỉnh sửa khoảng một lần mỗi giây tối đa. Telegram áp dụng các giới hạn flood riêng cho bot, và gửi liên tục lệnh chỉnh sửa trên mỗi token sẽ khiến bạn bị giới hạn tốc độ và làm chậm luồng.
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
Hai chi tiết quan trọng. Đầu tiên, luôn thực hiện một lần chỉnh sửa cuối cùng sau vòng lặp, vì các đoạn cuối thường đến giữa các lần chỉnh sửa theo thời gian. Thứ hai, Telegram từ chối một lần chỉnh sửa không thay đổi văn bản, nên bỏ qua lệnh gọi khi không có gì mới. Thư viện ném lỗi cho trường hợp đó, và một try/except xung quanh lệnh chỉnh sửa giữ kết nối streaming sống.
Hãy nhớ rằng một yêu cầu truyền phát giữ vị trí đồng thời của nó cho đến khi luồng kết thúc. Một bot với nhiều cuộc trò chuyện nói chuyện cùng lúc sẽ đạt giới hạn sớm hơn với truyền phát hơn là không có, điều này dẫn đến phần tiếp theo.
Giữ trong giới hạn tốc độ
Một khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút. Một khóa dùng thử cho phép 2 yêu cầu đồng thời và 60 yêu cầu mỗi phút. Một nhóm chat bận có thể dễ dàng vượt quá 2 yêu cầu đồng thời, nên hãy điều chỉnh giới hạn cho phù hợp với khóa bạn đang dùng.
Bảo vệ sạch nhất là một semaphore xung quanh lệnh gọi mô hình. Các yêu cầu vượt quá giới hạn chờ trong hàng bên trong quy trình của bạn thay vì va vào 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)
Nếu bạn vẫn nhận được HTTP 429, hãy đọc mã lỗi. concurrency có nghĩa là quá nhiều lệnh gọi cùng lúc, rate_limited có nghĩa là quá nhiều mỗi phút, và 429 với Retry-After: 5 có nghĩa là quá tải tạm thời; hãy đợi năm giây. SDK retry xử lý hầu hết những trường hợp này. Các yêu cầu thất bại hoặc bị từ chối không được tính phí, vì vậy các lần thử lại không thêm vào hóa đơn.
Một biện pháp bảo vệ khác là điều tốc theo người dùng. Nếu một người duy nhất gửi mười tin nhắn trong mười giây, hãy xử lý tuần tự các yêu cầu của họ bằng một khóa đồng bộ theo cuộc trò chuyện để các câu trả lời đến theo thứ tự và một cuộc trò chuyện không thể sử dụng tất cả tám khe.
Nhân vật, quy tắc và cuộc trò chuyện nhóm
Prompt hệ thống là nơi bot có được tính cách của nó. Viết nó như một bản tóm tắt ngắn: bot là ai, nó nói chuyện như thế nào, câu trả lời nên dài bao nhiêu và bất cứ điều gì nó không được làm. Đối với bot đóng vai hoặc đồng hành cho người trưởng thành, hãy mô tả bối cảnh và giọng điệu trong vài dòng và để người dùng điều khiển từ đó. Các prompt cụ thể thắng những cái dài; mô hình tuân theo một nhân vật năm dòng rõ ràng tốt hơn một trang quy tắc.
Một số quy tắc nằm ngoài prompt. Mô hình trả lời mà không từ chối nội dung cho mục đích người trưởng thành hợp pháp, nhưng nội dung tình dục liên quan đến người chưa thành niên luôn bị cấm, và bạn nên thực thi điều đó ở phía của mình. Nếu bot của bạn mở cho công chúng, hãy nói điều đó trong mô tả của nó, thêm thông báo độ tuổi trong tin nhắn bắt đầu và nhớ rằng Telegram có các điều khoản riêng cho bot mà bạn cũng phải tuân thủ. Các cuộc trò chuyện của người dùng đi đến API và prompt không được sử dụng để đào tạo; hãy cho người dùng biết bot của bạn lưu trữ gì.
Trong nhóm chat, không trả lời mọi tin nhắn. Chỉ phản hồi khi bot được đề cập hoặc khi ai đó trả lời một trong các tin nhắn của bot, và bỏ qua các tin nhắn do bot khác gửi. Trong python-telegram-bot, bạn có thể kiểm tra update.message.entities để tìm đề cập hoặc so sánh update.message.reply_to_message.from_user.id với ID của bot.
Khi có sự cố, hãy ghi lại tiêu đề phản hồi X-Request-Id cho mỗi lệnh gọi; bạn có thể đọc nó qua giao diện phản hồi thô của SDK. Trang hỗ trợ là nơi để hỏi về một yêu cầu cụ thể.
Chạy nó trong thực tế
Polling, như được sử dụng ở trên, là ổn cho một bot nhỏ: quy trình hỏi Telegram về các tin nhắn mới trong một vòng lặp và không cần địa chỉ công khai. Chạy nó dưới systemd hoặc container với khởi động lại tự động và lưu trữ hai bí mật trong môi trường tệp đơn vị hoặc kho bí mật. Thiết lập webhook giảm tải khi không hoạt động, nhưng nó cần HTTPS và một URL công khai, vì vậy hãy bắt đầu với polling.
Ước tính chi phí trước khi mời người dùng. API tính $0,15 cho mỗi 1 triệu token đầu vào và $0,50 cho mỗi 1 triệu token đầu ra. Một lượt điển hình với lịch sử được cắt ngắn gồm 2.000 token đầu vào và 500 token đầu ra tốn 2.000 x $0,15 / 1 triệu = $0,0003 cho đầu vào cộng 500 x $0,50 / 1 triệu = $0,00025 cho đầu ra, tổng cộng $0,00055. Một nghìn lượt tốn $0,55. Nếu một cuộc trò chuyện tăng lên 10.000 token đầu vào mỗi lượt, phần đầu vào đơn thuần đã là $0,0015, nên việc cắt ngắn sẽ tự trả chi phí của nó nhanh chóng.
Khi cần lưu trữ, hãy lưu lịch sử của mỗi cuộc trò chuyện dưới dạng JSON trong SQLite hoặc Redis, tải nó khi tin nhắn đầu tiên sau khi khởi động lại, và ghi lại sau mỗi câu trả lời. Thêm giới hạn tin nhắn hàng ngày cho mỗi người dùng nếu bot là công khai, để một người dùng nhiệt tình không thể làm cạn kiệt số dư. Tài liệu API liệt kê mọi tham số bạn có thể tinh chỉnh, và danh sách kiểm tra khóa sản xuất bao gồm việc xoay khóa và theo dõi tiêu đề số dư.
Hướng dẫn khác
Hỏi đáp
Tôi nên dùng thư viện nào cho phần Telegram?
Bất kỳ thư viện nào cũng được vì phía mô hình là một API HTTP đơn giản. Hướng dẫn này sử dụng python-telegram-bot phiên bản 20 trở lên, hỗ trợ bất đồng bộ và tương thích tốt với client OpenAI bất đồng bộ.
Tại sao bot của tôi trả lời chính nó hoặc với mọi người trong nhóm?
Trong nhóm, hãy hạn chế trình xử lý chỉ với các tin nhắn đề cập đến bot hoặc trả lời bot, và bỏ qua tin nhắn từ các bot khác. Nếu không, mọi tin nhắn trong nhóm đều kích hoạt một yêu cầu mô hình.
Một cuộc hội thoại với bot tốn bao nhiêu?
Một cuộc trao đổi ngắn với 2.000 token đầu vào và 500 token đầu ra tốn $0,00055, nghĩa là một nghìn lượt như vậy tốn $0,55. Lịch sử dài tốn nhiều hơn vì chúng được gửi lại ở mỗi lượt.
Bot có thể dùng cho đóng vai người lớn không?
Mô hình được tinh chỉnh để trả lời mà không từ chối nội dung cho mục đích người lớn hợp pháp, và bot cho trò chuyện tiểu thuyết hoặc bạn đồng hành là trường hợp điển hình. Nội dung tình dục liên quan đến người chưa thành niên luôn bị cấm, và Telegram có các quy tắc riêng mà bạn phải tuân thủ.
Khóa của bạn chỉ cách một biểu mẫu
Tạo tài khoản, sao chép khóa, thay đổi URL cơ sở. Đó là toàn bộ thiết lập.