OpenCode مع واجهة برمجة تطبيقات متوافقة مع OpenAI: الإعداد

ما تحتاجه قبل البدء

OpenCode هو وكيل برمجة مفتوح المصدر يعمل في طرفيتك. يمكنه التحدث مع العديد من مزودي النماذج، ويسمح لك بإضافة مزوّد خاص بك إذا كانت نقطة النهاية تتبع تنسيق دردشة OpenAI. هذه الواجهة تفعل ذلك، لذا فإن الإعداد مسألة ملء بضع حقول فقط.

اجمع هذه القيم الثلاث أولاً:

• عنوان الـ API الأساسي: https://api.kimicode.top/v1
• معرف النموذج: uncensored
• مفتاح API: أنشئ واحداً من صفحة مفتاح API. يمكن للحسابات الجديدة الحصول على رصيد تجريبي بقيمة $0.50 هناك بنقرة واحدة، وهو كافٍ للاختبارات أدناه. يسمح المفتاح التجريبي بـ 2 طلب متزامن و60 طلب في الدقيقة.

احتفظ بالمفتاح في متغير بيئة بدلاً من لصقه في الملفات التي تقوم بإيداعها:

Copyexport KIMICODE_API_KEY="your-key-here"

الخطوة 1: اختبار نقطة النهاية باستخدام curl

افعل هذا قبل تكوين أي أداة. إذا نجح curl ولم ينجح OpenCode، فأنت تعلم أن المشكلة في الإعداد. إذا فشل curl، فأصلح المفتاح أو عنوان URL مرة واحدة، وليس في مكانين.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

يجب أن تحصل على كائن JSON يحتوي على مصفوفة choices وكتلة usage. يعني الخطأ 401 أن المفتاح غير صحيح أو يفتقد بادئة Bearer. يعني الخطأ 404 عادةً أن عنوان URL مُدخل بشكل خاطئ أو يتضمن بالفعل /chat/completions.

يقوم وكيل البرمجة ببث إجاباته واستدعاء الأدوات، لذا تحقق من هذين الأمرين أيضاً:

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

يجب أن ترى سلسلة من الأسطر data:، يحتوي كل منها على جزء صغير من JSON، وينتهي ببيانات الاستخدام وعلامة نهائية. يعطل العلم -N التخزين المؤقت في curl لتظهر الحزم مع وصولها.

الخطوة 2: إضافة مزوّد مخصص إلى OpenCode

يقرأ OpenCode ملف تكوين JSON opencode.json من مجلد مشروعك أو من دليل التكوين الخاص به. تُعلن عن مزودي الأسلوب المشابه لـ OpenAI باستخدام حزمة OpenAI المتوافقة الخاصة بـ AI SDK، مع عنوان URL أساسي وقائمة بالنماذج. يتبع التخطيط أدناه وثائق OpenCode العامة وقت الكتابة. يمكن أن تتغير أسماء الحقول بين الإصدارات، لذا قارن ذلك بقسم المزود في وثائق OpenCode الحالية إذا تم رفض شيء ما.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

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

يُخبر التنسيق {env:KIMICODE_API_KEY} برنامج OpenCode بقراءة المتغير من سطر الأوامر الخاص بك. إذا كانت إصدارتك تتعامل مع بيانات الاعتماد عبر أمر تسجيل الدخول الخاص بها، فاستخدم تلك الطريقة واترك المفتاح خارج الملف. على أي حال، لا تُدرج مفتاحاً حقيقياً.

تكوين المشروع أو التكوين العالمي

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

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

الخطوة 3: اختيار النموذج وتشغيل مهمة

ابدأ OpenCode في مجلد مشروع وافتح منتقي النماذج الخاص به. يجب أن يظهر مزوّدك المخصص في القائمة مع اسم العرض الذي حددته. حدده، ثم امنح الوكيل مهمة صغيرة وقابلة للتحقق، مثل شرح دالة أو كتابة اختبار وحدة لملف قصير.

ابدأ صغيراً لسببين. أولاً، يمكنك رؤية ما إذا كانت استدعاءات الأدوات تعمل: عندما يطلب OpenCode من النموذج قراءة أو تحرير ملف، فإنه يفعل ذلك من خلال واجهة استدعاء الدوال. ثانياً، يرسل وكيل البرمجة الكثير من النص لكل دورة، بما في ذلك محتويات الملفات والسجل، لذا تستهلك الجلسة الطويلة الرموز بسرعة. يضع القسم التالي أرقاماً على ذلك.

إذا لم يظهر النموذج، تحقق من أن الملف صالح بصيغة JSON، وأنه موجود في المكان الذي يبحث عنه OpenCode للإعداد، وأن اسم المزوّد يطابق ما أدخلته في حقل model.

اختبار استدعاء الدوال ووضع JSON مباشرة

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

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

