Your privacy choices

Allow optional cookies for referral attribution, visit analytics, and Google Ads purchase measurement.

العودة إلى المدونة
العربيةDeutschEnglishEspañolFrançais日本語한국어LatinaBahasa MelayuPortuguês (Brasil)РусскийไทยTiếng Việt繁體中文中文

دليل Kimi K3.1 Pro لواجهة API واستخدامها مع Agent

Kimi K3.1 ProMoonshot APIAgentربط النماذج

تنتمي Kimi K3.1 Pro إلى عائلة K3.1 من Moonshot AI، وهي مصممة للبرمجة وإنشاء محتوى ثلاثي الأبعاد والبحث المالي وسير عمل Agent طويل الأمد. عند استدعائها عبر API الرسمي، يكون معرّف النموذج kimi-k3.1-pro، ويكون Base URL الخاص بـ OpenAI SDK هو https://api.moonshot.cn/v1. وضع التفكير مفعّل دائمًا. ويمكن ضبط مستوى الاستدلال على low أو high أو max، والقيمة الافتراضية هي max.البدء السريع الرسمي

يعرض هذا الدليل الربط والاستدلال والرؤية ودورة استخدام الأدوات استنادًا إلى وثائق API الرسمية. نتائج المعايير التي ينشرها المورّد هي نتائج صادرة عنه، وليست اختبارات أجرتها Guishu Intelligence.

لمحة سريعة

البند معلومات تم التحقق منها
معرّف النموذج الرسمي kimi-k3.1-pro
عنوان API الأساسي الرسمي https://api.moonshot.cn/v1
مستوى الاستدلال low وhigh وmax؛ الافتراضي: max
وضع التفكير مفعّل دائمًا
السياق تذكر الوثائق الرسمية أنه يدعم مليون token
الإصدار عالي السرعة kimi-k3.1-pro-highspeed؛ نموذج مستقل. تحقّق من كتالوج المنصة المعنية لمعرفة التوفّر والسعر.
تاريخ التحقق من الوثائق 2026-10-24

تستند معلومات القدرات والنماذج إلى وثائق Kimi K3.1 Pro الرسمية. وقد تتغير إصدارات النماذج وشروط الوصول والتكاليف. راجع أسعار النماذج لمعرفة التوفّر والأسعار الحالية على منصتنا.

ما المهام التي يناسبها هذا الإصدار؟

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

كاميرا ثلاثية الأبعاد: هل يتغير التصميم فعلًا مع تغيّر المعلمات؟

في مقال «خطت النماذج المحلية خطوة كبيرة أخرى إلى الأمام: تجربة عملية لـ Kimi K3.1 Pro»، طلب Liu Xiaopai من عدة نماذج إنشاء كاميرا تفاعلية. وذكر الكاتب أن K3.1 Pro أنشأت 34 مكوّنًا قابلًا للاختيار وفتحة عدسة ذات تسع شفرات، وأن 35 قراءة بصرية اجتازت فحوصه. وفي جولة ثانية، أدى تغيير العدسة من 50 mm إلى 85 mm إلى تغيير الشكل الهندسي أيضًا، لا إلى تبديل التسمية فحسب.

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

خريطة لعبة: أنشئ أداة ثم اطلب من Agent استخدامها

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

البحث المالي: افحص المعادلات والمراجع، لا الاستنتاجات وحدها

تصف مواد قدّمها Zenan وZhang Qian وPanda من المؤسسة الإعلامية Jiqizhixin نمذجة مالية وتقارير بحثية وأمثلة هندسية ثلاثية الأبعاد. كما تعرض الوثائق الرسمية نموذجًا ماليًا يمكن تعديل افتراضاته التشغيلية، وتقريرًا بحثيًا يتضمن مصادر. ومن معايير القبول المفيدة التحقق من تحديث المعادلات عند تغيير الافتراضات، وإمكانية تتبّع الأرقام المهمة إلى الملفات المصدرية، وفتح كل مرجع في التقرير والوصول إلى مصدره. عرض المورّد لا يضمن الدقة في كل مهمة مالية.عرض القدرات والأمثلة الرسمي

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

