繁中 ▾
取得 API 金鑰

Uncensored Endpoint Telegram 機器人:使用 Python 建置

要建置無審查的端點 Telegram 機器人,你需要三樣東西:來自 BotFather 的機器人權杖、API 金鑰,以及約 80 行 Python 程式碼,用於將每則 Telegram 訊息傳遞至聊天完成路由。本教學提供完整程式碼,然後加入記憶、串流和限制處理。

更新於

重點摘要

  1. 機器人使用 python-telegram-bot 處理 Telegram,並使用標準 OpenAI SDK 處理模型。
  2. 每個聊天保持短歷史,並進行修剪,使每個請求的體積小且成本低。
  3. 透過每秒編輯一次訊息來串流輸出,而不是每個 token 都編輯。
  4. 使用信號量將並行模型呼叫限制在 8 次,並重試 429 回應。
紙飛機聊天氣泡離開終端機朝向一排對話氣泡,代表 Telegram 機器人

你要建置的內容

該機器人只有一個任務:從 Telegram 聊天接收文字訊息,將其加入該聊天的歷史記錄,將歷史記錄傳送給 uncensored 模型,然後將答案回傳。每個 Telegram 聊天都有各自的記憶,因此與機器人對話的兩人不會看到彼此的上下文。

完成的專案是一個單一檔案,包含以下部分:

  1. API 的用戶端,使用指向 https://api.uncensoredendpoint.com/v1 的 OpenAI SDK。
  2. 聊天歷史記錄的字典,經過修剪以確保不會無限增長。
  3. 透過編輯單一 Telegram 訊息來串流輸出答案的訊息處理器。
  4. 一個信號量,確保你不會超過完整金鑰允許的 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 或容器中執行它,並將兩個金鑰儲存在 unit 檔案的環境變數或金鑰儲存庫中。設定 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,因此修剪歷史記錄能很快節省成本。

當你需要持久化時,請將每個聊天的歷史記錄儲存為 JSON 格式於 SQLite 或 Redis 中,在重新啟動後的第一則訊息時載入,並在每次回覆後寫回。如果機器人對外公開,請加入每用戶每日訊息限制,以免單一熱情的使用者耗盡餘額。API 文件 列出你可以調整的所有參數,金鑰生產環境檢查清單 涵蓋金鑰輪替與監控餘額標頭。

問答

我應該為 Telegram 端使用哪個程式庫?

任何程式庫皆可,因為模型端是純 HTTP API。本指南使用 python-telegram-bot 版本 20 或更新版本,其為非同步且與非同步 OpenAI 用戶端搭配良好。

為什麼我的機器人會回覆自己或群組中的每個人?

在群組中,將處理器限制為提及機器人或回覆機器人的訊息,並忽略來自其他機器人的訊息。否則,群組中的每則訊息都會觸發模型呼叫。

機器人對話的成本是多少?

一次包含 2,000 個輸入 token 和 500 個輸出 token 的短對話成本為 $0.00055,因此一千次這樣的對話成本為 $0.55。長歷史記錄成本較高,因為它們會在每個回合重新發送。

機器人可用於成人角色扮演嗎?

該模型經過調整,可針對合法的成人用途提供無內容審查的回答,而用於小說與伴侶聊天的機器人便是典型應用。涉及未成年人的性內容一律禁止,且 Telegram 有其自身規則,你必須遵守。

只需填寫一份表單即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。

取得 API 金鑰閱讀文件