الملخص
تشغّل Kimi Hosted Agents مهام ذكاء اصطناعي متعددة الخطوات مع جلسات مستمرة، وتنفيذ أدوات، وبيئات sandbox سحابية. يأخذك هذا الدليل من مفتاح Kimi API إلى عرض تقديمي قابل للتنزيل من ثلاث شرائح باستخدام Bash وcurl وjq. أولًا أكمل مهمة واحدة بمطالبة مستقلة بذاتها. ثم أضف مستندًا مرفوعًا، ووصل أدوات الأعمال، وتعامل مع الإخفاقات المهمة في تطبيق مُنشَر.
أبرز النقاط
- تربط Kimi Hosted Agents بين تعريف وكيل، وبيئة تنفيذ، وجلسة. احتفظ بمعرّفاتها متاحة طوال سير العمل.
- ابدأ بنتيجة صغيرة قابلة للتحقق. المثال الأول يُنتِج عرضًا تقديميًا ببيانات خيالية وحساب يمكنك التحقق منه.
- استخدم تيار الأحداث لمتابعة التنفيذ، ثم افحص الملف المُسلَّم. نجاح الاستجابة HTTP وحده لا يثبت نجاح المهمة.
- وسّع المثال العامل بمدخلات ملفات أو أدوات مخصصة أو خدمات MCP. لكل تكامل متطلباته الخاصة للتنفيذ والاعتماديات.
- ضع ميزانية معًا للاستخدام الاستدلالي وزمن تشغيل الـsandbox والملحقات، بما في ذلك إعادة التشغيل اللازمة لإنتاج نتيجة مقبولة.
ما هي Kimi Hosted Agents؟
أعلنت Moonshot AI عن Kimi Hosted Agents في 5 نوفمبر 2026، وطرحتها كخدمة للمؤسسات والمطورين الذين يبنون وكلاء طويلة التشغيل.
يستخدم المنتج نهج Harness كخدمة. الـHarness هو البرنامج المحيط بالنموذج الذي يدير تقدم العمل: الحفاظ على الحالة، واستدعاء الأدوات، وإدارة التنفيذ، والتعافي من الانقطاعات.
تأمل سير عمل بحث أسبوعي. توليد النص خطوة واحدة فقط. قد يحتاج التطبيق أيضًا إلى جلب المصادر، ومعالجة الملفات، وإنشاء الرسوم البيانية، وحفظ عرض تقديمي، والحفاظ على حالة كافية للمتابعة بعد انقطاع الاتصال.
توفر Hosted Agents تلك الطبقة التشغيلية. لا يزال فريقك يحدد المهمة التجارية، ويختار عمليات التكامل، ويقرر ما يشكّل نتيجة مقبولة.
يعرض المعمارية الرسمية الخاصة بـ Kimi التطبيق وخدمات المنصة ونواة التنفيذ المستخدمة بواسطة زمن التشغيل المستضاف.
القدرات الأساسية لأول تكامل لك
- الجلسات الدائمة تحتفظ معًا بمدخلات المهمة وأحداث التنفيذ والمخرجات.
- صناديق الرمل السحابية توفّر الأدوات اللازمة لمعالجة الملفات وإنشاء المخرجات.
- المهارات والملحقات تعبّئ قدرات قابلة لإعادة الاستخدام؛ الأدوات المخصصة وخدمات MCP توصل أنظمتك الخاصة.
نقطة التفتيش الأولى هي عرض تقديمي يمكنك فتحه وفحصه. تصبح مواصفات زمن التشغيل المفصلة مفيدة عندما تضيف اعتماديات أو تنقل سير عمل قائمًا إلى الـsandbox؛ يوثّق مرجع الـsandbox البيئة المتاحة.
ماذا تحتاج قبل استدعاء Kimi Hosted Agents API؟
- حساب على منصة Kimi مع الوصول إلى Hosted Agents ومفتاح API.
- Bash وcurl وjq على macOS أو Linux أو Windows مع WSL.
- طرفيتان: الطرفية A تُرسل الطلبات؛ الطرفية B تراقب أحداث التنفيذ.
- عارض عروض تقديمية لفتح ملف PPTX المُولّد.
أنشئ حساب منصة Kimi ومفتاح API في منطقة إدارة الـAPI ضمن وحدة التحكم. استخدم طرفية Bash واحدة، تُدعى الطرفية A، للإعداد وأوامر المهمة. أبقِها مفتوحة ليعاد استخدام متغيراتها في الخطوات اللاحقة. ثبّت curl وjq قبل المتابعة. تستخدم الأمثلة إصدار الـAPI التجريبي 2026-09-01-beta.
command -v curl &&
command -v jq &&
read -rsp "مفتاح Kimi API: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
export KIMI_API_KEY &&
export KIMI_BASE="https://api.moonshot.cn/v1" &&
export KIMI_VERSION="2026-09-01-beta"
كيف تُشغّل أول مهمة على Kimi Hosted Agents
يتبع سير العمل الانطلاق السريع لواجهة REST من Kimi. ستستخدم مساعد PPT الرسمي لتحويل موجز عمل خيالي قصير إلى عرض تقديمي. جميع بيانات الإدخال مضمنة في الطلب، لذا لا يحتاج التشغيل الأول إلى رفع ملف أو اتصال بيانات خاصة.
نفّذ كل كتلة بالترتيب وتحقق من مخرجاتها قبل المتابعة. الأوامر الموصولة بـ && توقف تلك الكتلة عند فشل طلب أو تحقق. عالج الخطأ المُبلغ قبل الانتقال إلى الخطوة التالية؛ حافظ على نفس معرّفات البيئة والجلسة عند إعادة محاولة إعداد موجود.
الخطوة 1: اختر مساعد PPT الرسمي
اجلب الوكلاء المتاحين وتفقّد أسمائهم وتعريفاتهم. عند المطالبة، ألصق معرّف مساعد PPT الرسمي المُجهّز بمهارات PPT. يتحقق الأمر النهائي من أن اختيارك موجود في القائمة المُعادة ويطبع تعريفه.
curl --fail-with-body -sS "$KIMI_BASE/agents" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o agents.json &&
jq -r '.items[] | [.id, .name] | @tsv' agents.json &&
read -rp "معرّف مساعد PPT: " AGENT_ID &&
jq -e --arg id "$AGENT_ID" \
'.items[] | select(.id == $id)' agents.json &&
export AGENT_ID
يجب أن يطبع الأمر النهائي تعريف الوكيل المحدد. إذا كان المساعد غير متاح في مشروعك، استخدم تهيئة وكيل PPT الرسمي لإعداد وكيل مكافئ قبل المتابعة.
الخطوة 2: أنشئ بيئة سحابية
البيئة هي تهيئة قابلة لإعادة الاستخدام لإعداد تنفيذك، بما في ذلك الحزم المثبتة والوصول الشبكي وأوامر البدء. إعادة استخدامها تمنح الجلسات اللاحقة نفس الإعداد؛ كل جلسة سحابية ما تزال تتلقى صندوق رمل ومساحة عمل خاصين بها. راجع دليل البيئة لخيارات التهيئة.
أنشئ البيئة مرة واحدة واحتفظ بمعرّفها. تُبنى الصور السحابية بشكل غير متزامن، لذا انتظر حتى تصبح حالة بنائها ready قبل إنشاء جلسة. إذا أبلغت الواجهة البرمجية أنها غير جاهزة، انتظر وأعد المحاولة مع نفس ENVIRONMENT_ID. إنشاء بيئة أخرى لا يُكمل بناء الأولى.
curl --fail-with-body -sS "$KIMI_BASE/environments" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
-d '{"name":"بيئة العرض التقديمي الأولى","config":{"type":"cloud"}}' \
-o environment.json &&
ENVIRONMENT_ID="$(jq -er '.id | strings | select(length > 0)' environment.json)" &&
export ENVIRONMENT_ID &&
printf 'البيئة: %s\n' "$ENVIRONMENT_ID"
الخطوة 3: أنشئ جلسة
تثبّت الجلسة إصدار الوكيل وإصدار البيئة المتاحين عند إنشائها. يزوّد الطلب أدناه معرّفاتهما؛ تختار المنصة الإصدارات وتجمّدها. يمكنك أيضًا تعيين agent_version لاختيار إصدار وكيل محدد. لا يؤدي تحديث الوكيل أو البيئة لاحقًا إلى تحديث جلسة موجودة، ولا يمكن للجلسة تبديل environment_id. أنشئ جلسة جديدة لاستخدام تهيئات معدلة. هذه القواعد موثقة في إنشاء الجلسة.
احتفظ بمعرّف الجلسة المُعاد لكلّ من تيار الأحداث وطلبات المهام. تبدأ الجلسة الجديدة بحالة idle؛ إرسال user.message يبدأ المهمة.
test -n "$AGENT_ID" &&
test -n "$ENVIRONMENT_ID" &&
jq -n --arg agent "$AGENT_ID" --arg env "$ENVIRONMENT_ID" \
'{agent_id:$agent,environment_id:$env,title:"عرض تقديمي لتحديث المنتج الأول"}' \
> session-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @session-request.json \
-o session.json &&
SESSION_ID="$(jq -er '.id | strings | select(length > 0)' session.json)" &&
export SESSION_ID &&
printf 'الجلسة: %s\n' "$SESSION_ID"
الخطوة 4: راقب التنفيذ في طرفية ثانية
افتح الطرفية B. أدخل نفس مفتاح الـAPI، ثم ألصق معرّف الجلسة المطبوع في الطرفية A. يعرض تيار الأحداث المُرسلة من الخادم تحديثات التنفيذ بينما تُرسل الطرفية A المهمة. أبقِ هذه الطرفية متصلة حتى تفحص النتيجة.
read -rsp "مفتاح Kimi API: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
read -rp "معرّف الجلسة من الطرفية A: " SESSION_ID &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS -N \
"https://api.moonshot.cn/v1/sessions/$SESSION_ID/events/stream" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: 2026-09-01-beta" \
-H "Accept: text/event-stream"
الخطوة 5: أرسل مهمة مكتفية ذاتيًا
عد إلى الطرفية A وأرسل حدث user.message. يستخدم المثال أرقامًا خيالية ويطلب مخرجًا محددًا. يجب أن يستخدم الوكيل الحقائق المزوّدة بدلًا من البحث عن بيانات أعمال داعمة.
cat > task.json <<'JSON' &&
{
"events": [{
"type": "user.message",
"data": {"content": [{
"type": "text",
"text": "أنشئ ملف PPTX من ثلاث شرائح لمنتج خيالي يسمى Northstar. استخدم فقط هذه الحقائق المزوّدة: لدى التجربة 120 مستخدمًا؛ كان 90 منهم نشطين هذا الأسبوع؛ تخطط الفريق لإجراء مقابلات مع 10 مستخدمين الأسبوع القادم. الشريحة 1: نظرة عامة على التجربة. الشريحة 2: النشاط الأسبوعي، بما في ذلك نسبة المستخدمين النشطين. الشريحة 3: الخطوات التالية. ضع علامة على الأعمال والبيانات بأنها خيالية. لا تتصفح الويب. احفظ العرض التقديمي وسجل ملف PPTX كـ artifact قابل للتنزيل باستخدام save_artifact."
}]}
}]
}
JSON
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @task.json
الخطوة 6: نزّل العرض التقديمي وافحصه
راقب أحداث session.status في الطرفية B. عندما تعود الجلسة إلى idle، افحص سبب الإيقاف: يشير end_turn إلى أن الدور انتهى، بينما يعني requires_action أن عميلك يجب أن يزوّد نتيجة أداة أو يتعامل مع تأكيد. تحقق أيضًا من أحداث session.error. بعد أن ينتهي الدور دون خطأ غير محلول، اسرد الـartifacts واختر ملف PPTX المُنشأ.
curl --fail-with-body -sS "$KIMI_BASE/artifacts?session_id=$SESSION_ID" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o artifacts.json &&
jq . artifacts.json &&
read -rp "معرّف الـPPTX artifact: " ARTIFACT_ID &&
test -n "$ARTIFACT_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/artifacts/$ARTIFACT_ID/content" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o northstar.pptx &&
printf 'تم تنزيل northstar.pptx\n'
افتح northstar.pptx. النتيجة الناجحة تحتوي على ثلاث شرائح، وتُعرّف البيانات بأنها خيالية، وتحسب النشاط الأسبوعي كالتالي: 90 ÷ 120 = 75%. يمنحك هذا تحققًا ملموسًا لكلٍ من تسليم الملف ودقة المحتوى قبل توصيل بيانات أعمال حقيقية.
كيف ترفع الملفات وتربطها بجلسة Kimi Hosted Agents؟
بعد نجاح العرض التقديمي الأول، ضع ملف report.pdf نموذجيًا في دليل عمل الطرفية A. تفصل واجهة الملفات بين رفع ملف وإرفاقه بجلسة. شغّل هذه الكتلة بمعرّف الجلسة الحالي بعد انتهاء المهمة الأولى.
استخدم purpose=file-extract لاستخراج النص من ملف PDF. تسمح واجهة الملفات حتى 100 MiB لكل ملف وتفترض 10 GiB من التخزين لكل مؤسسة. لا يمكن تحديث الملفات المرفوعة في مكانها؛ ارفع ملفًا مُنقحًا واربط معرّفه الجديد. أزل الملفات غير المستخدمة عند الحاجة لتفريغ التخزين.
مع kimi-api-version: 2026-09-01-beta، تحقق من extract_status في استجابة الرفع. يتابع هذا المثال فقط عندما تكون قيمتها ready. إذا كانت error، افحص تنسيق ومحتوى PDF ثم ارفع ملفًا مصححًا. تستطيع الواجهة إرفاق استخراج فاشل كملف خام، لكن ذلك لا يوفر النص المُستخرج الذي يتوقعه هذا الشرح. تؤدي الحالة المفقودة أو غير المتوقعة أيضًا إلى إيقاف الكتلة؛ افحص upload.json قبل المتابعة.
test -f report.pdf &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/files" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-F "file=@report.pdf" \
-F "purpose=file-extract" \
-o upload.json &&
FILE_ID="$(jq -er '.id | strings | select(length > 0)' upload.json)" &&
{
EXTRACT_STATUS="$(jq -r '.extract_status // "missing"' upload.json)" &&
case "$EXTRACT_STATUS" in
ready) true ;;
error)
printf '%s\n' 'فشل استخراج PDF. افحص ملف PDF وارفع ملفًا مصححًا.' >&2
false ;;
*)
printf 'extract_status غير متوقعة: %s. افحص upload.json قبل المتابعة.\n' "$EXTRACT_STATUS" >&2
false ;;
esac
} &&
jq -n --arg file "$FILE_ID" \
'{type:"file",file_id:$file}' > resource-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/resources" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @resource-request.json
لا يؤدي إرفاق الملف إلى إرسال مهمة جديدة. أبقِ الطرفية B متصلة وقدّم متابعة تُسمي المستند والمخرج المطلوب.
jq -n --arg prompt \
"استخدم الملف المرفق report.pdf لإنشاء ملف PPTX جديد من ثلاث شرائح. استبدل الموجز الخيالي السابق. لخّص التقرير وأدلته وخطواته التالية. لا تخترع أرقامًا مفقودة ولا تتصفح الويب. سجّل ملف الـPPTX النهائي باستخدام save_artifact." \
'{events:[{type:"user.message",data:{content:[{type:"text",text:$prompt}]}}]}' \
> followup.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @followup.json
عندما تنتهي هذه المهمة، كرّر خطوة سرد الـartifacts واختر ملف PPTX الجديد. قارِن ادعاءاته مع ملف PDF، خصوصًا أي أرقام وتواريخ وإجراءات مقترحة.
كيف توصل الأدوات إلى Kimi Hosted Agents؟
أدوات مخصصة تنفذها تطبيقك
لإجراء عمل تجاري مثل البحث عن حالة تسليم مشروع، استخدم أداة مخصصة تطبقها تطبيقك. إعلان الأداة يجعلها متاحة للوكيل؛ يظل كودك هو من ينفذ العملية.
- أعلن عن إدخال
customفي مصفوفةtoolsللوكيل باسم ووصف وinput_schemaبشكل كائن. - تعامل مع
agent.custom_tool_useمن تيار الأحداث وحقّق من صحة الوسائط المُقدمة قبل تنفيذ دالتك. - انشر حدث
user.custom_tool_resultإلى الجلسة، باستخدام قيمة JSONidلحدث الاستدعاء كـdata.event_id.
ابدأ بعملية استعلام للقراءة فقط. أبقِ التفويض والحماية من تكرار الإجراء داخل التطبيق عندما يستطيع تكامل ما تعديل سجلات الأعمال.
خدمات MCP وسير عمل أكبر
لخدمة MCP بعيدة، أعلن اتصالها في mcp_servers. خزّن بيانات الوصول في خزنة واربط تلك الخزنة عند إنشاء الجلسة. تكتشف المنصة أدوات الخدمة وتناديها؛ يجب أن يحتوي تعريف الخادم على تفاصيل الاتصال بدلًا من الأسرار.
تنظيم متعدد الوكلاء اختياري
تدعم المنصة تفويضًا من المنسّق إلى الطفل. يمكن للمنسّق إسناد مهام محدودة إلى خيوط فرعية وجمع نتائجها.
تقبل تهيئة التفويض ما بين 1–20 إدخال وكيل. هذا حد تهيئة، وليس دليلًا على 20 عاملًا متزامنًا أو تحسن سرعة بمقدار 20×. لا تستطيع الخيوط الفرعية إنشاء طبقة أخرى من الخيوط الفرعية.
قد يكون تصميم مفيد هو فصل جمع المصادر، والتحليل الكمي، والمراجعة التحريرية. غالبًا ما تُعالج مهمة تلخيص قصيرة بشكل أفضل بواسطة وكيل واحد.
كيف تنشر تكامل Kimi Hosted Agents؟
ضع استدعاءات Kimi API خلف واجهة خادم تطبيقك الخلفية. يمكن للمتصفح تقديم مهمة وعرض التقدم عبر نقاط النهاية الخاصة بك، بينما يحتفظ الجانب الخلفي بمفتاح الـAPI ويربط كل مستخدم بالج-sessions المسموح له بالوصول إليها. خزّن معرّف الجلسة مع الطلب التجاري حتى يتمكن إعادة تحميل الصفحة من فتح نفس المهمة.
تنفيذ مستضاف مقابل مستضاف ذاتيًا
استخدم بيئة سحابية لسير عمل PPT في هذا الدليل: فهي تدعم save_artifact وسير عمل ملفات الجلسة. اختر بيئة مستضافة ذاتيًا عندما يجب أن يعمل تنفيذ الـsandbox على مضيف تديره مؤسستك. ما تزال Kimi تدير الاستدلال على النموذج والتنظيم وإدارة الجلسة؛ تمر مدخلات الأدوات ونتائجها عبر منصتها. هذا نموذج تنفيذ هجين.
- تتطلب البيئات المستضافة ذاتيًا تحققًا مؤسسيًا. أنت تشغّل مضيف Worker وتثبّت تبعياته وتدير العزل والاعتمادات. يحتاج الـWorker إلى وصول HTTPS صادر إلى المنصة.
- يفتقر الوضع المستضاف ذاتيًا حاليًا إلى
save_artifactوأدوات IPython وبحث الصور. لا تُركب الملفات المرفوعة والمهارات والذاكرة على الـWorker، ولا تظهر ملفاته الخارجة في قائمة ملفات الجلسة. خطّط لكيفية تزويد المدخلات واسترجاع المخرجات قبل نقل هذا الشرح إلى ذلك الوضع.
لأول تكامل، ابدأ في السحابة. فكّر في الاستضافة الذاتية عندما يبرر التحكم في مضيف التنفيذ الإعداد الإضافي والتغييرات على تسليم الملفات.
اختيار من يدير زمن التشغيل
استخدم Hosted Agents عندما تريد من المنصة إدارة تنفيذ الجلسة. إذا كان فريقك بحاجة إلى بناء وتشغيل حلقة وكيل خاصة به، فإن CometAPI يوفر وصول API موحد للنماذج لذلك المكدس المخصص. تستخدم أمثلة Hosted Agents في هذا الدليل نقاط نهاية وأوراق اعتماد Kimi نفسها.
تسعير Kimi Hosted Agents وتحسين التكلفة
تتقاضى Kimi Hosted Agents مقابل رموز النموذج، وزمن تشغيل الـsandbox السحابي، واستدعاءات الملحقات المدفوعة. يُظهر الجدول أدناه كيف تؤثر تلك الرسوم على سير عمل العرض التقديمي. الأسعار باليوان الصيني (CNY)، تم التحقق منها في 10 نوفمبر 2026 مقابل تسعير Hosted Agents وتسعير استدلال النموذج. يساوي مليون رمز 1 MTok.
| Cost component | Billing unit | Rate and what it means for your task |
|---|---|---|
| Model inference | Per 1 MTok | بالنسبة إلى kimi-k3.1-pro: إدخال أساسي ¥13، مخرج ¥68، ضربات الكاش ¥1.30، كتابات كاش لمدة 5 دقائق ¥13، وكتابات كاش لمدة ساعة ¥26. طبّق السعر على كل فئة استخدام عبر جميع استدعاءات النموذج. |
| Cloud sandbox | Runtime; billed by the second | ¥0.072/ساعة لبيئة sandbox مع 1 نواة CPU و1 GB ذاكرة. عشر دقائق تكلف ¥0.012. |
| Plugins | Per billable call | أمثلة: بحث الويب ¥0.03/استدعاء؛ بحث الصور ¥0.045/استدعاء. لكل ملحق سعره الخاص. اضرب عدد الاستدعاءات لكل ملحق في سعره المدرج. |
| Total task cost | Per completed task | اجمع رسوم النموذج والـsandbox والملحقات. المجموع المحسوب لمثال PPT أدناه هو ¥0.544 بدون ملحقات مدفوعة، أو ¥0.724 مع ثلاث عمليات بحث ويب وعمليتي بحث صور مع نفس افتراضات الاستخدام وزمن التشغيل. |
سعر النموذج هو مثال للتخطيط لـ kimi-k3.1-pro، وليس ادعاءً بأن كل وكيل PPT رسمي يستخدم ذلك النموذج. تحقّق من تعريف نموذج الوكيل المحدد قبل تطبيق هذه الأسعار. تختلف الأسعار للنماذج الأخرى والمتغيرات عالية السرعة.
كيف تعد الرموز الداخلة والخارجة
يمكن للوكيل استدعاء نموذجه عدة مرات أثناء إنشاء عرض تقديمي واحد. أضِف الاستخدام المُفوتر من كل استدعاء، بما في ذلك الأدوار اللاحقة والتنقيحات. يمكن أن يشمل الإدخال: المطالبة، والنص المُستخرج من PDF، ونتائج الأدوات، وسياق المحادثة؛ استخدام المخرج لا يقتصر على الكلمات الظاهرة على الشرائح.
بالنسبة إلى تخزين K3 المؤقت، افصل بين الإدخال غير المُخزّن، وكتابات الكاش، وضربات الكاش. هذه فئات إدخال مميزة: لا تُفوِّت كامل إجمالي الإدخال بالسعر الأساسي ثم تُضيف رسوم الكاش لنفس الرموز. استخدم سعر الكتابة المناسب لمدة 5 دقائق أو ساعة. يشرح دليل فوترة الكاش كيفية التوفيق بين هذه الفئات والاستخدام المُبلَّغ.
مثال محسوب: عرض تقديمي من ثلاث شرائح
افترض أن وكيلك يستخدم kimi-k3.1-pro وأن تشغيلًا كاملًا لعرض من ثلاث شرائح يستهلك 20,000 رمز إدخال، و4,000 رمز مخرج مُفوتر، و10 دقائق من زمن تشغيل السحابة المفوتر. افترض عدم وجود ضربات كاش، ولا كتابات كاش لمدة ساعة، ولا ملحقات مدفوعة. كل الإدخال إما غير مُخزّن أو مكتوب إلى كاش 5 دقائق الافتراضي، وكلاهما بسعر ¥13/MTok. هذه كميات استخدام تقديرية للتخطيط، وليست قياسات لشرح Northstar.
| Charge | Calculation | Estimated cost |
|---|---|---|
| Model input | 20,000 ÷ 1,000,000 × ¥13 | ¥0.260 |
| Model output | 4,000 ÷ 1,000,000 × ¥68 | ¥0.272 |
| Cloud sandbox | 10 ÷ 60 × ¥0.072 | ¥0.012 |
| Paid plugins | 0 billable calls | ¥0.000 |
| Total | ¥0.260 + ¥0.272 + ¥0.012 | ¥0.544 (حوالي ¥0.54) |
يطلب الشرح المعتمد على الحقائق المُزوّدة من الوكيل عدم تصفح الويب. إذا وسّعته لاحقًا إلى عرض بحث مع ثلاث عمليات بحث ويب وعمليتي بحث صور، ستكون رسوم الملحقات 3 × ¥0.03 + 2 × ¥0.045 = ¥0.180. مع تثبيت الكميات الأخرى يصبح ¥0.544 + ¥0.180 = ¥0.724. قد تزيد الأبحاث أيضًا من رموز النموذج وزمن التشغيل، لذا استخدم الكميات المقاسة للفاتورة النهائية.
ماذا يتغير عند استخدام عدة وكلاء؟
يمكن للتفويض أن يضيف استدعاءات نموذجية، وسياقًا مكررًا، واستدعاءات أدوات، وعمل تنقيح. يضع سير العمل متعدّد الوكلاء في Kimi المنسّق والخيوط الفرعية في جلسة واحدة. عدد الخيوط الفرعية وحده ليس مضاعفًا لرسوم الـsandbox. اجمع استخدام النموذج والملحقات عبر الخيوط، واستخدم زمن التشغيل المفوتر الفعلي للجلسة. يمكن أن يزيد التنفيذ الأطول أو الجلسات السحابية المستقلة الإضافية تكلفة الـsandbox. يوضح الأسئلة الشائعة أن وقت الـsandbox يتوقف عن التراكم عند انتهاء جميع الخيوط وعودة الجلسة إلى حالة idle.
خفّض التكلفة لكل عرض تقديمي قابل للاستخدام
ابدأ بوكيل واحد ومخرج صغير. زوّد المقاطع المصدرية ذات الصلة، وقيّد عدد الشرائح، وفعّل عمليات البحث المدفوعة فقط عند الحاجة. أعِد الاتصال بتيار أحداث انقطع بدلًا من تقديم نفس المهمة مرة أخرى. بالنسبة لسير العمل المتكرر، افحص ضربات الكاش وحافظ على ثبات السياق القابل لإعادة الاستخدام. قارِن التكلفة الإجمالية لجميع المحاولات بعدد العروض التي تقبلها فعليًا؛ قد تُكلّفك مسودة أولى رخيصة تحتاج عدة إعادة تشغيل أكثر بشكل إجمالي.
استكشاف أخطاء واجهة API الشائعة وإصلاحها
- فشل المصادقة: تحقق من أن مفتاح الـAPI مضبوط في الطرفية التي تُرسل الطلب وينتمي إلى الحساب المقصود. افحص خطأ HTTP قبل تكرار الاستدعاء.
- يرفض curl خيارًا، أو jq مفقود: تحقق من الأدوات المثبتة. تتطلب هذه الأمثلة إصدار curl يدعم
--fail-with-bodyوتنفيذًا عاملاً لـjq في نفس بيئة Bash. - لا يستطيع jq استخراج معرّف: افتح JSON الاستجابة المحفوظة. قد تحتوي على خطأ API بدلًا من كائن مورد ناجح. أصلح الطلب أولًا بدلًا من تمرير معرّف فارغ إلى نقطة النهاية التالية.
- يتوقف سير عمل أداة مخصصة عن التقدم: افحص أحداث الأدوات المعلّقة. يعني سبب الإيقاف
requires_actionأن العميل يحتاج لإرجاع نتيجة أداة أو التعامل مع تأكيد قبل أن يواصل الخيط المتأثر. - تحتوي الشرائح المُنزّلة على ادعاءات غير مدعومة: قارِنها بالموجز أو التقرير المزوّد. عدّل المهمة مع التناقض المحدد وافحص المُخرج التالي قبل استخدامه.
سجّل نقطة النهاية وحالة HTTP ومعرّف الجلسة والحدث ذي الصلة عند تشخيص الفشل. أبقِ مفاتيح الـAPI خارج سجلات التشخيص.
الخلاصة
ابدأ بسير عمل Kimi Hosted Agents واحد كامل: اختر وكيلًا، حضّر بيئته، أنشئ جلسة، قدّم مهمة، وافحص الملف المُسلَّم. بمجرد أن يعمل هذا المسار، أضف مستندًا مصدريًا ثم أدوات الأعمال التي يحتاجها تطبيقك. أبقِ التقدم مرئيًا واحكم على كل تشغيل بناءً على فائدة مخرجه، لا بمجرد نجاح الطلب.
الأسئلة الشائعة
هل أحتاج لإرسال مهمة Kimi Hosted Agents مرة أخرى بعد انقطاع الاتصال؟
لا. لا يتطلب تيار أحداث منقطع تقديم مهمة جديدة. أعد الاتصال بقيمة id: لإطار SSE الأخير في ترويسة Last-Event-ID لاستئناف القراءة. هذه القيمة مؤشّر تيار، وليست معرّف JSON لكائن الحدث. يُجنبك إعادة الاتصال إرسال نفس العمل مرتين عن طريق الخطأ.
ماذا لو كان مخرج Kimi Hosted Agents مفقودًا من الـartifacts؟
قد يوجد ملف الـsandbox دون أن يُسجّل كـartifact. تحقق ما إذا كان الوكيل قد أكمل العرض التقديمي واستدعى save_artifact. إذا كان التسجيل مفقودًا، استخدم واجهات ملفات الجلسة لفحص دليل المخرجات: GET /v1/sessions/{session_id}/filesystem?prefix=output. يغطي السرد دليلًا واحدًا في كل مرة؛ حدّث prefix لفحص دليل فرعي. نزّل الملف المختار بـ GET /v1/sessions/{session_id}/filesystem/raw?path=output/northstar.pptx، مع استبدال مسار المثال بالمسار الدقيق المُعاد في السرد. رمّز قيمة الاستعلام بعنوان URL إذا احتوى المسار على مسافات أو محارف محجوزة أخرى. أدرج نفس ترويسات التفويض وإصدار الـAPI كما في هذا الشرح.
هل سيؤدي تحديث تهيئة Kimi Hosted Agents إلى تغيير جلسة نشطة؟
لا. تستخدم الجلسة إصدار الوكيل المثبّت عند الإنشاء. يؤدي تحديث الوكيل إلى إنشاء إصدار جديد للجلسات اللاحقة بينما تحتفظ الجلسات الحالية بتهيئتها الأصلية. لاختبار تعليمات أو أدوات منقحة، ابدأ جلسة جديدة وقارِن مخرجها مع التشغيل السابق.

