# Qwen Character API مرجع API كامل لنماذج لعب الأدوار Qwen Character من Alibaba. تستخدم نماذج Qwen Character نقطة نهاية chat completions في Flaq AI، لكنها تدعم أيضا حقولا خاصة بالشخصيات للذاكرة طويلة المدى، ومحاكاة الدردشة الجماعية، والاستكمال الجزئي من assistant. ## متغيرات النموذج يدعم هذا API متغيرين للنموذج: | النموذج | ID | الوصف | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | لعب أدوار شخصية بجودة أعلى | | **Qwen Flash Character** | `qwen-flash-character` | لعب أدوار شخصية أسرع وأقل تكلفة | ## مقارنة سريعة | الميزة | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | إدخال النص | مطلوب ✅ | مطلوب ✅ | | إدخال الصورة | غير مدعوم ❌ | غير مدعوم ❌ | | الذاكرة طويلة المدى | اختياري | اختياري | | `temperature` | اختياري | اختياري | | `seed` | اختياري | اختياري | | استجابة البث | SSE | SSE | ## كيف يعمل لعب أدوار الشخصيات استخدم رسائل `system` و`user` و`assistant` العادية للعب دور شخصية واحدة. ضع تعليمات الشخصية الثابتة في رسالة `system` للطلب الحالي. عند تفعيل الذاكرة طويلة المدى، ضع ملف الشخصية القابل لإعادة الاستخدام في `profile`. في محاكاة الدردشة الجماعية، لا يستنتج Qwen Character أسماء المتحدثين تلقائيا من `profile`. يجب على المستدعي كتابة أسماء المتحدثين في بداية `content` لكل رسالة، مثل `Cheng Yi:` أو `Ling Lu:`. لجعل النموذج يتابع كشخصية محددة، أضف رسالة assistant أخيرة يكون `content` فيها هو بادئة المتحدث المستهدف واضبط `partial: true`. `partial` حقل على مستوى الرسالة في رسالة assistant الأخيرة. وليس معامل طلب على المستوى الأعلى. ## Qwen Plus Character ### نقطة النهاية ```http POST /api/v1/chat/completions ``` ### معاملات الطلب #### مطلوب | المعامل | النوع | الوصف | |-----------|------|-------------| | `model` | string | يجب أن يكون `"qwen-plus-character"` | | `messages` | array | رسائل مرتبة بأدوار `system` و`user` و`assistant` الاختياري. | | `stream` | boolean | `true` لـ SSE، و`false` لاستجابة JSON واحدة. | #### الترويسات | الترويسة | مطلوب | الوصف | |--------|----------|-------------| | `Authorization` | مطلوب | مفتاح API، بالتنسيق `Bearer YOUR_API_KEY`. | | `Content-Type` | مطلوب | استخدم `application/json`. | | `Accept` | مطلوب | استخدم `text/event-stream` عندما تكون `stream` هي `true`؛ واستخدم `application/json` عندما تكون `stream` هي `false`. | | `x-session` | مطلوب عند تفعيل الذاكرة طويلة المدى | معرّف جلسة يحدده المستخدم لعزل الذاكرة طويلة المدى واسترجاعها. يتم عزل الذاكرة حسب مفتاح المستخدم، لذلك يمكن لمستخدمين مختلفين إعادة استخدام معرّف الجلسة نفسه دون مشاركة الذاكرة. | #### دعم الرسائل | الحقل | نص | ملف | صورة | |-------|------|------|-------| | `messages` | مطلوب ✅ | غير مدعوم ❌ | غير مدعوم ❌ | #### حقول الرسائل | الحقل | النوع | مطلوب | الوصف | |-------|------|----------|-------------| | `role` | string | مطلوب | يدعم `system` و`user` و`assistant`. | | `content` | string | مطلوب | نص الرسالة. في محاكاة الدردشة الجماعية، أدرج اسم المتحدث يدويا في البداية، مثل `Ling Lu:`. | | `partial` | boolean | اختياري | يستخدم فقط في رسالة assistant الأخيرة. اضبطه على `true` عندما يكون `content` بادئة يجب أن يتابع النموذج منها. | #### اختياري | المعامل | النوع | النطاق | الوصف | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | الحد الأقصى لرموز الإخراج. | | `temperature` | number | `0.0` - `1.0` | يتحكم في عشوائية الاستجابة. | | `seed` | integer | `0` - `2147483647` | بذرة عشوائية للحصول على مخرجات قابلة للتكرار. لا ترتبط بنافذة سياق المحادثة. | | `profile` | string | — | ملف الشخصية. مطلوب عندما تكون `enable_long_term_memory` هي `true`. لا يضيف `profile` أسماء المتحدثين إلى الرسائل تلقائيا. | | `enable_long_term_memory` | boolean | — | يفعّل الذاكرة طويلة المدى لهذا الطلب. يتطلب `profile` وترويسة `x-session`. | | `memory_entries` | integer | — | عدد إدخالات الذاكرة المطلوب استرجاعها أو الاحتفاظ بها للجلسة. لا تعرض الوثائق الرسمية حاليا حد نطاق ثابت. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | أنواع الذاكرة التي يجب تخطي حفظها لهذا الطلب. | عند تفعيل الذاكرة طويلة المدى، يجب تقديم: - ترويسة طلب `x-session` - `profile` في جسم الطلب - `enable_long_term_memory: true` يدعم `skip_save_types` هذه القيم: | القيمة | المعنى | |-------|---------| | `system` | تخطي حفظ رسائل `system` المضافة في هذا الطلب. | | `user` | تخطي حفظ رسائل `user` المضافة في هذا الطلب. | | `assistant` | تخطي حفظ رسائل `assistant` المضافة في هذا الطلب. | | `output` | تخطي حفظ رسالة assistant التي يولدها هذا الطلب. | ### طلب لعب أدوار أساسي ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 1200, temperature: 0.8, messages: [ { role: 'system', content: 'You are Jiang Rang, a witty high-school Go prodigy. Stay playful, warm, and concise.' }, { role: 'user', content: 'Why are you reading Go records outside the milk tea shop again?' } ] }) }); ``` ### طلب الذاكرة طويلة المدى ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'text/event-stream', 'Content-Type': 'application/json', 'x-session': 'your-session-id' }, body: JSON.stringify({ model: 'qwen-plus-character', messages: [ { role: 'system', content: 'You are a witty high-school student who speaks with humor and warmth.' }, { role: 'user', content: 'Remember that I prefer lightly sweet milk tea.' } ], stream: true, max_tokens: 1200, temperature: 0.8, seed: 12345, profile: 'You are a witty high-school student who remembers user preferences and stays in character.', enable_long_term_memory: true, memory_entries: 50, skip_save_types: [] }) }); ``` ### محاكاة الدردشة الجماعية باستخدام `partial` تُنفّذ محاكاة الدردشة الجماعية عبر نص الرسائل. لا يعيّن API أسماء المتحدثين أو ينقلها تلقائيا. اكتب اسم كل متحدث يدويا في بداية `content`، ثم أضف رسالة assistant أخيرة تحتوي على بادئة المتحدث المستهدف و`partial: true`. ```javascript const response = await fetch('https://api.flaq.ai/api/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen-plus-character', stream: false, max_tokens: 800, temperature: 0.8, messages: [ { role: 'system', content: 'In a musician group chat, Ling Lu is a 25-year-old gifted musician known for sharp humor and a regional accent. Cheng Yi is his music partner, Tao Le is his partner, and Ma Hui is a friend. Keep Ling Lu sarcastic but caring. Reply in one short message.' }, { role: 'user', content: 'Cheng Yi: Are you free this weekend? I want feedback on the new song.' }, { role: 'user', content: 'Tao Le: He is right, but do not stay up too late editing.' }, { role: 'user', content: 'Ma Hui: Let us grab dinner and talk. My treat.' }, { role: 'assistant', content: 'Ling Lu:', partial: true } ] }) }); ``` ### المتابعة كشخصية باستخدام `partial` استخدم نمط `partial` نفسه عندما لا يكون المستخدم قد رد بعد، لكنك تريد أن تواصل الشخصية الكلام. أضف رسالة assistant أخيرة تحتوي على بادئة الشخصية. ```javascript { model: 'qwen-plus-character', stream: false, messages: [ { role: 'system', content: 'You are Jiang Rang, a high-school Go prodigy. Speak with humor and warmth.' }, { role: 'assistant', content: 'Class monitor, what are you doing?' }, { role: 'assistant', content: '(He waves at you.) Did being class monitor make you forget how to answer me?' }, { role: 'assistant', content: 'Jiang Rang:', partial: true } ] } ``` ## Qwen Flash Character ### معاملات الطلب نفس بروتوكول Qwen Plus Character، مع هذه الاختلافات: | المعامل | Qwen Flash Character | |-----------|----------------------| | `model` | يجب أن يكون `"qwen-flash-character"` | ### مثال طلب ```javascript { model: 'qwen-flash-character', messages: [ { role: 'system', content: 'You are a calm library assistant who speaks briefly and vividly.' }, { role: 'user', content: 'Introduce yourself in three sentences.' } ], stream: true, max_tokens: 800, temperature: 0.7, seed: 12345 } ``` ## تنسيق الاستجابة تعيد نماذج Qwen Character اللغوية الكبيرة استجابات إكمال متوافقة مع OpenAI. عند استخدام `stream: true`، تكون الاستجابة في صورة Server-Sent Events؛ وعند استخدام `stream: false`، تكون الاستجابة كائن JSON واحدًا. ## أفضل الممارسات - ضع تعليمات الشخصية على مستوى الطلب في رسائل `system`. - ضع خلفية الشخصية القابلة لإعادة الاستخدام في `profile` فقط عند تفعيل الذاكرة طويلة المدى. - أعد استخدام قيمة `x-session` نفسها عبر المحادثات ذات الصلة عند تفعيل الذاكرة طويلة المدى. قد تُحذف الجلسات غير المستخدمة لمدة 365 يوما. - استمر في إرسال رسائل المحادثة الحديثة عندما يكون ذلك مفيدا؛ يمكن للذاكرة طويلة المدى والسياق قصير المدى العمل معا. - في محاكاة الدردشة الجماعية، اكتب أسماء المتحدثين يدويا في `content`. لن يستنتج API الأسماء من `profile`. - استخدم `partial: true` فقط في رسالة assistant الأخيرة عندما يجب أن يتابع النموذج من بادئة. - استخدم Qwen Flash Character للعب الأدوار الخفيف وQwen Plus Character لجودة حوار أغنى.