كيفية العمل مع واجهة برمجة تطبيقات Cohere

توفر Cohere للمطورين الوصول إلى نماذج لغوية كبيرة متطورة (LLMs) قادرة على فهم وتوليد نصوص شبيهة بالبشر. للتفاعل مع هذه النماذج برمجيًا، تحتاج إلى مفتاح API. يعمل هذا المفتاح كمحدد فريد لك وككلمة مرور، مما يسمح لأنظمة Cohere بالتحقق من طلباتك وتتبع استخدامك.

ستوجهك هذه الدليل خلال الخطوات الأساسية: الحصول على مفتاح API الخاص بك، وفهم الفروقات الحرجة بين أنواع المفاتيح (خصوصًا فيما يتعلق بالتكاليف وحدود الاستخدام)، وإجراء اختبار أولي بسيط باستخدام أداة Apidog للتأكد من أن مفتاحك يعمل بشكل صحيح.

الخطوة 1: الحصول على مفتاح API الخاص بك من Cohere

الحصول على مفتاحك هو الخطوة الأولى والأهم. تجعل Cohere هذه العملية بسيطة نسبيًا من خلال لوحة التحكم الخاصة بهم.

1. انتقل إلى لوحة تحكم Cohere: افتح متصفح الويب الخاص بك وانتقل إلى نقطة الوصول الرئيسية لمنصة Cohere. عادةً ما ستجد صفحة تسجيل الدخول أو التسجيل.
2. الوصول إلى حسابك:

• إذا كان لديك حساب في Cohere بالفعل، سجل الدخول باستخدام بيانات الاعتماد الخاصة بك.
• إذا كنت جديدًا على Cohere، ستحتاج إلى التسجيل للحصول على حساب. اتبع عملية التسجيل، التي تنطوي عادةً على تقديم عنوان بريد إلكتروني وتعيين كلمة مرور.

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

ابدأ توليد المفتاح: داخل قسم مفاتيح API، ستجد خيارًا لإنشاء مفتاح جديد. من المحتمل أن ترى خيارات تميز بين أنواع المفاتيح، والأهم "المفتاح التجريبي" و"المفتاح الإنتاجي". لإجراء الاختبارات الأولية والتعلم، اختر الخيار لتوليد مفتاح تجريبي.

امنح المفتاح اسمًا: ستظهر لك نافذة تطلب منك تسمية مفتاحك. اختر اسمًا وصفيًا سيساعدك على تذكر دوره لاحقًا، خاصة إذا كنت تقوم بتوليد مفاتيح متعددة لمشاريع مختلفة. تشمل الأمثلة "MyFirstTestKey" أو "LearningProjectKey" أو "ApidogTestingKey".

قم بتوليد وتأمين مفتاحك: انقر على الزر لتأكيد وتوليد المفتاح (مثل "توليد مفتاح تجريبي"). ستقوم Cohere بعد ذلك بعرض مفتاح API الجديد الخاص بك. هذه هي المرة الوحيدة التي سيتم فيها عرض المفتاح بالكامل. من الضروري للغاية نسخ هذا المفتاح على الفور وتخزينه في مكان آمن جدًا، مثل مدير كلمات المرور أو ملاحظة آمنة. عامل هذا المفتاح بنفس مستوى الحماية التي تعامله بها ككلمة مرور. لا تشاركه علنًا، ولا تدمجه مباشرة في كود جانب العميل، ولا تلتزم به في أنظمة التحكم في النسخ مثل Git. بمجرد إغلاق نافذة المنبثقة أو التنقل بعيدًا، لا يمكنك استرجاع المفتاح الكامل مرة أخرى لأسباب أمنية (على الرغم من أنه يمكنك رؤية اسم المفتاح وربما أول/آخر بضع شخصيات في لوحة التحكم). إذا فقدته، ستحتاج إلى توليد واحد جديد.

مع نسخ مفتاح API وتأمينه، أنت مستعد لفهم ما يمكنك القيام به به والقواعد المرتبطة بذلك.

الخطوة 2: فهم أنواع المفاتيح، والتكاليف، وحدود الاستخدام

ليست جميع مفاتيح API في Cohere متساوية. نوع المفتاح الذي لديك يحدد مدى قدرتك على استخدام API، ومدى السرعة التي يمكنك استخدامها بها، وما إذا كان ذلك يتسبب في تكاليف. فهم هذه الاختلافات أمر حيوي لتجنب أي انقطاعات غير متوقعة أو رسوم.

A. مفاتيح API التجريبية: مجانية للتقييم

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

