AR ▾
llmwebsearchapi.com
llmwebsearchapi.com›دليل
احصل على مفتاح API

أجرِ أول استدعاء لواجهة برمجة تطبيقات LLM باستخدام Python وcurl

إليك كيفية إجراء استدعاء LLM API عملياً: طلب POST واحد يحتوي على مفتاح، واسم نموذج، وقائمة رسائل، وتعود الإجابة كـ JSON. يشرح هذا الدليل استخدام curl، Python، البث المتدفق، التكلفة والأخطاء التي ستواجهها أولاً.

رسم توضيحي معزول لبرنامج طرفي يرزم حزم بيانات إلى مكعب يعيد فقاعات حوار

الاستدعاء في خمس خطوات

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

  1. احصل على مفتاح API من صفحة المفاتيح. يمكن للحسابات الجديدة المطالبة برصيد تجريبي صغير هناك بنقرة واحدة.
  2. اختر نقطة النهاية: https://api.llmwebsearchapi.com/v1/chat/completions.
  3. أرسل المفتاح في الرأس Authorization: Bearer YOUR_API_KEY.
  4. أرسل جسم الطلب بصيغة JSON مع تعيين model إلى uncensored وقائمة messages.
  5. اقرأ choices[0].message.content من الـ JSON الذي يعود.

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

طلبك الأول مع curl

يُعد curl أسرع طريقة لإثبات أن مفتاحك ومسار الشبكة يعملان، لأنه لا توجد مكتبة وسيطة. احفظ مفتاحك في متغير بيئة أولاً حتى لا ينتهي بك الأمر في سجل سطر الأوامر (shell history) كجزء من أمر طويل.

export API_KEY="YOUR_API_KEY"

curl https://api.llmwebsearchapi.com/v1/chat/completions   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You answer in two short sentences."},
      {"role": "user", "content": "What is a token in a language model?"}
    ],
    "temperature": 0.7
  }'

يتألف الجسم من ثلاثة أجزاء ذات أهمية. model يحدد ما يجب أن يجيبك؛ في هذه الخدمة يوجد استمارة واحدة، لذا تكون القيمة دائماً uncensored. messages هو المحادثة حتى الآن. temperature يتحكم في مدى جرأة الصياغة، من قرب 0 للإخراج القابل للتكرار إلى حوالي 1 لتنوع أكبر.

يمكنك أيضاً التحقق من قبول المفتاح دون توليد أي شيء: أرسل طلب GET إلى /v1/models بنفس رأس Authorization. إذا كانت القائمة تحتوي على uncensored، فإن المصادقة تعمل وأي فشل لاحق يتعلق بجسم الطلب وليس بالمفتاح.

نفس الاستدعاء في Python

لا تحتاج إلى عميل خاص. تعمل الحزمة الرسمية openai إذا وجهتها إلى URL أساسي مختلف. قم بتثبيتها باستخدام pip install openai.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You answer in two short sentences."},
        {"role": "user", "content": "What is a token in a language model?"},
    ],
    temperature=0.7,
)

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

شيئان يستحقان النسخ إلى كودك الخاص. أولاً، احتفظ بالمفتاح خارج ملف المصدر؛ اقرأه من متغير بيئة مع os.environ["API_KEY"] بمجرد تجاوز التجارب. ثانياً، اطبع resp.usage أثناء التعلم. رؤية تعداد الرموز بجانب النص هو أسرع طريقة لبناء إحساس بتكلفة المكالمة.

نظراً لأن الواجهة تتبع تنسيق OpenAI، فإن نفس الهيكل يعمل من Node، Go، Ruby، أو استخدام fetch الخام. يتغير فقط التركيب النحوي حول طلب POST. يدرج دليل البدء السريع في المستندات المعلمات المدعومة.

قراءة الاستجابة

الاستجابة هي كائن JSON. ستتعامل مع أربعة أجزاء منه في الغالب:

  • يمثل choices[0].message.content النص المُولّد.
  • يشير choices[0].finish_reason إلى سبب توقف التوليد. يعني stop أن النموذج أنهى المهمة؛ بينما يعني length أنه تجاوز حد الرموز وقد يكون النص مقطوعاً.
  • يحتوي usage على prompt_tokens، وcompletion_tokens والمجموع الكلي. هذا هو الأساس الذي تُبنى عليه الفواتير.
  • تشمل رؤوس الاستجابة X-Request-Id وX-Balance-USD. قم بتسجيل معرف الطلب مع كل استدعاء. إذا تواصلت مع الدعم، فإن هذا المعرف يتيح لهم العثور على طلبك المحدد.

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

الرسائل، الذاكرة، والبث المتدفق

لا تتذكر الـ API هويتك

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

from openai import OpenAI

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

