# API Qwen Character เอกสารอ้างอิง API ฉบับสมบูรณ์สำหรับโมเดลสวมบทบาทตัวละคร Qwen โดย Alibaba โมเดล Qwen Character ใช้ endpoint 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` ตามปกติสำหรับการสวมบทบาทตัวละครเดียว ใส่คำสั่ง persona ที่คงที่สำหรับคำขอปัจจุบันไว้ในข้อความ `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 | ข้อความตามลำดับที่มี role `system`, `user` และ `assistant` แบบไม่บังคับ | | `stream` | boolean | `true` สำหรับ SSE, `false` สำหรับการตอบกลับ JSON รายการเดียว | #### Header | Header | จำเป็น | คำอธิบาย | |--------|----------|-------------| | `Authorization` | จำเป็น | คีย์ API ในรูปแบบ `Bearer YOUR_API_KEY` | | `Content-Type` | จำเป็น | ใช้ `application/json` | | `Accept` | จำเป็น | ใช้ `text/event-stream` เมื่อ `stream` เป็น `true`; ใช้ `application/json` เมื่อ `stream` เป็น `false` | | `x-session` | จำเป็นเมื่อเปิดใช้หน่วยความจำระยะยาว | ID เซสชันที่ผู้ใช้กำหนดเองสำหรับการแยกและเรียกคืนหน่วยความจำระยะยาว หน่วยความจำจะถูกแยกตาม user key ดังนั้นผู้ใช้ต่างคนสามารถใช้ ID เซสชันเดียวกันซ้ำได้โดยไม่แชร์หน่วยความจำกัน | #### การรองรับข้อความ | ฟิลด์ | ข้อความ | ไฟล์ | รูปภาพ | |-------|------|------|-------| | `messages` | จำเป็น ✅ | ไม่รองรับ ❌ | ไม่รองรับ ❌ | #### ฟิลด์ข้อความ | ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย | |-------|------|----------|-------------| | `role` | string | จำเป็น | รองรับ `system`, `user` และ `assistant` | | `content` | string | จำเป็น | ข้อความของ message สำหรับการจำลองแชตกลุ่ม ให้ใส่ชื่อผู้พูดด้วยตนเองที่จุดเริ่มต้น เช่น `Ling Lu:` | | `partial` | boolean | ไม่บังคับ | ใช้เฉพาะกับข้อความ assistant สุดท้าย ตั้งค่าเป็น `true` เมื่อ `content` เป็นคำนำหน้าที่โมเดลควรเขียนต่อ | #### ไม่บังคับ | พารามิเตอร์ | ประเภท | ช่วง | คำอธิบาย | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | จำนวน token เอาต์พุตสูงสุด | | `temperature` | number | `0.0` - `1.0` | ควบคุมความสุ่มของการตอบกลับ | | `seed` | integer | `0` - `2147483647` | seed แบบสุ่มสำหรับเอาต์พุตที่ทำซ้ำได้ ไม่เกี่ยวข้องกับหน้าต่างบริบทของบทสนทนา | | `profile` | string | — | โปรไฟล์ตัวละคร จำเป็นเมื่อ `enable_long_term_memory` เป็น `true` `profile` จะไม่เพิ่มชื่อผู้พูดลงในข้อความโดยอัตโนมัติ | | `enable_long_term_memory` | boolean | — | เปิดใช้หน่วยความจำระยะยาวสำหรับคำขอนี้ ต้องใช้ `profile` และ header `x-session` | | `memory_entries` | integer | — | จำนวนรายการหน่วยความจำที่ต้องเรียกคืนหรือเก็บไว้สำหรับเซสชัน เอกสารทางการยังไม่ได้ระบุขอบเขตช่วงแบบตายตัวในปัจจุบัน | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | ประเภทหน่วยความจำที่ต้องข้ามการบันทึกสำหรับคำขอนี้ | เมื่อเปิดใช้หน่วยความจำระยะยาว คุณต้องระบุ: - header คำขอ `x-session` - `profile` ใน body คำขอ - `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` การจำลองแชตกลุ่มทำผ่านข้อความใน message 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 } ``` ## รูปแบบการตอบกลับ โมเดล LLM Qwen Character ส่งคืนการตอบกลับแบบ completion ที่เข้ากันได้กับ OpenAI เมื่อใช้ `stream: true` การตอบกลับจะอยู่ในรูปแบบ Server-Sent Events; เมื่อใช้ `stream: false` การตอบกลับจะเป็นออบเจ็กต์ JSON เดียว ## แนวทางปฏิบัติที่ดีที่สุด - ใส่คำสั่ง persona ระดับคำขอในข้อความ `system` - ใส่พื้นหลังตัวละครที่ใช้ซ้ำได้ใน `profile` เฉพาะเมื่อเปิดใช้หน่วยความจำระยะยาว - ใช้ค่า `x-session` เดิมซ้ำในบทสนทนาที่เกี่ยวข้องเมื่อเปิดใช้หน่วยความจำระยะยาว เซสชันที่ไม่ได้ใช้งานเป็นเวลา 365 วันอาจถูกล้าง - ส่งข้อความบทสนทนาล่าสุดต่อไปเมื่อมีประโยชน์ หน่วยความจำระยะยาวและบริบทระยะสั้นสามารถทำงานร่วมกันได้ - สำหรับการจำลองแชตกลุ่ม ให้เขียนชื่อผู้พูดใน `content` ด้วยตนเอง API จะไม่อนุมานชื่อจาก `profile` - ใช้ `partial: true` เฉพาะในข้อความ assistant สุดท้ายเมื่อโมเดลควรเขียนต่อจากคำนำหน้า - ใช้ Qwen Flash Character สำหรับการสวมบทบาทแบบเบา และใช้ Qwen Plus Character สำหรับคุณภาพบทสนทนาที่สมบูรณ์กว่า