اختر نمط التكامل أولاً
تقع معظم أعمال تكامل GLM API في أحد الأشكال الأربعة، ويؤثر الاختيار في كل ما يلي: مكان تخزين الأسرار، وكيفية التعامل مع الذروات، وكيف يبدو الفشل للمستخدم.
| النمط | مناسب لـ | المخاطر الرئيسية |
|---|---|---|
| وكيل الخادم الخلفي | تطبيقات الويب وتطبيقات الهاتف التي تمتلك مستخدمين خاصين بها | نقطة النهاية المفتوحة التي يمكن لأي شخص استنزافها |
| عامل الطابور | الروبوتات، والوظائف الدفعية، ومعالجة النصوص بالجملة | تراكم الطلبات عندما تتجاوز الطلبات حدود المعدل |
| روبوت الدردشة | شخصيات ومرافق في Discord أو Telegram أو Matrix | تضخم التكلفة بسبب طول سجلات المحادثة |
| أداة الأتمتة | سير العمل في الأدوات التي تقدم عقدة HTTP أو عقدة OpenAI | فشل صامت عند حدوث خطأ في خطوة ما |
تستخدم الأنماط الأربعة نفس الاستدعاء من الداخل: POST /v1/chat/completions على https://api.glmapikey.com/v1 بمفتاح Bearer والنموذج uncensored. الـ API متوافق مع OpenAI، لذا يمكنك استخدام أي SDK من OpenAI، أو HTTP الخام إذا لم يكن لديك SDK في بيئة العمل الخاصة بك. إنه نموذج مفتوح الأوزان واحد تديره جهة مستقلة، وليس الـ API الرسمي لأي بائع وليس وسيط توجيه، لذا صمّم لسلوك نموذج واحد. نص فقط: إذا كان منتجك يحتاج أيضاً إلى صور أو تضمينات (embeddings)، خطط لمزود خدمة ثانٍ لهذه الأجزاء.
تحتوي صفحة التوثيق على نقاط النهاية والرؤوس، ويشرح مقال مفتاح GLM كيفية الحصول على مفتاح.
وكيل الخادم الخلفي: أبقي المفتاح بعيداً عن العميل
يمكن فحص أي شيء يعمل في المتصفح أو حزمة التطبيق. إذا تم شحن المفتاح هناك، يمكن لأي شخص نسخه وإنفاق رصيدك. الحل هو مسار خادم رفيع يحمل المفتاح، ويطبق قواعدك الخاصة، ويعيد توجيه الطلب.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import AsyncOpenAI
from pydantic import BaseModel
app = FastAPI()
client = AsyncOpenAI(
base_url="https://api.glmapikey.com/v1",
api_key="YOUR_KEY",
)
class Ask(BaseModel):
prompt: str
@app.post("/ask")
async def ask(body: Ask):
async def gen():
stream = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": body.prompt[:4000]}],
max_tokens=600,
stream=True,
)
async for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
yield chunk.choices[0].delta.content
return StreamingResponse(gen(), media_type="text/plain")
يقوم المسار باقتطاع الـ prompt ويحدّ من الرد، وهو الحد الأدنى. أضف ضوابط حقيقية قبل الإطلاق: مصادقة المستخدم، ميزانية رموز يومية لكل مستخدم، وحدّ لمعدل الطلب لكل عنوان IP أو حساب. يعيد الـ API بيانات الاستخدام في كل استدعاء، لذا يمكنك حساب الرموز لكل مستخدم في قاعدة بياناتك ورفض الطلبات التي تتجاوز حصتهم.
يتطلب البث المتدفق عبر وكيل فحصاً واحداً: تأكد من أن وكيل عكسي (reverse proxy) الخاص بك لا يخزن استجابة في الذاكرة المؤقتة، وإلا ستصل النصوص في كتلة واحدة في النهاية بدلاً من كلمة بكلمة.
عامل الطابور: احترام حدّ التوازي
الحدود خاصة بكل مفتاح. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة. يسمح المفتاح التجريبي بـ 2 و60. بالنسبة للتيار المستمر من الوظائف، عادةً ما يكون التوازي هو العامل المحدد أولاً، لأن كل طلب يشغل فتحة حتى يكتمل، والطلب المتدفق حتى ينتهي البث.
مجموعة عمال مُضبوطة على الحدّ الأقصى هي الحلّ الأنظف. تنتظر المهام في طابورك بدلاً من أن تفشل بخطأ 429:
import asyncio
from openai import AsyncOpenAI, RateLimitError
client = AsyncOpenAI(
base_url="https://api.glmapikey.com/v1",
api_key="YOUR_KEY",
max_retries=0,
)
WORKERS = 8 # use 2 on a trial key
async def run_job(prompt: str) -> str:
for attempt in range(5):
try:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=500,
)
return r.choices[0].message.content
except RateLimitError as e:
delay = float(e.response.headers.get("retry-after", 2 * (attempt + 1)))
await asyncio.sleep(delay)
raise RuntimeError("gave up after repeated 429 responses")
async def worker(queue: asyncio.Queue, results: list):
while True:
prompt = await queue.get()
try:
results.append(await run_job(prompt))
finally:
queue.task_done()
async def main(prompts):
queue, results = asyncio.Queue(), []
for p in prompts:
queue.put_nowait(p)
tasks = [asyncio.create_task(worker(queue, results)) for _ in range(WORKERS)]
await queue.join()
for t in tasks:
t.cancel()
return results
يخبرك رمز الخطأ في جسم 429 سبب إيقافك: rate_limited للطلبات في الدقيقة، concurrency للكثرة في وقت واحد، و429 عادي مع Retry-After: 5 لحمل زائد قصير. احترام الرأس أسهل من تخمين التأخير. الطلبات الفاشلة والمرفوضة لا تُحسب، لذا لا تكلف إعادة المحاولة شيئًا.
البوتات والشخصيات
تظهر مفاجآت التكلفة عادةً في روبوت الدردشة، لأن الروبوت الذي يحتفظ بسجل المحادثات يعيد إرساله مع كل رسالة. قرر مبكراً عدد رسائل السجل التي تريد الاحتفاظ بها، واحفظ السجل بنفسك، لأن الـ API لا تحتفظ بحالة بين الاستدعاءات.
مثال على الميزانية يوضح النقطة. لنفترض أن روبوتاً لديه 500 مستخدم نشط يرسل كل منهم 20 رسالة يومياً. تحمل كل رسالة 1,500 رمز مدخل (شخصية، سجل قصير والسطر الجديد) وتعيد 250 رمزاً:
- لكل رسالة: 1,500 / 1,000,000 × $0.15 = $0.000225 للإدخال، زائد 250 / 1,000,000 × $0.50 = $0.000125 للإخراج، أي $0.00035
- لكل يوم: 500 × 20 = 10,000 رسالة، أي $3.50
- لكل 30 يوماً: $105
إذا سمحت للسجل بالنمو حتى يملأ نافذة سياق بحجم 12,000 رمز، يرتفع عدد الرموز المدخلة لكل رسالة ثمانية أضعاف إلى 12,000 رمز، أو $0.0018 للإدخال وحده، وترتفع التكلفة الشهرية وفقاً لذلك. يساعد النافذة المتحركة مع ملخص قصير للأحداث الأقدم على الحفاظ على اتساق الشخصية بسعر أقل.
بالنسبة لروبوتات الرفقة ولعب الأدوار، احتفظ بقواعد المنتج في طبقتك الخاصة. النموذج مُدرّب للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين، والحدّ الصارم الوحيد هو المحتوى الجنسي الذي يتضمن القاصرين، وهو ما ترفضه الخدمة. إذا كان روبوتك يعمل في خادم عام، أضف فحص العمر وقواعد القناة التي تتوافق مع المنصة التي تشغله عليها.
أدوات الأتمتة وسير العمل بدون كود
يمكن لأدوات سير العمل التي تقدم عقدة بأسلوب OpenAI مع عنوان URL أساسي قابل للتكوين استخدام هذا الـ API بتغيير ثلاثة حقول: عنوان URL إلى https://api.glmapikey.com/v1، والمفتاح واسم النموذج إلى uncensored. الأدوات التي تحتوي فقط على عقدة طلب HTTP عامة يمكنها إرسال الطلب الخام بدلاً من ذلك:
curl https://api.glmapikey.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "uncensored", "messages": [{"role": "user", "content": "Classify this ticket: printer offline"}], "response_format": {"type": "json_object"}}'
بالنسبة لخطوات سير العمل التي تغذي خطوة أخرى، يُستحسن استخدام وضع JSON، حتى تتلقى العقدة التالية نصاً قابلاً للتحليل. أضف فرع خطأ لأي خطوة تستدعي الـ API، لأن استجابات 429 و5xx ستحدث أحياناً، وسيكون من الصعب العثور على فشل صامت في منتصف سير العمل لاحقاً. اضبط إعادة محاولة مع انتظار قصير على تلك العقدة، وتأكد من أن الفروع المتوازية لا تتجاوز عدد الطلبات المتزامنة التي يسمح بها مفتاحك.
ما يراه المستخدمون عند حدوث خطأ
يحتاج كل تكامل إلى خطة للمسار غير السعيد، والجزء الذي يظهر للمستخدم مهم بقدر أهمية كود إعادة المحاولة. تظهر ثلاث حالات في الممارسة العملية.
الأولى هي زيادة حمل قصيرة: 429 مع Retry-After: 5. أعد المحاولة بهدوء، وأظهر مؤشر كتابة في هذه الأثناء، حتى يرى المستخدم ردّاً أبطأ قليلاً بدلاً من خطأ. الثانية هي الوصول إلى حد مجموعة العمال الخاصة بك. إذا كانت جميع الفتحات الثمانية مشغولة، ضع الرسالة في الطابور وأخبر المستخدم أنها في الانتظار، وهو أفضل من شاشة فارغة. الثالثة هي نفاد الرصيد، وهو ما لا تحله إعادة المحاولة. راقب رأس الرصيد، واضبط تنبيهاً عند عتبة تختارها، واحتفظ برسالة بديلة جاهزة ليوم نفاد الرصيد دون أن تلاحظ.
لا تعرض أخطاء الـ API الخام للمستخدمين النهائيين. سجّلها مع معرف الطلب، واعرض جملة بسيطة توضح ما حدث وما يجب فعله بعد ذلك. لا تتضمن المفتاح، أو عنوان URL الأساسي، أو تتبعات المكدس في أي شيء يمكن للمستخدم قراءته.
المال، المراقبة وفحوصات الإطلاق
الفوترة مسبقة الدفع. يمكنك شحن أي مبلغ صحيح من $20 إلى $500، مع +5% من $50، و+10% من $100 و+15% من $200. الرصيد لا ينتهي، ولا يوجد اشتراك. ادفع بالعملات المشفرة فقط (USDT على TRC20، USDC على Base). يمكن للمستخدمين الجدد المطالبة بـ $0.50 من رصيد تجريبي بنقرة واحدة على صفحة مفتاح API، ساري لمدة 7 أيام، حتى تتمكن من اختبار التكامل قبل تمويله. انظر صفحة الأسعار للحصول على الأسعار.
ما يجب مراقبته في الإنتاج:
- الرصيد. اقرأ
X-Balance-USDمن الاستجابات واضبط تنبيهاً عندما ينخفض تحت عتبة تختارها. - معرفات الطلب. احفظ
X-Request-Idبجانب كل مهمة حتى يمكن تتبع فشل واحد. - استخدام الرموز. اجمع
usageلكل مستخدم ولكل ميزة لمعرفة أين يذهب المال. - معدل 429. العدد المتزايد يعني أن مجموعة العمال أكبر من حدود المفتاح.
قائمة إطلاق قصيرة: أرسل طلباً حقيقياً واحداً من المضيف الإنتاجي، واختبر 429 قسريًا في بيئة الاختبار، وتأكد من أن المستخدم لا يمكنه الوصول إلى الـ API بدون مصادقتك، واكتب ما تعرضه خدمتك عندما تكون الـ API غير متاحة. الموجّهات لا تُستخدم للتدريب، وهو ما يمكنك إبلاغ مستخدميك به، لكن قل في سياسة الخصوصية الخاصة بك أن نصوصهم تُرسل إلى مزود طرف ثالث لتوليد الردود.