• التكلفة: المفاتیح التجريبیة مجانية للاستخدام. لن يتم محاسبتك على الاستخدام المرتبط بمفتاح تجريبي.
• حد الاستخدام الإجمالي: القيود الأكثر أهمية هي حدود شهرية تبلغ 1000 استدعاء API إجمالي عبر جميع نقاط نهاية Cohere مجتمعة. هذا يعني أن كل طلب تقدمه (سواءً كان إلى Chat أو Embed أو Rerank، إلخ) يُحسب ضمن هذا المجموع الشهري. بمجرد أن تصل إلى 1000 استدعاء في شهر تقويمي، سيتوقف مفتاحك عن العمل حتى يبدأ الشهر التالي.
• حدود المعدل (طلبات في الدقيقة - RPM): لضمان الاستخدام العادل واستقرار النظام، تحتوي المفاتيح التجريبية أيضًا على حدود صارمة للمعدل، مما يقيد عدد الطلبات التي يمكنك إرسالها خلال دقيقة واحدة إلى نقاط نهاية محددة. هذه ضرورية لتكون على دراية بها، حيث إن تجاوزها سيؤدي إلى أخطاء 429 Too Many Requests. تشمل حدود معدل مفتاح التجربة:
• نقطة نهاية الدردشة (/v2/chat): 20 طلب في الدقيقة. هذه هي النقطة المستخدمة للذكاء الاصطناعي التفاعلي، وتوليد النصوص، والتلخيص، إلخ.
• نقطة نهاية التضمين (/v2/embed) - النص: 100 طلب في الدقيقة. تُستخدم لتوليد تضمينات متجهية لبيانات النصوص (البحث الدلالي، التجميع).
• نقطة نهاية التضمين (/v2/embed) - الصور: 5 طلبات في الدقيقة. تُستخدم لتوليد تضمينات متجهية لبيانات الصور (البحث متعدد الوسائط).
• نقطة نهاية إعادة الترتيب (/v2/rerank): 10 طلبات في الدقيقة. تُستخدم لتحسين ترتيب الصلاحية لنتائج البحث.
• نقطة نهاية التحويل إلى رموز (/v2/tokenize): 100 طلب في الدقيقة. تُستخدم لرؤية كيفية تحليل النص إلى رموز بواسطة نماذج Cohere.
• نقطة نهاية التصنيف (/v1/classify): 100 طلب في الدقيقة. تُستخدم لمهام تصنيف النص (قديمة، يُفضل الآن التخصيص).
• نقاط النهاية القديمة (تلخيص، إنتاج): 5 طلبات في الدقيقة.
• أخرى/افتراضية: قد تنطبق حدود على نقاط النهاية الأخرى الأقل شيوعًا أو نقاط إدارة.

المفاتيح التجريبية مثالية لـ:

• تعلم كيفية عمل API في Cohere.
• التجريب مع نماذج ومعلمات مختلفة في Playground أو من خلال استدعاءات مباشرة.
• بناء مشاريع شخصية صغيرة أو نماذج أولية مع استخدام متوقع محدود.
• تقييم قدرات Cohere قبل الالتزام بالاستخدام المدفوع.

إذا كنت تضرب باستمرار الحد الشهري أو حدود المعدل في الدقيقة، فإن هذا يعد مؤشرًا قويًا على أنك بحاجة إلى الترقية إلى مفتاح إنتاج.

B. مفاتيح API الإنتاجية: لبناء وتوسيع النطاق

عندما تكون جاهزًا لبناء تطبيقات مع مستخدمين فعليين، وتحميل أحمال أكبر، أو تجاوز قيود التجربة، ستحتاج إلى مفتاح إنتاج. يتطلب ذلك إعداد معلومات الفوترة في حسابك في Cohere.

