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

كيفية تنفيذ نموذج LLM في بايثون باستخدام واجهة برمجة تطبيقات مستضافة

لمعظم المشاريع، يعتمد تنفيذ نموذج LLM في بايثون على استدعاء نموذج مستضاف عبر HTTP، وليس تدريبه أو خدمته بنفسك. مع واجهة برمجة تطبيقات متوافقة مع OpenAI، يستغرق الأمر حوالي عشرة أسطر، ويمكن أن يتطور الكود نفسه إلى البث المتدفق وإخراج JSON واستدعاء الدوال.

محدّث

طرفية ترسل شعاعًا إلى خادم سحابي وتتلقى مكعبات بيانات، توضح استدعاء بايثون لنموذج LLM مستضاف

نقاط رئيسية

  • ثبّت الحزمة openai، واضبط عنوان URL الأساسي والمفتاح، واستخدم معرف النموذج uncensored.
  • يتم دعم البث المتدفق، ووضع JSON، واستدعاء الدوال، وتستخدم جميعها وسائط SDK القياسية.
  • احتفظ بسجل الدردشة في قائمة وراقب نافذة الـ 100,000 رمز.
  • عالج خطأ HTTP 429 بإعادة محاولة قصيرة؛ الطلبات الفاشلة أو المرفوضة لا تُحسب.

API مستضاف أو نموذجك الخاص

هناك طريقتان لإدراج نموذج لغوي في برنامج Python. يمكنك تشغيل الأوزان بنفسك، وهو ما يعني الحاجة إلى GPU، وحزمة الخدمة (serving stack)، وخيارات التكميم (quantization)، ووقت انتظار طويل للتنزيلات. أو يمكنك إرسال طلبات إلى نموذج يشغله طرف آخر. المسار الأول منطقي للأبحاث، أو لعزل البيانات بدقة، أو للحجم الثابت العالي جداً. المسار الثاني يناسب كل شيء آخر: سكريبت، بوت، ميزة منتج، أو نموذج أولي تريد تشغيله بحلول وقت الغداء.

يتبع هذا الدليل المسار الثاني. الخدمة هنا هي API نصوص متوافق مع OpenAI، مستضاف، يحتوي على نموذج واحد مفتوح الأوزان، يشغله مزود مستقل ومضبوط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. ليست API رسمية لأي بائع نماذج. لأنها تتبع طلب OpenAI، فإن حزمة openai القياسية تعمل، وكذلك requests الخام إذا كنت تفضل عدم وجود تبعيات.

الخطوة 1: التثبيت وإجراء أول طلب

ثبّت الـ SDK واحفظ مفتاحك في متغير بيئة، حتى لا يظهر أبداً في كود المصدر الخاص بك.

pip install openai
export API_KEY="your-key-here"

ثم أنشئ عميلاً باستخدام Base URL الخاص بالخدمة. الأشياء الوحيدة التي تغيرها مقارنة بأي إعداد آخر على طراز OpenAI هي URL، والمفتاح، واسم النموذج.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.fluxapikey.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain list comprehensions in two sentences."},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

هذا برنامج كامل يعمل. نقطة النهاية خلفه هي POST /v1/chat/completions، موثقة بـ Authorization: Bearer <key>، وGET /v1/models تعدد معرف النموذج. يمكنك الحصول على مفتاح ورصيد تجريبي صغير من صفحة المفاتيح.

الخطوة 2: بث الإجابة

انتظار عدة ثوانٍ للحصول على رد كامل يبدو بطيئاً في طرفية أو صفحة ويب. اضبط stream=True واطبع الرموز (tokens) عند وصولها عبر أحداث مُرسلة من الخادم (SSE).

# client from step 1: base_url https://api.fluxapikey.com/v1
stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short story opening about a lighthouse keeper."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

أرقام الاستخدام تصل في نهاية البث، لذا قد لا تحتوي الشريحة الأخيرة على خيارات. لهذا السبب يتحقق الحلقة من chunk.choices أولاً. شيء واحد يجب تذكره: الطلب المتدفق يحتفظ بمكان الـ concurrency الخاص به حتى ينتهي البث، لذا اقرأه حتى النهاية أو أغلقه.

الخطوة 3: الحفاظ على محادثة

النموذج لا يملك ذاكرة بين الطلبات. المحادثة هي مجرد قائمة رسائل متزايدة تعيد إرسالها في كل مرة. فئة صغيرة تكفي:

# client from step 1: base_url https://api.fluxapikey.com/v1
class Chat:
    def __init__(self, system):
        self.messages = [{"role": "system", "content": system}]

    def say(self, text):
        self.messages.append({"role": "user", "content": text})
        r = client.chat.completions.create(model="uncensored", messages=self.messages)
        answer = r.choices[0].message.content
        self.messages.append({"role": "assistant", "content": answer})
        return answer

bot = Chat("You are a patient Python tutor.")
print(bot.say("What is a generator?"))
print(bot.say("Show me one with yield."))

