عنوان URL الأساسي لواجهة Kimi Code: إعداد الرابط الأساسي لعملاء OpenAI

الرابط وما يعنيه كل جزء منه

إذا كنت تبحث عن Kimi Code API URL، فقد تكون تبحث عن عنوان خدمة Kimi الخاصة بها. لذلك، استخدم التوثيق من المورد، لأنني لا أضمنه. يعمل هذا الموقع على شيء مختلف: واجهة برمجة تطبيقات (API) متوافقة مع OpenAI مستضافة أمام نموذج واحد مفتوح الأوزان، وتشغله جهة مستقلة. عنوانه هو:

Copyhttps://api.kimicode.cc/v1

هذا السلسلة هي الرابط الأساسي. إنه الجزء الذي تشاركه كل الطلبات. تضيف مكتبة الـ SDK باقي الأجزاء. عند استدعاء chat.completions.create، ترسل مكتبة OpenAI طلب POST إلى https://api.kimicode.cc/v1/chat/completions. قائمة النماذج موجودة في https://api.kimicode.cc/v1/models وتتطلب طلب GET.

هذان الطريقتان هما الطريقتان الوحيدتان اللتان تخدمهما واجهة برمجة التطبيقات (API) هذه: POST /v1/chat/completions و GET /v1/models. إذا كنت تتوقع وجود نقاط نهاية للصور أو الصوت أو التضمين (embeddings)، فهي غير موجودة هنا. إنها واجهة برمجة تطبيقات (API) للنصوص فقط.

ثلاث إعدادات مهمة، ولا يتعين تغيير أي شيء آخر في كود OpenAI الحالي: الرابط الأساسي، مفتاح API، ومعرف النموذج uncensored.

لماذا يُعد الرابط الأساسي المفتاح الوحيد

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

هذا يفسر سبب كون الترحيل من مزود آخر متوافق مع OpenAI عادةً ثلاث تعديلات فقط: الرابط الأساسي، والمفتاح، واسم النموذج. الحقول في الاستجابة، مثل choices، و message، و finish_reason و usage، لها نفس الأسماء، لذا يستمر الكود الذي يقرأها في العمل.

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

متغيرات البيئة للأدوات التي لا يمكنك تعديلها

تبني العديد من أدوات سطر الأوامر والأطر عميل OpenAI دون السماح لك بالوصول إلى المُنشئ (constructor). عادةً ما تقرأ متغيرات البيئة القياسية، لذا فإن تعيينها يكفي:

Copyexport OPENAI_BASE_URL="https://api.kimicode.cc/v1"
export OPENAI_API_KEY="YOUR_KEY"

بعض الأدوات الأقدم تبحث عن OPENAI_API_BASE بدلاً من ذلك، لذا إذا تجاهلت الاسم الأول، جرب الاسم الثاني. بعد تعيينها، قم بتشغيل الأداة في نفس جلسة وحدة التحكم (shell)، لأن المتغيرات المحددة في نافذة وحدة تحكم أخرى لا يتم مشاركتها.

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

احصل على مفتاح أولاً

يتم مصادقة الطلبات باستخدام رأس (header) على شكل Authorization: Bearer YOUR_KEY. تبني كل مكتبة SDK رسمية هذا الرأس لك من حجة api_key. يمكنك إنشاء المفتاح بعد تسجيل الدخول باستخدام Google أو باستخدام بريد إلكتروني وكلمة مرور.

يمكن للحسابات الجديدة المطالبة برصيد تجربي بقيمة $0.50 بنقرة واحدة على صفحة مفتاح API. لا يحتاج إلى بطاقة ويستمر لمدة 7 أيام. هذا يكفي لتشغيل كل الأمثلة أدناه عدة مرات. تسمح المفاتيح التجريبية بـ 2 طلب متزامن و60 طلب في الدقيقة، لذا قم بتشغيل الأمثلة واحدة تلو الأخرى.

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

الطلب الأول في curl

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

Copyexport KIMICODE_KEY="YOUR_KEY"

curl https://api.kimicode.cc/v1/models   -H "Authorization: Bearer $KIMICODE_KEY"

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

يعيد الاستدعاء الأول قائمة النماذج، والتي يجب أن تتضمن uncensored. يعيد الثاني كائن إكمال دردشة قياسي. انظر إلى رؤوس الاستجابة باستخدام curl -i وسترى X-Request-Id، و X-Balance-USD، و X-RateLimit-Limit-Requests و X-RateLimit-Limit-Concurrency. احتفظ بمعرف الطلب إذا اتصلت بـ الدعم بخصوص استدعاء معين.

Python باستخدام SDK

قم بتثبيت المكتبة باستخدام pip install openai، ثم غيّر حجتين في مُهيّئ العميل.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.cc/v1",
    api_key=os.environ["KIMICODE_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what a base URL is in two sentences."},
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)

تُمرر معلمات مثل temperature، و top_p، و stop، و seed وعقوبات التردد والوجود إلى النموذج. قيمة max_tokens اختيارية. بدونها، يمكن أن يستخدم الإكمال ما تبقى من نافذة 100,000 رمز، والتي هي الموجّه (prompt) والإكمال معاً.

تقرأ المكتبة أيضاً متغيرين للبيئة إذا لم تمرر وسائط: OPENAI_BASE_URL و OPENAI_API_KEY. هذا مفيد للأدوات التي لا يمكنك تعديلها. قم بتعيين كليهما، وشغّل الأداة، وستتحدث مع واجهة برمجة التطبيقات (API) هذه.