history = [{"role": "system", "content": "You are a concise assistant."}]

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

print(ask("Name one use for a text API."))
print(ask("Give a second one."))

تذكر أن السجل الأطول يعني المزيد من رموز الإدخال في كل استدعاء لاحق. للجلسات الطويلة، قم بتقليص أو تلخيص المحادثات الأقدم.

البث المتدفق لواجهة مستجيبة

اضبط stream على true، ويرسل الخادم النص على شكل أجزاء عبر أحداث الإرسال من الخادم (SSE)، مما يسمح لنافذة الدردشة بإظهار الكلمات مع وصولها. تصل أرقام الاستخدام في نهاية البث.

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Explain HTTP in three sentences."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

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

تكلفة الاستدعاء الواحد

السعر يعتمد على الرمز، والدفع حسب الاستخدام: $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، تُخصم من رصيد مسبق الدفع. لا يوجد اشتراك، والطلبات الفاشلة أو المرفوضة لا تُخصم منها. الرصيد لا ينتهي.

خذ الاستدعاء الصغير من السابق وقل إنه استخدم 1,200 رمز إدخال و 400 رمز ناتج:

  • مدخلات: 1,200 / 1,000,000 × $0.15 = $0.00018
  • الإخراج: 400 / 1,000,000 × $0.50 = $0.00020
  • المجموع: $0.00038

رصيد التجربة بقيمة $0.50 سيغطي حوالي 1,300 مكالمة بهذا الحجم، لأن $0.50 مقسومة على $0.00038 تساوي حوالي 1,316. التجربة صالحة لمدة 7 أيام ولا تحتاج إلى بطاقة. عند الانتقال، تتراوح عمليات الشحن من $20 إلى $500 بمبالغ صحيحة، مع مكافأة 5% من $50، و10% من $100 و15% من $200. تحتوي صفحة التسعير على التفاصيل الحالية وطرق الدفع المقبولة.

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

الأخطاء والحدود التي ستواجهها أولاً

تقع معظم الفشل المبكر ضمن فئات قليلة.

العرضالسبب المعتادالحل
خطأ المصادقة (عادةً HTTP 401)مفتاح مفقود أو غير صحيح، أو كلمة Bearer منسيةتحقق من الرأس، وتأكد من أن المفتاح لا يحتوي على مسافة لاحقة
تم رفض الطلب لأنه غير صالح (عادةً HTTP 400)JSON غير صالح، أو messages مفقودةتحقق من صحة JSON؛ في curl، انتبه إلى علامات الاقتباس حول -d
HTTP 429، الكود rate_limitedأكثر من 300 طلب في الدقيقة باستخدام مفتاح كامل، أو 60 باستخدام مفتاح تجريبيأبطئ وأعد المحاولة
HTTP 429، الكود concurrencyأكثر من 8 طلبات في وقت واحد على مفتاح كامل، أو 2 على مفتاح تجريبيقم بترتيب الطلبات في الكود الخاص بك
HTTP 429 مع Retry-After: 5حمل زائد مؤقتانتظر 5 ثوانٍ المذكورة ثم حاول مرة أخرى

إعادة المحاولة أمر سهل الإضافة. تنتظر هذه النسخة وقتاً أطول قليلاً بعد كل محاولة فاشلة:

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.llmwebsearchapi.com/v1",
    api_key="YOUR_API_KEY",
    max_retries=0,
)

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

يمكن أن يصل حجم جسم الطلب إلى 8 MB، وهو أكثر بكثير من أي موجّه يتسع في نافذة السياق.

ملاحظة لموقع بأسلوب البحث

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

بأي حال، يبقى شكل المكالمة كما هو في الأمثلة أعلاه. ترسل الرسائل، وتحصل على نص، وتدفع مقابل الرموز في الاتجاهين. عندما تكون جاهزاً، أنشئ مفتاحاً وشغّل أمر curl من أعلى هذه الصفحة.

أسئلة وأجوبة

هل أحتاج إلى مكتبة OpenAI لاستدعاء هذه الـ API؟

لا. أي عميل HTTP يعمل لأنه طلب JSON POST عادي. مكتبات OpenAI SDK مريحة، وتحتاج فقط إلى عنوان URL أساسي ومفتاح مختلف.

لماذا يحصل سؤالي التالي على إجابة بلا سياق؟

لا تحتفظ الـ API بأي ذاكرة بين المكالمات. أرسل الرسائل السابقة مرة أخرى في مصفوفة الرسائل في كل مرة.

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

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

ماذا أفعل بعد HTTP 429؟

انتظر وأعد المحاولة. إذا كان هناك رأس Retry-After، انتظر المدة المحددة؛ وإلا خفف الضغط لبضع ثوانٍ وقلل عدد الطلبات المتزامنة.

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

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