نافذة السياق هي 100,000 رمز (token)، مشتركة بين الموجّه (prompt) والإكمال. هذا مساحة واسعة، لكن المحادثة الطويلة تنمو مع كل دور، وتدفع مقابل كل السجل في كل طلب. عندما يصبح كبيراً، احذف الأدوار الأقدم أو استبدلها بملخص قصير تطلب من النموذج كتابته.

الخطوة 4: الحصول على مخرجات مهيكلة

البرامج تريد بيانات، ليس فقرات. وضع JSON يجعل الرد JSON صالحاً. قل في الموجّه (prompt) المفاتيح التي تتوقعها.

# client from step 1: base_url https://api.fluxapikey.com/v1
import json

r = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": 'Return JSON like {"title": str, "tags": [str]}.'},
        {"role": "user", "content": "Summarise: a tutorial on async IO in Python."},
    ],
)
data = json.loads(r.choices[0].message.content)
print(data["title"], data["tags"])

JSON صالح لا يضمن مفاتيحك. تحقق منها في الكود وأعد المحاولة مرة واحدة إذا كان أحدها مفقوداً.

الخطوة 5: دع النموذج يستدعي دوالك

استدعاء الدوال (function calling) يسمح للنموذج بطلب برنامجك لتشغيل دالة، ثم الاستمرار بالنتيجة. تصف الأداة، تتحقق مما إذا كان الرد يحتوي على استدعاء، تشغله وترسل المخرجات مع الدور tool.

# client from step 1: base_url https://api.fluxapikey.com/v1
import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_word_count",
        "description": "Count the words in a text.",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
r = client.chat.completions.create(model="uncensored", messages=messages, tools=tools, tool_choice="auto")
msg = r.choices[0].message

if msg.tool_calls:
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = len(args["text"].split())
        messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

تحقق دائماً من الحجج قبل اتخاذ إجراء بشأنها، لأن النموذج يمكن أن ينتج استدعاءً لم تتوقعه. استدعاءات الأداة تتدفق أيضاً، كـ tool_calls deltas، إذا كنت بحاجة لذلك. الـ توثيق يدرج كل حقل.

الخطوة 6: معالجة حدود المعدل والأخطاء

المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة؛ المفتاح التجريبي يسمح بـ 2 و60. إذا تجاوزت الحد يرد الـ API بـ HTTP 429. رمز الخطأ هو rate_limited لعدد الطلبات الزائد في الدقيقة وconcurrency لعدد الطلبات المتزامنة الزائد. في حالة الحمل الزائد المؤقت تحصل أيضاً على 429، مع رأس Retry-After: 5. غلاف إعادة محاولة صغير يغطي الحالات الثلاث:

# client from step 1: base_url https://api.fluxapikey.com/v1
import time
from openai import RateLimitError

def ask(messages, tries=4):
    for i in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError:
            time.sleep(5 * (i + 1))
    raise RuntimeError("still limited after retries")

إذا كنت تشغل العمل في خيوط، حددها بـ 8 باستخدام ThreadPoolExecutor(max_workers=8) حتى لا تصل إلى حد التزامن إلا نادراً. يحمل كل رد X-Request-Id، وهو ما يجب ذكره إذا اتصلت بـ الدعم، وX-Balance-USD يظهر رصيدك المتبقي. الحد الأقصى لحجم الجسم هو 8 MB.

إعدادات تغير المخرجات

يحدث معظم ضبط الإعدادات اليومية ضمن مجموعة صغيرة من المعاملات، التي تُمرَّر جميعها إلى النموذج.

  • يتحكم temperature في العشوائية. استخدم 0.2 أو أقل للاستخراج والتصنيف، وحوالي 0.7 للدردشة، و1.0 أو أكثر للعصف الذهني والخيال.
  • يُقصي top_p الذيل غير المحتمل لخيارات الكلمات. غيّر إما هذا المعامل أو درجة الحرارة، وليس كليهما معاً، لتعرف أيّهما أدى العمل.
  • يجعل seed عمليات التشغيل المتكررة أكثر قابلية للمقارنة. وهو مفيد في الاختبارات التي تريد فيها رؤية تأثير تغيير الموجّه دون الضوضاء.
  • ينهي stop التوليد عند سلسلة تختارها، وهو مفيد لقطع النموذج الذي يستمر في إضافة تعليقات.
  • يعد max_tokens اختيارياً. بدونه قد يستخدم التوليد كل ما تبقى من نافذة الـ 100,000 رمز. اضبطه عندما تريد حداً صارماً للطول والتكلفة.
  • تثبط عقوبات التكرار والحضور التكرار، مما يساعد في المخرجات الإبداعية الطويلة التي تبدأ بالتكرار.

اكتب الإعدادات التي استخدمتها بجانب أي مخرج تهمك. بعد أشهر، يكون سؤال "لماذا أجاب بشكل مختلف" في الغالب بسبب معامل تغير أو رسالة نظام تغيرت.