Node، البث المتدفق، ووضع JSON

إعداد Node.js يشبه Python. ثبّت المكتبة باستخدام npm install openai.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kimicode.cc/v1",
  apiKey: process.env.KIMICODE_KEY,
});

// Streaming over SSE
const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Write a four-line poem about routers." }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

// JSON mode
const json = await client.chat.completions.create({
  model: "uncensored",
  response_format: { type: "json_object" },
  messages: [
    { role: "system", content: "Reply with a JSON object only." },
    { role: "user", content: "Give me keys name and port for a local dev server." },
  ],
});
console.log(JSON.parse(json.choices[0].message.content));

يستخدم البث المتدفق أحداثًا تُرسل من الخادم (SSE)، ويُبلغ عن الاستخدام في نهاية البث. يحتفظ طلب البث بمكانه في فتحة التزامن حتى ينتهي البث، لذا فإن العميل الذي يفتح بثًا ولا يقرأه سيحجز فتحة. في وضع JSON، ما زال يتعين عليك توجيه النموذج في الموجّه للإجابة بصيغة JSON. يحدد هذا العلم تنسيق الإخراج، لكن التوجيه الواضح يمنحك أسماء حقول أفضل.

استدعاء الدوال

تستخدم الأدوات الشكل المعتاد لـ OpenAI: قائمة tools، وtool_choice اختياري، مع إرسال نتائج الأدوات كرسائل تحمل role: "tool". عند البث المتدفق، تصل أجزاء استدعاء الدوال tool_calls على دفعات عبر القطع.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.kimicode.cc/v1", api_key=os.environ["KIMICODE_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_port",
        "description": "Look up the port of a named local service",
        "parameters": {
            "type": "object",
            "properties": {"service": {"type": "string"}},
            "required": ["service"],
        },
    },
}]

messages = [{"role": "user", "content": "Which port does the api service use?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]

messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps({"service": "api", "port": 8080}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)

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

عند فشل الرابط

تندرج معظم الأخطاء ضمن قائمة قصيرة.

• 404 Not Found. المسار غير صحيح. الأسباب الشائعة: تم ضبط الرابط الأساسي على https://api.kimicode.cc بدون /v1، أو على https://api.kimicode.cc/v1/chat/completions مما يجعل العميل يلحق المسار مرتين. استخدم بالضبط الرابط الأساسي المذكور أعلاه.
• 401 غير مصرح. المفتاح مفقود، أو يحتوي على مسافة أو سطر جديد زائد، أو أن الرأس ليس رمز Bearer. اطبع طول المتغير للتحقق.
• 429 مع الرمز rate_limited. تجاوزت الحد المسموح لكل دقيقة: 300 طلب للمفتاح الكامل، و60 للمفتاح التجريبي.
• 429 مع الرمز concurrency. طلبات متزامنة كثيرة: 8 للمفتاح الكامل، و2 للمفتاح التجريبي.
• 429 مع رأس Retry-After: 5. حمل زائد مؤقت. انتظر خمس ثوانٍ وأعد المحاولة.
• حجم الطلب كبير جداً. حد الجسم هو 8 MB، ويجب أن يكون مجموع الموجّه والإكمال ضمن 100,000 رمز.

حلقة إعادة المحاولة التي تحترم Retry-After وتتراجع عند الرمزين الآخرين تتعامل مع معظم هذا. تكلفة كل استدعاء صغيرة؛ صفحة التسعير تحتوي على معدلات لكل رمز، ودليل البدء السريع يوضح خطوات الترحيل من مزود آخر بأسلوب OpenAI.

إعادة المحاولة وعادات الإنتاج

بمجرد نجاح أول استدعاء، أضف غلاف إعادة المحاولة قبل النشر. احترم رأس Retry-After عند وجوده، واستخدم تأخيرًا عشوائيًا قصيرًا في الحالات الأخرى.

Copyimport os, time, random
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.kimicode.cc/v1", api_key=os.environ["KIMICODE_KEY"])

def ask(messages, tries=5):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError as err:
            retry_after = 5
            if getattr(err, "response", None) is not None:
                retry_after = int(err.response.headers.get("retry-after", 5))
            time.sleep(retry_after + random.random())
    raise RuntimeError("still rate limited after retries")

حدد حدّ الطلبات المتزامنة الخاص بك ليتناسب مع مفتاحك: مجموعة خيوط بسعة 8 للمفتاح الكامل، و2 للمفتاح التجريبي. يمنع ذلك حدوث خطأ concurrency منذ البداية، ويحافظ عليك ضمن حدّ 300 طلب في الدقيقة حتى عندما يستغرق كل استدعاء أكثر من بضع ثوانٍ.

أخيراً، تذكر أنك تدفع لكل رمز. سجّل كائن usage لكل استدعاء، وتابع رأس X-Balance-USD. عند $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج، تكون تكلفة دورة محادثة نموذجية جزءاً من سنت واحد، لكن الحلقات والسجلات الطويلة تتراكم، والسجل يخبرك أين.

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

• أسعار Kimi Code API مقابل الرموز حسب الاستخدام
• Kimicode في Cursor بديل: إعداد نقطة النهاية المخصصة
• Groq API: خرافات مقابل حقائق حول LLMs بدون رقابة