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

سير عمل واجهة برمجة تطبيقات LLM في Python: الإعداد خطوة بخطوة

وجّه OpenAI SDK إلى عنوان URL أساسي جديد، واستخدم معرف النموذج uncensored، وأضف إعادة المحاولة، والتشغيل المتوازي، واستدعاء الأدوات طبقة تلو الأخرى.

تم التحديث

خط أنابيب من الكتل المتوهجة مع مكعبات البيانات التي تنقسم إلى مسارات متوازية، تمثل سير عمل LLM في Python

نقاط رئيسية

  • ثبّت openai، اضبط base_url على https://api.veo3apis.com/v1 واستخدم النموذج uncensored.
  • عالج 429 بالانتظار حتى انتهاء مهلة إعادة المحاولة؛ الطلبات الفاشلة لا تُحسب.
  • اضبط حجم مجموعة الخيوط للمفتاح: 8 عمال للمفتاح الكامل، و2 لمفتاح التجربة.
  • اقرأ X-Balance-USD من رؤوس الاستجابة لتتبع الإنفاق لكل تشغيل.

النسخة المختصرة

لبناء سكريبت Python لسير عمل API LLM، ثبّت الـ SDK الرسمي الخاص بـ OpenAI، واضبط عنوان URL الأساسي على https://api.veo3apis.com/v1، واستخدم مفتاحك كمفتاح API، واستدعِ النموذج uncensored. لا يتغير شيء آخر. الخدمة متوافقة مع OpenAI، لذا فإن كل نمط تعرفه بالفعل من الـ SDK يعمل: مكالمات الدردشة المباشرة، البث المتدفق، وضع JSON، واستدعاء الدوال.

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

النموذج هو نموذج مفتوح الأوزان واحد تشغله مزود مستقل. إنه ليس الـ API الرسمي لأي بائع كبير، وهو ليس وسيط توجيه (router)، لذا يوجد معرف نموذج واحد فقط يجب تذكره. يتعامل مع النصوص فقط. لا يوجد توليد صور أو صوت أو فيديو، ولا تضمينات (embeddings)، ولا ضبط دقيق (fine-tuning).

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

تحتاج إلى Python 3.9 أو أحدث. ثبّت الـ SDK:

pip install openai

أنشئ مفتاحاً من صفحة API key بعد تسجيل الدخول بـ Google أو باستخدام بريد إلكتروني وكلمة مرور. تحتوي الصفحة أيضاً على مطالبة بنقرة واحدة للحصول على رصيد تجريبي مجاني بقيمة $0.50، صالح لمدة 7 أيام، لكل شخص، دون الحاجة إلى بطاقة. ثم قم بأصغر استدعاء ممكن:

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "List three uses for a hosted text API."},
    ],
)

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

إذا طُبع نص وكائن استخدام، فإن المصادقة والتوجيه ومعرف النموذج جميعها صحيحة. يرسل الـ SDK مفتاحك كـ Authorization: Bearer، ويذهب الطلب إلى POST /v1/chat/completions. يمكنك التحقق من معرفات النماذج التي يراها مفتاحك باستخدام client.models.list()، والتي تستدعي GET /v1/models.

نسخة curl الخام مفيدة عند التصحيح من خادم بدون Python:

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

حافظ على التكوين في عميل واحد

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

import os
from openai import OpenAI

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

MODEL = "uncensored"


def ask(system: str, user: str, **kwargs) -> str:
    resp = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": user},
        ],
        **kwargs,
    )
    return resp.choices[0].message.content

هناك خياران مقصودان هنا. يفعّل max_retries=0 إعادة المحاولة المدمجة في الـ SDK، مما يجعل منطق إعادة المحاولة في القسم التالي هو الوحيد، مما يسهل فهم السلوك. مهلة الاستجابة 120 ثانية تترك مجالاً للإكمال الطويل؛ نافذة السياق هي 100,000 رمز للموجّه بالإضافة إلى الإكمال، ويستغرق الإجابة الكبيرة وقتاً للبث المتدفق. تمرر معاملات أخذ العينات مثل temperature، top_p، stop، seed والعقوبات عبر **kwargs كما هو معتاد.

أعد المحاولة للأخطاء المناسبة

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

لجميع الحالات الثلاث علاج واحد: الانتظار، ثم المحاولة مرة أخرى. يحترم هذا الغلاف الرأس ويتباطأ عند غيابه.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.veo3apis.com/v1",
    api_key="YOUR_API_KEY",
)
import time
from openai import RateLimitError, APIConnectionError, APIStatusError