• التكلفة: تعمل المفاتيح الإنتاجية بنموذج الدفع وفق الاستخدام استنادًا بشكل أساسي إلى استخدام الرموز. الرموز هي وحدات نص (تقريبًا تتوافق مع الكلمات أو أجزاء من الكلمات) التي تعالجها النماذج. يتم تحصيل الرسوم عن كل من الرموز التي ترسلها إلى النموذج (الرموز المدخلة) والرموز التي يولدها النموذج في استجابته ( الرموز الناتجة).
• تختلف الأسعار حسب النموذج: النماذج الأقوى عمومًا تكلف أكثر لكل رمز من نماذج أسرع وأخف.
• أسعار نموذجية (توضيحية - تحقق من صفحة الأسعار الرسمية لـ Cohere للأسعار الحالية):
• نموذج Command R: قد تكلف حوالي 0.50 دولار لكل مليون رمز مدخل و1.50 دولار لكل مليون رمز الناتج. (ملاحظة: نتائج البحث السابقة أشارت إلى 2.50 دولار للمدخلات / 10.00 دولارات للناتجات لنموذج Command R - باستخدام هذه القيم: 2.50 دولار / 1M رموز مدخلة، 10.00 دولارات / 1M رموز منتّجة).
• نموذج Command R+: كونه أكثر قدرة، من المحتمل أن يكون له سعر أعلى، ربما 3.00 دولارات لكل مليون رموز مدخلة و15.00 دولارًا لكل مليون رموز منتّجة.
• نماذج التضمين (مثل embed-english-v3.0): عادةً ما تكون تكلفة نماذج التضمين تستند فقط إلى الرموز المدخلة، حيث إنها لا تنتج نصوص طويلة. قد تكون التكلفة حوالي 0.10 دولار لكل مليون رموز مدخلة.
• حساب الرموز: توفر Cohere نقطة نهاية Tokenizer ووثائق لمساعدتك في فهم كيفية ترجمة النص إلى رموز لتقدير دقيق للتكلفة. المدخلات والنواتج الأطول بالطبع تكلف أكثر.
• حد الاستخدام الإجمالي: لا يوجد حد إجمالي شهري للمكالمات لمفاتيح الإنتاج. يمكنك إجراء أي عدد من المكالمات حسب الحاجة، بشرط أن تبقى ضمن حدود المعدل وتدير تكاليفك.
• حدود المعدل (طلبات لكل دقيقة - RPM): تستفيد المفاتيح الإنتاجية من حدود المعدل أعلى بكثير، مما يسمح للتطبيقات بالتعامل مع مزيد من الحركة:
• نقطة نهاية الدردشة (/v2/chat): 500 طلب في الدقيقة (مقارنة بـ 20/دقيقة للتجربة).
• نقطة نهاية التضمين (/v2/embed) - النص: 2000 طلب في الدقيقة (مقارنة بـ 100/دقيقة).
• نقطة نهاية التضمين (/v2/embed) - الصور: 400 طلب في الدقيقة (مقارنة بـ 5/دقيقة).
• نقطة نهاية إعادة الترتيب (/v2/rerank): 1000 طلب في الدقيقة (مقارنة بـ 10/دقيقة).
• نقطة نهاية التحويل إلى رموز (/v2/tokenize): 2000 طلب في الدقيقة.
• نقطة نهاية التصنيف (/v1/classify): 1000 طلب في الدقيقة.
• زيادة حد المعدل: للتطبيقات ذات الحجم الكبير جدًا، قد يكون من الممكن طلب زيادات أخرى في حد المعدل عن طريق التواصل مع دعم Cohere.

المفاتيح الإنتاجية ضرورية لـ:

• تطوير ونشر التطبيقات المخصصة للمستخدمين النهائيين.
• التعامل مع أحجام ثابتة أو عالية من طلبات API.
• أي استخدام تجاري.
• فتح الإمكانيات الكاملة للأداء دون قيود تجريبية.

C. اختيار المفتاح الصحيح:

• ابدأ بالمفتاح التجريبي: ابدأ دائمًا بمفتاح تجريبي من أجل التعلم والتطور الأولي.
• راقب الاستخدام: راقب حجم الطلبات وتكرارها.
• ترقية عند الحاجة: إذا كانت تطبيقاتك تضرب باستمرار حدود المعدل، أو تتجاوز حد المكالمات الشهري البالغ 1000، أو إذا كنت تستعد للإطلاق علنيًا أو تجاريًا، قم بالترقية إلى مفتاح إنتاج من خلال إضافة تفاصيل الفوترة في لوحة التحكم الخاصة بـ Cohere.

حسنًا، إليك قسم "الخطوة 3" المعدَّل الذي يركز على اختبار طلب الدردشة المتدفقة المقدم في أمر curl باستخدام Apidog، معروض بصيغة Markdown:

الخطوة 3: إجراء اختبار API أساسي لطلب الدردشة المتدفقة باستخدام Apidog

قبل دمج API في كود معقد، خاصةً للردود المتدفقة، من المفيد إجراء اختبار مباشر. يسمح لك Apidog بتكرار بنية أمر curl للتحقق من مفتاحك وفهم تدفق الطلب/الرد الأساسي للتدفّق.

1. قم بتشغيل Apidog: افتح تطبيق Apidog على جهاز الكمبيوتر الخاص بك.
2. إنشاء طلب جديد: انقر على زر '+' أو ما يعادله لإنشاء طلب API جديد. سمّه شيئًا وصفيًا، مثل "اختبار دردشة متدفقة من Cohere".
3. تكوين نقطة النهاية:

