# API Qwen Character Tài liệu tham chiếu API đầy đủ cho các mô hình nhập vai nhân vật Qwen của Alibaba. Các mô hình Qwen Character dùng endpoint chat completions của Flaq AI, đồng thời hỗ trợ các trường riêng cho nhân vật để dùng bộ nhớ dài hạn, mô phỏng chat nhóm và tiếp tục assistant một phần. ## Biến thể mô hình API này hỗ trợ hai biến thể mô hình: | Mô hình | ID | Mô tả | |-------|----|-------------| | **Qwen Plus Character** | `qwen-plus-character` | Nhập vai nhân vật chất lượng cao hơn | | **Qwen Flash Character** | `qwen-flash-character` | Nhập vai nhân vật nhanh hơn và tiết kiệm hơn | ## So sánh nhanh | Tính năng | Qwen Plus Character | Qwen Flash Character | |---------|---------------------|----------------------| | Đầu vào văn bản | Bắt buộc ✅ | Bắt buộc ✅ | | Đầu vào hình ảnh | Không được hỗ trợ ❌ | Không được hỗ trợ ❌ | | Bộ nhớ dài hạn | Tùy chọn | Tùy chọn | | `temperature` | Tùy chọn | Tùy chọn | | `seed` | Tùy chọn | Tùy chọn | | Phản hồi streaming | SSE | SSE | ## Cách hoạt động của nhập vai nhân vật Dùng các tin nhắn `system`, `user` và `assistant` thông thường cho nhập vai một nhân vật. Đặt hướng dẫn persona ổn định cho yêu cầu hiện tại trong tin nhắn `system`. Khi bộ nhớ dài hạn được bật, đặt hồ sơ nhân vật có thể tái sử dụng trong `profile`. Với mô phỏng chat nhóm, Qwen Character không tự động suy luận tên người nói từ `profile`. Bên gọi phải viết tên người nói ở đầu mỗi `content` của tin nhắn, chẳng hạn `Cheng Yi:` hoặc `Ling Lu:`. Để mô hình tiếp tục với tư cách một nhân vật cụ thể, hãy thêm tin nhắn assistant cuối cùng có `content` là tiền tố người nói mục tiêu và đặt `partial: true`. `partial` là trường cấp tin nhắn trên tin nhắn assistant cuối cùng. Đây không phải là tham số yêu cầu cấp cao nhất. ## Qwen Plus Character ### Điểm cuối ```http POST /api/v1/chat/completions ``` ### Tham số yêu cầu #### Bắt buộc | Tham số | Kiểu | Mô tả | |-----------|------|-------------| | `model` | string | Phải là `"qwen-plus-character"` | | `messages` | array | Các tin nhắn theo thứ tự với vai trò `system`, `user` và `assistant` tùy chọn. | | `stream` | boolean | `true` cho SSE, `false` cho một phản hồi JSON duy nhất. | #### Header | Header | Bắt buộc | Mô tả | |--------|----------|-------------| | `Authorization` | Bắt buộc | API key, theo định dạng `Bearer YOUR_API_KEY`. | | `Content-Type` | Bắt buộc | Dùng `application/json`. | | `Accept` | Bắt buộc | Dùng `text/event-stream` khi `stream` là `true`; dùng `application/json` khi `stream` là `false`. | | `x-session` | Bắt buộc khi bộ nhớ dài hạn được bật | ID phiên do người dùng tự định nghĩa để cô lập và gọi lại bộ nhớ dài hạn. Bộ nhớ được cô lập theo user key, vì vậy những người dùng khác nhau có thể dùng lại cùng một ID phiên mà không chia sẻ bộ nhớ. | #### Hỗ trợ tin nhắn | Trường | Văn bản | Tệp | Hình ảnh | |-------|------|------|-------| | `messages` | Bắt buộc ✅ | Không được hỗ trợ ❌ | Không được hỗ trợ ❌ | #### Trường tin nhắn | Trường | Kiểu | Bắt buộc | Mô tả | |-------|------|----------|-------------| | `role` | string | Bắt buộc | Hỗ trợ `system`, `user` và `assistant`. | | `content` | string | Bắt buộc | Văn bản tin nhắn. Với mô phỏng chat nhóm, hãy tự thêm tên người nói ở đầu, chẳng hạn `Ling Lu:`. | | `partial` | boolean | Tùy chọn | Chỉ dùng trên tin nhắn assistant cuối cùng. Đặt thành `true` khi `content` là tiền tố mà mô hình cần tiếp tục từ đó. | #### Tùy chọn | Tham số | Kiểu | Phạm vi | Mô tả | |-----------|------|-------|-------------| | `max_tokens` | integer | `> 0` | Số token đầu ra tối đa. | | `temperature` | number | `0.0` - `1.0` | Kiểm soát độ ngẫu nhiên của phản hồi. | | `seed` | integer | `0` - `2147483647` | Seed ngẫu nhiên cho đầu ra có thể tái lập. Trường này không liên quan đến cửa sổ ngữ cảnh của cuộc trò chuyện. | | `profile` | string | — | Hồ sơ nhân vật. Bắt buộc khi `enable_long_term_memory` là `true`. `profile` không tự động thêm tên người nói vào tin nhắn. | | `enable_long_term_memory` | boolean | — | Bật bộ nhớ dài hạn cho yêu cầu. Yêu cầu `profile` và header `x-session`. | | `memory_entries` | integer | — | Số mục bộ nhớ cần gọi lại hoặc giữ lại cho phiên. Tài liệu chính thức hiện chưa công bố giới hạn phạm vi cố định. | | `skip_save_types` | string[] | `system`, `user`, `assistant`, `output` | Các loại bộ nhớ cần bỏ qua khi lưu cho yêu cầu này. | Khi bộ nhớ dài hạn được bật, bạn phải cung cấp: - header yêu cầu `x-session` - `profile` trong body yêu cầu - `enable_long_term_memory: true` `skip_save_types` hỗ trợ các giá trị sau: | Giá trị | Ý nghĩa | |-------|---------| | `system` | Bỏ qua việc lưu các tin nhắn `system` được thêm trong yêu cầu này. | | `user` | Bỏ qua việc lưu các tin nhắn `user` được thêm trong yêu cầu này. | | `assistant` | Bỏ qua việc lưu các tin nhắn `assistant` được thêm trong yêu cầu này. | | `output` | Bỏ qua việc lưu tin nhắn assistant được tạo bởi yêu cầu này. | ### Yêu cầu nhập vai cơ bản ```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?' } ] }) }); ``` ### Yêu cầu bộ nhớ dài hạn ```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: [] }) }); ``` ### Mô phỏng chat nhóm với `partial` Mô phỏng chat nhóm được triển khai thông qua văn bản tin nhắn. API không tự động gán hoặc di chuyển tên người nói. Hãy viết thủ công tên từng người nói ở đầu `content`, sau đó thêm tin nhắn assistant cuối cùng với tiền tố người nói mục tiêu và `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 } ] }) }); ``` ### Tiếp tục với tư cách nhân vật bằng `partial` Dùng cùng mẫu `partial` khi người dùng chưa trả lời nhưng bạn muốn nhân vật tiếp tục nói. Thêm tin nhắn assistant cuối cùng với tiền tố nhân vật. ```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 ### Tham số yêu cầu Cùng giao thức như Qwen Plus Character, với các khác biệt sau: | Tham số | Qwen Flash Character | |-----------|----------------------| | `model` | Phải là `"qwen-flash-character"` | ### Ví dụ yêu cầu ```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 } ``` ## Định dạng phản hồi Các mô hình LLM Qwen Character trả về phản hồi completion tương thích với OpenAI. Với `stream: true`, phản hồi là Server-Sent Events; với `stream: false`, phản hồi là một đối tượng JSON duy nhất. ## Phương pháp hay nhất - Đặt hướng dẫn persona ở cấp yêu cầu trong tin nhắn `system`. - Chỉ đặt bối cảnh nhân vật có thể tái sử dụng trong `profile` khi bộ nhớ dài hạn được bật. - Dùng lại cùng giá trị `x-session` trên các cuộc trò chuyện liên quan khi bộ nhớ dài hạn được bật. Các phiên không được sử dụng trong 365 ngày có thể bị xóa. - Tiếp tục gửi các tin nhắn hội thoại gần đây khi hữu ích; bộ nhớ dài hạn và ngữ cảnh ngắn hạn có thể hoạt động cùng nhau. - Với mô phỏng chat nhóm, hãy tự viết tên người nói trong `content`. API sẽ không suy luận tên từ `profile`. - Chỉ dùng `partial: true` trên tin nhắn assistant cuối cùng khi mô hình cần tiếp tục từ một tiền tố. - Dùng Qwen Flash Character cho nhập vai nhẹ và Qwen Plus Character cho chất lượng hội thoại phong phú hơn.