Uncensored Endpoint Telegram 机器人:使用 Python 构建
要构建无审查接口 Telegram 机器人,你需要三样东西:来自 BotFather 的机器人令牌、API 密钥,以及约 80 行 Python 代码,用于将每条 Telegram 消息传递给聊天补全路由。本教程提供完整代码,然后添加记忆、流式输出和限制处理功能。
要点
- 机器人使用 python-telegram-bot 处理 Telegram 通信,使用标准 OpenAI SDK 调用模型。
- 为每个会话保留简短历史记录,并进行修剪,以确保每次请求都保持简短且成本低廉。
- 通过每秒编辑一次消息来实现流式输出,而不是在每个 token 处编辑。
- 使用信号量将并行模型调用限制为 8 次,并重试 429 响应。

你正在构建的内容
机器人的唯一任务是:获取 Telegram 聊天中的文本消息,将其添加到该聊天的历史记录中,将历史记录发送给模型 uncensored,然后将答案发布回去。每个 Telegram 聊天都有自己独立的记忆,因此两个与机器人交谈的人永远不会看到彼此的上下文。
完成的项目是一个包含以下部分的单文件:
- API 客户端,使用指向
https://api.uncensoredendpoint.com/v1的 OpenAI SDK。 - 聊天历史记录字典,经过修剪,使其不会无限增长。
- 通过编辑一条 Telegram 消息来流式输出答案的消息处理器。
- 信号量,确保你不超过完整密钥允许的 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"
如果你稍后从试用版转向真实流量,预付额度来自 $20 到 $500 的充值,可通过加密货币(TRC20 上的 USDT 或 Base 上的 USDC)完成。定价页面 列出了奖励层级。
最小可用机器人
从最小的能回复消息的版本开始。它还没有流式输出和修剪功能,因此你可以先确认基本功能。
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 可以在不编写重试循环的情况下提供一些余量。
不会无限增长的内存
聊天补全是无状态的。模型只知道你在每次请求中发送的内容,因此机器人会在每次交互时重新发送历史记录。这就是无界历史记录成为主要成本和延迟陷阱的原因。上下文窗口为 100,000 个 token,这很多,但你在每次交互中都要为每个输入 token 付费,而大多数聊天机器人不需要那么多。
一个简单的策略效果很好:保留系统提示词,并只保留最后 N 条消息。二十条消息(用户十条,机器人十条)适合休闲聊天。
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]
在任意点截断可能会留下以助手消息开头的历史记录。这对该模型来说是无害的,但如果你希望它整洁,当第一条剩余消息不是来自用户时,再删除一条消息。
对于角色或长故事,模型需要记住早期的事实,修剪会丢失它们。两种常见的修复方法是固定笔记和滚动摘要。固定笔记是你保留在系统提示词中的一小段事实,例如姓名和当前场景。滚动摘要要求模型每三十条消息左右将历史记录的较旧部分压缩成一段话,然后你将这段话存储在这些消息的位置。
添加一个 /reset 命令来清除 history[chat_id]。人们喜欢从头开始,这对你来说没有任何成本。
通过编辑一条消息实现回复流式输出
等待十秒钟获取长答案在聊天应用中感觉很慢。流式输出让回复在屏幕上逐步显示。Telegram 不接受逐 token 发送消息,因此技巧是发送一个占位符,然后在文本到达时编辑它。最多每秒编辑一次。Telegram 对机器人应用自己的速率限制,如果在每个 token 处都调用编辑,你会被限速并减慢流式输出。
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
两个细节很重要。首先,循环结束后始终进行最终编辑,因为最后的块通常在定时编辑之间到达。其次,Telegram 拒绝不更改文本的编辑,因此当没有新内容时跳过调用。库会为此情况抛出错误,围绕编辑的 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 表示临时过载;等待五秒钟。SDK 重试处理了大部分这些情况。失败或拒绝的请求不收费,因此重试不会增加账单。
另一个防护是每用户限流。如果一个人十秒钟内发送十条消息,使用每个聊天的锁来序列化他们的请求,使答案按顺序到达,并且一个聊天不能使用所有八个槽位。
人设、规则和群组聊天
系统提示词是机器人获得其性格的地方。像简短的简介一样编写它:机器人是谁,它如何说话,答案应该多长,以及它不能做什么。对于面向成人的角色扮演或伴侣机器人,用几行描述设置和语气,让用户从那里引导。具体的提示词优于长提示词;模型遵循清晰的五行人设优于遵循一页规则。
一些规则位于提示词之外。该模型可在合法成人用途下无审查地回答,但涉及未成年人的性内容始终不允许,你也应该在客户端强制执行这一点。如果你的机器人面向公众,请在其描述中说明,在开始消息中添加年龄通知,并记住 Telegram 有自己的机器人条款,你也必须遵守。你的用户的对话会发送到 API,且提示词不用于训练;告诉你的用户你的机器人存储了什么。
在群组聊天中,不要回复每条消息。仅在提及机器人或有人回复其消息时回复,并忽略其他机器人发送的消息。在 python-telegram-bot 中,你可以检查 update.message.entities 是否有提及,或将 update.message.reply_to_message.from_user.id 与机器人自己的 ID 进行比较。
当出现问题时,记录每次调用的 X-Request-Id 响应头;你可以通过 SDK 的原始响应接口读取它。支持页面 是询问特定请求的地方。
实际运行
轮询,如上所述,适用于小型机器人:进程在循环中询问 Telegram 新消息,不需要公共地址。在 systemd 或容器中运行它并配置自动重启,并将两个密钥保存在单元文件的环境或密钥存储中。Webhook 设置可降低空闲负载,但需要 HTTPS 和公共 URL,因此从轮询开始。
在邀请人们之前估算成本。API 每 1M 输入 token 收费 $0.15,每 1M 输出 token 收费 $0.50。带有修剪历史记录的典型交互,2,000 个输入 token 和 500 个输出 token 的成本为 2,000 x $0.15 / 1M = $0.0003 输入加上 500 x $0.50 / 1M = $0.00025 输出,总计 $0.00055。一千次交互的成本为 $0.55。如果聊天每次交互增长到 10,000 个输入 token,仅输入部分就变为 $0.0015,因此修剪很快就能收回成本。
当你需要持久化时,将每个聊天的历史记录存储为 SQLite 或 Redis 中的 JSON,在重启后的第一条消息时加载它,并在每次回复后写回它。如果机器人是公开的,添加每用户每日消息限制,以便一个热情的用户不会耗尽余额。API 文档 列出了你可以调整的所有参数,生产环境检查清单 涵盖了轮换密钥和监控余额响应头。
更多指南
问答
Telegram 端应该使用哪个库?
任何库都可以,因为模型端是纯 HTTP API。本指南使用 python-telegram-bot 20 或更高版本,它是异步的,与异步 OpenAI 客户端配合良好。
为什么我的机器人会回复自己或群组中的所有人?
在群组中,将处理器限制为仅处理提及机器人或回复机器人的消息,并忽略来自机器人的消息。否则,群组中的每条消息都会触发模型调用。
机器人对话的成本是多少?
2,000 个输入 token 和 500 个输出 token 的简短交互成本为 $0.00055,因此一千次交互的成本为 $0.55。较长的历史记录成本更高,因为它们在每轮对话中都会被重新发送。
机器人可以用于成人角色扮演吗?
该模型经过调整,可在合法成人用途下不进行内容拒绝地回答,而用于小说和陪伴聊天的机器人是典型用例。涉及未成年人的性内容始终不允许,且 Telegram 有自己的规则,你必须遵守。
你的密钥只需填写一个表单即可获取
创建账户,复制密钥,更改基础 URL。这就是全部设置。