تشغيل العديد من الطلبات في وقت واحد

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

from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.fluxapikey.com/v1", api_key="YOUR_KEY")

def summarise(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarise in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

texts = ["first document", "second document", "third document"]
with ThreadPoolExecutor(max_workers=8) as pool:
    for line in pool.map(summarise, texts):
        print(line)

حافظ على عدد العاملين عند 8 أو أقل، أو عند 2 في مفتاح التجربة. إذا كنت لا تزال ترى استجابات 429 مع الرمز concurrency، فقلل العدد بمقدار واحد أو اثنين. يهم حدّ المعدل 300 في الدقيقة للطلبات السريعة القصيرة، لذا يمكن أن تصل مجموعة من المكالمات الصغيرة إلى هذا الحد قبل الوصول إلى حدّ التوازي.

المشاكل الشائعة وحلولها

تأتي معظم أخطاء اليوم الأول من قائمة قصيرة من الأسباب.

  • خطأ 401 أو خطأ في المصادقة. المفتاح مفقود، أو مكتوب بشكل خاطئ، أو مُرسل إلى المضيف الخطأ. اطبع عنوان URL الأساسي الذي يستخدمه عميلك وتأكد من أنه ينتهي بـ /v1.
  • لم يتم العثور على النموذج. يجب أن يكون معرف النموذج هو uncensored. أرسل طلب GET /v1/models إذا أردت تأكيد ما يسرده الخادم.
  • رد فارغ أو مقطوع. يوقف الحدّ المنخفض لـ max_tokens الإجابة في منتصف الجملة. ارفعها أو أزلها. تحقق من finish_reason في الاختيار: يعني length الوصول إلى الحدّ.
  • JSON غير قابل للتحليل. إما أن الرد كان مقتطعاً، أو أن الموجّه لم يصف الهيكل. أصلح الموجّه أولاً ولف عملية التحليل في كتلة try.
  • بطء الرمز الأول. يستغرق الموجّه الطويل جداً وقتاً أطول للمعالجة. قلل السجل أو أرسل سياقاً أقل.
  • حجم الطلب كبير جداً. حدّ الجسم هو 8 ميجابايت، ونافذة السياق هي 100,000 رمز. قسّم المستندات الكبيرة إلى أجزاء ولخّص كل جزء.

عندما يبدو شيء ما خاطئاً بعد ذلك، سجّل رأس X-Request-Id مع الإدخال الذي فشل. هذا يسمح لـ الدعم بإيجاد الطلب المحدد.

التكلفة

تدفع $0.15 لكل مليون رمز مدخل و $0.50 لكل مليون رمز مخرج من رصيد مسبق الدفع. تكلفة مكالمة نموذجية تحتوي على 2,000 رمز مدخل و 500 رمز مخرج هي 0.002 × $0.15 = $0.0003 للمدخلات بالإضافة إلى 0.0005 × $0.50 = $0.00025 للمخرجات، أي ما مجموعه $0.00055. تكلف عشرة آلاف مكالمة من هذا النوع $5.50. الطلبات الفاشلة أو المرفوضة لا تُحسب عليها التكلفة ولا تنتهي صلاحية الرصيد أبداً. تتراوح عمليات الشحن من $20 إلى $500؛ انظر الأسعار للحصول على مستويات المكافآت. لا تُستخدم الموجّهات للتدريب.

تتكلف رموز الإخراج أكثر من رموز الإدخال، لذا فإن عادة التكلفة الأقل هي طلب إجابات قصيرة: قل جملتين، أو JSON فقط، واضبط max_tokens إلى حد معقول. اقرأ resp.usage أثناء التطوير لرؤية عدد الرموز الحقيقي لموجّهاتك، واضربه في الأسعار أعلاه قبل توسيع مهمة ما. يُظهر رأس X-Balance-USD ما تبقى بعد كل طلب.

أسئلة وأجوبة

هل أحتاج إلى وحدة معالجة رسومات لتطبيق LLM في Python؟

ليس مع API المستضاف. كود Python الخاص بك يرسل فقط طلبات HTTP، لذا فإن أي كمبيوتر محمول يعمل.

هل يمكنني استخدام الحزمة الرسمية لـ openai؟

نعم. اضبط base_url على عنوان URL الخاص بالخدمة، و api_key على مفتاحك، واستخدم معرف النموذج uncensored.

هل يدعم الكود غير المتزامن؟

يعمل عميل AsyncOpenAI الخاص بـ SDK مع نفس base_url والمفتاح. حافظ على التزامن عند 8 طلبات أو أقل.

كيف يمكنني تجربته دون دفع؟

أنشئ حساباً واحصل على رصيد تجريبي مجاني بقيمة $0.50 في صفحة المفتاح. صالح لمدة 7 أيام ولا يحتاج إلى بطاقة.

مفتاحك على بُعد استمارة واحدة

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

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