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

واجهة برمجة تطبيقات LLM في Python: الدردشة، البث المتدفق واستدعاء الدوال

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

تم التحديث

شريط من كتل الكود يتدفق من جهاز كمبيوتر محمول إلى فقاعات دردشة، يوضح استدعاء واجهة برمجة تطبيقات LLM في Python
01

نقاط رئيسية

  • ثبّت الحزمة openai، اضبط عنوان URL الأساسي والمفتاح، واستخدم معرف النموذج uncensored.
  • استخدم البث المتدفق عبر stream=True وأغلق التدفق مبكراً لتحرير سعة التزامن.
  • تعيد استدعاءات الدوال حججاً يجب عليك تحليلها والتحقق منها قبل تشغيل أي شيء.
  • تعامل مع الخطأ 429 باستخدام Retry-After، وحد الطلبات المتوازية إلى 8 في المفتاح الكامل.

تثبيت الـ SDK وإجراء أول طلب

إذا كنت تريد إعدادًا لواجهة برمجة تطبيقات LLM بلغة Python يعمل في خمس دقائق، فإن مكتبة OpenAI SDK هي كل ما تحتاجه. الواجهة متوافقة مع OpenAI، لذا يمكنك الاحتفاظ بالعميل الرسمي وتغيير قيمتين فقط: عنوان URL الأساسي والمفتاح. معرف النموذج هو uncensored.

أولاً احصل على مفتاح. سجّل في صفحة مفتاح API، واحصل على رصيد التجربة بنقرة واحدة، وانسخ المفتاح. ثم ثبّت العميل واحتفظ بالمفتاح بعيدًا عن شفرة المصدر.

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

الآن أصغر برنامج مفيد:

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what a context window is in two sentences."},
    ],
    temperature=0.7,
)

print(resp.choices[0].message.content)
print(resp.usage)

هذا هو التكامل بأكمله. يعطي resp.usage عدد رموز الموجّه والإكمال، والتي يمكنك ضربها في الأسعار الموجودة في صفحة التسعير ($0.15 لكل مليون رمز مدخل، و$0.50 لكل مليون رمز مخرج) لمعرفة تكلفة كل استدعاء. تقبل نقطة النهاية نفسها أيضًا POST /v1/responses إذا كانت شفرة المصدر تستخدم بالفعل هذا التنسيق، ويعرض GET /v1/models معرف النموذج.

كيف يبدو الطلب والاستجابة

يخفي عميل OpenAI تفاصيل HTTP، لكن من المفيد معرفتها عند حدوث خطأ. ترسل المكتبة طلبًا POST إلى /v1/chat/completions مع رمز حامل. يمكنك إعادة إنتاج المكالمة باستخدام curl ومقارنتها.

curl https://api.llmmodelsapi.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "Say hello"}]}'

معلمات مفيدة يتم تمريرها إلى النموذج: temperature، top_p، stop، seed وعقوبات التكرار والحضور. max_tokens اختياري. إذا تركته، يمكن أن يستخدم الإكمال أي شيء متبقي من نافذة 100,000 رمز (الموجّه والإكمال معًا).

يُعدّ تسجيل رأسين من رؤوس الاستجابة في كل استدعاء أمرًا مفيدًا: X-Request-Id لأسئلة الدعم، وX-Balance-USD لرصيدك المتبقي. مع مكتبة Python SDK، يمكنك الوصول إليها عبر الاستجابة الخام:

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Ping"}],
    max_tokens=20,
)
print(raw.headers.get("X-Request-Id"))
print(raw.headers.get("X-Balance-USD"))
completion = raw.parse()
print(completion.choices[0].message.content)

بث الرموز عند وصولها

لواجهات الدردشة وأي شيء ينتظره شخص، قم ببث الإجابة. اضبط stream=True وتكرّر عبر القطع. ترسل الواجهة القطع عبر أحداث الإرسال من الخادم، وتحمل القطعة الأخيرة معلومات الاستخدام عندما تطلبها.

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short product description for a mechanical keyboard."}],
    stream=True,
    stream_options={"include_usage": True},
)

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

تفاصيلان يُخطئ فيهما الكثيرون. أولاً، تحتوي بعض القطع على قائمة choices فارغة (مثل قطعة الاستخدام)، لذا تحقق من صحة البيانات قبل الوصول إليها. ثانياً، يحتفظ الطلب المتدفق بمكان في سعة التوازي حتى ينتهي البث. إذا فتحت تدفقاً وتخلّيت عنه دون إغلاقه، يظل هذا المكان مشغولاً وقد تفشل الطلبات اللاحقة بخطأ concurrency. استخدم التدفق داخل كتلة with أو استدعِ stream.close() إذا توقفت عن القراءة مبكراً.

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

مكالمة أداة ضد النموذج

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

import json

