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

نقاط رئيسية
- تدعم نقطة النهاية الأدوات، tool_choice، tool_calls المتدفقة ونتائج role: tool.
- حدّ حلقة عملك، تحقق من حجج الأدوات وأعد المحاولة مع استجابات 429 بفترة انتظار قصيرة.
- احتفظ بالمعالجات المتوازية عند أو أقل من 8 على مفتاح كامل؛ يحمل البث المتدفق فتحة حتى ينتهي.
- تتطلب تشغيل وكيل من ست خطوات مع نمو في السياق تكلفة تقارب نصف سنت واحد.
ما الذي يحتاجه الوكيل من واجهة برمجة التطبيقات
إذا كنت تختار واجهة برمجة تطبيقات نماذج LLM للوكلاء، فإن قائمة التحقق أقصر مما تقترحه التسويق. تحتاج إلى استدعاء أدوات موثوق، نافذة سياق كبيرة بما يكفي لاستيعاب المحادثة الجارية، حدود معدل قابلة للتنبؤ، وسعر لا يعاقب حلقة تعمل العديد من المكالمات.
تغطي هذه الـ API تلك النقاط عبر واجهة OpenAI القياسية. تدعم tools وtool_choice، وتعيد tool_calls في كل من الاستجابات العادية والمُدفقة (streamed)، وتقبل نتائج الأدوات كرسائل مع role: "tool". يتوفر وضع JSON عبر response_format. تبلغ نافذة السياق 100,000 رمز (token) للموجّه (prompt) بالإضافة إلى الإكمال، ومعرف النموذج هو uncensored.
بما أن جانب الإطار هو مجرد عميل OpenAI، فإن معظم مكتبات الوكلاء التي تتيح لك تعيين عنوان URL أساسي ستعمل. توجهها إلى https://api.llmmodelsapi.com/v1، وزوّد بمفتاحك وحدد اسم النموذج. تفاصيل الإعداد موجودة في التوثيق، ويمكنك الحصول على مفتاح من صفحة المفاتيح.
يحدد اثنان من الحدود التصميم. أولاً، النموذج للنصوص فقط، لذا يجب أن يحدث أي معالجة للصور أو الصوت أو الملفات في أدواتك ويعود كنص. ثانياً، لا توجد تضمينات على نقطة النهاية هذه، لذا إذا كان وكيلك يقوم بالاسترجاع، فيحتاج البحث المتجه إلى مصدر آخر.
موجّه نظام يحافظ على عقلانية الحلقة
يأتي معظم فشل الوكلاء من التعليمات الغامضة، وليس من واجهة برمجة التطبيقات. يخبرك الموجّه النظامي الجيد بالنموذج من هو، وما هي الأدوات المتاحة، ومتى يتوقف وما هو تنسيق الإجابة النهائية. إليك واحدًا لمساعد بحث.
أنت مساعد بحث. يمكنك استدعاء أدوات search_notes و read_note. استدعِ أداة فقط عندما تحتاج إلى معلومات لا تملكها بالفعل. استخدم ما لا يزيد عن خمس استدعاءات للأدوات. عندما يكون لديك ما يكفي، رد بإجابة قصيرة وقائمة بمعرفات الملاحظات التي استخدمتها. إذا لم تحتوي الملاحظات على الإجابة، قل ذلك بوضوح.
لاحظ ما يفعله. يحدد الأدوات، ويحدد ميزانية المكالمات، ويحدد شرط التوقف ويمنح النموذج الإذن بالقول إنه لا يعرف. الجزء الأخير مهم، لأن الوكيل الذي يُجبر على الإجابة سيخترع شيئًا.
عيّن درجة حرارة منخفضة لاستخدام الأدوات. القيم حول 0.2 إلى 0.4 تحافظ على استقرار أسماء الأدوات وتنسيقات الحجج. إذا كان وكيلك يكتب أيضاً نصاً إبداعياً في النهاية، يمكنك رفع درجة الحرارة لذلك الاستدعاء النهائي فقط. يتم تمرير معلمة seed كما هي، وهو ما يساعد عندما تريد إعادة تشغيل التجربة أثناء تصحيح الأخطاء.
بالنسبة لوكلاء الخيال للبالغين ولعب الأدوار، يعمل نفس النمط: ضع الشخصية وقواعد المشهد والأدوات في رسالة النظام. النموذج مُضبط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. محتوى الجنس الذي ينطوي على قاصرين يظل خارج الحدود المسموح بها.
حلقة وكيل بسيطة في Python
الحلقة أدناه تحتوي على أداة واحدة، وهي بحث في قاموس يمثل بياناتك الحقيقية. تتوقف عندما يرد النموذج بدون استدعاء أداة، أو بعد عدد ثابت من الخطوات.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")
NOTES = {
"n1": "Invoice 114 was paid on March 3.",
"n2": "Invoice 115 is overdue by 12 days.",
}
def search_notes(query):
return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]
TOOLS = [{
"type": "function",
"function": {
"name": "search_notes",
"description": "Search internal notes by keyword",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
}]
SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."
def run(question, max_steps=6):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": question},
]
for step in range(max_steps):
resp = client.chat.completions.create(
model="uncensored",
messages=messages,
tools=TOOLS,
temperature=0.3,
max_tokens=500,
)
msg = resp.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
try:
args = json.loads(call.function.arguments)
result = search_notes(args["query"])
except Exception as exc:
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: step limit reached."
print(run("Which invoice is overdue?"))
تستحق ثلاثة تفاصيل الانتباه. حد الخطوات يمنع النموذج المشوش من التكرار حتى ينفد رصيدك. يحول كتلة try سلسلة حجة غير صالحة إلى رسالة خطأ يمكن للنموذج قراءتها وتصحيحها. وكل نتيجة أداة تُرسل مرة أخرى مع tool_call_id المطابق، وهو ما يعرف به النموذج أي استدعاء ينتمي إليه كل إجابة.
التعامل مع استجابات 429 والتزامن
الوكلاء متفجرون. قد يوزع المخطط فرعيًا خمس مهام فرعية في وقت واحد، وكل منها يشغل حلقة خاصة به. هذا هو المكان الذي تظهر فيه حدود المعدل.
يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 و60. بعد تجاوز الحد، تجيب الواجهة API بـ HTTP 429. يرمز رمز الخطأ إلى الحد الذي وصلته: rate_limited للطلبات في الدقيقة، concurrency للكثير في وقت واحد. في حالة الحمل الزائد المؤقت، تحصل أيضاً على 429، مع رأس Retry-After: 5.
عامل مع كل هذه كقابلة لإعادة المحاولة. انتظر عدد الثواني في الرأس، أو بضع ثوانٍ إذا كان غائبًا، وأرسل الطلب مرة أخرى. الطلبات الفاشلة لا تُحسب، لذا فإن إعادة المحاولة لا تكلف شيئًا. غلاف صغير يؤدي المهمة.
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)
def chat_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(model="uncensored", **kwargs)
except RateLimitError as err:
wait = 5
if err.response is not None:
wait = int(err.response.headers.get("retry-after", 5))
time.sleep(wait)
raise RuntimeError("Still rate limited after 5 attempts")
لتجنب 429 من الأساس، حدّ مجموعة عمالك. يتطابق قفل السعة (semaphore) من 8 مع المفتاح الكامل. إذا كنت تبث الاستجابات إلى واجهة مستخدم، تذكر أن البث يحتفظ بفتحة التزامن حتى وصول الرمز الأخير، لذا فإن عميلاً بطيئاً يقرأ إجابة طويلة يشغل فتحة طوال الوقت. قراءة رؤوس X-RateLimit-Limit-Requests وX-RateLimit-Limit-Concurrency تتيح لكبرمجتك التكيف مع أي مفتاح يستخدمه.
السياق، الذاكرة وتكلفة التشغيل
كل خطوة في الحلقة تعيد إرسال السجل الكامل. هذا كيف تعمل واجهات الدردشة، وهذا يعني أن رموز المدخلات تنمو مع كل استدعاء أداة. خذ تشغيلًا من ست خطوات حيث يبدأ الموجّه بـ 2,000 رمز وينمو بـ 1,000 لكل خطوة، مع 300 رمز مخرج لكل خطوة.
- رموز المدخلات: 2,000 + 3,000 + 4,000 + 5,000 + 6,000 + 7,000 = 27,000
- رموز المخرجات: 6 x 300 = 1,800
- تكلفة المدخلات: 27,000 x 0.15 / 1,000,000 = $0.00405
- تكلفة المخرجات: 1,800 × 0.50 / 1,000,000 = $0.0009
- الإجمالي: $0.00495 لكل تشغيل
تتكلف ألف عملية من هذا النوع $4.95. وهذا رخيص بما يكفي للسماح للوكيل بالتفكير في عدة خطوات، لكن النمو يستحق المتابعة. مع وجود مساحة لـ 100,000 رمز، سيمتلئ نافذة السياق في النهاية لدى وكيل طويل التشغيل، وستكلف الموجّه الذي بهذا الحجم 100,000 × 0.15 / 1,000,000 = $0.015 للإدخال في كل خطوة.
ثلاث عادات تبقي التكلفة تحت السيطرة. اقتطع نتائج الأدوات الكبيرة قبل إدراجها في المحادثة، مثل أول 2,000 حرف من صفحة ويب. لخص الخطوات القديمة في رسالة قصيرة واحدة بمجرد تجاوز السجل حداً معيناً. واحفظ الحقائق الدائمة في قاعدة بياناتك الخاصة بدلاً من الاعتماد على المحادثة كذاكرة.
يُظهر رأس X-Balance-USD في كل استجابة الرصيد المتبقي، مما يسمح لمشرف الوكيل بإيقاف التشغيل عندما ينخفض الرصيد تحت حد أدنى. الرصيد مسبق الدفع من $20، ولا ينتهي. انظر إلى صفحة الأسعار للحصول على مكافآت الشحن.
حدود صادرة للتخطيط حولها
تحتاج الوكلاء المبنية على أي نموذج إلى ضوابط، وهذا النموذج ليس استثناءً. كن مستعداً لما يلي.
- حجوز غير صالحة. يمكن للنموذج إنتاج حجوز أدوات لا تكون صالحة بصيغة JSON أو تفتقر إلى حقل مطلوب. قم بالتحقق من صحة الحجوز بشكل دفاعي وأعد الخطأ كنتيجة للأداة.
- اختيار الأداة خاطئ. اكتب وصفًا قصيرًا ومميزًا لكل أداة. إذا تشابهت أدوات، قد يخلط النموذج بينها. استخدم
tool_choiceلفرض استدعاء محدد عندما يتطلب التدفق ذلك. - نص فقط. لا يوجد إدخال أو إخراج للصور، ولا صوت، ولا تضمينات، ولا ضبط دقيق. قم بهذه الأجزاء في مكان آخر ومرر النتيجة كنص.
- نموذج واحد. يوجد نموذج مفتوح الأوزان واحد خلف نقطة النهاية، وليس موزعاً عبر موردين. لا يمكنك اختيار نموذج أصغر للخطوات السهلة.
- أدوات مدمرة. لا تمنح الوكيل أداة حذف أو دفع دون خطوة تأكيد في كودك الخاص.
تستفيد وكلاء التخطيط أيضاً من مرحلة ثانية. بعد أن يعيد الحلقة إجابة، يمكنك إجراء استدعاء رخيص آخر يطلب من النموذج التحقق من الإجابة مقابل نتائج الأدوات التي رآها، باستخدام وضع JSON لإرجاع حكم وقائمة بالادعاءات غير المدعومة. يضيف ذلك بضع مئات من الرموز ويكشف عن الفشل الأكثر شيوعاً، وهو إجابة واثقة تتجاهل ما أوردته الأدوات.
أخيراً، سجّل كل خطوة. احفظ الرسائل، وحجوز الأدوات، ورأس X-Request-Id من كل استجابة. عندما يفشل التشغيل، يسمح معرّف الطلب بالرجوع إلى الاستدعاء المحدد، ويظهر السجل المسجل أي نتيجة أداة أضلت النموذج. من الأسهل تحسين الوكلاء عندما يمكنك إعادة تشغيل فشل معين وتغيير شيء واحد في كل مرة.
اختبر الوكيل بالتجربة قبل الالتزام. يمكن للمستخدمين الجدد الحصول على $0.50 من الرصيد، وهو ما يغطي حوالي 101 تشغيل كامل (0.50 / 0.00495) في التشغيل ذي الخطوات الست المذكور أعلاه. ضع في اعتبارك طلبات التشغيل المتزامنة البالغ عددها 2 في التجربة وشغّل وكيل واحد في كل مرة. للحصول على نظرة أوسع على الخدمة، اقرأ ملخص الدفع حسب الرمز. لا تُستخدم الموجّهات في التدريب.
المزيد من الأدلة
أسئلة وأجوبة
هل تدعم الواجهة البرمجية استدعاء الأدوات للوكلاء؟
نعم. يقبل الأدوات وtool_choice، ويعيد tool_calls (حتى عند البث المتدفق)، ويقبل النتائج كرسائل بـ role: tool.
كم عدد استدعاءات الوكيل التي يمكن تشغيلها بالتزامن؟
المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة. المفتاح التجريبي يسمح بـ 2 متزامن و60 في الدقيقة.
ماذا يجب أن يفعل الوكيل عندما يحصل على 429؟
انتظر قيمة Retry-After، أو بضع ثوانٍ إذا لم تكن موجودة، ثم أعد المحاولة. الطلبات المرفوضة لا تُحسب.
هل يمكن للوكيل التعامل مع الصور أو الصوت؟
لا. يعمل النموذج مع النص فقط، لذا يجب معالجة أي وسائط أخرى بواسطة أدواتك الخاصة وإدراجها كنص.
مفتاحك على بُعد نموذج واحد
أنشئ حساباً، وانسخ المفتاح، ثم غيّر عنوان URL الأساسي. هذه هي الإعدادات الكاملة.