Best LLM API الدليل
كيفية استخدام واجهة برمجة تطبيقات LLM: من أول طلب إلى البث المتدفق
يعني استخدام واجهة برمجة تطبيقات LLM إرسال قائمة رسائل بصيغة JSON عبر HTTPS وقراءة الرد. تأخذك هذا الدليل من الحصول على مفتاح إلى إرسال أول طلب، ثم إلى البث المتدفق، والإخراج بصيغة JSON، واستدعاء الدوال.
تم التحديث:

نقاط رئيسية
- نقطة النهاية متوافقة مع OpenAI: غيّر Base URL والمفتاح، واحتفظ بـ SDK الخاص بك.
- استخدم معرف النموذج uncensored وأرسل طلب POST إلى /v1/chat/completions.
- يتم دعم البث المتدفق، ووضع JSON، واستدعاء الدوال.
- يعني 429 إبطاء السرعة؛ اقرأ رمز الخطأ لمعرفة السبب.
ما هو استدعاء واجهة برمجة تطبيقات LLM
إذا كنت تتساءل كيفية استخدام خدمات LLM API، فإن الفكرة بسيطة. ترسل طلب HTTPS POST مع قائمة بالرسائل. كل رسالة لها دور (system، user أو assistant) وبعض النص. يشغل الخادم النموذج ويرسل رسالة المساعد التالية. هذا هو العقد بأكمله.
ليس للنموذج ذاكرة بين الاستدعاءات. إذا أردت محادثة، فأرسل الرسائل السابقة مرة أخرى في كل مرة. وهذا هو سبب نمو الموجهات، ونمو التكلفة معها، وأهمية نافذة السياق التي تتسع لـ 100,000 رمز (token): فهي الحد الأقصى لمجموع الموجه والرد.
هذه الخدمة تتحدث نفس بروتوكول واجهة Chat Completions الخاصة بـ OpenAI. يعمل أي SDK متوافق مع OpenAI أو عميل متوافق بمجرد تغيير شيئين، وهما Base URL والمفتاح. يدخل النص ويخرج النص فقط. لا يوجد توليد صور أو صوت أو فيديو، ولا توجد نقطة نهاية للـ embeddings.
يتم استخدام بعض المصطلحات في بقية هذا الدليل. الـ رمز (token) هو جزء من النص، بحجم يساوي تقريباً ثلاثة أرباع كلمة إنجليزية في المتوسط. رموز الإدخال هي كل ما ترسله، ورموز الإخراج هي ما يكتبه النموذج. تُحاسَب على كليهما، بمعدلات مختلفة، ويخبرك الرد بالضبط كم استخدم من كل نوع. الـ base URL هو العنوان الذي يسبقه العميل لكل مسار، ومفتاح API هو السر الذي يثبت أن الطلب ملكك. إذا كنت تعرف هذه الكلمات الأربع، فالباقي روتيني.
الخطوة 1: احصل على مفتاح ولاحظ ثلاث قيم
أنشئ حساباً باستخدام Google، أو باستخدام بريد إلكتروني وكلمة مرور، وافتح صفحة مفتاح API. هناك يمكنك نسخ مفتاحك والمطالبة برصيد $0.50 التجريبي بنقرة واحدة. لا حاجة لبطاقة ائتمان للتجربة.
تحتاج إلى ثلاث قيم لكل طلب:
- عنوان URL الأساسي:
https://api.bestllmapi.com/v1 - معرف النموذج:
uncensored - رأس المصادقة:
Authorization: Bearer YOUR_KEY
احتفظ بالمفتاح خارج نظام التحكم في الإصدارات. ضعهِ في متغير بيئة مثل LLM_API_KEY واقرأه من هناك. أي شخص يملك المفتاح يمكنه إنفاق رصيدك.
الخطوة 2: أرسل طلبك الأول باستخدام curl
يُعد curl أسرع طريقة للتحقق من أن كل شيء يعمل، قبل استخدام أي مكتبة.
export LLM_API_KEY="paste-your-key-here"
curl https://api.bestllmapi.com/v1/chat/completions \
-H "Authorization: Bearer $LLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Explain what a token is in two sentences."}
],
"temperature": 0.7
}'
الرد بصيغة JSON. النص موجود في choices[0].message.content، ويحتوي كائن usage على رموز الموجّه والرد، وهي الأساس في الفوترة. يمكنك أيضاً سرد النماذج عبر GET https://api.bestllmapi.com/v1/models؛ يجب أن ترى uncensored.
تساعدك رؤوس الاستجابة أيضًا. يُعرّف X-Request-Id المكالمة إذا تواصلت مع الدعم، ويُظهر X-Balance-USD ما تبقى في حسابك.
قراءة الاستجابة واختيار المعاملات
تحتوي الاستجابة على بعض الحقول التي يجب معرفتها قبل كتابة أي كود للتحليل. choices هو قائمة، وعادةً ما تريد العنصر الأول. داخله، يحمل message.content النص، ويخبرك finish_reason عن سبب توقف النموذج. تعني القيمة stop أنه انتهى بشكل طبيعي. تعني القيمة length أنه وصل إلى حد max_tokens أو نفدت نافذة السياق، لذا قد يكون الرد مقطوعًا.
يعطي كائن usage رموز (tokens) للموجّه، ورموز الإكمال، والمجموع. سجّل هذه القيم لكل مكالمة منذ اليوم الأول. إنها الطريقة الوحيدة الموثوقة لمعرفة التكلفة الحقيقية لتطبيقك، وتسهل اكتشاف الأخطاء التي ترسل نفس الموجّه الطويل مرتين.
اختيار المعاملات يعتمد بشكل أساسي على نوع المهمة. للاستخراج والتصنيف والبرمجة، استخدم درجة حرارة منخفضة مثل 0.2، بحيث يعطي المدخل نفسه مخرجاً متطابقاً تقريباً. للعصف الذهني والقصص، تعطي القيم من 0.8 إلى 1.0 تنوعاً أكبر. غيّر قيمة واحدة في كل مرة، واستخدم seed عندما تريد مقارنة متكررة بين نسختين من الموجّه.
الخطوة 3: استخدم OpenAI SDK في Python أو Node
في الممارسة العملية، ستستخدم مكتبة. في بايثون، ثبّت المكتبة عبر pip install openai، وجّهها إلى عنوان URL الأساسي الجديد.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.bestllmapi.com/v1",
api_key=os.environ["LLM_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a hiking app."},
],
temperature=0.8,
max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)
نسخة Node متطابقة تقريبًا. قم بالتثبيت باستخدام npm install openai.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.bestllmapi.com/v1",
apiKey: process.env.LLM_API_KEY,
});
const resp = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Give me three names for a hiking app." }],
});
console.log(resp.choices[0].message.content);
يُعد max_tokens اختياريًا. إذا تركته، فقد تستخدم الاستجابة كل ما تبقى من نافذة 100,000 رمز، لذا اضبطه عندما تريد إجابات قصيرة. تُمرر إعدادات أخذ العينات temperature، وtop_p، وstop، وseed، والعقوبات مباشرةً إلى النموذج.
الخطوة 4: بث الرد
بدون البث المتدفق، سيحدق المستخدم في شاشة فارغة حتى يكتمل الرد بالكامل. مع stream: true، يرسل الخادم الرموز عبر أحداث الإرسال من الخادم (SSE) بمجرد إنتاجها، وتصل إجماليات الاستخدام في النهاية.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
print("\nTokens:", chunk.usage.total_tokens)
شيء واحد يجب تذكره: يحتفظ الطلب المتدفق بخانة التزامن الخاصة به حتى ينتهي البث. يسمح المفتاح الكامل بـ 8 طلبات متزامنة، بينما يسمح المفتاح التجريبي بـ 2. إذا أغلق المستخدم علامة التبويب، أغلق البث من جانبك أيضًا، وإلا ستظل الخانة مشغولة.
إدامة المحادثة
نظرًا لأن الـ API لا يحتوي على ذاكرة، فإن تطبيق الدردشة عبارة عن حلقة تضيف إلى قائمة. النمط أدناه هو جوهر معظم تطبيقات الدردشة.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])
messages = [{"role": "system", "content": "You are a friendly travel planner."}]
while True:
user_text = input("You: ")
if user_text.strip().lower() in ("quit", "exit"):
break
messages.append({"role": "user", "content": user_text})
resp = client.chat.completions.create(model="uncensored", messages=messages)
answer = resp.choices[0].message.content
messages.append({"role": "assistant", "content": answer})
print("Bot:", answer)
كل تكرار ترسل القائمة كاملة، لذا ترتفع التكلفة لكل دورة مع طول المحادثة. السعر هو $0.15 لكل مليون رمز مدخل و $0.50 لكل مليون رمز مخرج. دورة تحتوي على 2,000 رمز مدخل و 400 رمز مخرج تكلف 2,000 / 1,000,000 x $0.15 = $0.0003 زائد 400 / 1,000,000 x $0.50 = $0.0002، أي $0.0005. بهذا المعدل، يغطي رصيد التجربة بقيمة $0.50 حوالي 1,000 دورة.
عندما تصبح القائمة طويلة، احذف أقدم رسائل المستخدم والمساعد، لكن احتفظ برسالة النظام في الأعلى. أو اطلب من النموذج كتابة ملخص قصير للجولات المبكرة واستبدلها به.
الخطوة 5: وضع JSON واستدعاء الأدوات
عندما يحتاج كودك إلى تحليل الرد، اطلب صيغة JSON. اضبط response_format على {"type": "json_object"} وأضف كلمة "JSON" في الموجّه أيضاً حتى يعرف النموذج الشكل المطلوب.
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply only with JSON."},
{"role": "user", "content": "Extract name and city: 'Maria lives in Lisbon.' Use keys name and city."},
],
)
print(json.loads(resp.choices[0].message.content))
يسمح استدعاء الدوال النموذج بطلب تشغيل دالة في كودك. تصف الدالة في tools؛ يرد النموذج بإدخال tool_calls بدلاً من النص؛ تقوم بتشغيل الدالة وترسل النتيجة مرة أخرى باستخدام role: "tool".
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up 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:
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)
result = {"order_id": args["order_id"], "status": "shipped"}
messages.append(msg)
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)
قد تنتج النماذج أحياناً وسائط غير صالحة، لذا قم بتغليف json.loads في كتلة try في الكود الفعلي وأرسل خطأ كنتيجة للدالة إذا فشل التحليل.
عند حدوث خطأ
معظم مشاكل اليوم الأول هي واحدة من هذه.
- 401 أو خطأ في المصادقة: المفتاح مفقود، يحتوي على خطأ مطبعي، أو أن الرأس ليس بصيغة
Bearer KEY. - 404: عنوان URL الأساسي يفتقر إلى
/v1، أو أنك اتصلت بالمسار الخاطئ. مسار المحادثة هو/v1/chat/completions. - 429 مع رمز
rate_limited: لقد تجاوزت حدّ المعدل للطلبات في الدقيقة (300 على مفتاح كامل، 60 على مفتاح تجريبي). - 429 مع الرمز
concurrency: عدد كبير جداً من الطلبات في وقت واحد (8 للمفتاح الكامل، 2 لمفتاح التجربة). قم بترتيب طلباتك في طابور. - 429 مع
Retry-After: 5: حمل زائد مؤقت. انتظر خمس ثوانٍ وأعد المحاولة. - الطلب كبير جداً: حدّ حجم الـ body هو 8 MB، ويجب أن يتسع الـ prompt والرد معاً لـ 100,000 رمز.
الطلبات الفاشلة أو المرفوضة لا تُحسب، لذا فإن إعادة المحاولة بعناية لا تكلف شيئاً إضافياً. لكل رمز خطأ ومزيد من الأمثلة، اقرأ التوثيق، وشاهد الأسعار لتقدير تكلفة عبء العمل بسعر $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج.
إعادة المحاولة بأدب في الكود
سكربت يرسل العديد من الطلبات سيواجه حتماً خطأ 429. الحل هو غلاف إعادة محاولة صغير ينتظر ثم يحاول مرة أخرى. تحترم هذه النسخة فترة الانتظار لمدة خمس ثوانٍ التي يطلبها API عند الحمل الزائد المؤقت.
import os, time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.bestllmapi.com/v1", api_key=os.environ["LLM_API_KEY"])
def ask(prompt, tries=5):
for attempt in range(tries):
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
except RateLimitError:
time.sleep(5 * (attempt + 1))
raise RuntimeError("still rate limited after retries")
print(ask("List three uses for a paperclip."))
إذا كنت تشغل العديد من الطلبات بالتوازي، حدد عدد العمال ضمن حدّ التزامن الخاص بك. مجموعة خيوط (thread pool) بحجم 8 تتوافق مع مفتاح كامل، و 2 تتوافق مع مفتاح تجريبي. تجاوز ذلك ينتج فقط أخطاء concurrency.
المزيد من الأدلة
أسئلة وأجوبة
هل أحتاج إلى SDK خاص؟
لا. أي SDK متوافق مع OpenAI أو عميل متوافق مع OpenAI يعمل. اضبط عنوان URL الأساسي على https://api.bestllmapi.com/v1, لاستخدام مفتاحك، واضبط النموذج على uncensored.
هل يمكنني تجربته قبل الدفع؟
نعم. يمكن للمستخدمين الجدد الحصول على رصيد تجريبي بقيمة $0.50 بنقرة واحدة في صفحة مفتاح API. لا يتطلب بطاقة وهو صالح لمدة 7 أيام.
هل تتذكر الواجهة الرسائل السابقة؟
لا. أرسل سجل المحادثة في قائمة الرسائل في كل طلب. يجب أن يتسع الـ prompt والرد ضمن نافذة السياق التي تتكون من 100,000 رمز (token).
ماذا يعني خطأ 429؟
لقد وصلت إلى حد. يعني الرمز rate_limited تجاوز عدد الطلبات في الدقيقة، ويعني concurrency تجاوز عدد الطلبات في وقت واحد، ويعني رأس Retry-After حدوث حمل زائد قصير.
مفتاحك على بُعد استمارة واحدة
أنشئ حساباً، وانسخ المفتاح، ثم غيّر عنوان URL الأساسي. هذه هي الإعدادات الكاملة.