AR ▾
احصل على مفتاح API

روبوت Uncensored Endpoint على تيليجرام: ابنِه باستخدام Python

لبناء نقطة نهاية uncensored لبوت تيليجرام، تحتاج إلى ثلاثة أجزاء: رمز بوت من BotFather، ومفتاح API، وحوالي 80 سطرًا من Python تمرر كل رسالة تيليجرام إلى مسار إكمال الدردشة. يوفر هذا الشرح الكود الكامل، ثم يضيف الذاكرة، والبث، ومعالجة الحدود.

تم التحديث

نقاط رئيسية

  1. يستخدم البوت مكتبة python-telegram-bot لتيليجرام وحزمة تطوير البرمجيات (SDK) القياسية الخاصة بـ OpenAI للنموذج.
  2. احتفظ بسجل قصير لكل دردشة وقصّه بحيث تبقى كل الطلبات صغيرة ورخيصة.
  3. البث المتدفق عن طريق تحرير رسالة واحدة مرة واحدة في الثانية، وليس على كل رمز.
  4. حدّ الطلبات المتزامنة للنموذج عند 8 باستخدام semaphor وأعد محاولة استجابات 429.
فقاعة دردشة ورقة طائرة تخرج من الطرفية نحو صف من فقاعات الكلام، تمثل روبوت تيليجرام

ما تبنيه

يتمثل دور البوت في مهمة واحدة: أخذ رسالة نصية من دردشة على Telegram، وإضافتها إلى سجل تلك الدردشة، وإرسال السجل إلى النموذج uncensored، ثم نشر الإجابة مرة أخرى. تحصل كل دردشة على Telegram على ذاكرة خاصة بها، لذا لا يرى شخصان يتحدثان إلى البوت سياق بعضهما البعض.

يتألف المشروع النهائي من ملف واحد يحتوي على الأجزاء التالية:

  1. عميل لواجهة برمجة التطبيقات، باستخدام حزمة تطوير البرمجيات (SDK) الخاصة بـ OpenAI والموجه نحو https://api.uncensoredendpoint.com/v1.
  2. قاموس لسجلات الدردشة، يتم تقصيره بحيث لا ينمو بلا حدود.
  3. معالج رسائل يقوم ببث الإجابة عن طريق تعديل رسالة واحدة على Telegram.
  4. أداة تحكم (semaphore) تضمن بقاءك دون حد 8 طلبات متزامنة التي يسمح بها المفتاح الكامل.

لا يحتاج أي شيء هنا إلى قاعدة بيانات. عند إعادة تشغيل الروبوت، تُعاد تعيين السجلات، وهو أمر مناسب للإصدار الأول. يغطي قسم لاحق أين تضيف الاستمرارية.

المتطلبات المسبقة

تحتاج إلى Python 3.10 أو أحدث وبيانات اعتماد اثنين.

  • رمز بوت Telegram. افتح دردشة مع BotFather داخل Telegram، وأرسل الأمر لإنشاء بوت جديد، واختر اسماً واسم مستخدم، وانسخ الرمز الذي يعيده. عامل الرمز مثل كلمة المرور.
  • مفتاح 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 بالعملات المشفرة فقط، إما USDT على TRC20 أو USDC على Base. صفحة التسعير تدرج مستويات المكافآت.

بوت عملي بسيط

ابدأ بأصغر نسخة تجيب على الرسائل. لا تحتوي على بث أو تقصير بعد، لذا يمكنك تأكيد التوصيلات الأساسية أولاً.

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 حرفاً. قد يؤدي الإجابة الطويلة من النموذج إلى فشل استدعاء الإرسال. يمكنك لاحقاً تقسيم الإجابات الطويلة إلى رسائل متعددة بدلاً من قطعها.

