---
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
---

<p align="center">
  <img src="assets/joyfox-reverie-27b-banner.png" alt="JoyFox-Reverie-27B" width="100%">
</p>

<p align="center">
  <img src="assets/joyfox-reverie-tagline-zh.png" alt="让想象中的角色，走进每一次对话。" width="760">
</p>

<p align="center">
  <a href="https://huggingface.co/joyfox/JoyFox-Reverie-27B">模型主页</a> · <a href="https://huggingface.co/joyfox/JoyFox-Reverie-27B/blob/main/README.md">English</a> · <a href="https://huggingface.co/joyfox/JoyFox-Reverie-27B/blob/main/README_ZH.md">简体中文</a>
</p>

> 让故事有回响，让日常有陪伴。

JoyFox-Reverie-27B 是 JoyFox 基于 [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B) 打造的对话模型，面向角色扮演、共同创作故事与朋友式交流。

“Reverie”意为遐想：你可以认识一个角色，走进一段故事，也可以在一天结束时，找一个熟悉的声音聊聊天。从细致的虚构场景到轻松的日常交流，对话体验由你的设定展开。

## ✨ 模型特点

- **角色对话：**通过人物背景、说话风格、关系与场景提示塑造角色。
- **朋友式交流：**设定亲切自然的聊天风格，围绕日常话题与个人想法展开对话。
- **共同叙事：**一起创作场景与对白，明确双方分别控制的人物。
- **灵活表达：**指定回复语言、叙述视角、篇幅，以及动作与对白的比例。
- **思考模式控制：**通过附带聊天模板选择直接回复或启用思考。
- **视觉上下文：**保留上游视觉组件，可通过兼容的处理器与运行框架接入图片和视频。

## 🚀 快速开始

### 使用 Transformers

使用支持 Qwen3.8 检查点及其处理器的当前 Transformers 版本。架构加载方式可参考 [Transformers 文档](https://huggingface.co/docs/transformers/model_doc/qwen3_5)。

```bash
pip install -U torch transformers accelerate
```

以下示例关闭思考模式，直接开始角色对话：

```python
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 部署时可增加张量并行度。

```bash
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 部署指南](https://recipes.vllm.ai/Qwen/Qwen3.8-27B)。

### 调用聊天 API

服务启动后，发送对话请求：

```bash
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` 替换为下面的内容，再执行相同的模板处理与生成步骤：

```python
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": "这张图片里有什么引起你的注意？"},
        ],
    },
]
```

图片和视频的处理方式取决于运行框架。视频输入格式与媒体参数可参考[上游使用指南](https://huggingface.co/Qwen/Qwen3.8-27B)。

## 💬 对话风格

### 角色扮演

角色提示词可以围绕人物身份、关系与当前场景展开：

```text
你是米拉，一间海边小书店的店主，也是我的旧友。
说话风格：温和、细心，偶尔带一点冷幽默。
当前场景：下雨的傍晚，书店即将打烊。
以对白为主，需要时加入简短动作描写。
围绕已经建立的事实推进场景，把我的行动与决定留给我。
```

### 朋友式聊天

希望直接交流、不加入虚构场景时，可以这样设定：

```text
像一个愿意倾听的朋友一样和我聊天。语气自然、轻松，顺着我提出的话题交流。在有助于对话时提问，也可以表达你的看法，不必把每次回复都变成建议。除非我要求角色扮演，否则不要加入动作描写或舞台旁白。
```

### 共同创作故事

```text
我们一起创作一个悬疑故事。你控制配角与环境，我控制主角。沿着已经发生的事件推进，逐步引入线索，并为我的下一步决定留下空间。
```

## 🧠 思考模式

直接进行角色聊天时，向聊天模板传入 `enable_thinking=False`。附带模板默认启用思考。

需要思考时，可将以下参数传给 `processor.apply_chat_template`：

```python
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](https://huggingface.co/joyfox/JoyFox-Reverie-27B/tree/main/GGUF)。每个主文件均包含 MTP 张量；图片输入请搭配对应的 F16 `mmproj`。

| 文件 | 大小（GiB） |
|---|---:|
| [JoyFox-Reverie-27B-UD-Q4_K_M.gguf](GGUF/JoyFox-Reverie-27B-UD-Q4_K_M.gguf) | 15.33 |
| [JoyFox-Reverie-27B-UD-Q4_K_S.gguf](GGUF/JoyFox-Reverie-27B-UD-Q4_K_S.gguf) | 14.30 |
| [JoyFox-Reverie-27B-UD-Q4_K_XL.gguf](GGUF/JoyFox-Reverie-27B-UD-Q4_K_XL.gguf) | 16.35 |
| [JoyFox-Reverie-27B-UD-Q5_K_M.gguf](GGUF/JoyFox-Reverie-27B-UD-Q5_K_M.gguf) | 18.41 |
| [JoyFox-Reverie-27B-UD-Q5_K_S.gguf](GGUF/JoyFox-Reverie-27B-UD-Q5_K_S.gguf) | 17.38 |
| [JoyFox-Reverie-27B-UD-Q5_K_XL.gguf](GGUF/JoyFox-Reverie-27B-UD-Q5_K_XL.gguf) | 19.44 |
| [JoyFox-Reverie-27B-UD-Q6_K.gguf](GGUF/JoyFox-Reverie-27B-UD-Q6_K.gguf) | 20.47 |
| [JoyFox-Reverie-27B-UD-Q6_K_L.gguf](GGUF/JoyFox-Reverie-27B-UD-Q6_K_L.gguf) | 22.53 |
| [JoyFox-Reverie-27B-UD-Q6_K_M.gguf](GGUF/JoyFox-Reverie-27B-UD-Q6_K_M.gguf) | 21.50 |
| [JoyFox-Reverie-27B-UD-Q6_K_XL.gguf](GGUF/JoyFox-Reverie-27B-UD-Q6_K_XL.gguf) | 23.56 |
| [mmproj-JoyFox-Reverie-27B-F16.gguf](GGUF/mmproj-JoyFox-Reverie-27B-F16.gguf) | 0.86 |

### 下载 GGUF

使用支持 `qwen35` 的当前 llama.cpp 版本。文本聊天只需下载一个主 GGUF；图片输入还需对应的 `mmproj`。下面以 Q4 XL 为例，使用其他档位时替换主模型文件名即可。

```bash
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
```
### 文本聊天

在下载后的模型目录中运行：

```bash
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 的占用。

### 启动聊天服务

```bash
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` 聊天接口：

```bash
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 视觉投影文件：

```bash
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 版本可使用以下命令启用：

```bash
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](LICENSE) 许可证，是 JoyFox 基于 [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B) 构建的衍生模型。感谢 Qwen 团队与 Hugging Face 生态。