• طريقة HTTP: اختر POST.
• URL: أدخل URL نقطة النهاية للدردشة من Cohere v2: https://api.cohere.ai/v2/chat

4. إعداد الرؤوس:

• انتقل إلى علامة التبويب "رؤوس". ستحتاج إلى إضافة عدة رؤوس بناءً على أمر curl:
• Accept: المفتاح: Accept، القيمة: application/json
• Content-Type: المفتاح: Content-Type، القيمة: application/json
• Authorization: المفتاح: Authorization، القيمة: Bearer YOUR_API_KEY (استبدل YOUR_API_KEY بمفتاح API الحقيقي الخاص بك. تأكد من وجود مسافة بعد Bearer).

5. بناء جسم الطلب (مع تمكين التدفق):

• انتقل إلى علامة التبويب "الجسم".
• اختر الخيار للدخول "الخام".
• اختر JSON كتنسيق.
• ألصق الحمولة JSON التالية، مماثلة لبيانات أمر curl، بما في ذلك العلم الحيوي "stream": true:

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "Hello world!"
    }
  ]
}

(ملاحظة: استخدم المثال curl "role": "user" (حروف صغيرة) والنموذج "command-a-03-2025". لقد احتفظت بـ "role": "USER" والنموذج "command-r" للتناسق مع الأمثلة السابقة، لكن يجب عليك تعديل نموذج وحروف الدور في JSON أعلاه ليتطابق تمامًا مع الطلب المحدد الذي تنوي اختباره إذا كان مختلفًا.)

6. تنفيذ الطلب: انقر على زر "أرسل" في Apidog.

7. تحليل الاستجابة (تفاصيل التدفق):

• رمز الحالة: ينبغي أن تتلقى رمز حالة 200 OK إذا تم قبول الطلب الأولي من قبل الخادم.
• رؤوس الاستجابة: تحقق من رؤوس الاستجابة بحثًا عن علامات التدفق، مثل Transfer-Encoding: chunked.
• جسم الاستجابة: قد يختلف كيفية عرض Apidog للاستجابة المتدفقة. قد:
• تنتظر حتى تكتمل التدفق وتظهر النص المجمّع بالكامل أو حمولة الحدث النهائية.
• تظهر قطع البيانات الخام أو الأحداث المرسلة من الخادم (SSE) كما تصل، والتي قد تبدو كأجسام JSON متعددة واحدة تلو الأخرى.
• من المحتمل ألا تعرض النص بسلاسة رمزيًا تلو الآخر مثل التطبيق المعد خصيصًا لذلك.
• المحتوى: تحقق من محتوى جسم الاستجابة. ينبغي أن ترى أحداثًا تتعلق بالتدفق، مثل أحداث text-generation التي تحتوي على أجزاء من استجابة "Hello world!"، وفي النهاية حدث stream-end يشير إلى أن العملية انتهت.
• الأخطاء: إذا تلقيت أخطاء (401، 403، 400، 429)، تشخيصها كما هو موضح سابقًا (تحقق من مفتاح API، صلاحية JSON، حدود المعدل). قد يحدث 400 Bad Request إذا كان النموذج المحدد لا يدعم التدفق أو إذا كانت المعلمات الأخرى غير متوافقة.

يساعدك هذا الاختبار في التأكد من أن API تقبل طلب التدفق الخاص بك وأن مفتاحك صالح لهذا النوع من التفاعل، حتى لو لم يكن Apidog هو الأداة المثالية لـ تصور الطبيعة الزمنية الفعلية للتدفق. إنه يتحقق من أن إعداد الطلب الأساسي صحيح.

الخاتمة

الآن أصبح لديك مفتاح API الخاص بك من Cohere وتفهم الفروقات الأساسية بين مفاتيح التجربة والإنتاج، لا سيما فيما يتعلق بالحد البالغ 1000 مكالمة شهرية وحدود المعدل في الدقيقة على مفاتيح التجربة مقابل نظام الدفع وفق الاستخدام القائم على الرموز والحدود العالية للمفاتيح الإنتاجية. لقد أجريت أيضًا اختبارًا أساسيًا ولكنه أساسي باستخدام Apidog لتأكيد أن مفتاحك يعمل ويمكنك هيكلة مكالمة API بسيطة.

هذه الأساسيات ضرورية للتفاعل بشكل فعال مع API في Cohere. تذكر أن تحافظ على أمن مفتاحك، وتراقب استخدامك مقابل الحدود (خاصةً عند استخدام مفتاح تجريبي)، وتشير إلى وثائق Cohere للحصول على معلومات مفصلة عن النماذج المحددة والمعلمات المتقدمة واستخدام SDK عند البدء في بناء تطبيقات أكثر تعقيدًا.