تعيد حزمة تطوير البرمجيات (SDK) الخاصة بـ OpenAI محاولة بعض الفشل تلقائيًا، بما في ذلك استجابات 429، مع تأخير زمني قصير. يمكنك إعداد max_retries=3 للحصول على هامش صغير من المرونة دون الحاجة لكتابة حلقة إعادة محاولة بعد.

ذاكرة لا تنمو إلى الأبد

إكمالات الدردشة عديمة الحالة. يعرف النموذج فقط ما ترسله في كل طلب، لذا يعيد البوت إرسال السجل في كل خطوة. هذا هو السبب في أن السجل غير المحدود هو فخ التكلفة وزمن الاستجابة. نافذة السياق هي 100,000 رمز، وهو الكثير، لكنك تدفع عن كل رمز مدخل في كل خطوة، ومعظم بوتات الدردشة لا تحتاج إلى ذلك القدر.

تعمل سياسة بسيطة بشكل جيد: الاحتفاظ بالموجه النظامي، والاحتفاظ بآخر 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 حدود الفيض الخاصة به على البوتات، وسيؤدي إرسال طلب التعديل مع كل رمز إلى إبطاء التدفق.

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 طلب في وقت واحد بسهولة، لذا اضبط حدّ المعدل بما يتناسب مع المفتاح الذي تستخدمه.

أفضل طريقة للحماية هي استخدام قفل عدّاد (semaphore) حول استدعاء النموذج. تنتظر الطلبات التي تتجاوز الحدّ في طابور داخل عملية البرمجيات الخاصة بك بدلاً من الارتداد عن الـ 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 عددًا كبيرًا في الدقيقة، ويعني 429 مع Retry-After: 5 حملًا زائديًا مؤقتًا؛ انتظر خمس ثوانٍ. تتعامل إعادة المحاولة في SDK مع معظم هذه الحالات. الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها، لذا لا تضيف عمليات إعادة الإرسال إلى الفاتورة.

حماية أخرى هي تنظيم الطلبات لكل مستخدم. إذا أرسل شخص واحد عشرة رسائل في عشر ثوانٍ، قم بتنفيذ الطلبات بشكل تسلسلي باستخدام قفل لكل دردشة حتى تصل الإجابات بالترتيب ولا تستخدم دردشة واحدة كل الأماكن الثمانية المتاحة.

الشخصية، القواعد ودردشات المجموعات

الموجّه (system prompt) هو المكان الذي يحصل فيه البوت على شخصيته. اكتبه كملخص قصير: من هو البوت، كيف يتحدث، كم يجب أن تكون الإجابات، وأي شيء يجب ألا يفعله. بالنسبة لبوت لعب الأدوار أو رفقة للبالغين، صف الإعداد والنبرة في بضعة أسطر واسمح للمستخدم بالتوجيه من هناك. الموجّهات المحددة أفضل من الطويلة؛ يتبع النموذج شخصية واضحة من خمسة أسطر أفضل من صفحة من القواعد.

بعض القواعد تقع خارج الموجه. يجيب النموذج بدون رفض المحتوى للاستخدام القانوني للبالغين، لكن المحتوى الجنسي الذي يتضمن قاصرين غير مسموح به أبدًا، ويجب عليك فرض ذلك من جانبك أيضًا. إذا كان روبوتك مفتوحًا للجمهور، فأعلن ذلك في وصفه، وأضف إشعارًا بالعمر في رسالة البدء، وتذكر أن لـ Telegram شروطًا خاصة بالروبوتات يجب عليك أيضًا اتباعها. تذهب محادثات مستخدميك إلى واجهة برمجة التطبيقات، ولا تُستخدم الموجهات للتدريب؛ أخبر مستخدميك بما يخزنه روبوتك الخاص.

في محادثات المجموعات، لا تجب على كل رسالة. استجب فقط عندما يُذكر الروبوت أو عندما يرد شخص على إحدى رسائله، وتجاهل الرسائل المرسلة من روبوتات أخرى. في python-telegram-bot يمكنك التحقق من update.message.entities للإشارة أو مقارنة update.message.reply_to_message.from_user.id بمعرف الروبوت الخاص.

