Upload folder using huggingface_hub

README.md

@@ -1,3 +1,241 @@
 ---
 license: apache-2.0
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- hunyuan
+- hy4
+- moe
+- text-generation
 ---
+<p align="left">
+    <a href="https://huggingface.co/tencent/Hy4-preview/blob/main/README_CN.md">中文</a>&nbsp;｜&nbsp;English
+</p>
+<br>
+
+<p align="center">
+ <img src="assets/logo-en.png" width="400"/> <br>
+</p>
+
+<div align="center" style="line-height: 1;">
+
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](#license)
+&nbsp;&nbsp;
+[![HuggingFace](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Tencent%20Hy-ffc107?color=ffc107&logoColor=white)](https://huggingface.co/tencent/Hy4-preview)
+&nbsp;&nbsp;
+[![ModelScope](https://img.shields.io/badge/ModelScope-Tencent%20Hy-624aff)](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview)
+&nbsp;&nbsp;
+[![cnb.cool](https://img.shields.io/badge/cnb.cool-Tencent%20Hy-blue?logoColor=white)](https://cnb.cool/ai-models/tencent/Hy4-preview)
+&nbsp;&nbsp;
+[![GitCode](https://img.shields.io/badge/GitCode-Tencent%20Hy-red?logoColor=white)](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview)
+
+</div>
+
+<p align="center">
+    🖥️&nbsp;<a href="https://aistudio.tencent.com/"><b>Official Website</b></a>&nbsp;&nbsp;|&nbsp;&nbsp;
+    💬&nbsp;<a href="https://github.com/Tencent-Hunyuan/Hy4-preview"><b>GitHub</b></a></p>
+
+---
+
+## Table of Contents
+
+- [Model Introduction](#model-introduction)
+- [A New Flagship Generation](#a-new-flagship-generation)
+- [Built for Real-World Productivity](#built-for-real-world-productivity)
+- [Benchmark Appendix](#benchmark-appendix)
+- [Known Limitations](#known-limitations)
+- [News](#news)
+- [Model Links](#model-links)
+- [Quickstart](#quickstart)
+- [Deployment](#deployment)
+  - [vLLM](#vllm)
+  - [SGLang](#sglang)
+- [Finetuning](#finetuning)
+- [Quantization](#quantization)
+- [License](#license)
+- [Contact Us](#contact-us)
+
+---
+
+## Model Introduction
+
+**Hy4 preview** is a new-generation Mixture-of-Experts (MoE) flagship model developed by the Tencent Hy Team. The model comprises 770B total parameters, of which 49B are activated per token. The backbone consists of 78 layers, where the first layer uses a standard dense FFN and the remaining 77 layers replace it with MoE, each containing 256 routed experts and 1 shared expert; every token activates the top-8 routed experts along with the shared expert. In addition to the backbone, 1 native MTP layer (10B total parameters, 0.7B activated) is built in for speculative decoding.
+
+On the architecture side, inspired by DeepSeek and GLM, the attention module employs Gated [DeepSeek Sparse Attention](https://arxiv.org/abs/2512.02556) (Gated DSA) with [IndexCache](https://arxiv.org/abs/2603.12201) for cross-layer sparse index reuse. The residual pathway uses [iHC (identity Hyper-Connections)](https://zhuanlan.zhihu.com/p/2010852389670908320) to expand inter-layer information flow.
+
+### Model Specifications
+
+> The table below lists backbone parameters only, excluding the MTP layer.
+
+| Property | Value |
+|:---|:---|
+| Architecture | Mixture-of-Experts (MoE) |
+| Total Parameters | 770B |
+| Activated Parameters | 49B |
+| Layers | 78 |
+| Hidden Size | 6144 |
+| Attention Type | Gated DSA |
+| Attention Heads | 64 |
+| Query Compression Dimension | 2048 |
+| Key-Value Compression Dimension | 512 |
+| Indexer Heads / Head Dimension | 32 / 128 |
+| Indexer top-k | 2048 |
+| Residual Streams | 4 |
+| Routed Experts | 256 |
+| Shared Experts | 1 |
+| Activated Routed Experts per Token | 8 |
+| MoE Intermediate Size | 2048 |
+| FFN Intermediate Size | 18432 |
+| Context Length | 1M |
+| Vocabulary Size | 120832 |
+
+## A New Flagship Generation
+
+We scaled Hy4 preview on three fronts: model size, context length, and training data. Stronger pre-training and a substantially larger post-training run compound into another step change in capability — the largest generation-over-generation gain we've measured, and enough to put Hy4 preview at the open-source frontier.
+
+<p align="center">
+  <img src="assets/benchmark.jpg" width="100%"/>
+</p>
+
+## Built for Real-World Productivity
+
+We partnered with top experts inside Tencent — such as software engineers, game developers, finance analysts, and security experts — and built training data around the work they ship. The result is a model that gets meaningfully further on the tasks these teams run every day:
+
+**Software engineering**: Better at understanding, planning, debugging, and verifying long-horizon development tasks, with further gains in the visual taste and interaction quality of front-end work.
+
+**Office and analysis**: Takes messy context spread across many files and converts it into shareable artifacts — documents, spreadsheets, and presentations — handling data analysis, equations, and financial models with greater precision.
+
+**Game development**: Turns a single prompt into a playable prototype and works fluently with game engines, so developers can keep refining complex projects over multiple turns.
+
+**Scientific research**: Stronger understanding, reasoning, and problem-solving on hard research questions, with solid progress across AI research, molecular dynamics, condensed matter physics, and pure mathematics.
+
+We also continue to co-design Hy4 preview with Tencent products like CodeBuddy and WorkBuddy, so that gains in the model show up in the work people actually do with it. To check that, we ran a blind side-by-side evaluation: 163 internal experts rated model outputs on 203 engineering tasks. Hy4 preview came out slightly ahead of both GLM 5.3 (2.99 vs. 2.92 average, 46.8% wins / 12.8% ties / 40.4% losses) and Kimi K3 (2.99 vs. 2.94, 51.2% wins / 7.9% ties / 40.9% losses).
+
+## Benchmark Appendix
+
+<p align="center">
+  <img src="assets/benchmark-appendix.jpg" width="100%"/>
+</p>
+
+## Known Limitations
+
+This is an early version of Hy4. There is real headroom left in both pre-training and post-training, and we are shipping with known issues — among them, spending longer than necessary reasoning through complex tasks, and a tendency to over-verify its own work. As with Hy3 preview, we would rather ship early and hear what breaks — that's what made Hy3 substantially better, and it's how we will get Hy4 right. We will also keep collaborating closely with Tencent's products and in-house experts to push the boundaries of model intelligence while making it more abundant and affordable.
+
+## News
+
+* 🔥 We open-source **Hy4 preview** and **Hy4 preview-FP8** model weights on [Hugging Face](https://huggingface.co/tencent/Hy4-preview), [ModelScope](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview), [GitCode](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview), and [CNB](https://cnb.cool/ai-models/tencent/Hy4-preview).
+
+## Model Links
+
+| Model Name | Description | Hugging Face | ModelScope | GitCode | CNB |
+|:---|:---|:---:|:---:|:---:|:---:|
+| Hy4 preview | Instruct model | 🤗 [Model](https://huggingface.co/tencent/Hy4-preview) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview) | [Model](https://cnb.cool/ai-models/tencent/Hy4-preview) |
+| Hy4 preview-FP8 | FP8 quantized instruct model | 🤗 [Model](https://huggingface.co/tencent/Hy4-preview-FP8) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview-FP8) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview-FP8) | [Model](https://cnb.cool/ai-models/tencent/Hy4-preview-FP8) |
+
+## Quickstart
+
+Deploy Hy4 preview with [vLLM](#vllm) or [SGLang](#sglang) first, then call the OpenAI-compatible API:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
+
+response = client.chat.completions.create(
+    model="hy4-preview",
+    messages=[
+        {"role": "user", "content": "Hello! Can you briefly introduce yourself?"},
+    ],
+    temperature=0.9,
+    top_p=1.0,
+)
+print(response.choices[0].message.content)
+```
+
+> **Recommended parameters**: `temperature=0.9`, `top_p=1.0`.
+>
+> **Reasoning mode**: Defaults to `"high"` (deep chain-of-thought), which suits complex tasks such as math, coding, and reasoning. For direct responses, pass `extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}}`.
+
+See the [Deployment](#deployment) section below for how to start the API server.
+
+## Deployment
+
+For production serving, we recommend using [vLLM](https://github.com/vllm-project/vllm) or [SGLang](https://docs.sglang.io/).
+
+### vLLM
+
+Build vLLM from source:
+```bash
+uv venv --python 3.12 --seed --managed-python
+source .venv/bin/activate
+git clone https://github.com/vllm-project/vllm.git
+cd vllm
+uv pip install --editable . --torch-backend=auto
+```
+
+Start the vLLM server with MTP enabled:
+
+```bash
+vllm serve tencent/Hy4-preview-FP8 \
+  --tensor-parallel-size 8 \
+  --speculative-config.method mtp \
+  --speculative-config.num_speculative_tokens 3 \
+  --attention-backend FLASHMLA_SPARSE \
+  --tool-call-parser hy_v4 \
+  --reasoning-parser hy_v4 \
+  --enable-auto-tool-choice \
+  --port 8000 \
+  --served-model-name hy4-preview
+```
+
+### SGLang
+
+Build SGLang from source:
+```bash
+git clone https://github.com/sgl-project/sglang
+cd sglang
+pip3 install pip --upgrade
+pip3 install "transformers>=5.6.0"
+pip3 install -e "python"
+```
+
+Launch SGLang server with MTP enabled:
+
+```bash
+python3 -m sglang.launch_server \
+  --model tencent/Hy4-preview-FP8 \
+  --tp-size 8 \
+  --tool-call-parser hy_v4 \
+  --reasoning-parser hy_v4 \
+  --speculative-num-steps 2 \
+  --speculative-eagle-topk 1 \
+  --speculative-num-draft-tokens 3 \
+  --speculative-algorithm EAGLE \
+  --port 8000 \
+  --served-model-name hy4-preview
+```
+
+## Finetuning
+
+Hy4 preview provides a complete model finetuning pipeline. For detailed documentation, please refer to: [Finetuning Guide](https://huggingface.co/tencent/Hy4-preview/blob/main/finetune/README.md)
+
+## Quantization
+
+We provide [AngelSlim](https://github.com/tencent/AngelSlim), a more accessible, comprehensive, and efficient toolkit for large model compression. AngelSlim supports a comprehensive suite of compression tools for large-scale multimodal models, including common quantization algorithms, low-bit quantization, and speculative sampling.
+
+## License
+
+Hy4 preview is released under the **Apache License 2.0**. See [LICENSE](https://huggingface.co/tencent/Hy4-preview/blob/main/LICENSE) for details.
+
+## Contact Us
+
+If you have any questions or suggestions, feel free to reach out to our R&D and product teams via email:
+
+📧 **hunyuan_opensource@tencent.com**
+
+---
+
+<p align="center">
+  <i>Hy4 preview is developed by the Tencent Hy Team.</i>
+</p>

README_CN.md

@@ -0,0 +1,232 @@
+<p align="left">
+   <a href="https://huggingface.co/tencent/Hy4-preview">English</a>&nbsp;｜&nbsp;中文
+</p>
+<br>
+
+<p align="center">
+ <img src="assets/logo-zh.png" width="400"/> <br>
+</p>
+
+<div align="center" style="line-height: 1;">
+
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](#许可证)
+&nbsp;&nbsp;
+[![HuggingFace](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Tencent%20Hy-ffc107?color=ffc107&logoColor=white)](https://huggingface.co/tencent/Hy4-preview)
+&nbsp;&nbsp;
+[![ModelScope](https://img.shields.io/badge/ModelScope-Tencent%20Hy-624aff)](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview)
+&nbsp;&nbsp;
+[![cnb.cool](https://img.shields.io/badge/cnb.cool-Tencent%20Hy-blue?logoColor=white)](https://cnb.cool/ai-models/tencent/Hy4-preview)
+&nbsp;&nbsp;
+[![GitCode](https://img.shields.io/badge/GitCode-Tencent%20Hy-red?logoColor=white)](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview)
+
+</div>
+
+<p align="center">
+    🖥️&nbsp;<a href="https://aistudio.tencent.com/"><b>官方网站</b></a>&nbsp;&nbsp;|&nbsp;&nbsp;
+    💬&nbsp;<a href="https://github.com/Tencent-Hunyuan/Hy4-preview"><b>GitHub</b></a></p>
+
+---
+
+## 目录
+
+- [模型介绍](#模型介绍)
+- [新一代旗舰模型](#新一代旗舰模型)
+- [为真实生产力而生](#为真实生产力而生)
+- [Benchmark 附录](#benchmark-附录)
+- [已知局限](#已知局限)
+- [新闻](#新闻)
+- [模型链接](#模型链接)
+- [快速开始](#快速开始)
+- [推理和部署](#推理和部署)
+  - [vLLM](#vllm)
+  - [SGLang](#sglang)
+- [模型微调](#模型微调)
+- [量化工具](#量化工具)
+- [许可证](#许可证)
+- [联系我们](#联系我们)
+
+---
+
+## 模型介绍
+
+**Hy4 preview** 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。
+
+在架构层面，受到 DeepSeek 和 GLM 的启发，注意力侧采用 Gated [DeepSeek Sparse Attention](https://arxiv.org/abs/2512.02556)（Gated DSA），并引入 [IndexCache](https://arxiv.org/abs/2603.12201) 跨层复用稀疏索引，残差侧采用 [iHC (identity Hyper-Connections)](https://zhuanlan.zhihu.com/p/2010852389670908320) 扩展层间信息通路。
+
+### 模型规格
+
+> 下表仅列出主干网络参数，不含MTP层
+
+| 属性 | 值 |
+|:---|:---|
+| 架构 | 混合专家（MoE） |
+| 总参数 | 770B |
+| 激活参数量 | 49B |
+| 层数 | 78 |
+| 隐藏层维度 | 6144 |
+| 注意力类型 | Gated DSA |
+| 注意力头数 | 64 |
+| Query 压缩维度 | 2048 |
+| Key-Value 压缩维度 | 512 |
+| Indexer 头数 / 头维度 | 32 / 128 |
+| Indexer top-k | 2048 |
+| 残差流数 | 4 |
+| 路由专家数 | 256 |
+| 共享专家数 | 1 |
+| 单 token 激活路由专家数 | 8 |
+| MoE中间层维度 | 2048 |
+| FFN中间层维度 | 18432 |
+| 上下文长度 | 1M |
+| 词表大小 | 120832 |
+
+## 新一代旗舰模型
+
+Hy4 preview 在模型尺寸、上下文长度、数据规模上都进行了显著的扩展，预训练和后训练的共同进步带来了智能水平的又一次巨大提升，稳居开源模型第一梯队。
+
+<p align="center">
+  <img src="assets/benchmark.jpg" width="100%"/>
+</p>
+
+## 为真实生产力而生
+
+通过与腾讯内部软件工程师、游戏开发者、金融分析师、安全专家等各领域顶尖专家的高质量数据共建，Hy4 preview 在各类真实生产力任务上取得显著进步：
+
+**软件工程**：增强长程开发任务的理解、规划、调试与验证能力，进一步提升前端开发的视觉审美和交互质量。
+
+**办公分析**：显著提升复杂办公环境理解和金融分析能力，着重优化数据分析、跨文件协作，完成从信息处理到文档、表格与演示文稿交付的完整流程。
+
+**游戏开发**：增强一句需求直接生成可玩原型的能力，并能熟练使用游戏引擎，开发者可以通过多轮交互持续完善复杂游戏项目。
+
+**科学研究**：显著提升复杂科研问题的理解、推理与求解能力，模型在 AI 研发、分子动力学模拟、凝聚态物理、基础数学等各类场景中均有长足进步。
+
+同时，Hy4 preview 持续与 CodeBuddy / WorkBuddy 等产品深度协同，优化生产力场景的真实用户体验。为验证这一点，我们组织了 163 位内部专家基于 203 个真实工程任务进行模型盲测：Hy4 preview（均分 2.99 / 4）略优于 GLM 5.3（均分 2.92 / 4；胜 46.8% / 平 12.8% / 负 40.4%）和 Kimi K3（均分 2.94 / 4；胜 51.2% / 平 7.9% / 负 40.9%）。
+
+## Benchmark 附录
+
+<p align="center">
+  <img src="assets/benchmark-appendix.jpg" width="100%"/>
+</p>
+
+## 已知局限
+
+Hy4 preview 是 Hy4 迭代��一个早期版本，预训练和后训练均仍有较大的提升空间，也有一些已知问题，如复杂任务上的长思考和过度自我验证倾向。如同 Hy3 preview，我们希望通过 Hy4 preview 的尽快发布获得广泛的真实反馈，从而显著提升 Hy4 正式版。同时，我们将坚持发挥与腾讯产品和专家深度合作的独特优势，持续提升生产力的普惠性和上限。
+
+## 新闻
+
+* 🔥 我们在 [Hugging Face](https://huggingface.co/tencent/Hy4-preview)、[ModelScope](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview)、[GitCode](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview) 和 [CNB](https://cnb.cool/ai-models/tencent/Hy4-preview) 开源了 **Hy4 preview** 和 **Hy4 preview-FP8** 模型权重。
+
+## 模型链接
+
+| 模型名 | 简介 | Hugging Face | ModelScope | GitCode | CNB |
+|:---|:---|:---:|:---:|:---:|:---:|
+| Hy4 preview | Instruct 模型 | 🤗 [Model](https://huggingface.co/tencent/Hy4-preview) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview) | [Model](https://cnb.cool/ai-models/tencent/Hy4-preview) |
+| Hy4 preview-FP8 | FP8 量化 Instruct 模型 | 🤗 [Model](https://huggingface.co/tencent/Hy4-preview-FP8) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy4-preview-FP8) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy4-preview-FP8) | [Model](https://cnb.cool/ai-models/tencent/Hy4-preview-FP8) |
+
+## 快速开始
+
+建议先通过 [vLLM](#vllm) 或 [SGLang](#sglang) 部署服务，然后通过 OpenAI 兼容 API 调用：
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
+
+response = client.chat.completions.create(
+    model="hy4-preview",
+    messages=[
+        {"role": "user", "content": "你好！请简单介绍一下你自己。"},
+    ],
+    temperature=0.9,
+    top_p=1.0,
+)
+print(response.choices[0].message.content)
+```
+
+> **推荐参数**：`temperature=0.9`，`top_p=1.0`。
+>
+> **推理模式**：默认为 `"high"`（深度思维链），适合数学、编程、推理等复杂任务；日常对话如需直接回复，可传入 `extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}}`。
+
+具体部署方式请参考下方[推理和部署](#推理和部署)章节。
+
+## 推理和部署
+
+对于生产环境部署，我们建议使用 [vLLM](https://github.com/vllm-project/vllm) 或 [SGLang](https://docs.sglang.io/)。
+
+### vLLM
+
+从源码构建 vLLM：
+
+```bash
+uv venv --python 3.12 --seed --managed-python
+source .venv/bin/activate
+git clone https://github.com/vllm-project/vllm.git
+cd vllm
+uv pip install --editable . --torch-backend=auto
+```
+
+启动 vLLM 服务，开启 MTP：
+
+```bash
+vllm serve tencent/Hy4-preview-FP8 \
+  --tensor-parallel-size 8 \
+  --speculative-config.method mtp \
+  --speculative-config.num_speculative_tokens 3 \
+  --attention-backend FLASHMLA_SPARSE \
+  --tool-call-parser hy_v4 \
+  --reasoning-parser hy_v4 \
+  --enable-auto-tool-choice \
+  --port 8000 \
+  --served-model-name hy4-preview
+```
+
+### SGLang
+
+从源码构建 SGLang：
+
+```bash
+git clone https://github.com/sgl-project/sglang
+cd sglang
+pip3 install pip --upgrade
+pip3 install "transformers>=5.6.0"
+pip3 install -e "python"
+```
+
+启动 SGLang 服务，开启 MTP：
+```bash
+python3 -m sglang.launch_server \
+  --model tencent/Hy4-preview-FP8 \
+  --tp-size 8 \
+  --tool-call-parser hy_v4 \
+  --reasoning-parser hy_v4 \
+  --speculative-num-steps 2 \
+  --speculative-eagle-topk 1 \
+  --speculative-num-draft-tokens 3 \
+  --speculative-algorithm EAGLE \
+  --port 8000 \
+  --served-model-name hy4-preview
+```
+
+## 模型微调
+
+Hy4 preview 提供了完整的模型微调流程，详细的微调文档请参考：[模型微调指南](https://huggingface.co/tencent/Hy4-preview/blob/main/finetune/README_CN.md)
+
+## 量化工具
+
+我们提供了 [AngelSlim](https://github.com/tencent/AngelSlim)——一套易用、全面、高效的大模型压缩工具包，涵盖常用量化算法、低比特量化和投机采样等能力。
+
+## 许可证
+
+Hy4 preview 基于 **Apache 2.0 许可证** 发布。详情请参阅 [LICENSE](https://huggingface.co/tencent/Hy4-preview/blob/main/LICENSE)。
+
+## 联系我们
+
+如有问题或建议，欢迎通过邮件联系我们的研发和产品团队：
+
+📧 **hunyuan_opensource@tencent.com**
+
+---
+
+<p align="center">
+  <i>Hy4 preview 由腾讯混元团队研发。</i>
+</p>