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

starsfriday

Publish JoyFox-Reverie-27B

2171588 3 days ago

preview code

Raw History Blame Contribute Delete

12.9 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-en.png" alt="Characters to imagine. Conversations to share." width="760">
	</p>

	<p align="center">
	<a href="https://huggingface.co/joyfox/JoyFox-Reverie-27B">Model</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>

	> A familiar voice for imagined worlds and everyday moments.

	JoyFox-Reverie-27B is a conversational model from JoyFox, derived from [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B) and focused on character roleplay, shared storytelling, and companion dialogue.

	“Reverie” evokes the space between imagination and conversation: a character to meet, a story to explore, or a familiar voice to talk to at the end of the day. Define the experience through your prompt, from a richly described fictional setting to a relaxed everyday exchange.

	## ✨ Highlights

	- Character dialogue: shape a persona through background, voice, relationships, and scene instructions.
	- Companion conversations: set a friendly conversational style for everyday topics and personal reflection.
	- Shared storytelling: create dialogue and scenes together, defining which characters each participant controls.
	- Flexible expression: specify the reply language, narrative perspective, response length, and balance of action and dialogue.
	- Thinking controls: choose direct replies or enable reasoning through the supplied chat template.
	- Visual context: the checkpoint retains the upstream visual components for image and video inputs through compatible processors and runtimes.

	## 🚀 Quickstart

	### Transformers

	Use a current Transformers build that supports the Qwen3.8 checkpoint and its processor. Architecture loading details are covered in the [Transformers documentation](https://huggingface.co/docs/transformers/model_doc/qwen3_5).

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

	The following example starts a character conversation with thinking disabled:

	```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": "You are Mira, an old friend who runs a seaside bookshop. Speak naturally, stay in character, and let me choose my own actions."},
	{"role": "user", "content": "I push open the shop door after a long day. Got a moment to talk?"},
	]
	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))
	```

	### Serving with vLLM

	The following command exposes a chat endpoint with a 32K context setting. Allocate enough GPU memory for the BF16 weights and runtime state; increase tensor parallelism when using multiple GPUs.

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

	For multiple GPUs, add `--tensor-parallel-size` with your GPU count. Context capacity and concurrency depend on available memory. Consult the [vLLM Qwen3.8 recipe](https://recipes.vllm.ai/Qwen/Qwen3.8-27B) for framework requirements and hardware configuration.

	### Chat API

	Once the server is running, send a conversation request:

	```bash
	curl http://localhost:8000/v1/chat/completions \
	-H 'Content-Type: application/json' \
	-d '{
	"model": "JoyFox-Reverie-27B",
	"messages": [
	{
	"role": "system",
	"content": "Speak naturally as my old friend Mira. Let me choose my own actions."
	},
	{
	"role": "user",
	"content": "I had a long day. Can we talk for a bit?"
	}
	],
	"temperature": 0.7,
	"top_p": 0.9,
	"max_tokens": 512,
	"chat_template_kwargs": {
	"enable_thinking": false
	}
	}'
	```

	For multi-turn chat, append each assistant reply and the next user message to `messages` before sending the next request. The server uses the model's supplied chat template.

	### Image Input

	With the model and processor from the Transformers example, replace `messages` with the following, then run the same template and generation steps:

	```python
	messages = [
	{"role": "system", "content": "Describe the scene as Mira, a seaside bookshop owner. Distinguish what you see from what you imagine."},
	{
	"role": "user",
	"content": [
	{"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
	{"type": "text", "text": "What do you notice in this picture?"},
	],
	},
	]
	```

	Image and video processing depends on the serving framework. For video input formats and media controls, refer to the [upstream usage guide](https://huggingface.co/Qwen/Qwen3.8-27B).

	## 💬 Conversation Styles

	### Character Roleplay

	A character prompt works best when it identifies the speaker, the relationship, and the current scene:

	```text
	You are Mira, the owner of a small seaside bookshop and an old friend of mine.
	Voice: warm, observant, with occasional dry humor.
	Scene: a rainy evening just before closing time.
	Write mostly dialogue, with brief actions where useful.
	Keep the setting grounded in established facts. Leave my actions and decisions to me.
	```

	### Companion Chat

	For a conversation without a fictional scene:

	```text
	Talk with me like a thoughtful friend. Use natural, relaxed language and follow the topic I bring up. Ask questions when they help, and share your perspective without turning every reply into advice. Avoid stage directions unless I ask for roleplay.
	```

	### Shared Storytelling

	```text
	We are writing a mystery together. You control the supporting cast and environment; I control the protagonist. Build on established events, introduce clues gradually, and leave room for my next decision.
	```

	## 🧠 Thinking Controls

	For direct character dialogue, pass `enable_thinking=False` to the chat template. Thinking is enabled by default in the included template.

	When reasoning is useful, these options can be passed to `processor.apply_chat_template`:

	```python
	chat_options = {
	"enable_thinking": True,
	"reasoning_effort": "medium",
	"preserve_thinking": True,
	}
	```

	`reasoning_effort` accepts `low`, `medium`, and `xhigh` (the default). `preserve_thinking` controls retention of reasoning content in earlier assistant messages. For the chat API, place template options inside `chat_template_kwargs`; the server's reasoning parser separates reasoning from the answer.

	## 🎛️ Generation Settings

	The quickstart uses temperature `0.7`, top-p `0.9`, and top-k `20` for direct dialogue. The included generation configuration uses temperature `1.0`, top-p `0.95`, and top-k `20`.

	Treat these as starting points. Lower temperature for more restrained replies; increase it when exploring more varied phrasing. Adjust one setting at a time, and keep enough output tokens for the desired response length. Sampling options vary across serving frameworks.

	## 💡 Best Practices

	- Keep the character card concise and explicit. Separate permanent identity from the current scene.
	- Carry earlier messages forward so the model can use established events and relationships.
	- State who controls each character and whether the model may introduce new events.
	- Specify the language, point of view, and desired length rather than relying on implied style.
	- For long sessions, maintain a short summary of established facts alongside recent messages.
	- Treat fictional dialogue as generated fiction, and verify factual statements when accuracy matters.

	## 📦 GGUF

	UD quantizations from Q4 through Q6 are available in [GGUF](https://huggingface.co/joyfox/JoyFox-Reverie-27B/tree/main/GGUF). Every main file includes MTP tensors; use the matching F16 `mmproj` for images.

	\| File \| Size (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 \|

	### Download a GGUF

	Use a current llama.cpp build with `qwen35` support. Download one main GGUF; the matching `mmproj` is needed only for image input. The examples below use Q4 XL; replace the main filename to use another available quantization.

	```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
	```
	### Text Chat

	Run the following command from the downloaded model directory:

	```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` applies the bundled chat template; `--reasoning off` selects direct replies. Adjust `-c` for your desired context and available memory. `-ngl all` offloads the model to the GPU; reduce the offload when it does not fit. The download size excludes runtime buffers and KV cache.

	### Chat Server

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

	The server provides a web interface at `http://127.0.0.1:8080` and a chat endpoint at `/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}'
	```

	### Image Input

	Use the matching F16 visual projector with your chosen main GGUF:

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

	### Optional MTP Decoding

	All main GGUF files include native MTP tensors. On a compatible llama.cpp build, start the server with bundled MTP:

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

	This replaces the ordinary server command. No separate draft-model download is required. MTP uses additional memory; speed depends on draft acceptance and the workload.

	### Choosing a Quantization

	Q4 S has the smallest footprint in this release. Q4 XL offers a practical starting point for roleplay; Q5 and Q6 require more memory. Choose according to available memory and your preferred output quality. For a GGUF application, load the downloaded main file and use the supplied chat template; image input additionally requires the matching visual projector and application support.

	## 📜 License and Acknowledgments

	JoyFox-Reverie-27B is released under [Apache-2.0](LICENSE). It is a JoyFox derivative of [Qwen3.8-27B](https://huggingface.co/Qwen/Qwen3.8-27B). Thanks to the Qwen team and the Hugging Face ecosystem.