Text Generation
Transformers
Safetensors
PyTorch
ONNX
English
qtensorformer
q-tensorformer
high-throughput-inference
tensor-train
tensor-networks
tensorrt-llm
vllm
continuous-batching
paged-attention
speculative-decoding
zero-svd
adaptive-computation
dynamic-neural-networks
kv-cache
kv-cache-quantization
attention-sinks
lyapunov-stability
control-theory
contextual-bandits
edge-ai
edge-inference
on-device-ai
model-compression
hopper-h100
blackwell-b200
jetson-orin
jetson-thor
grouped-query-attention
rotary-position-embeddings
custom_code
academic-paper
ieee
neurips
vit-ap-university
deepseek
deepseek-r1
reasoning
chain-of-thought
gsm8k
openai-compatible
fastapi
rest-api
sse-streaming
onnx-runtime
embedded-ai
hardware-telemetry
power-efficiency
green-ai
raspberry-pi
smollm2
qwen2.5
llama-3.2
apple-silicon
Instructions to use Premchan369/Q-TensorFormer with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Premchan369/Q-TensorFormer with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("text-generation", model="Premchan369/Q-TensorFormer", trust_remote_code=True)# pip install -U transformers accelerate # Load model directly from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained("Premchan369/Q-TensorFormer", trust_remote_code=True, device_map="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use Premchan369/Q-TensorFormer with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "Premchan369/Q-TensorFormer" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Premchan369/Q-TensorFormer", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'Use Docker
docker model run hf.co/Premchan369/Q-TensorFormer
- SGLang
How to use Premchan369/Q-TensorFormer 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 "Premchan369/Q-TensorFormer" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Premchan369/Q-TensorFormer", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'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 "Premchan369/Q-TensorFormer" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Premchan369/Q-TensorFormer", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }' - Docker Model Runner
How to use Premchan369/Q-TensorFormer with Docker Model Runner:
docker model run hf.co/Premchan369/Q-TensorFormer
File size: 12,047 Bytes
15a4381 7aefd9e 15a4381 377d9af 15a4381 377d9af 15a4381 377d9af 15a4381 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 | """
Configuration class for Q-TensorFormer: Closed-Loop Information-Adaptive Tensor Network LLM.
Supports:
- Grouped-Query Attention (GQA) with RoPE
- Tensor-Train (TT) low-rank linear layers
- Closed-loop PID dynamic resource controller
- Adaptive KV cache with attention sinks & cold-line quantization
- Turnkey Hugging Face AutoConfig registration
"""
import math
from typing import List, Optional, Tuple, Union
from transformers.configuration_utils import PretrainedConfig
from transformers import AutoConfig
def factorize_dim(dim: int, num_cores: int = 3) -> Tuple[int, ...]:
"""
Heuristically factorize an integer dimension into `num_cores` balanced sub-dimensions.
Used for automatic TT core shape inference.
"""
factors: List[int] = []
d = dim
for i in range(2, int(math.isqrt(dim)) + 1):
while d % i == 0:
factors.append(i)
d //= i
if d > 1:
factors.append(d)
if not factors:
factors = [dim]
# Combine or pad to exactly num_cores
while len(factors) < num_cores:
# Split the largest factor
idx = max(range(len(factors)), key=lambda i: factors[i])
val = factors[idx]
sqrt_val = math.isqrt(val)
if sqrt_val > 1 and val % sqrt_val == 0:
factors[idx] = sqrt_val
factors.append(val // sqrt_val)
else:
factors.append(1)
while len(factors) > num_cores:
# Multiply the two smallest factors
factors.sort()
factors[0] = factors[0] * factors[1]
factors.pop(1)
factors.sort(reverse=True)
return tuple(factors)
class QTensorFormerConfig(PretrainedConfig):
r"""
This is the configuration class to store the configuration of a [`QTensorFormerForCausalLM`].
It is used to instantiate a Q-TensorFormer model according to the specified arguments, defining the model
architecture, Tensor-Train decomposition parameters, closed-loop PID controller, and adaptive KV cache.
Configuration objects inherit from [`PretrainedConfig`] and can be used to control the model outputs.
Read the documentation from [`PretrainedConfig`] for more information.
Args:
vocab_size (`int`, *optional*, defaults to 32000):
Vocabulary size of the Q-TensorFormer model. Defines the number of different tokens that can be
represented by the `inputs_ids` passed when calling [`QTensorFormerForCausalLM`].
hidden_size (`int`, *optional*, defaults to 2048):
Dimension of the hidden representations.
num_hidden_layers (`int`, *optional*, defaults to 16):
Number of hidden layers in the Transformer decoder.
num_attention_heads (`int`, *optional*, defaults to 16):
Number of attention heads for each attention layer in the Transformer decoder.
num_key_value_heads (`int`, *optional*, defaults to 4):
This is the number of key_value heads that should be used to implement Grouped Query Attention.
If `num_key_value_heads=num_attention_heads`, the model will use Multi Head Attention (MHA), if
`num_key_value_heads=1` the model will use Multi Query Attention (MQA) otherwise GQA is used.
intermediate_size (`int`, *optional*, defaults to 5632):
Dimension of the MLP representations.
max_position_embeddings (`int`, *optional*, defaults to 4096):
The maximum sequence length that this model might ever be used with.
rms_norm_eps (`float`, *optional*, defaults to 1e-6):
The epsilon used by the rms normalization layers.
tt_ranks (`List[int]`, *optional*, defaults to `[1, 16, 16, 1]`):
Tensor-Train ranks $[R_0, R_1, \dots, R_d]$ for linear projections. Must start and end with 1.
tt_shapes (`List[Tuple[Tuple[int, ...], Tuple[int, ...]]]`, *optional*):
Explicit list of input/output factor shapes for TT projections. If None, automatically inferred.
enable_dynamic_routing (`bool`, *optional*, defaults to `True`):
Whether to dynamically modulate TT contraction rank and KV cache precision on a per-token basis.
pid_kp (`float`, *optional*, defaults to 0.1):
Proportional gain for the closed-loop dual-subgradient PID resource controller.
pid_ki (`float`, *optional*, defaults to 0.01):
Integral gain for the closed-loop dual-subgradient PID resource controller.
pid_kd (`float`, *optional*, defaults to 0.05):
Derivative gain for the closed-loop dual-subgradient PID resource controller.
hysteresis_threshold (`float`, *optional*, defaults to 0.15):
Hysteresis deadband $\tau$ to prevent high-frequency routing chattering and oscillation.
attention_sink_size (`int`, *optional*, defaults to 4):
Number of initial tokens to permanently preserve in the KV cache as attention sinks.
kv_cache_window_size (`int`, *optional*, defaults to 1024):
Sliding window size for local token residency in the adaptive KV cache.
quantize_kv_cold (`bool`, *optional*, defaults to `True`):
Whether to dynamically quantize cold KV tokens outside the immediate window.
kv_quant_bits (`int`, *optional*, defaults to 4):
Quantization bit-width for cold KV tokens (4 or 8).
target_energy_budget (`float`, *optional*, defaults to 1.0):
Normalized energy budget set-point for the PID controller.
rope_theta (`float`, *optional*, defaults to 10000.0):
The base period of the RoPE embeddings.
initializer_range (`float`, *optional*, defaults to 0.02):
The standard deviation of the truncated_normal_initializer for initializing all weight matrices.
tie_word_embeddings (`bool`, *optional*, defaults to `False`):
Whether to tie weight embeddings.
"""
model_type = "qtensorformer"
keys_to_ignore_at_loading = []
def __init__(
self,
vocab_size: int = 32000,
hidden_size: int = 2048,
num_hidden_layers: int = 16,
num_attention_heads: int = 16,
num_key_value_heads: Optional[int] = None,
intermediate_size: int = 5632,
max_position_embeddings: int = 4096,
rms_norm_eps: float = 1e-6,
tt_ranks: Optional[List[int]] = None,
tt_shapes: Optional[List[Tuple[Tuple[int, ...], Tuple[int, ...]]]] = None,
enable_dynamic_routing: bool = True,
pid_kp: float = 0.1,
pid_ki: float = 0.01,
pid_kd: float = 0.05,
hysteresis_threshold: float = 0.15,
attention_sink_size: int = 4,
kv_cache_window_size: int = 1024,
quantize_kv_cold: bool = True,
kv_quant_bits: int = 4,
target_energy_budget: float = 1.0,
rope_theta: float = 10000.0,
initializer_range: float = 0.02,
tie_word_embeddings: bool = False,
use_cache: bool = True,
bos_token_id: Optional[int] = 1,
eos_token_id: Optional[int] = 2,
pad_token_id: Optional[int] = None,
**kwargs,
):
# Resolve legacy parameter aliases if provided in kwargs
if "d_model" in kwargs:
hidden_size = kwargs.pop("d_model")
if "n_layers" in kwargs:
num_hidden_layers = kwargs.pop("n_layers")
if "n_heads" in kwargs:
num_attention_heads = kwargs.pop("n_heads")
if "n_kv_heads" in kwargs:
num_key_value_heads = kwargs.pop("n_kv_heads")
if "max_seq_len" in kwargs:
max_position_embeddings = kwargs.pop("max_seq_len")
if "ff_multiplier" in kwargs and intermediate_size == 5632:
ff_mult = kwargs.pop("ff_multiplier")
intermediate_size = hidden_size * ff_mult
if "tt_rank" in kwargs and tt_ranks is None:
r = kwargs.pop("tt_rank")
tt_ranks = [1, r, r, 1]
self.vocab_size = vocab_size
self.hidden_size = hidden_size
self.num_hidden_layers = num_hidden_layers
self.num_attention_heads = num_attention_heads
# Key-Value heads: default to GQA 4 if heads >= 4, else match num_attention_heads
if num_key_value_heads is None:
num_key_value_heads = min(4, num_attention_heads)
elif num_key_value_heads > num_attention_heads:
num_key_value_heads = num_attention_heads
self.num_key_value_heads = num_key_value_heads
self.intermediate_size = intermediate_size
self.max_position_embeddings = max_position_embeddings
self.rms_norm_eps = rms_norm_eps
# Tensor-Train parameters
self.tt_ranks = tt_ranks if tt_ranks is not None else [1, 16, 16, 1]
self.tt_shapes = tt_shapes
# Closed-loop PID & Dynamic Routing parameters
self.enable_dynamic_routing = enable_dynamic_routing
self.pid_kp = pid_kp
self.pid_ki = pid_ki
self.pid_kd = pid_kd
self.hysteresis_threshold = hysteresis_threshold
self.target_energy_budget = target_energy_budget
# Adaptive KV Cache parameters
self.attention_sink_size = attention_sink_size
self.kv_cache_window_size = kv_cache_window_size
self.quantize_kv_cold = quantize_kv_cold
self.kv_quant_bits = kv_quant_bits
# Attention & Position parameters
self.rope_theta = rope_theta
self.initializer_range = initializer_range
self.use_cache = use_cache
self.bos_token_id = bos_token_id
self.eos_token_id = eos_token_id
self.pad_token_id = pad_token_id
super().__init__(
bos_token_id=bos_token_id,
eos_token_id=eos_token_id,
pad_token_id=pad_token_id,
tie_word_embeddings=tie_word_embeddings,
**kwargs,
)
self._validate_config()
def _validate_config(self):
if self.hidden_size % self.num_attention_heads != 0:
raise ValueError(
f"hidden_size ({self.hidden_size}) must be divisible by num_attention_heads ({self.num_attention_heads})"
)
if self.num_attention_heads % self.num_key_value_heads != 0:
raise ValueError(
f"num_attention_heads ({self.num_attention_heads}) must be divisible by num_key_value_heads ({self.num_key_value_heads})"
)
if len(self.tt_ranks) < 3:
raise ValueError(f"tt_ranks must contain at least 3 elements [1, ..., 1], got {self.tt_ranks}")
if self.tt_ranks[0] != 1 or self.tt_ranks[-1] != 1:
raise ValueError(f"Boundary tt_ranks must be 1, got {self.tt_ranks}")
if self.kv_quant_bits not in (4, 8):
raise ValueError(f"kv_quant_bits must be either 4 or 8, got {self.kv_quant_bits}")
@property
def head_dim(self) -> int:
return self.hidden_size // self.num_attention_heads
@property
def num_key_value_groups(self) -> int:
return self.num_attention_heads // self.num_key_value_heads
@property
def d_model(self) -> int:
return self.hidden_size
@property
def n_layers(self) -> int:
return self.num_hidden_layers
@property
def n_heads(self) -> int:
return self.num_attention_heads
@property
def n_kv_heads(self) -> int:
return self.num_key_value_heads
@property
def max_seq_len(self) -> int:
return self.max_position_embeddings
def get_tt_shapes(self, in_features: int, out_features: int) -> Tuple[Tuple[int, ...], Tuple[int, ...]]:
"""Compute or retrieve input and output tensor modes for TTLinear."""
num_cores = len(self.tt_ranks) - 1
in_shape = factorize_dim(in_features, num_cores=num_cores)
out_shape = factorize_dim(out_features, num_cores=num_cores)
return in_shape, out_shape
# Register QTensorFormerConfig with Hugging Face AutoConfig
AutoConfig.register("qtensorformer", QTensorFormerConfig)
|