يحتوي الرد الجيد على إدخال tool_calls يسمي read_file مع سلسلة حجة JSON. يشغل الوكيل الأداة، ثم يرسل النتيجة مرة أخرى كرسالة مع role مضبوطاً على tool، ويستمر النموذج من هناك. إذا رأيت نصاً عاديًا فقط، جرب موجهاً أكثر مباشرة، لأن ما إذا كان النموذج يقرر استدعاء أداة هو جزء من سلوكه.

وضع JSON هو مفتاح منفصل. إضافة "response_format": {"type": "json_object"} تطلب مخرج JSON صالح، وتساعد عندما يحتاج نص برمجي آخر إلى تحليل ما يعود. اذكر JSON في موجّهك أيضاً، حتى يعرف النموذج الشكل المتوقع.

حجم السياق وتكلفة الجلسة

نافذة السياق هي 100,000 رمز، وتشمل الموجّه والمكمل معاً. ضبط limit.context على 100000 يخبر الوكيل بالحد الفعلي، حتى يتمكن من تقصير أو تلخيص السجل قبل أن تضطر الخادم لرفض الطلب. قد يستخدم المكمل أي مساحة متبقية، وmax_tokens اختياري.

الفوترة هي $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج. الوكلاء ثقيلون بالإدخال، لأن كل دورة تعيد إرسال المحادثة. إليك مثال محسوب لجلسة متوسطة:

• 40 دورة، كل منها ترسل حوالي 30,000 رمز مدخل: 1,200,000 رمز مدخل، وهو 1.2 × $0.15 = $0.18.
• تعيد كل دورة حوالي 800 رمز إخراج: 32,000 رمز إخراج، وهو 0.032 x $0.50 = $0.016.
• المجموع: $0.196، أي حوالي عشرين سنتاً للجلسة بأكملها.

ستختلف أرقامك. اقرأ قيم usage في الردود، أو راقب رأس X-Balance-USD، الذي يبلغ عن رصيدك المتبقي في كل رد. الرصيد مسبق الدفع ولا ينتهي، ولا تُفرض رسوم على الطلبات الفاشلة أو المرفوضة. التفاصيل في صفحة التسعير.

توقعات صادقة لوكيل البرمجيات

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

يتعامل مع الأنابيب التي يحتاجها الوكيل: استدعاء الدوال مع tool_calls المتدفق، ونتائج الأدوات المرسلة مرة أخرى كرسائل role: "tool"، ووضع JSON من خلال response_format. هو نص فقط، بدون صور، لذا لن تعمل الميزات التي تلتقط لقطات شاشة.

هناك قيدان مهمان للوكلاء. المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة. الوكلاء الفرعيون أو تشغيل الأدوات المتوازي الذي يطلق العديد من المكالمات في وقت واحد يمكن أن يضرب حدّ التوازي، ويحتفظ الطلب المتدفق بمكانه حتى ينتهي البث المتدفق. عندما يحدث ذلك تحصل على HTTP 429 مع الكود concurrency. يعني الكود rate_limited الكثير من الطلبات في الدقيقة. في حالة الحمل الزائد المؤقت قد ترى أيضاً 429 مع Retry-After: 5. قلل التوازي أو انتظر وأعد المحاولة.

استكشاف الأخطاء وإصلاحها

العرض	السبب المحتمل	الحل
401 غير مصرح	مفتاح فارغ أو خاطئ؛ متغير البيئة غير مضبوط في غلاف الأوامر الذي أطلق OpenCode	شغّل echo $KIMICODE_API_KEY في نفس الطرفية، ثم أعد تشغيل OpenCode
404 غير موجود	يحتوي Base URL على /chat/completions أو يفتقر إلى /v1	استخدم بالضبط https://api.kimicode.top/v1
النموذج غير موجود	مفتاح النموذج يختلف عن uncensored	طابق المفتاح في models مع المعرّف الذي يعيده GET /v1/models
429 مع concurrency	عدد كبير من الطلبات في آن واحد	قلل المكالمات المتوازية للدوال، أو انتظر حتى تنتهي التدفقات
الطلب كبير جدًا	جسم الطلب أكثر من 8 ميجابايت أو السجل قريباً من حد نافذة السياق	ابدأ جلسة جديدة أو لخص السجل

لأي شيء غير مغطى هنا، صفحة التوثيق تحتوي على مرجع الطلب الكامل، ودليل التكامل يغطي نفس نقطة النهاية من زاوية عملاء آخرين بأسلوب OpenAI.

المزيد من الأدلة

• ماذا يعني متوافق مع OpenAI بالنسبة لواجهة برمجة التطبيقات؟
• بديل Kimicode: واجهة برمجة تطبيقات LLM مستضافة بدون رقابة
• واجهة برمجة تطبيقات LLM بدون رقابة: تكامل متوافق مع OpenAI والأسعار