Uncensored Endpoint Telegramボット:Pythonで構築
無検閲のTelegramボットエンドポイントを作成するには、BotFatherからのボットトークン、APIキー、そして各Telegramメッセージをチャット補完エンドポイントに渡す約80行のPythonコードの3つが必要です。このガイドでは完全なコードを示し、その後メモリ、ストリーミング、制限処理を追加します。
主要ポイント
- ボットはTelegramにpython-telegram-botを、モデルに標準のOpenAI SDKを使用します。
- チャットごとに短い履歴を保持し、すべてのリクエストを小さく安価に保つようにトリミングします。
- トークンごとにではなく、1秒に1回程度メッセージを編集してストリーミングします。
- セマフォで同時モデル呼び出しを8に制限し、429応答を再試行します。

あなたが構築しているもの
ボットの役割は1つだけです:Telegramチャットからのテキストメッセージを受け取り、そのチャットの履歴に追加し、履歴をモデルuncensoredに送信し、回答を返信します。各Telegramチャットには独自のメモリがあるため、2人のユーザーがボットと会話しても互いの文脈を見ることはありません。
完成したプロジェクトは以下の部分を持つ単一ファイルです:
- API用のクライアント。OpenAI SDKを使用し、
https://api.uncensoredendpoint.com/v1を指すように設定します。 - チャット履歴の辞書。無限に大きくなりすぎないよう、必要に応じて切り捨てられます。
- Telegramメッセージを1つ編集して回答をストリーミングするメッセージハンドラ。
- フルキーが許可する8件の並行リクエストを下回るようにするセマフォ。
ここにはデータベースは必要ありません。ボット再起動時に履歴はリセットされますが、これは最初のバージョンでは問題ありません。後のセクションで永続性を追加する場所をカバーします。
前提条件
Python 3.10以降と2つの認証情報が必要です。
- Telegramボットトークン。 Telegram内でBotFatherとチャットを開き、新しいボットを作成するためのコマンドを送信し、名前とユーザー名を選択し、返されるトークンをコピーします。トークンはパスワードのように扱ってください。
- APIキー。 Googleまたはメールアドレスとパスワードでキーページにサインアップしてください。新規ユーザーはワンクリックで$0.50の試用クレジットを請求でき、このボットを何度もテストするのに十分な額です。試用キーでは並行リクエスト2件、1分あたり60件のリクエストが許可されます。
2つのライブラリをインストールし、環境変数としてシークレットをエクスポートして、ソースコードに保存されないようにします:
pip install "python-telegram-bot>=20" openai
export TELEGRAM_TOKEN="123456:your-bot-token"
export API_KEY="your-api-key"
後でトライアルから実際のトラフィックに移行する場合、クレジットは暗号資産(TRC20上のUSDTまたはBase上のUSDC)のチャージ($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でボットにこんにちはと送ってください。Telegramは1メッセージあたり4096文字が上限なので、answer[:4000]が必要です。それがないと、長いモデルの応答により送信呼び出しが失敗する可能性があります。後で切り捨てる代わりに、長い応答を複数のメッセージに分けられます。
OpenAI SDKは、429応答を含む一部の失敗を短いバックオフで自動的に再試行します。max_retries=3を設定すると、再試行ループを書かずに少しの余裕が得られます。
無限に増えないメモリ
チャット補完はステートレスです。モデルは各リクエストで送信された内容しか認識しないため、ボットは履歴を毎回再送信します。これが、履歴が無限に大きくなることが主なコストとレイテンシの罠となる理由です。コンテキストウィンドウは100,000トークンですが、これは非常に大きな数値です。ただし、あなたは毎ターンに入力トークンに対して課金され、ほとんどのチャットボットはそれほどの容量を必要としません。
単純なポリシーが効果的です:システムプロンプトを保持し、最後のNメッセージのみを保持します。20メッセージ(ユーザーとボットからそれぞれ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]
任意の地点で切り捨てると、アシスタントのメッセージから始まる履歴が残る場合があります。このモデルでは害はありませんが、整理したい場合は、最初の残存メッセージがユーザー由来でない場合に、さらに1つのメッセージを削除します。
キャラクターや長い物語など、モデルが初期の事実を覚える必要がある場合、トリミングするとそれらが失われます。一般的な解決策として、固定ノートとローリングサマリーがあります。固定ノートは、名前や現在のシーンなどの事実の短いブロックで、システムプロンプトに保持します。ローリングサマリーは、約30メッセージごとにモデルに履歴の古い半分を要約させ、その結果をメッセージの代わりに保存します。
/resetコマンドを追加してhistory[chat_id]をクリアします。ユーザーはリセットを好みますし、コストもかかりません。
1つのメッセージを編集して応答をストリーミング
チャットアプリで長い回答を10秒待つのは遅く感じられます。ストリーミングにより、返信が画面に表示されていきます。Telegramはメッセージをトークン単位で受け取ることはできないため、手法としては、プレースホルダーを送信し、テキストが届くたびにそれを編集します。編集は最大で1秒に1回程度にしてください。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
2つの詳細が重要です。まず、ループの最後に必ず最終編集を行ってください。最後のチャンクは通常、時間ベースの編集の間に到着するためです。第二に、Telegramはテキストが変更されていない編集を拒否するため、新しいテキストがない場合は呼び出しをスキップします。ライブラリはその場合にエラーを発生させるため、編集をtry/exceptで囲むことでストリーミングを維持できます。
ストリーミングリクエストはストリーミングが終了するまで同時実行数の枠を占有することに注意してください。複数のチャットで同時に会話するボットは、ストリーミングなしの場合よりも早く制限に達します。これが次のセクションにつながります。
レート制限内に収まるようにする
フルキーは8つの同時リクエストと1分あたり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は1分あたりの呼び出し過多、Retry-After: 5付きの429は一時的な過負荷を意味し、5秒待ちます。SDKのリトライはこれらの大部分を処理します。失敗または拒否されたリクエストは課金されないので、リトライで請求額が増えることはありません。
もう1つのガードとして、ユーザーごとのペース調整があります。1人のユーザーが10秒間に10メッセージを送信する場合、チャットごとにロックを使用してリクエストを直列化し、応答が順序通り届き、1つのチャットが8つの枠をすべて占有しないようにします。
ペルソナ、ルール、グループチャット
システムプロンプトはボットのキャラクターを設定する場所です。短い指示書のように記述してください:ボットは誰か、どのように話すか、回答の長さはどのくらいか、そして何をしてはいけないか。成人向けのロールプレイやコンパニオンボットの場合、設定とトーンを数行で記述し、そこからユーザーが操作できるようにします。具体的なプロンプトが長いものより優れています。モデルは、ルールが1ページ分あるよりも、明確な5行のペルソナの方がよく従います。
プロンプトの外にあるルールもあります。モデルは法的な成人利用に対してコンテンツ拒否なしで応答しますが、未成年者を含む性的コンテンツは常に禁止されており、あなた側でもそれを強制する必要があります。ボットが一般公開されている場合は、説明にそれを明記し、開始メッセージに年齢通知を追加し、Telegramにはボット独自の規約があることを覚えておいてください。ユーザーの会話はAPIに送信され、プロンプトはトレーニングに使用されません。あなたのボットが何を保存するかをユーザーに伝えてください。
グループチャットでは、すべてのメッセージに返信しないでください。ボットがメンションされた場合、または誰かがボットのメッセージに返信した場合のみ返信し、他のボットからのメッセージは無視してください。python-telegram-botでは、メンションがあるかどうかをupdate.message.entitiesで確認し、update.message.reply_to_message.from_user.idがボット自身のIDと一致するかどうかを比較できます。
何らかのエラーが発生した場合は、各呼び出しに対してX-Request-Idレスポンスヘッダーをログに記録してください。これはSDKの生レスポンスインターフェースを通じて読み取ることができます。特定のリクエストに関する問い合わせは、サポートページで行ってください。
本番環境での実行
上記で使用されているポーリングは、小規模なボットには問題ありません。プロセスはループ内でTelegramから新しいメッセージをフェッチし、公開アドレスを必要としません。systemdや自動再起動機能付きのコンテナで実行し、2つのシークレットをユニットファイルの環境変数またはシークレットストアに保管してください。Webhookの設定はアイドル時の負荷を軽減しますが、HTTPSと公開URLが必要となるため、まずはポーリングから始めてください。
ユーザーを招待する前にコストを見積もってください。APIは1M入力トークンあたり$0.15、1M出力トークンあたり$0.50を請求します。トリミングされた履歴を含む典型的なターン(2,000入力トークン、500出力トークン)のコストは、入力で2,000 x $0.15 / 1M = $0.0003、出力で500 x $0.50 / 1M = $0.00025、合計$0.00055です。1,000回のターンで$0.55かかります。チャットが1ターンあたり10,000入力トークンに成長した場合、入力部分だけでも$0.0015になるため、トリミングはすぐに元を取ります。
永続性が必要な場合は、各チャットの履歴をSQLiteやRedisにJSON形式で保存し、再起動後の最初のメッセージでそれを読み込み、各返信後に書き戻してください。公開ボットの場合、ユーザーごとの1日あたりのメッセージ制限を追加し、熱心なユーザー1人によって残高が枯渇しないようにしてください。APIドキュメントには調整可能な全パラメータが記載されており、キー本番環境チェックリストにはキーのローテーションと残高ヘッダーの監視がカバーされています。
その他のガイド
質問と回答
Telegram側にはどのライブラリを使用すべきですか?
モデル側が単純なHTTP APIであるため、どのライブラリでも動作します。このガイドでは、非同期であり、非同期のOpenAIクライアントと相性の良いpython-telegram-botバージョン20以降を使用しています。
なぜボットは自分自身やグループ内の全員に返信してしまうのですか?
グループでは、ハンドラをボットへのメンションがあるメッセージ、またはボットへの返信があるメッセージに制限し、ボットからのメッセージは無視してください。そうしないと、グループ内のすべてのメッセージがモデル呼び出しをトリガーします。
ボットの会話にはいくらかかりますか?
2,000トークンの入力と500トークンの出力の短いやり取りは$0.00055で、それら1,000組は$0.55かかります。長い履歴は各ターンで再送信されるため、コストが高くなります。
ボットは成人向けロールプレイに使用できますか?
モデルは、法的な成人向け利用に対してコンテンツ拒否なしで回答するように調整されており、フィクションやコンパニオンチャットのボットは典型的なケースです。未成年者を含む性的コンテンツは常に禁止されており、Telegramには従うべき独自のルールがあります。
キーはフォーム 1 つで手に入ります
アカウントを作成し、キーをコピーし、ベースURLを変更します。これでセットアップは完了です。