استدعاء أساسي لـ API

يستخدم المثال الرسمي Python 3.9+ وOpenAI SDK. خزّن مفتاح API في متغير بيئة؛ ولا تضعه في الشيفرة المصدرية أو ترفعه إلى نظام إدارة الإصدارات.

python3 -m pip install --upgrade 'openai>=1.0'
export MOONSHOT_API_KEY="your-api-key"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

result = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "اذكر ثلاث طرق لتصميم عملية موثوقة لمراجعة الشيفرة."}],
    reasoning_effort="high",
)
print(result.choices[0].message.content)

للاتصال المباشر بـ Moonshot، استخدم مفتاحًا صادرًا عنها وعنوان Base URL الرسمي أعلاه. وعند استخدام خدمة خارجية متوافقة مع OpenAI، استبدل Base URL والمفتاح واسم النموذج بالقيم التي تقدمها تلك الخدمة؛ ولا تشارك معها بيانات اعتماد Moonshot. للاطلاع على النماذج والفوترة المتاحة حاليًا من Guishu Intelligence، راجع صفحة أسعار النماذج.

اختيار مستوى الاستدلال

تعمل K3.1 Pro دائمًا في وضع التفكير. يتحكم reasoning_effort في مستوى الاستدلال، ولا يفعّل وضع التفكير أو يوقفه. الخيارات الرسمية هي low وhigh وmax، والقيمة الافتراضية max.وثائق مستوى الاستدلال

  • في الأسئلة والأجوبة القصيرة أو مهام التحويل ذات البنية الواضحة، جرّب low أولًا.
  • في تعديلات الشيفرة متعددة الخطوات والتحليل والتخطيط، ابدأ بـ high.
  • في المهام المعقدة التي تتطلب استدلالًا أعمق، قارن max من حيث الجودة ووقت الاستجابة والتكلفة الفعلية.

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

المحادثات متعددة الأدوار: احتفظ برسالة assistant كاملة

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

messages = [{"role": "user", "content": "ضع أولًا خطة للترحيل، ثم اشرح المخاطر."}]
first = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=messages,
    reasoning_effort="high",
)
messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "حوّل قسم المخاطر إلى قائمة تحقق."})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)

إذا كان تطبيقك يحفظ المحادثات بين الطلبات، فاحفظ حقول الرسائل التي يتطلبها البروتوكول، وتحقق من الوثائق الرسمية لكيفية تسلسل SDK لكائنات الرسائل.

استدعاء الأدوات وحلقة Agent

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

import json

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_order",
        "description": "الاستعلام عن حالة الطلب",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]
messages = [{"role": "user", "content": "تحقّق من حالة الطلب A-104"}]
response = client.chat.completions.create(
    model="kimi-k3.1-pro", messages=messages, tools=tools
)
assistant = response.choices[0].message
messages.append(assistant)  # احتفظ برسالة assistant كاملة

for call in assistant.tool_calls or []:
    args = json.loads(call.function.arguments)
    # في تطبيق فعلي، تحقّق من المعاملات وصلاحيات المستخدم قبل
    # استدعاء وظيفة أعمال خاضعة للضوابط.
    tool_result = {"order_id": args["order_id"], "status": "processing"}
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(tool_result),
    })

final = client.chat.completions.create(
    model="kimi-k3.1-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)

يشترط دليل استدعاء الأدوات الرسمي أيضًا إرجاع نتيجة كل أداة مع tool_call_id المطابق، والاحتفاظ برسالة assistant كاملة في الأدوار التالية. ويتولى التطبيق مسؤولية التفويض والتحقق من المعاملات والمهل الزمنية وضمان عدم تكرار الأثر والتدقيق.

إدخال الصور: استخدم مصفوفة من الكائنات

تنص الوثائق الرسمية على أن content في رسالة الرؤية يجب أن يكون مصفوفة من الكائنات، لا سلسلة متسلسلة. يرسل المثال الصورة عبر Base64 Data URL. ويمكن أيضًا استخدام مرجع ملف ms:// ضمن مسار الملفات المدعوم. لا تفترض إمكانية قراءة عنوان عام عادي لصورة.وثائق إدخال الصور

import base64
from pathlib import Path

image_data = base64.b64encode(Path("diagram.png").read_bytes()).decode()
response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {
                "url": f"data:image/png;base64,{image_data}"
            }},
            {"type": "text", "text": "صف مكوّنات النظام والروابط بينها في المخطط."},
        ],
    }],
)
print(response.choices[0].message.content)

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

