Instructions to use LordNeel/Hy3-GGUF with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use LordNeel/Hy3-GGUF with llama-cpp-python:

# !pip install llama-cpp-python

from llama_cpp import Llama

llm = Llama.from_pretrained(
	repo_id="LordNeel/Hy3-GGUF",
	filename="Hy3-IQ2_M-imatrix.gguf",
)

llm.create_chat_completion(
	messages = [
		{
			"role": "user",
			"content": "What is the capital of France?"
		}
	]
)

Notebooks
Google Colab
Kaggle
Local Apps Settings

llama.cpp

How to use LordNeel/Hy3-GGUF 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 LordNeel/Hy3-GGUF:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf LordNeel/Hy3-GGUF:Q4_K_M

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf LordNeel/Hy3-GGUF:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf LordNeel/Hy3-GGUF: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 LordNeel/Hy3-GGUF:Q4_K_M
# Run inference directly in the terminal:
./llama-cli -hf LordNeel/Hy3-GGUF: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 LordNeel/Hy3-GGUF:Q4_K_M
# Run inference directly in the terminal:
./build/bin/llama-cli -hf LordNeel/Hy3-GGUF:Q4_K_M

Use Docker

docker model run hf.co/LordNeel/Hy3-GGUF:Q4_K_M

LM Studio
Jan

vLLM

How to use LordNeel/Hy3-GGUF with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "LordNeel/Hy3-GGUF"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "LordNeel/Hy3-GGUF",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/LordNeel/Hy3-GGUF:Q4_K_M

Ollama
How to use LordNeel/Hy3-GGUF with Ollama:
```
ollama run hf.co/LordNeel/Hy3-GGUF:Q4_K_M
```

Unsloth Studio

How to use LordNeel/Hy3-GGUF with Unsloth Studio:

Install Unsloth Studio (macOS, Linux, WSL)

curl -fsSL https://unsloth.ai/install.sh | sh
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for LordNeel/Hy3-GGUF to start chatting

Install Unsloth Studio (Windows)

irm https://unsloth.ai/install.ps1 | iex
# Run unsloth studio
unsloth studio -H 0.0.0.0 -p 8888
# Then open http://localhost:8888 in your browser
# Search for LordNeel/Hy3-GGUF to start chatting

Using HuggingFace Spaces for Unsloth

# No setup required
# Open https://huggingface.co/spaces/unsloth/studio in your browser
# Search for LordNeel/Hy3-GGUF to start chatting

How to use LordNeel/Hy3-GGUF with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf LordNeel/Hy3-GGUF:Q4_K_M

Configure the model in Pi

# Install Pi:
npm install -g @mariozechner/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "LordNeel/Hy3-GGUF:Q4_K_M"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Hermes Agent new

How to use LordNeel/Hy3-GGUF with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf LordNeel/Hy3-GGUF: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 LordNeel/Hy3-GGUF:Q4_K_M

Run Hermes

hermes

Atomic Chat new

OpenClaw new

How to use LordNeel/Hy3-GGUF with OpenClaw:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf LordNeel/Hy3-GGUF: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 "LordNeel/Hy3-GGUF: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"

Docker Model Runner
How to use LordNeel/Hy3-GGUF with Docker Model Runner:
```
docker model run hf.co/LordNeel/Hy3-GGUF:Q4_K_M
```

Lemonade

How to use LordNeel/Hy3-GGUF with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull LordNeel/Hy3-GGUF:Q4_K_M

Run and chat with the model

lemonade run user.Hy3-GGUF-Q4_K_M

List all available models

lemonade list

Hy3 — GGUF (imatrix)

High-quality imatrix GGUF quantizations of tencent/Hy3, Tencent's 295B-parameter Mixture-of-Experts model with ~21B active parameters per token.

Produced with a Hy3-enabled llama.cpp branch (build 9909, commit 56142c5f8). Every quant in this repo was measured for quality (KL divergence, perplexity, and top-token agreement against BF16 reference logits) and throughput (llama-bench on 8× RTX PRO 6000 Blackwell) — full raw data is included under benchmarks/.

Model Overview


