NF4 (bitsandbytes 4-bit) build of Fish Speech S2-Pro

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+overview.png filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

LICENSE.md

@@ -0,0 +1,94 @@
+# FISH AUDIO RESEARCH LICENSE AGREEMENT
+
+**Last Updated: March 7, 2026**
+
+## I. INTRODUCTION
+
+This Agreement applies to any individual person or entity ("You", "Your" or "Licensee") that uses or distributes any portion or element of the Fish Audio Materials or Derivative Works thereof for any Research, Non-Commercial, or Commercial purpose. Capitalized terms not otherwise defined herein are defined in Section V below.
+
+This Agreement is intended to allow research and non-commercial uses of the Materials free of charge. Any Commercial use of the Materials requires a separate license from Fish Audio.
+
+By clicking "I Accept" or by using, distributing, or accessing any portion or element of the Fish Audio Materials or Derivative Works, You agree that You have read, understood and are bound by the terms of this Agreement. If You are acting on behalf of a company, organization or other entity, then "You" includes you and that entity, and You agree that You: (i) are an authorized representative of such entity with the authority to bind such entity to this Agreement, and (ii) You agree to the terms of this Agreement on that entity's behalf.
+
+## II. RESEARCH & NON-COMMERCIAL USE LICENSE
+
+Subject to the terms of this Agreement, Fish Audio grants You a non-exclusive, worldwide, non-transferable, non-sublicensable, revocable and royalty-free limited license under Fish Audio's intellectual property or other rights owned by Fish Audio embodied in the Fish Audio Materials to use, reproduce, distribute, and create Derivative Works of, and make modifications to, the Fish Audio Materials for any Research or Non-Commercial Purpose.
+
+"Research Purpose" means academic or scientific advancement, and in each case, is not primarily intended for commercial advantage or monetary compensation to You or others.
+
+"Non-Commercial Purpose" means any purpose other than a Research Purpose that is not primarily intended for commercial advantage or monetary compensation to You or others, such as personal use (i.e., hobbyist) or evaluation and testing.
+
+## III. COMMERCIAL USE
+
+**Any use of the Fish Audio Materials or Derivative Works for a Commercial Purpose requires a separate written license agreement from Fish Audio.** No commercial rights are granted under this Agreement.
+
+"Commercial Purpose" means any purpose other than a Research Purpose or Non-Commercial Purpose that is primarily intended for or directed toward commercial advantage or monetary compensation to You or others, including but not limited to: (i) creating, modifying, or distributing Your product or service, including via a hosted service or application programming interface, (ii) Your business's or organization's internal operations, and (iii) any use in connection with a product or service for which You charge a fee or generate revenue, whether directly or indirectly.
+
+To obtain a commercial license, please contact Fish Audio at:
+
+- **Website:** [https://fish.audio](https://fish.audio)
+- **Email:** business@fish.audio
+
+## IV. GENERAL TERMS
+
+Your Research and Non-Commercial License under this Agreement is subject to the following terms.
+
+### a. Distribution & Attribution
+
+If You distribute or make available the Fish Audio Materials or a Derivative Work to a third party, or a product or service that uses any portion of them, You shall: (i) provide a copy of this Agreement to that third party, (ii) retain the following attribution notice within a "Notice" text file distributed as a part of such copies: "This model is licensed under the Fish Audio Research License, Copyright © 39 AI, INC. All Rights Reserved.", and (iii) prominently display "Built with Fish Audio" on a related website, user interface, blogpost, about page, or product documentation.
+
+If You create a Derivative Work, You may add your own attribution notice(s) to the "Notice" text file included with that Derivative Work, provided that You clearly indicate which attributions apply to the Fish Audio Materials and state in the "Notice" text file that You changed the Fish Audio Materials and how it was modified.
+
+### b. Use Restrictions
+
+Your use of the Fish Audio Materials and Derivative Works, including any output or results of the Fish Audio Materials or Derivative Works, must comply with applicable laws and regulations (including Trade Control Laws and equivalent regulations) and adhere to Fish Audio's Acceptable Use Policy, which is hereby incorporated by reference.
+
+Furthermore, You will not use the Fish Audio Materials or Derivative Works, or any output or results of the Fish Audio Materials or Derivative Works, to create or improve any foundational generative AI model (excluding the Models or Derivative Works).
+
+### c. Intellectual Property
+
+**(i) Trademark License.** No trademark licenses are granted under this Agreement, and in connection with the Fish Audio Materials or Derivative Works, You may not use any name or mark owned by or associated with Fish Audio or any of its Affiliates, except as required under Section IV(a) herein.
+
+**(ii) Ownership of Derivative Works.** As between You and Fish Audio, You are the owner of Derivative Works You create, subject to Fish Audio's ownership of the Fish Audio Materials and any Derivative Works made by or for Fish Audio.
+
+**(iii) Ownership of Outputs.** As between You and Fish Audio, You own any outputs generated from the Models or Derivative Works to the extent permitted by applicable law.
+
+**(iv) Disputes.** If You or Your Affiliate(s) institute litigation or other proceedings against Fish Audio (including a cross-claim or counterclaim in a lawsuit) alleging that the Fish Audio Materials, Derivative Works or associated outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by You, then any licenses granted to You under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Fish Audio from and against any claim by any third party arising out of or related to Your use or distribution of the Fish Audio Materials or Derivative Works in violation of this Agreement.
+
+**(v) Feedback.** From time to time, You may provide Fish Audio with verbal and/or written suggestions, comments or other feedback related to Fish Audio's existing or prospective technology, products or services (collectively, "Feedback"). You are not obligated to provide Fish Audio with Feedback, but to the extent that You do, You hereby grant Fish Audio a perpetual, irrevocable, royalty-free, fully-paid, sub-licensable, transferable, non-exclusive, worldwide right and license to exploit the Feedback in any manner without restriction. Your Feedback is provided "AS IS" and You make no warranties whatsoever about any Feedback.
+
+### d. Disclaimer of Warranty
+
+UNLESS REQUIRED BY APPLICABLE LAW, THE FISH AUDIO MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OR LAWFULNESS OF USING OR REDISTRIBUTING THE FISH AUDIO MATERIALS, DERIVATIVE WORKS OR ANY OUTPUT OR RESULTS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE FISH AUDIO MATERIALS, DERIVATIVE WORKS AND ANY OUTPUT AND RESULTS.
+
+### e. Limitation of Liability
+
+IN NO EVENT WILL FISH AUDIO OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF FISH AUDIO OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+### f. Term and Termination
+
+The term of this Agreement will commence upon Your acceptance of this Agreement or access to the Fish Audio Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Fish Audio may terminate this Agreement if You are in breach of any term or condition of this Agreement. Upon termination of this Agreement, You shall delete and cease use of any Fish Audio Materials or Derivative Works. Sections IV(d), (e), and (g) shall survive the termination of this Agreement.
+
+### g. Governing Law
+
+This Agreement will be governed by and construed in accordance with the laws of the United States and the State of California without regard to choice of law principles, and the UN Convention on Contracts for International Sale of Goods does not apply to this Agreement.
+
+## V. DEFINITIONS
+
+**"Affiliate(s)"** means any entity that directly or indirectly controls, is controlled by, or is under common control with the subject entity; for purposes of this definition, "control" means direct or indirect ownership or control of more than 50% of the voting interests of the subject entity.
+
+**"Agreement"** means this Fish Audio Research License Agreement.
+
+**"Derivative Work(s)"** means (a) any derivative work of the Fish Audio Materials as recognized by U.S. copyright laws and (b) any modifications to a Model, and any other model created which is based on or derived from the Model or the Model's output, including "fine tune" and "low-rank adaptation" models derived from a Model or a Model's output, but do not include the output of any Model.
+
+**"Documentation"** means any specifications, manuals, documentation, and other written information provided by Fish Audio related to the Software or Models.
+
+**"Fish Audio"** or **"we"** means 39 AI, INC. and its Affiliates.
+
+**"Model(s)"** means, collectively, Fish Audio's proprietary models and algorithms, including machine-learning models, trained model weights and other elements of the foregoing.
+
+**"Software"** means Fish Audio's proprietary software made available under this Agreement now or in the future.
+
+**"Fish Audio Materials"** means, collectively, Fish Audio's proprietary Models, Software and Documentation (and any portion or combination thereof) made available under this Agreement.
+
+**"Trade Control Laws"** means any applicable U.S. and non-U.S. export control and trade sanctions laws and regulations.

README.md

@@ -0,0 +1,122 @@
+---
+license: other
+license_name: fish-audio-research-license
+license_link: https://huggingface.co/fishaudio/s2-pro/blob/main/LICENSE
+base_model: fishaudio/s2-pro
+pipeline_tag: text-to-speech
+library_name: transformers
+tags:
+  - text-to-speech
+  - tts
+  - voice-cloning
+  - bitsandbytes
+  - nf4
+  - 4-bit
+  - quantized
+language:
+  - en
+  - zh
+  - ja
+  - ko
+  - id
+  - de
+  - fr
+  - ar
+---
+
+# Fish Speech S2-Pro — NF4 (bitsandbytes 4-bit)
+
+A **bitsandbytes NF4 4-bit** quantization of [`fishaudio/s2-pro`](https://huggingface.co/fishaudio/s2-pro),
+the 4B-parameter flagship Fish Audio S2 text-to-speech model.
+
+Roughly **4.9 GB** on disk against 8.5 GB of bf16 safetensors, and it loads
+directly as 4-bit — no quantization step at startup.
+
+Everything the base model does is preserved: voice cloning from a short
+reference clip, ~50 languages, and inline expressiveness tags such as
+`[laugh]`, `[whispers]`, `[sighs]`.
+
+## Intended use
+
+This checkpoint is built for
+[scarxity/fish-speech-int4-patch](https://github.com/scarxity/fish-speech-int4-patch),
+a fork whose `server-4gb` / `webui-4gb` Docker profiles run S2-Pro on a **4 GB**
+laptop GPU (measured 3294 MiB peak on a simulated 4096 MiB budget, faster than
+realtime on an RTX 4060 Ti).
+
+> **The 4 GB figure comes from the fork's serving code, not from these weights
+> alone.** The quantization is what fits ~4.9 GB on disk; getting into 4 GB of
+> VRAM additionally needs the fork's decode-only codec, host-resident embedding
+> table, sliced `lm_head`, and chunked codec decode. Stock upstream code with
+> this checkpoint will need more VRAM than that.
+
+```bash
+git clone https://github.com/scarxity/fish-speech-int4-patch
+cd fish-speech-int4-patch
+
+huggingface-cli download scarxity/fish-speech-s2-pro-nf4 --local-dir checkpoints/s2-pro-nf4
+
+docker compose --profile server-4gb build
+docker compose --profile server-4gb up -d
+```
+
+Then POST to `http://localhost:8880/v1/tts`:
+
+```json
+{ "text": "Hello, world.", "reference_id": "my-voice" }
+```
+
+An OpenAI-compatible `/v1/audio/speech` endpoint and a Gradio WebUI (port 7860)
+are included. See the fork's
+[4 GB guide](https://github.com/scarxity/fish-speech-int4-patch/blob/main/docs/en/4gb-laptop.md)
+for reference-voice setup and long-text handling.
+
+## Requirements
+
+- NVIDIA GPU (bitsandbytes NF4 is CUDA-only)
+- `bitsandbytes >= 0.43`
+- Loading flags `--bnb4 --half`
+
+This is **NF4**, not GPTQ, AWQ, or int4 — those formats are not interchangeable,
+and loaders for them will not read this checkpoint.
+
+## Quantization details
+
+| | |
+|---|---|
+| Scheme | bitsandbytes NF4 (normal-float 4-bit) |
+| Double quantization | enabled (`compress_statistics=True`) |
+| Compute dtype | fp16 |
+| Quantized | the 36-layer slow backbone and the 4-layer depth transformer |
+| Effective | ~4.13 bits/weight |
+
+## Architecture
+
+S2-Pro is a Dual-AR model over an RVQ audio codec (10 codebooks, 21.53 Hz):
+
+- **Slow AR** (36 layers, dim 2560) predicts the semantic codebook along time —
+  words, pronunciation, language, and the inline emotion tags.
+- **Fast AR** (4 layers, dim 2560) runs nine times per frame for the residual
+  codebooks — timbre and fine acoustic texture.
+- **Codec** upsamples the codes ×2048 to a 44.1 kHz waveform.
+
+## Notes
+
+- `tokenizer_config.json` in this repo declares `PreTrainedTokenizerFast`.
+  Some S2-Pro copies ship `TokenizersBackend`, a transformers v5 name that
+  older loaders reject with `UnboundLocalError: tokenizer`.
+- Voice cloning is **in-context**: the reference clip's codes are prepended to
+  every request rather than fine-tuned in. Keep reference clips near 10 seconds
+  — a 31.7 s clip costs 683 prompt tokens on every request against 220 for a
+  10.2 s one.
+
+## License
+
+Released under the **Fish Audio Research License**, inherited from the base
+model. Review it before any commercial or redistributive use.
+
+## Credits
+
+- [Fish Audio](https://fish.audio/) — the S2 model, all core research and architecture
+- [groxaxo/fish-speech-int4-patch](https://github.com/groxaxo/fish-speech-int4-patch) — the original NF4 quantization path
+- [Technical report](https://arxiv.org/abs/2603.08823)

chat_template.jinja

@@ -0,0 +1,85 @@
+{%- if tools %}
+    {{- '<|im_start|>system\n' }}
+    {%- if messages[0].role == 'system' %}
+        {{- messages[0].content + '\n\n' }}
+    {%- endif %}
+    {{- "# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>\n\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\n<tool_call>\n{\"name\": <function-name>, \"arguments\": <args-json-object>}\n</tool_call><|im_end|>\n" }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {{- '<|im_start|>system\n' + messages[0].content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
+{%- for message in messages[::-1] %}
+    {%- set index = (messages|length - 1) - loop.index0 %}
+    {%- if ns.multi_step_tool and message.role == "user" and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}
+        {%- set ns.multi_step_tool = false %}
+        {%- set ns.last_query_index = index %}
+    {%- endif %}
+{%- endfor %}
+{%- for message in messages %}
+    {%- if (message.role == "user") or (message.role == "system" and not loop.first) %}
+        {{- '<|im_start|>' + message.role + '\n' + message.content + '<|im_end|>' + '\n' }}
+    {%- elif message.role == "assistant" %}
+        {%- set content = message.content %}
+        {%- set reasoning_content = '' %}
+        {%- if message.reasoning_content is defined and message.reasoning_content is not none %}
+            {%- set reasoning_content = message.reasoning_content %}
+        {%- else %}
+            {%- if '</think>' in message.content %}
+                {%- set content = message.content.split('</think>')[-1].lstrip('\n') %}
+                {%- set reasoning_content = message.content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
+            {%- endif %}
+        {%- endif %}
+        {%- if loop.index0 > ns.last_query_index %}
+            {%- if loop.last or (not loop.last and reasoning_content) %}
+                {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content.strip('\n') + '\n</think>\n\n' + content.lstrip('\n') }}
+            {%- else %}
+                {{- '<|im_start|>' + message.role + '\n' + content }}
+            {%- endif %}
+        {%- else %}
+            {{- '<|im_start|>' + message.role + '\n' + content }}
+        {%- endif %}
+        {%- if message.tool_calls %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if (loop.first and content) or (not loop.first) %}
+                    {{- '\n' }}
+                {%- endif %}
+                {%- if tool_call.function %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {{- '<tool_call>\n{"name": "' }}
+                {{- tool_call.name }}
+                {{- '", "arguments": ' }}
+                {%- if tool_call.arguments is string %}
+                    {{- tool_call.arguments }}
+                {%- else %}
+                    {{- tool_call.arguments | tojson }}
+                {%- endif %}
+                {{- '}\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {{- message.content }}
+        {{- '\n</tool_response>' }}
+        {%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+    {%- if enable_thinking is defined and enable_thinking is false %}
+        {{- '<think>\n\n</think>\n\n' }}
+    {%- endif %}
+{%- endif %}

codec.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:74fc41c5a7151c6f350af8bd7e5d6e3accfcc7f3dfbfac23afd35af07052bb2f
+size 1871099728

config.json

@@ -0,0 +1,37 @@
+{
+    "attention_o_bias": false,
+    "attention_qk_norm": true,
+    "attention_qkv_bias": false,
+    "audio_embed_dim": 2560,
+    "codebook_size": 4096,
+    "dim": 2560,
+    "dropout": 0.0,
+    "fast_attention_o_bias": false,
+    "fast_attention_qk_norm": false,
+    "fast_attention_qkv_bias": false,
+    "fast_dim": 2560,
+    "fast_head_dim": 128,
+    "fast_intermediate_size": 9728,
+    "fast_n_head": 32,
+    "fast_n_local_heads": 8,
+    "head_dim": 128,
+    "initializer_range": 0.01976423537605237,
+    "intermediate_size": 9728,
+    "is_reward_model": false,
+    "max_seq_len": 32768,
+    "model_type": "dual_ar",
+    "n_fast_layer": 4,
+    "n_head": 32,
+    "n_layer": 36,
+    "n_local_heads": 8,
+    "norm_eps": 1e-06,
+    "norm_fastlayer_input": true,
+    "num_codebooks": 10,
+    "rope_base": 1000000,
+    "scale_codebook_embeddings": true,
+    "semantic_begin_id": 151678,
+    "semantic_end_id": 155773,
+    "tie_word_embeddings": true,
+    "use_gradient_checkpointing": true,
+    "vocab_size": 155776
+}

model.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08b409f40c653cf2af5b5b08a797c67ba706d22b586c831c14e5ac156b1960ae
+size 3117301458

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f24e08099d45a8adf3f52f5f0b03276e433bb9d689bb15fcbcc48ce58744588b
+size 12217872

tokenizer_config.json

@@ -0,0 +1,14 @@
+{
+  "add_prefix_space": false,
+  "backend": "tokenizers",
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|endoftext|>",
+  "errors": "replace",
+  "is_local": true,
+  "model_max_length": 131072,
+  "pad_token": "<|endoftext|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "PreTrainedTokenizerFast",
+  "unk_token": null
+}