Instructions to use joyfox/JoyFox-Reverie-27B with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use joyfox/JoyFox-Reverie-27B with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="joyfox/JoyFox-Reverie-27B")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
pipe(text=messages)

# pip install -U transformers accelerate
# Load model directly
from transformers import AutoProcessor, AutoModelForMultimodalLM

processor = AutoProcessor.from_pretrained("joyfox/JoyFox-Reverie-27B")
model = AutoModelForMultimodalLM.from_pretrained("joyfox/JoyFox-Reverie-27B", device_map="auto")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
inputs = processor.apply_chat_template(
	messages,
	add_generation_prompt=True,
	tokenize=True,
	return_dict=True,
	return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=256)
print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:]))

Notebooks
Google Colab
Kaggle
Local Apps Settings

llama.cpp

How to use joyfox/JoyFox-Reverie-27B with llama.cpp:

Install (macOS, Linux)

curl -LsSf https://llama.app/install.sh | sh
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
# Run inference directly in the terminal:
llama cli -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
# Run inference directly in the terminal:
llama cli -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Use pre-built binary

# Download pre-built binary from:
# https://github.com/ggerganov/llama.cpp/releases
# Start a local OpenAI-compatible server with a web UI:
./llama-server -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
# Run inference directly in the terminal:
./llama-cli -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Build from source code

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j --target llama-server llama-cli
# Start a local OpenAI-compatible server with a web UI:
./build/bin/llama-server -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
# Run inference directly in the terminal:
./build/bin/llama-cli -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Use Docker

docker model run hf.co/joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

LM Studio
Jan

vLLM

How to use joyfox/JoyFox-Reverie-27B with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "joyfox/JoyFox-Reverie-27B"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "joyfox/JoyFox-Reverie-27B",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Use Docker

docker model run hf.co/joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

SGLang

How to use joyfox/JoyFox-Reverie-27B with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "joyfox/JoyFox-Reverie-27B" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "joyfox/JoyFox-Reverie-27B",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "joyfox/JoyFox-Reverie-27B" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "joyfox/JoyFox-Reverie-27B",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Ollama
How to use joyfox/JoyFox-Reverie-27B with Ollama:
```
ollama run hf.co/joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
```
Unsloth Desktop

How to use joyfox/JoyFox-Reverie-27B with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Configure the model in Pi

# Install Pi:
npm install -g @earendil-works/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "joyfox/JoyFox-Reverie-27B:UD-Q4_K_M"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Docker Model Runner
How to use joyfox/JoyFox-Reverie-27B with Docker Model Runner:
```
docker model run hf.co/joyfox/JoyFox-Reverie-27B:UD-Q4_K_M
```

Lemonade

How to use joyfox/JoyFox-Reverie-27B with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Run and chat with the model

lemonade run user.JoyFox-Reverie-27B-UD-Q4_K_M

List all available models

lemonade list

Hermes Agent

How to use joyfox/JoyFox-Reverie-27B with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Run Hermes

hermes

Atomic Chat

OpenClaw

How to use joyfox/JoyFox-Reverie-27B with OpenClaw:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf joyfox/JoyFox-Reverie-27B:UD-Q4_K_M

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "joyfox/JoyFox-Reverie-27B:UD-Q4_K_M" \
  --custom-provider-id llama-cpp \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

JoyFox-Reverie-27B / README_ZH.md

starsfriday

Publish JoyFox-Reverie-27B

2171588 11 days ago

preview code

Raw History Blame Contribute Delete

12.2 kB

---
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 生态。

	---
	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 生态。