license: apache-2.0
base_model: Qwen/Qwen3.8-27B
library_name: transformers
pipeline_tag: image-text-to-text
language:
- zh
- en
tags:
- joyfox
- roleplay
- conversational
- companion
- creative-writing
- vision
model_name: JoyFox-Reverie-27B
让故事有回响，让日常有陪伴。
JoyFox-Reverie-27B 是 JoyFox 基于 Qwen3.8-27B 打造的对话模型，面向角色扮演、共同创作故事与朋友式交流。
“Reverie”意为遐想：你可以认识一个角色，走进一段故事，也可以在一天结束时，找一个熟悉的声音聊聊天。从细致的虚构场景到轻松的日常交流，对话体验由你的设定展开。
✨ 模型特点
- 角色对话：通过人物背景、说话风格、关系与场景提示塑造角色。
- 朋友式交流：设定亲切自然的聊天风格，围绕日常话题与个人想法展开对话。
- 共同叙事：一起创作场景与对白，明确双方分别控制的人物。
- 灵活表达：指定回复语言、叙述视角、篇幅，以及动作与对白的比例。
- 思考模式控制：通过附带聊天模板选择直接回复或启用思考。
- 视觉上下文：保留上游视觉组件，可通过兼容的处理器与运行框架接入图片和视频。
🚀 快速开始
使用 Transformers
使用支持 Qwen3.8 检查点及其处理器的当前 Transformers 版本。架构加载方式可参考 Transformers 文档。
pip install -U torch transformers accelerate
以下示例关闭思考模式，直接开始角色对话：
import torch
from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
model_id = "joyfox/JoyFox-Reverie-27B"
processor = AutoProcessor.from_pretrained(model_id)
model = Qwen3_5ForConditionalGeneration.from_pretrained(
model_id,
dtype=torch.bfloat16,
device_map="auto",
)
messages = [
{"role": "system", "content": "你是经营海边书店的旧友米拉。自然交谈，保持角色设定，让我自己决定行动。"},
{"role": "user", "content": "忙了一整天，我推开书店的门。你现在有空聊聊吗？"},
]
inputs = processor.apply_chat_template(
messages,
tokenize=True,
add_generation_prompt=True,
enable_thinking=False,
return_dict=True,
return_tensors="pt",
).to(model.device)
with torch.inference_mode():
output = model.generate(
**inputs,
max_new_tokens=512,
do_sample=True,
temperature=0.7,
top_p=0.9,
top_k=20,
)
reply = output[0, inputs["input_ids"].shape[-1]:]
print(processor.decode(reply, skip_special_tokens=True))
使用 vLLM 部署
下面的命令启动聊天服务，使用 32K 上下文设置。请为 BF16 权重与运行状态分配足够显存；多 GPU 部署时可增加张量并行度。
pip install -U vllm
vllm serve joyfox/JoyFox-Reverie-27B \
--served-model-name JoyFox-Reverie-27B \
--dtype bfloat16 \
--max-model-len 32768 \
--reasoning-parser qwen3
使用多 GPU 时，添加 --tensor-parallel-size 并设置 GPU 数量。上下文容量与并发数取决于可用显存。框架要求与硬件配置可参考 vLLM Qwen3.8 部署指南。
调用聊天 API
服务启动后，发送对话请求：
curl http://localhost:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "JoyFox-Reverie-27B",
"messages": [
{
"role": "system",
"content": "你是旧友米拉。自然交谈，让我自己决定行动。"
},
{
"role": "user",
"content": "今天有点累，可以陪我聊会儿吗？"
}
],
"temperature": 0.7,
"top_p": 0.9,
"max_tokens": 512,
"chat_template_kwargs": {
"enable_thinking": false
}
}'
多轮聊天时，将每次模型回复和下一条用户消息追加到 messages 后再发送请求。服务使用模型附带的聊天模板。
图片输入
使用 Transformers 示例中的模型与处理器，将 messages 替换为下面的内容，再执行相同的模板处理与生成步骤：
messages = [
{"role": "system", "content": "你是海边书店的店主米拉。描述画面时，区分实际看到的内容与想象。"},
{
"role": "user",
"content": [
{"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
{"type": "text", "text": "这张图片里有什么引起你的注意？"},
],
},
]
图片和视频的处理方式取决于运行框架。视频输入格式与媒体参数可参考上游使用指南。
💬 对话风格
角色扮演
角色提示词可以围绕人物身份、关系与当前场景展开：
你是米拉，一间海边小书店的店主，也是我的旧友。
说话风格：温和、细心，偶尔带一点冷幽默。
当前场景：下雨的傍晚，书店即将打烊。
以对白为主，需要时加入简短动作描写。
围绕已经建立的事实推进场景，把我的行动与决定留给我。
朋友式聊天
希望直接交流、不加入虚构场景时，可以这样设定：
像一个愿意倾听的朋友一样和我聊天。语气自然、轻松，顺着我提出的话题交流。在有助于对话时提问，也可以表达你的看法，不必把每次回复都变成建议。除非我要求角色扮演，否则不要加入动作描写或舞台旁白。
共同创作故事
我们一起创作一个悬疑故事。你控制配角与环境，我控制主角。沿着已经发生的事件推进，逐步引入线索，并为我的下一步决定留下空间。
🧠 思考模式
直接进行角色聊天时，向聊天模板传入 enable_thinking=False。附带模板默认启用思考。
需要思考时，可将以下参数传给 processor.apply_chat_template：
chat_options = {
"enable_thinking": True,
"reasoning_effort": "medium",
"preserve_thinking": True,
}
reasoning_effort 支持 low、medium 与默认的 xhigh。preserve_thinking 控制此前助手消息中的思考内容是否保留。调用聊天 API 时，将模板参数放入 chat_template_kwargs；服务端的 reasoning parser 会区分思考内容与正式回答。
🎛️ 生成参数
快速开始示例使用 temperature 0.7、top-p 0.9、top-k 20 进行直接对话。附带生成配置的默认值为 temperature 1.0、top-p 0.95、top-k 20。
可将这些参数作为起点。需要更克制的表达时降低 temperature，希望探索更多措辞时适当提高。建议一次调整一个参数，并为预期回复长度预留足够的输出 token。不同运行框架支持的采样项可能不同。
💡 使用建议
- 角色卡保持简洁、明确，区分长期身份与当前场景。
- 多轮请求携带此前的消息，让模型能够利用已建立的事件与人物关系。
- 明确双方控制哪些角色，以及模型是否可以主动引入新事件。
- 直接指定语言、视角与回复长度，让交流风格更贴合你的设定。
- 长时间对话可维护简短的事实摘要，并保留最近的对话消息。
- 将虚构对白作为创作内容；需要准确事实时，对相关陈述进行核实。
📦 GGUF
Q4–Q6 的 UD 量化文件位于 GGUF。每个主文件均包含 MTP 张量；图片输入请搭配对应的 F16 mmproj。
下载 GGUF
使用支持 qwen35 的当前 llama.cpp 版本。文本聊天只需下载一个主 GGUF；图片输入还需对应的 mmproj。下面以 Q4 XL 为例，使用其他档位时替换主模型文件名即可。
pip install -U huggingface_hub
hf download joyfox/JoyFox-Reverie-27B \
GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf \
GGUF/mmproj-JoyFox-Reverie-27B-F16.gguf \
--local-dir JoyFox-Reverie-27B
cd JoyFox-Reverie-27B
文本聊天
在下载后的模型目录中运行：
llama-cli -m GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf \
--jinja --reasoning off -c 32768 -ngl all \
--temp 0.7 --top-p 0.9 --top-k 20
--jinja 使用模型内置聊天模板，--reasoning off 直接生成回复。-c 设置上下文长度，可按显存调整；-ngl all 将模型卸载到 GPU，显存不足时可减少 GPU 层数。文件大小不包含运行缓冲区与 KV cache 的占用。
启动聊天服务
llama-server -m GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf \
--jinja --reasoning off -c 32768 -ngl all \
--host 127.0.0.1 --port 8080
服务提供 http://127.0.0.1:8080 网页界面，以及 /v1/chat/completions 聊天接口：
curl http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"messages":[{"role":"system","content":"You are Mira, my old friend. Speak naturally."},{"role":"user","content":"How was your day?"}],"temperature":0.7,"top_p":0.9,"max_tokens":256}'
图片输入
图片输入使用所选主 GGUF 与配套的 F16 视觉投影文件：
llama-cli -m GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf \
--mmproj GGUF/mmproj-JoyFox-Reverie-27B-F16.gguf \
--image example.png --prompt "Describe this image." \
--jinja --reasoning off -c 4096 -ngl all
可选 MTP 推测解码
全部主 GGUF 都包含原生 MTP 张量。兼容的 llama.cpp 版本可使用以下命令启用：
llama-server -m GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf \
--jinja --reasoning off -c 32768 -ngl all \
--spec-type draft-mtp --spec-draft-n-max 3 \
--host 127.0.0.1 --port 8080
这条命令替代普通服务启动命令，不需要单独下载 draft 模型。MTP 会增加显存占用，实际速度收益取决于草稿接受率与对话内容。
选择量化档位
Q4 S 是本次发布中体积最小的档位。Q4 XL 可作为 RP 使用的起点，Q5、Q6 需要更多内存。可结合设备容量与实际生成效果选择。使用 GGUF 应用时，加载主文件并启用附带聊天模板；图片输入还需要配套视觉投影文件以及应用本身支持。
📜 许可证与致谢
JoyFox-Reverie-27B 采用 Apache-2.0 许可证，是 JoyFox 基于 Qwen3.8-27B 构建的衍生模型。感谢 Qwen 团队与 Hugging Face 生态。