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

نقاط رئيسية
- مكالمة دردشة واحدة تحول فكرة أولية إلى موجّه جاهز؛ معرّف النموذج هو uncensored.
- وضع JSON يعيد حقولاً يمكن لبرمجيتك تخزينها والبحث فيها.
- المفتاح الكامل يشغّل 8 طلبات متزامنة و300 طلب في الدقيقة؛ أعد المحاولة عند أخطاء 429 باستخدام Retry-After.
- الواجهة تكتب النصوص فقط؛ ألصق الموجّه في أداة الفيديو أو الصور الخاصة بك.
ما الذي تفعله واجهة برمجة تطبيقات LLM في عمل الموجهات
واجهة برمجة تطبيقات LLM للموجهات ممتازة في الجزء الذي يُرهق الناس من عمل الموجهات: تحويل فكرة من ثلاث كلمات إلى وصف كامل، كتابة عشرة متغيرات لنفس المشهد، أو إعادة كتابة موجه ليتمسك بتنسيق المنزل. ترسل الفكرة الأولية ومجموعة من القواعد، وتحصل على نص موجه جاهز. لأن نقطة النهاية متوافقة مع OpenAI، فإن الكود هو نفس مكالمة الدردشة التي ستكتبها لأي نموذج آخر.
حد واحد أولاً. هذه الخدمة تُرجع نصًا فقط. لا تعرض الفيديو أو الصور أو الصوت. إذا كان هدفك النهائي هو مقطع من أداة لتوليد الفيديو من النص، فإن واجهة برمجة التطبيقات تكتب الموجه، وتقوم بلصق أو توجيه هذا الموجه إلى أي مولّد تستخدمه. هذا الفصل مفيد بحد ذاته، لأن كتابة الموجهات هي الخطوة البطيئة والمتكررة، ورموز النص رخيصة.
النموذج هو نموذج مفتوح الأوزان مُعدّ للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين، لذا فإن مهمة كتابة موجه حول مشهد إثارة مظلم أو معركة فانتازيا عنيفة لن تُرفض مع محاضرة. الحد الصارم الوحيد هو أنه لن يتم إنتاج أي شيء يتضمن قاصرين في المحتوى الجنسي.
مكالمة كاتبة موجهات أولى في Python
ثبّت الـ SDK مع pip install openai ووجّهه نحو URL الأساسي. معرف النموذج هو uncensored، ويُدرج المفتاح كرمز Bearer، ويتولى الـ SDK ذلك لك.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
SYSTEM = (
"You write prompts for a text-to-video tool. "
"Given a rough idea, reply with one prompt of 60 to 90 words. "
"Name the subject, the camera movement, the lighting and the mood. "
"Reply with the prompt only, no preamble."
)
def expand(idea: str) -> str:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": idea},
],
temperature=0.8,
max_tokens=300,
)
return resp.choices[0].message.content.strip()
print(expand("a lighthouse during a storm, seen from a drone"))
ثلاث تفاصيل تجعل هذا العمل أفضل من المحاولة الأولى عادةً. رسالة النظام تحدد الطول والعناصر التي يجب أن يذكرها كل موجه، لذا تظل المخرجات قابلة للمقارنة. ضبط temperature حول 0.8 يعطي تنوعًا بين التشغيلات دون الانحراف عن الفكرة. وmax_tokens اختياري هنا، لكن الحد الأقصى لـ 300 يمنع الرد الطويل من أن يكلّف أكثر مما ينبغي. إذا تركته، يمكن للإكمال استخدام ما تبقى من نافذة الـ 100,000 رمز.
إذا كنت تريد عشر تجارب لفكرة واحدة، لا تُكرر الحلقات عشر مرات بنفس الإعدادات وتأمل. إما أن ترفع درجة الحرارة وتمرر seed مختلفًا لكل مكالمة، أو اطلب عشرة موجهات مرقمة في رد واحد وقسّمها في الكود. الخيار الثاني أرخص لأن التعليمات تُرسل مرة واحدة.
إرجاع موجهات منظمة بوضع JSON
النص الحر جيد للإنسان. بمجرد أن يستهلك النص المخرجات، تريد حقولًا. وضع JSON يجعل الرد كائن JSON صالح، لذا يمكنك قراءة الموجه، والعناصر التي تريد استبعادها وبعض الوسوم دون كتابة محلل هش. اذكر كلمة JSON والمفاتيح التي تتوقعها في رسالة النظام، واضبط response_format.
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": (
"Return a JSON object with the keys prompt (string), "
"avoid (string) and tags (list of at most five short strings)."
),
},
{"role": "user", "content": "a night market in the rain, handheld camera"},
],
)
data = json.loads(resp.choices[0].message.content)
print(data["prompt"])
print(data["tags"])
احفظ الكائن، وليس النص فقط. جدول بأعمدة للفكرة، والموجه النهائي، والوسوم والتاريخ يتيح لك البحث في سجلك لاحقًا، ويجعل من السهل رؤية أي التعليمات أنتجت الموجهات التي احتفظت بها.
عندما يجب أن يتبع المخرج تنسيقًا لا يلتقطه JSON، مثل ترتيب ثابت لخطوط موسومة، قل ذلك بمثال واحد ملموس داخل رسالة النظام. النماذج تنسخ الأمثلة بشكل أكثر موثوقية من اتباعها للوصف المجرد.
بث النتيجة لأدوات تفاعلية
إذا كان شخص ما ينتظر النتيجة، على سبيل المثال في أداة موجهات داخلية أو لوحة دردشة، بث الإجابة لتظهر الكلمات الأولى فورًا. اضبط stream: true؛ تصل الإجابة كحدث يرسله الخادم، ويُبلغ عن الاستخدام في نهاية البث.
from openai import OpenAI
client = OpenAI(
base_url="https://api.veo3apis.com/v1",
api_key="YOUR_API_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Rewrite the user's prompt to be more specific about camera and light."},
{"role": "user", "content": "a man walking through a foggy forest"},
],
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()
تذكر أن الطلب المُبثّ يحتفظ بفتحة التزامن الخاصة به حتى ينتهي البث. المفتاح الكامل يسمح بـ 8 طلبات في وقت واحد، لذا فإن ثمانية مستخدمين يقرأون بثًا بطيئًا في نفس اللحظة سيحجبون التاسع. لأداة داخلية صغيرة، هذا كافٍ. لأي شيء عام، رتب الطلبات من جانبك.
تشغيل دفعة ضمن حدود المعدل
مهام كتابة الموجهات التي توفر أكثر وقت هي الدفعات: 500 لقطة منتج، 200 فكرة مشهد من نص، جدول بيانات كامل من الأسطر الأولية. المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة، والمفتاح التجريبي يسمح بـ 2 و60. مجموعة خيوط بحجم المفتاح هي أبسط طريقة للبقاء ضمن كلا الرقمين.
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
SYSTEM = "Turn the idea into one 60 to 90 word video prompt. Reply with the prompt only."
def expand(idea: str) -> str:
for attempt in range(4):
try:
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": idea},
],
max_tokens=300,
)
return resp.choices[0].message.content.strip()
except RateLimitError as err:
wait = int(err.response.headers.get("Retry-After", "5"))
time.sleep(wait)
raise RuntimeError("gave up on: " + idea)
ideas = ["a paper boat in a gutter", "a train crossing a salt flat", "a chef plating dessert"]
with ThreadPoolExecutor(max_workers=8) as pool:
prompts = list(pool.map(expand, ideas))
for idea, prompt in zip(ideas, prompts):
print(idea, "->", prompt[:80])
يمكن أن يعني 429 شيئين. رمز الخطأ rate_limited يعني أنك تجاوزت الطلبات في الدقيقة؛ concurrency يعني أن هناك طلبات كثيرة تعمل في وقت واحد. الحمل الزائد المؤقت يُرجع أيضًا 429 مع رأس Retry-After: 5. الحلقة أعلاه تنتظر طالما يقول الرأس وتعيد المحاولة. الطلبات الفاشلة أو المرفوضة لا تُحتسب رسومها، لذا فإن إعادة المحاولة لا تضاعف التكلفة.
اكتب النتائج على القرص أثناء التقدم، سطر واحد لكل موجه جاهز. ملف JSON-lines يعمل جيدًا: كائن واحد لكل سطر يحمل الفكرة، والموجه والوقت، حتى يتمكن التشغيل المنهار من تخطي ما تم إنجازه بالفعل عند إعادة تشغيله. دفعة من بضعة آلاف من المكالمات ستضرب في النهاية لحظة شبكة سيئة، ولا تريد أن تبدأ من جديد من الأعلى.
ضع دليل الأسلوب في نافذة السياق التي تتسع لـ 100k
الموجهات تصبح أفضل عندما يعرف النموذج قواعدك. مع نافذة تتسع لـ 100,000 رمز، الموجه والإكمال، يمكنك وضع الكثير في رسالة النظام: دليل أسلوب، قائمة بالعبارات المحظورة، عشرون موجهًا معتمدًا كمثال، وقاموس لكيفية تسمية فريقك لحركات الكاميرا.
استخدم هذه المساحة عن قصد، واحتفظ بقاعدة واحدة في ذهنك: النموذج يتبع ما هو مكتوب، لذا اكتب القواعد كما لو كنت توجّه زميلًا جديدًا. قائمة قصيرة من خمس أمثلة ممتازة تفوق خمسين مختلطة، لأن النموذج يجمع متوسط ما يراه. ضع الأمثلة بنفس التنسيق الذي تريد استلامه. إذا كان للمشروع شخصية متكررة، اكتب ورقة الشخصية مرة واحدة، مع الشعر والملابس والعمر (شخصيات بالغة فقط) موصوفة بكلمات ثابتة، وأخبر النموذج بنسخ تلك الكلمات حرفيًا في كل موجه. هذه أرخص حيلة متاحة للاتساق: نفس العبارة تظهر في كل موجه، لذا يرى المولد في الأسفل نفس الوصف في كل مرة.
التعليمات الطويلة تُعاد إرسالها مع كل مكالمة، لذا تُحتسب رسومها مع كل مكالمة. عند $0.15 لكل مليون رمز مدخل، فإن دليل الأسلوب الذي يتكون من 3,000 رمز يكلف $0.00045 لكل مكالمة في المدخلات فقط. هذا مبلغ صغير، ولكن عبر 10,000 مكالمة، يصبح $4.50، لذا قم بتقليص الدليل بمجرد أن يعمل. صفحة التسعير تحتوي على المعدلات الكاملة إذا كنت تريد تشغيل أرقامك الخاصة.
المشاكل الشائعة وكيفية حلها
تظهر بعض الأخطاء مرة تلو الأخرى في خطوط أنابيب كتابة الموجهات.
- إدخال في المخرجات. الردود التي تبدأ بـ "إليك الموجه الخاص بك:" تُدرج داخل المولد. أنهِ رسالة النظام بـ "أجب بالموجه فقط" ثم احذف النتيجة.
- الموجّهات الطويلة جدًا. زيادة عدد الكلمات لا تعطي دائمًا فيديو أو صورًا أفضل. حدد نطاقًا للكلمات في التعليمات وتحقق منه في الكود.
- نفس الفكرة، نفس المخرجات. إذا مررت
seedبقيمة ثابتة، تتكرر التشغيلات. غيّر البذرة لكل عنصر، أو اتركها خارجًا عندما تريد التنوع. - خلط الأدوار. احتفظ بالقواعد في رسالة النظام والفكرة في رسالة المستخدم. وضع كليهما في كتلة واحدة يجعل النموذج يعامل قواعدك كمحتوى لإعادة كتابته.
- الانحراف عبر دفعة طويلة. قد تنزلق الجودة عندما تعمل التعليمات نفسها آلاف المرات. افحص عينات من بداية الدفعة ووسطها ونهايتها، واحتفظ برسالة النظام تحت التحكم في الإصدارات لتعرف أي صياغة أنتجت أي دفعة.
- عدم وجود خطوة مراجعة. اقرأ عينة من كل دفعة قبل إرسال الموجّهات إلى أداة لاحقة مكلفة. عشر دقائق من القراءة توفر الكثير من عمليات التوليد المهدرة.
للبدء، أنشئ حساباً، واحصل على رصيد تجريبي بقيمة $0.50 من صفحة مفتاح API، ثم شغّل السكربت الأول أعلاه. الرصيد التجريبي مخصص لمرة واحدة لكل شخص، ويستمر لمدة 7 أيام ولا يتطلب بطاقة. يدرج الدليل كل معلمة يتم تمريرها، بما في ذلك top_p، وstop، والغرامات.
المزيد من الأدلة
أسئلة وأجوبة
هل يمكن لهذه الواجهة إنشاء الفيديو نفسه؟
لا. هي تولد النصوص فقط. استخدمها لكتابة الموجّه، ثم مرر هذا الموجّه إلى أداة الفيديو التي تختارها.
كم عدد الموجّهات التي يمكنني كتابتها في الدقيقة؟
المفتاح الكامل يسمح بـ 300 طلب في الدقيقة و8 في وقت واحد. مفتاح التجربة يسمح بـ 60 في الدقيقة و2 في وقت واحد.
ماذا يحدث إذا أرسلت الكثير من الطلبات؟
تستقبل HTTP 429 مع رمز rate_limited أو concurrency. انتظر قيمة Retry-After، ثم أرسل الطلب مرة أخرى.
هل تُستخدم الموجّهات الخاصة بي للتدريب؟
لا. لا تُستخدم الموجّهات للتدريب.
مفتاحك على بُعد استمارة واحدة
أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.