def get_order_status(order_id: str) -> str:
    # Replace with a real lookup
    return json.dumps({"order_id": order_id, "status": "shipped"})

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up the status of an order by its ID",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)

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

قم دائمًا بتحليل call.function.arguments كـ JSON داخل كتلة try في الشفرة الحقيقية، لأن النماذج تنتج أحيانًا وسائط لا تتطابق مع مخططك. تحقق من الصحة قبل تنفيذ أي شيء له آثار جانبية. لحلقات الوكلاء الأطول أمداً، انظر إلى دليل استخدام هذه الواجهة للوكلاء.

تتدفق استدعاءات الأداة أيضًا: تصل الوسائط على شكل قطع في delta.tool_calls، وتقوم بدمجها حسب الفهرس حتى ينتهي البث.

وضع JSON للإخراج المنظم

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"sentiment\": \"positive|negative|neutral\", \"confidence\": 0-1}"},
        {"role": "user", "content": "The setup took ten minutes and everything just worked."},
    ],
    response_format={"type": "json_object"},
    temperature=0,
)
data = json.loads(resp.choices[0].message.content)
print(data["sentiment"])

استخدم temperature=0 للاستخراج والتصنيف بحيث تعطي التشغيلات المتكررة نفس التصنيفات. أضف seed إذا أردت تقييد أخذ العينات أكثر، وتحقق دائمًا من صحة النتيجة بعد تحليلها مقابل مخططك الخاص.

الحدود، إعادة المحاولة، ومعالجة الأخطاء

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

تعيد مكتبة OpenAI SDK محاولة بعض الأخطاء بالفعل، لكن يجب عليك تعيين السياسة بنفسك:

import os
import time
from openai import OpenAI, RateLimitError, APIConnectionError

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key=os.environ["LLM_API_KEY"], max_retries=0, timeout=120)

def ask(messages, tries=5):
    delay = 2
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError as e:
            wait = float(e.response.headers.get("Retry-After", delay))
            time.sleep(wait)
            delay = min(delay * 2, 30)
        except APIConnectionError:
            time.sleep(delay)
            delay = min(delay * 2, 30)
    raise RuntimeError("gave up after retries")

إذا وزعت العمل باستخدام الخيوط أو asyncio، قم بتقييد المجموعة عند 8 (أو 2 في مفتاح التجربة) باستخدام سيمافور. هذا يبقيك تحت حد التزامن دون الاعتماد على إعادة المحاولة. الطلبات الفاشلة أو المرفوضة لا يتم احتساب رسوم عليها، لذا فإن إعادة المحاولة لا تكلف إضافيًا للمحاولات الفاشلة.

تحقق من رصيدك عبر الكود GET /v1/balance، أو اقرأ قيمة X-Balance-USD من أي استجابة. القائمة الكاملة للمعلمات موجودة في وثائق API.

كم يكلف تشغيل هذه الأمثلة

الأمثلة المذكورة أعلاه صغيرة. تكلفة استدعاء يحتوي على 300 رمز موجّه و200 رمز إكمال هي 300 × $0.15 / 1M زائد 200 × $0.50 / 1M، وهو $0.000045 زائد $0.0001، أو $0.000145. حوالي 6,900 من هذه المكالمات تتسع في $1. يغطي رصيد التجربة بقيمة $0.50 حوالي 3,400 منها، وهو صالح لمدة 7 أيام دون تفاصيل الدفع.

بعد انتهاء التجربة، قم بشحن أي مبلغ صحيح من $20 إلى $500، مع مكافأة بنسبة 5% عند الشحن بمبلغ $50، و10% عند $100، و15% عند $200. الرصيد لا ينتهي ولا توجد اشتراكات. لا تُستخدم الموجّهات للتدريب.

02

أسئلة وأجوبة

هل يمكنني استخدام مكتبة Python الرسمية من OpenAI؟

نعم. اضبط base_url على عنوان الـ API و api_key على مفتاحك، ثم استدعِ chat.completions.create مع النموذج uncensored.

هل تدعم الـ API الـ Python غير المتزامن؟

نعم، استخدم AsyncOpenAI مع نفس عنوان URL الأساسي والمفتاح. حافظ على عدد المهام المتزامنة عند 8 أو أقل في المفتاح الكامل، أو 2 في مفتاح التجربة.

كيف أرى عدد الرموز التي استخدمتها المكالمة؟

اقرأ resp.usage في الطلب العادي، أو مرر stream_options مع include_usage في الطلب المتدفق. اضرب الناتج في $0.15 لكل مليون رمز إدخال و $0.50 لكل مليون رمز إخراج.

ما هو الحد الأقصى لطول الموجّه؟

نافذة السياق هي 100,000 رمز، للموجه والإكمال معاً. حجم جسم الطلب محدود بـ 8 MB.

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

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

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