عند حدوث خطأ، سجّل رأس الاستجابة X-Request-Id لكل مكالمة؛ يمكنك قراءته عبر واجهة الاستجابة الخام الخاصة بـ SDK. صفحة الدعم هي المكان المناسب للاستفسار عن طلب معين.

تشغيله في بيئة الإنتاج

الاستعلام (Polling)، كما هو مستخدم أعلاه، جيد للروبوت الصغير: تطلب العملية من Telegram الرسائل الجديدة في حلقة ولا تحتاج إلى عنوان عام. قم بتشغيله تحت systemd أو حاوية مع إعادة تشغيل تلقائي، واحتفظ بالقيم السرية في بيئة ملف الوحدة أو متجر الأسرار. يقلل إعداد الـ webhook من الحمل أثناء الخمول، لكنه يحتاج إلى HTTPS وعنوان URL عام، لذا ابدأ بالاستعلام.

قدّر التكلفة قبل دعوة الناس. تفرض الـ API $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج. تكلفة دورة نموذجية مع سجل مختصر يحتوي على 2000 رمز مدخل و500 رمز مخرج هي 2000 × $0.15 / 1M = $0.0003 للمدخلات بالإضافة إلى 500 × $0.50 / 1M = $0.00025 للمخرجات، وهو ما مجموعه $0.00055. تكلفة ألف دورة هي $0.55. إذا نمت الدردشة إلى 10000 رمز مدخل لكل دورة، تصبح تكلفة المدخلات وحدها $0.0015، لذا فإن التقليم يغطي تكلفته بسرعة.

عند الحاجة إلى الاستمرارية، احفظ سجل كل دردشة كـ JSON في SQLite أو Redis، حمّله في الرسالة الأولى بعد إعادة التشغيل، واكتبه مرة أخرى بعد كل رد. أضف حدًا يوميًا لعدد الرسائل لكل مستخدم إذا كان الروبوت عامًا، حتى لا يستنفد مستخدم متحمس الرصيد. وثائق API تدرج كل معلمة يمكنك ضبطها، وقائمة مراجعة الإنتاج تغطي تدوير المفاتيح ومراقبة رأس الرصيد.

أسئلة وأجوبة

ما هي المكتبة التي يجب أن أستخدمها لجانب Telegram؟

أي مكتبة تعمل لأن جانب النموذج هو API HTTP عادي. يستخدم هذا الدليل python-telegram-bot الإصدار 20 أو أحدث، وهو غير متزامن ويتناسب جيدًا مع عميل OpenAI غير المتزامن.

لماذا يرد البوت على نفسه أو على الجميع في مجموعة؟

في المجموعات، قيّد المعالج للرسائل التي تذكر البوت أو ترد عليه، وتجاهل الرسائل من البوتات. خلاف ذلك، فإن كل رسالة في المجموعة تثير استدعاء النموذج.

كم تكلفة محادثة البوت؟

تبادل قصير يحتوي على 2000 رمز مدخل و500 رمز مخرج يكلف $0.00055، لذا فإن ألف منها تكلف $0.55. السجلات الطويلة تكلف أكثر لأنها تُعاد إرسالها في كل دورة.

هل يمكن استخدام البوت للعب الأدوار للبالغين؟

يتم ضبط النموذج للإجابة دون رفض المحتوى للاستخدام القانوني للبالغين، وتُعد بوتات الخيال والتحدث المرافق حالة نموذجية. لا يُسمح مطلقًا بالمحتوى الجنسي الذي يتضمن قاصرين، ولـ Telegram قواعد خاصة يجب عليك اتباعها.

مفتاحك على بُعد نموذج واحد

أنشئ حسابًا، وانسخ المفتاح، ثم غيّر URL الأساسي. هذا هو الإعداد الكامل.

احصل على مفتاح APIاقرأ المستندات