def call_with_retry(messages, tries=5, **kwargs):
    delay = 2
    for attempt in range(tries):
        try:
            return client.chat.completions.create(
                model="uncensored", messages=messages, **kwargs
            )
        except RateLimitError as err:
            wait = err.response.headers.get("Retry-After")
            time.sleep(int(wait) if wait else delay)
            delay = min(delay * 2, 30)
        except APIConnectionError:
            time.sleep(delay)
            delay = min(delay * 2, 30)
        except APIStatusError as err:
            if err.status_code < 500:
                raise
            time.sleep(delay)
            delay = min(delay * 2, 30)
    raise RuntimeError("request failed after retries")

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

قم بتشغيل مدخلات متعددة بالتزامن

لحلقة تكرار عبر مدخلات كثيرة، يكفي مجموعة الخيوط. عميل الـ SDK آمن للمشاركة عبر الخيوط. اضبط حجم المجموعة حسب مفتاحك: 8 عمال للمفتاح الكامل، و2 للمفتاح التجريبي.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.veo3apis.com/v1",
    api_key="YOUR_API_KEY",
)
import time
from concurrent.futures import ThreadPoolExecutor
from openai import RateLimitError


def summarize(text: str) -> str:
    for _ in range(5):
        try:
            resp = client.chat.completions.create(
                model="uncensored",
                messages=[
                    {"role": "system", "content": "Summarize the text in two sentences."},
                    {"role": "user", "content": text},
                ],
                max_tokens=150,
            )
            return resp.choices[0].message.content.strip()
        except RateLimitError as err:
            time.sleep(int(err.response.headers.get("Retry-After", "5")))
    return ""


documents = ["First long text...", "Second long text...", "Third long text..."]

with ThreadPoolExecutor(max_workers=8) as pool:
    summaries = list(pool.map(summarize, documents))

for s in summaries:
    print(s)

حجم المجموعة ليس هو نفسه معدل الطلب. ثمانية عمال ينهون كل منهم مكالمة في نصف ثانية سيجعلان 960 طلب في الدقيقة، وهو أعلى بكثير من 300. إذا كانت مكالماتك سريعة، أضف تأخيراً صغيراً أو محدد معدل الرمز (token-bucket limiter) لتبقى تحت الحدّ لكل دقيقة. إذا كانت مكالماتك بطيئة، فإن التوازي هو الحدّ الذي ستلتقيه أولاً. الطلبات المتدفقة تحتفظ بمكانها حتى ينتهي البث المتدفق.

المخرجات المهيكلة واستدعاء الدوال

تحوّل ميزتان استدعاء الدردشة إلى خطوة سير عمل يمكن للبرامج الأخرى الاعتماد عليها. يضمن وضع JSON مخرجات قابلة للتحليل. يتيح استدعاء الدوال للنموذج طلب كودك للقيام بشيء ما ثم استخدام الإجابة.

وضع JSON

اضبط response_format ليكون كائن JSON ووصف المفاتيح في الموجّه.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON: {\"title\": string, \"tags\": [string]}"},
        {"role": "user", "content": "A short post about nightly backups."},
    ],
)
post = json.loads(resp.choices[0].message.content)
print(post["title"], post["tags"])

استدعاء الدوال

عرّف الأدوات مع tools، وفرض اختيار مع tool_choice، شغّل الدالة بنفسك وأرسل النتيجة كرسالة مع role: "tool".

from openai import OpenAI

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

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

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

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

تحقق دائماً من وجود tool_calls قبل قراءته. قد يجيب النموذج مباشرة، ويجب أن يتعامل كودك مع كلا النتيجتين.

سلس الخطوات في خط أنابيب

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

from openai import OpenAI

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

def step(system: str, user: str, temperature: float = 0.7) -> str:
    resp = client.chat.completions.create(
        model="uncensored",
        messages=[
            {"role": "system", "content": system},
            {"role": "user", "content": user},
        ],
        temperature=temperature,
        max_tokens=800,
    )
    return resp.choices[0].message.content.strip()


topic = "a changelog entry for a new export feature"

draft = step("Write the requested text in under 120 words.", topic)
review = step(
    "List at most three concrete problems with this text: vague wording, missing detail, wrong tone.",
    draft,
    temperature=0.2,
)
final = step(
    "Rewrite the text so it fixes every listed problem. Reply with the text only.",
    "TEXT:\n" + draft + "\n\nPROBLEMS:\n" + review,
)
print(final)

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

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

تتبع الرصيد ومعرفات الطلب