Base model	`tencent/Hy3`
Architecture	`hy_v3` (MoE, 295B total / ~21B active)
Context length	262,144 tokens
Chat template	Embedded in GGUF metadata
License	Apache 2.0 (inherited from base model)
Conversion	Hy3-enabled `llama.cpp`, build `9909` (`56142c5f8`), BF16 source, MTP/NextN block excluded
Imatrix	96 chunks, custom calibration corpus (`calibration/hy3_imatrix_calibration.txt`)

The GGUFs are converted from the BF16 base model with the MTP/NextN block excluded (--no-mtp) — intentional for normal serving. Q8_0 was intentionally skipped for this release.

Which File Should I Download?

Sizes below are weights only — leave headroom for KV cache and compute buffers.

Use case	File	Size	Why
Highest quality	`Hy3-Q6_K-imatrix.gguf`	226.24 GiB	Effectively lossless in this set: mean KLD 0.0207, 95.1% top-token agreement, PPL ratio ≈ 1.0. Needs ~3× 96 GB GPUs or 256 GB+ unified memory.
Recommended default	`Hy3-Q4_K_M-imatrix.gguf`	167.08 GiB	Best quality/size/speed balance. Mean KLD 0.0904, 90.0% top-token agreement. Fits on 2× 96 GB GPUs.
Smaller fallback	`Hy3-Q3_K_L-imatrix.gguf`	143.06 GiB	Use when Q4 doesn't fit; quality loss is materially higher than Q4 (mean KLD 0.162).
Minimum size	`Hy3-IQ2_M-imatrix.gguf`	90.32 GiB	Smallest artifact — fits a single 96 GB GPU (tight) or 128 GB unified memory. Use only when size is the hard constraint (mean KLD 0.531).

Download

# Single quant (example: Q4_K_M)
hf download LordNeel/Hy3-GGUF Hy3-Q4_K_M-imatrix.gguf --local-dir ./Hy3-GGUF

Run with llama.cpp

Use --split-mode layer for multi-GPU. (--split-mode tensor crashed in CUDA decode during testing on this Hy3 GGUF path — see Known Limitations.)

llama-server \
  --hf-repo LordNeel/Hy3-GGUF \
  --hf-file Hy3-Q4_K_M-imatrix.gguf \
  -ngl 999 \
  --split-mode layer \
  --tensor-split 1,1,1,1,1,1,1,1 \
  -c 8192 \
  -b 1024 \
  -ub 512

The chat template is embedded in the GGUF, so llama-server / llama-cli chat modes work out of the box.

Quality Metrics

Quality was measured with llama-perplexity --kl-divergence against BF16 no-MTP reference logits generated from tencent/Hy3.

Eval setup

Corpus: WikiText-2 raw test (llama.cpp scripts/get-wikitext-2.sh)
Slice: 128 chunks × context 512 (nominally 65,536 tokens)
Flags: -c 512 --chunks 128 -b 1024 -ub 512 -ngl 999 --split-mode layer --tensor-split 1,1,1,1,1,1,1,1
The BF16 reference logits file was kept local as a large intermediate and is not uploaded.

Artifact	Size GiB	BPW	PPL(Q)	PPL ratio	Mean KLD	Median KLD	RMS Δp	Same top-p
`Hy3-Q6_K-imatrix.gguf`	226.24	6.59	4.7705 ± 0.0673	0.9979 ± 0.0016	0.0207 ± 0.0004	0.0038	5.19 ± 0.09%	95.12 ± 0.12%
`Hy3-Q4_K_M-imatrix.gguf`	167.08	4.86	5.0395 ± 0.0728	1.0541 ± 0.0036	0.0904 ± 0.0014	0.0168	10.56 ± 0.13%	90.00 ± 0.17%
`Hy3-Q3_K_L-imatrix.gguf`	143.06	4.16	5.3576 ± 0.0797	1.1207 ± 0.0052	0.1624 ± 0.0023	0.0316	13.68 ± 0.15%	86.83 ± 0.19%
`Hy3-IQ2_M-imatrix.gguf`	90.32	2.63	6.6560 ± 0.0993	1.3923 ± 0.0116	0.5314 ± 0.0059	0.1567	24.79 ± 0.19%	74.75 ± 0.24%

Lower KLD, PPL ratio, and RMS Δp are better; higher same top-p is better. "Same top-p" is the percentage of positions where the quant and the BF16 reference agree on the highest-probability token.

