قبل تشغيل أي شيء
لا تحتاج سوى إلى مفتاح. أنشئ واحدًا على صفحة مفتاح API؛ يمكن للحسابات الجديدة المطالبة برصيد تجريبي مجاني بقيمة $0.50 بنقرة واحدة، بدون بطاقة. قم بتصديره حتى تتمكن الأمثلة من قراءته:
export API_KEY="YOUR_KEY"
pip install openai
npm install openai
تتبع API تنسيق إكمال الدردشة الخاص بـ OpenAI. تعرض POST /v1/chat/completions وGET /v1/models، تقبل Authorization: Bearer، وتقدم نموذجًا واحدًا بمعرف uncensored. هذا النموذج هو نموذج مفتوح الأوزان الذي يشغله مزود مستقل ومضبوط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. إنه ليس API الرسمي لأي بائع نماذج. يتعامل مع النصوص فقط: لا صور، ولا صوت، ولا تضمينات، ولا ضبط دقيق.
تتدرج الأمثلة أدناه من أبسط استدعاء إلى استدعاء الدوال. إذا كنت بحاجة فقط إلى أقصر تحقق ممكن يعمل فيه مفتاحك، فإن أمر curl الأول كافٍ.
طلب أولي باستخدام curl، والمعلمات التي تهم
curl https://api.glmapikey.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "What is a mutex, in one sentence?"}
],
"temperature": 0.3,
"max_tokens": 80
}'
الاستجابة هي كائن JSON يحتوي على choices[0].message.content الذي يحمل الإجابة، وكائن usage يحتوي على prompt_tokens وcompletion_tokens. تتضمن رؤوس الاستجابة X-Request-Id، وX-Balance-USD، والرأسين X-RateLimit-Limit. أضف -i إلى curl لعرضها.
تُمرر الحقول temperature، وtop_p، وstop، وseed، وعقوبات التواجد والتردد مباشرة إلى النموذج. يعتبر max_tokens اختياريًا. بدونه، يمكن أن يستغرق الإكمال كل ما تبقى من نافذة الـ 100,000 رمز بعد موجّهك.
يحتوي جسم إكمال الدردشة على العديد من الحقول الاختيارية، لكن خمسة منها تؤدي معظم العمل. يتم تمرير جميعها إلى النموذج.
| الحقل | ما يفعله | الاستخدام النموذجي |
|---|---|---|
temperature | تعطي القيم الأعلى صياغة أكثر تنوعًا | 0.2 للاستخراج، 0.8 للخيال |
top_p | تحدّ من العيّنة لأكثر الرموز احتمالًا | اتركها على الإعداد الافتراضي ما لم تقم بضبطها |
stop | ينهي الرد عند ظهور سلسلة نصية | القطع عند محدد مثل سطر فارغ |
seed | يجعل العيّنة قابلة للتكرار بأفضل جهد ممكن | مقارنة نسختين من الموجّه |
presence_penalty، وfrequency_penalty | تثبيط تكرار الرموز | قيم صغيرة مثل 0.3 عندما تتكرر النصوص |
غيّر قيمة واحدة في كل مرة واحتفظ بالموجّه نفسه، وإلا لن تتمكن من معرفة أي تغيير ساعد. لأي شيء يتغذى على الكود، مثل التصنيف أو الاستخراج، استخدم درجة حرارة منخفضة وبذرة ثابتة حتى تتمكن من إعادة تشغيل الاختبار ورؤية النتيجة نفسها. للكتابة الإبداعية، ارفع درجة الحرارة ودع العقوبات تتعامل مع التكرار.
حقل max_tokens اختياري هنا. عند تركه، قد يستخدم الرد كل المساحة المتبقية في نافذة الـ 100,000 رمز، وهو نادرًا ما يكون ما تريده لإجابة سطر واحد. اضبطه كلما عرفت طول الإجابة.
بايثون: محادثة مع ذاكرة
واجهة الـ API عديمة الحالة، لذا عليك أنت إدارة المحادثة وإرسالها في كل مرة. يحافظ هذه الحلقة على قائمة بالرسائل ويضيف كلا الطرفين:
from openai import OpenAI
client = OpenAI(
base_url="https://api.glmapikey.com/v1",
api_key="YOUR_KEY",
)
messages = [{"role": "system", "content": "You are a helpful assistant."}]
while True:
user = input("you> ")
if not user:
break
messages.append({"role": "user", "content": user})
resp = client.chat.completions.create(model="uncensored", messages=messages)
reply = resp.choices[0].message.content
messages.append({"role": "assistant", "content": reply})
print("bot>", reply)
نظرًا لأن كل استدعاء يعيد إرسال القائمة الكاملة، فإن رموز المدخلات تزداد مع طول المحادثة. عند $0.15 لكل مليون رمز مدخل، هذا رخيص، لكنه يتراكم في الجلسات الطويلة، لذا احذف الرسائل القديمة بمجرد تجاوز السلسلة الحجم الذي تريد الدفع مقابله. تحتوي صفحة التسعير على أمثلة عملية.
البث المتدفق في Python وNode
قم بتعيين stream: true ويرسل الخادم الرموز بمجرد إنتاجها، عبر أحداث الإرسال من الخادم. في Python:
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write four lines about the sea."}],
stream=True,
)
text = ""
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text += piece
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
print("\ntokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
ينتهي البث بمعلومات الاستخدام، ولهذا السبب تتحقق الحلقة منها. نفس الشيء في Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.glmapikey.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Write four lines about the sea." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
تفاصيل حول حدود المعدل: يحافظ الطلب المتدفق على فتحة التزامن الخاصة به حتى ينتهي البث. إذا بدأت بثًا ولم تقرأه حتى النهاية، تظل هذه الفتحة مشغولة. استهلك أو أغلق البث دائمًا.
وضع JSON للإخراج المنظم
عندما يحتاج كودك إلى تحليل الإجابة، اطلب كائن JSON باستخدام response_format. كما يجب أن تحدد في الموجّه الشكل الذي تريده، لأن علم التنسيق يضمن صحة صيغة JSON، وليس مخططك الخاص.
import json
resp = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Reply only with JSON: {\"title\": string, \"tags\": [string]}."},
{"role": "user", "content": "Suggest a title and three tags for a post about home espresso."},
],
temperature=0.2,
)
data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])
تحقق من وجود المفاتيح التي تحتاجها قبل استخدامها، واحتفظ بدرجة الحرارة منخفضة لأعمال الاستخراج. إذا فشل التحليل، فإن إعادة المحاولة مرة واحدة بنفس المدخلات تعمل عادةً، ولا يتم تحميل الطلبات الفاشلة.
استدعاء الدوال: رحلة ذهاب وعودة كاملة
يتيح استدعاء الدوال للنموذج طلب تشغيل دالة في الكود الخاص بك. تصف الدالة في tools، ويرد النموذج بـ tool_calls، تقوم بتشغيلها وترسل النتيجة مرة أخرى كرسالة role: "tool".
import json
def get_weather(city: str) -> dict:
return {"city": city, "temp_c": 18, "sky": "cloudy"}
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
messages = [{"role": "user", "content": "Is it warm in Lisbon right now?"}]
first = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(get_weather(**args)),
})
final = client.chat.completions.create(
model="uncensored", messages=messages, tools=tools
)
print(final.choices[0].message.content)
else:
print(msg.content)
الدالة هنا تعيد بيانات ثابتة، لذا استبدلها ببحث حقيقي. تصل حجج الأداة كسلسلة JSON، لذا قم دائمًا بتحليلها والتحقق من صحة القيم قبل اتخاذ إجراء. مع stream: true، تصل tool_calls على شكل أجزاء تقوم بتجميعها قبل التحليل. استخدم tool_choice لفرض أداة محددة عندما تحتاج إلى ذلك.
تكلفة الأمثلة والأخطاء التي تضيع ساعة
تشغيل الأمثلة يكلف القليل جدًا، لكنه يساعد على رؤية الحساب مرة واحدة. عند $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز ناتج:
- حلقة المحادثة، بموجّه بحجم 1,200 رمز ورد بحجم 300 رمز: $0.00018 للمدخلات بالإضافة إلى $0.00015 للمخرجات يساوي $0.00033. ألف دورة تكلف $0.33.
- رحلة استدعاء الأداة تتطلب استدعاءين. إذا استخدم الأول 400 رمز مدخل و60 مخرج، والثاني 500 مدخل و150 مخرج، فإن الإجمالي هو 900 مدخل و210 مخرج: $0.000135 بالإضافة إلى $0.000105 يساوي $0.00024.
- البث المتدفق يكلف نفس تكلفة الاستدعاء العادي بنفس عدد الرموز. الفرق يظهر عندما ترى النص، وليس في التكلفة.
رصيد التجربة بقيمة $0.50 سيدفع أكثر من 1,500 دورة من حلقة المحادثة بهذا الحجم ($0.50 / $0.00033)، لذا يمكنك التجربة بحرية قبل شحن الرصيد. الطلبات الفاشلة والمرفوضة لا تُحتسب، مما يعني أن خطأ في التحليل يجعلك تعيد تشغيل الاستدعاء لا يكلفك مقابل المحاولات الفاشلة.
- عنوان URL الأساسي الخاطئ. يجب أن ينتهي بـ
/v1. إضافة/chat/completionsبنفسك إلى عنوان URL الأساسي لـ SDK يعطي خطأ 404 لأن الـ SDK يضيف المسار. - اسم نموذج مختلف. الأسماء المنسوخة من منصات أخرى غير موجودة هنا. المعرف هو
uncensored. - الافتراض بأن الذاكرة تعمل. الـ API لا يتذكر المكالمات السابقة. أرسل السجل في كل مرة.
- تحليل JSON الخاص بالنموذج دون حماية. احط
json.loadsداخل كتلة try وضع خطة للاستجابة غير الجيدة. - ترك البث مفتوحًا. البث غير المكتمل يُبقي فتحة التزامن مشغولة، والمفتاح التجريبي لديه اثنان فقط.
- وضع المفتاح في كود الواجهة الأمامية. احتفظ به على الخادم.
إذا بدا شيء ما خاطئاً بعد ذلك، أرسل طلباً باستخدام curl وقارنه بما تنتجه شيفرتك. يزيل طلب curl الـ SDK من المعادلة ويجعل الاختلافات في الجسم واضحة.
قراءة الاستخدام والرصيد والأخطاء
لمعاينة الرؤوس من الـ Python SDK، استخدم غلاف الاستجابة الخام:
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("x-request-id"))
print("balance usd:", raw.headers.get("x-balance-usd"))
print("rpm limit:", raw.headers.get("x-ratelimit-limit-requests"))
completion = raw.parse()
print(completion.usage.total_tokens)
سجّل معرف الطلب مع كل استدعاء لتتمكن من الإشارة إلى طلب واحد لاحقاً. استخدم رأس الرصيد لإطلاق تنبيه قبل نفاد الرصيد.
عند تجاوز حدّ المعدل، تُعيد الـ API استجابة HTTP 429، ويخبرك رمز الخطأ أيّ حدّ تم تجاوزه:
| الرمز أو الرأس | ما يجب فعله | ما يجب فعله |
|---|---|---|
rate_limited | عدد كبير جداً من الطلبات في الدقيقة (300 على المفتاح الكامل، 60 على التجريبي) | تراجع ووزّع الطلبات |
concurrency | عدد كبير جداً في آنٍ واحد (8 على المفتاح الكامل، 2 على التجريبي) | انتظر انتهاء طلب قيد التنفيذ |
Retry-After: 5 | حمل زائد مؤقت | أعد المحاولة بعد خمس ثوانٍ |
الطلبات الفاشلة أو المرفوضة لا تُحسب. يمكن أن يصل جسم الطلب إلى 8 MB. للمرجع الكامل وكيفية إعادة استخدام كود العميل الحالي، انظر إلى المستندات. للحصول على شرح لكيفية الحصول على مفتاح، انظر مقال مفتاح GLM API.