يحمل كل استجابة رؤوسًا تستحق تسجيلها: يُعرّف X-Request-Id المكالمة عند التواصل مع الدعم، ويُظهر X-Balance-USD ما تبقى من رصيدك، بينما يبلغك الرأسان X-RateLimit-Limit بحدود الطلبات والتزامن المفتوحة لمفتاحك. يخفي الـ SDK الرؤوس افتراضيًا؛ استخدم غلاف الاستجابة الخام لقراءتها.

from openai import OpenAI

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

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with the single word ready."}],
    max_tokens=10,
)

print("request id:", raw.headers.get("X-Request-Id"))
print("balance usd:", raw.headers.get("X-Balance-USD"))
print("req limit:", raw.headers.get("X-RateLimit-Limit-Requests"))
print("concurrency limit:", raw.headers.get("X-RateLimit-Limit-Concurrency"))

resp = raw.parse()
print(resp.choices[0].message.content)

التسعير هو $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، لذا فإن مكالمة تحتوي على 1,000 رمز مدخل و500 رمز مخرج تكلف $0.00015 + $0.00025 = $0.0004. سير عمل يشغل 5,000 من هذه المكالمات ينفق $2.00. اطبع الرصيد في بداية ونهاية التشغيل، وستعرف تكلفة كل دفعة دون أي أدوات إضافية. لمعدلات الأسعار ومكافآت شحن الرصيد، انظر إلى صفحة التسعير؛ لكل معلمة مدعومة، اقرأ وثائق API.

عادة أخرى تستحق اعتمادها: احتفظ بالموجّهات خارج سجلاتك ما لم تكن بحاجة إليها. لا تُستخدم الموجّهات المرسلة إلى هذا الـ API للتدريب، لكن ملفات السجل الخاصة بك تقع تحت مسؤوليتك.

استكشاف أخطاء إعداد جديد

تأتي معظم مشاكل التشغيل الأولي من قائمة قصيرة من الأسباب.

  • تعلق المكالمة أو تظهر أخطاء أثناء الاتصال. تحقق من عنوان URL الأساسي. يجب أن ينتهي بـ /v1، ويضيف الـ SDK /chat/completions تلقائيًا. يعد تكرار المسار الخطأ الشائع.
  • خطأ في المصادقة. المفتاح مفقود، أو مقطوع، أو يحتوي على فراغ أو سطر جديد ناتج عن النسخ واللصق. اطبع طوله، وليس المفتاح نفسه، وقارنه بما يظهر في صفحة المفتاح.
  • نموذج غير موجود. معرف النموذج هو uncensored، بحروف صغيرة. اتصل بنقطة النهاية الخاصة بالنماذج لمعرفة ما يمكن لمفتاحك استخدامه بالضبط.
  • خطأ 429 مستمر في نص برمجي صغير. قد تكون تستخدم مفتاح التجربة، الذي يسمح بـ 2 طلب متزامن و 60 طلبًا في الدقيقة. قلل عدد العاملين إلى 2، أو قم بشحن الرصيد للحصول على مفتاح كامل.
  • إجابات مقطوعة. يؤدي انخفاض max_tokens إلى إنهاء الرد مبكرًا. زد هذه القيمة، أو أزلها واترك الإكمال يستخدم باقي نافذة السياق.
  • طلب كبير جدًا. حد حجم جسم الطلب هو 8 MB، وحد نافذة الرموز هو 100,000 رمز للموجّه والإكمال معًا. قسّم المدخلات الكبيرة إلى أجزاء وعالجها كمكالمات منفصلة.

عندما يبدو أن هناك خطأ في جانب الخدمة، أرسل قيمة X-Request-Id إلى جهة الاتصال في الموقع. يتيح معرف الطلب للمشغل العثور على مكالمتك الدقيقة، وهو أكثر فائدة بكثير من وصف ما رأيته.

01

أسئلة وأجوبة

هل أحتاج إلى SDK خاص؟

لا. يعمل الـ Python SDK الرسمي من OpenAI بمجرد ضبط base URL ومفتاحك.

أي معرّف نموذج أستخدم؟

استخدم uncensored. يمكنك سرد المعرفات المتاحة عبر GET /v1/models.

كم عدد الطلبات التي يمكن تشغيلها بالتوازي؟

المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة. يسمح مفتاح التجربة بـ 2 و60.

هل يعمل البث المتدفق في الـ Python SDK؟

نعم. مرر stream=True وتكرّر عبر القطع. يُبلغ عن الاستخدام في نهاية البث.

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

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

احصل على مفتاح APIاقرأ التوثيق