Raw quality data: benchmarks/kld_wikitext2_c512_chunks128.json · benchmarks/kld_eval_manifest.json · benchmarks/kld_logs/

Throughput

llama-bench, CUDA backend, 8× NVIDIA RTX PRO 6000 Blackwell Server Edition, -ngl 999 --split-mode layer --tensor-split 1/1/…, prompt 512, generation 128, 3 reps, batch 1024, ubatch 512, F16 KV cache.

BF16 no-MTP GGUF reference size used for compression ratios: 549.66 GiB (590,197,887,712 bytes).

Artifact	Size GiB	BPW	Compression	Prompt tok/s	Generate tok/s
`Hy3-IQ2_M-imatrix.gguf`	90.32	2.63	6.09×	1249.4	78.7
`Hy3-Q3_K_L-imatrix.gguf`	143.06	4.16	3.84×	1348.5	63.3
`Hy3-Q4_K_M-imatrix.gguf`	167.08	4.86	3.29×	1495.0	67.3
`Hy3-Q6_K-imatrix.gguf`	226.24	6.59	2.43×	1232.4	57.4

Raw throughput data: benchmarks/summary.json and the per-quant benchmarks/*_llama_bench_p512_n128_r3.json files.

Charts

Production Serving Notes

For quality-first GGUF serving, use Q6_K:

Serving artifact	Size GiB	BPW	Prompt tok/s	Generate tok/s	Mean KLD	PPL ratio	Same top-p
`Hy3-Q6_K-imatrix.gguf`	226.24	6.59	1232.4	57.4	0.0207	0.9979	95.12%

For maximum batched throughput on the tested 8-GPU machine, a separate (non-GGUF) FP8 SGLang profile was faster:

SGLang 0.5.5 Hy3 backport, TP=8
FP8 weights + FP8 E4M3 KV cache with calibrated K/V scales
CUDA graph batch sizes [1,2,4,8,16,32]
Best measured: 688.76 aggregate output tok/s at concurrency 32 over 128 successful requests

Raw reference: benchmarks/sglang_fp8_tp8_reference.json. Tencent's base model card provides vLLM and SGLang recipes for Hy3.

Quantization Recipe

Source GGUF: BF16, --no-mtp, --fuse-gate-up-exps (1199 tensors in the no-MTP BF16 GGUF)
Imatrix: llama-imatrix, 96 chunks, calibration text from hy3_calibration_512.jsonl (uploaded as calibration/hy3_imatrix_calibration.txt)
Imatrix file: imatrix/Hy3-imatrix.gguf — included so you can reproduce or make additional quants

llama-quantize \
  --imatrix Hy3-imatrix.gguf \
  --leave-output-tensor \
  --token-embedding-type q8_0 \
  Hy3-BF16.gguf \
  Hy3-Q4_K_M-imatrix.gguf \
  Q4_K_M \
  64

The full reproduction runner used for this release: scripts/run_hy3_gguf_stream_upload.sh

Known Limitations

KLD/PPL numbers come from a bounded WikiText-2 slice (128 × 512 ctx), not a full downstream task harness. MMLU/GPQA/coding evals were not run for these GGUFs; see the upstream task scores on Tencent's base model card instead.
The GGUFs exclude the MTP/NextN block — intentional for normal serving.
--split-mode tensor was unstable (CUDA decode crash) on the tested stack for this Hy3 GGUF path. Use --split-mode layer.
A GPTQ4/SGLang variant was tested separately and classified invalid (generation collapsed into repeated punctuation); those artifacts are not published here.
Q8_0 was intentionally skipped for this release.

Benchmark Hardware

8× NVIDIA RTX PRO 6000 Blackwell Server Edition (~97 GB VRAM each)
CUDA 12.8, driver 570.195.03
AMD EPYC 9B14 host, 224 logical CPUs, ~1.5 TiB RAM

Acknowledgements

Tencent Hunyuan for the Hy3 base model (Apache 2.0)
The llama.cpp project and the Hy3 support branch these conversions were built on

Downloads last month: 294

GGUF

Model size

295B params

Architecture

hy_v3

Hardware compatibility

2-bit

3-bit

4-bit

6-bit

View +1 variant

Model tree for LordNeel/Hy3-GGUF

Base model

tencent/Hy3

Quantized

(40)

this model