تفسير المعايير الرسمية وتجارب الأطراف الأخرى

تذكر وثائق Moonshot أن K3.1 Pro حققت 65.7% في Terminal-Bench 4.0، وتعرض مقارنات مع GPT-6 Astra وClaude Opus 5.5. هذه أرقام معايير نشرها المورّد. فسّرها في ضوء مجموعة المهام وإعدادات الاختبار وتاريخ النشر؛ فهي لا تتنبأ بمعدل النجاح في جميع مهام البرمجة.نظرة عامة رسمية على النموذج ومعاييره

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

قائمة التحقق للربط

  1. حدّد ما إذا كنت تتصل مباشرةً بـ API الرسمي أو تستخدم خدمة متوافقة، ثم استخدم معرّف النموذج وBase URL والمفتاح المطابقين.
  2. ابدأ بمستوى استدلال أقل، وقارن الجودة ووقت الاستجابة والفوترة على مهام تمثيلية.
  3. في المحادثات متعددة الأدوار وسير عمل Agent، احتفظ برسالة assistant كاملة واربط نتائج الأدوات بالاستدعاء الصحيح.
  4. أنشئ رسائل الرؤية كمصفوفة من الكائنات، واستخدم ترميزًا أو مسار ملفات مدعومًا للصور المحلية.
  5. ضع حدودًا للصلاحيات، وتحقق من المعاملات، وحدد مهلًا زمنية وآلية لمعالجة فشل تنفيذ الأدوات.
  6. قبل النشر، تحقّق من كتالوج النماذج الحالي والمناطق المتاحة والأسعار بدلًا من إعادة استخدام إعداد قديم.

الأسئلة الشائعة

ما معرّف API لنموذج Kimi K3.1 Pro؟

تذكر الوثائق الرسمية المعرّف kimi-k3.1-pro. أما الإصدار عالي السرعة فيُسمى kimi-k3.1-pro-highspeed، وينبغي التعامل معه كإعداد نموذج منفصل.

ما مستوى الاستدلال الافتراضي؟

تسرد الوثائق الرسمية low وhigh وmax، والقيمة الافتراضية هي max. أما وضع التفكير نفسه فمفعّل دائمًا.

هل يمكنني تمرير عنوان URL للصورة مباشرةً؟

لا. تنص الوثائق الرسمية صراحةً على عدم دعم عناوين الصور العامة. استخدم مصفوفة كائنات للرؤية مع Base64 Data URL، أو مرجع ms:// عبر مسار الملفات.

لماذا ينبغي أن يعيد Agent رسالة assistant كاملة؟

قد تحتوي الرسالة على حقول منظمة مثل استدعاءات الأدوات. الاقتصار على النص يؤدي إلى فقدان معلومات لازمة للتفاعلات اللاحقة. كما يجب إعادة نتائج الأدوات مع tool_call_id المطابق.

هل توفر Guishu Intelligence نموذج Kimi K3.1 Pro؟

راجع صفحة أسعار النماذج للاطلاع على النماذج المتاحة والتوجيه والأسعار الحالية. وجود قدرات في API الرسمي لا يعني أن النموذج أو إصداره عالي السرعة متاح على منصتنا.

لمزيد من القراءة

تاريخ التحقق من الوثائق الرسمية: 2026-10-24. قد تتغير قدرات النموذج ومعلمات API وشروط الوصول؛ راجع وثائق Moonshot Kimi API.