Kimi K2.5 HuggingFace: Model Card, Usage Guide & Integration 2026

# Install HuggingFace Hub
pip install huggingface-hub

# Login (required for gated models)
huggingface-cli login

# Download the model
huggingface-cli download moonshotai/Kimi-K2.5 --local-dir ./kimi-k2-5

from huggingface_hub import snapshot_download

# Download model
model_path = snapshot_download(
    repo_id="moonshotai/Kimi-K2.5",
    local_dir="./kimi-k2-5",
    local_dir_use_symlinks=False
)

print(f"Model downloaded to: {model_path}")

from transformers import AutoModelForCausalLM, AutoTokenizer

# Load tokenizer
tokenizer = AutoTokenizer.from_pretrained(
    "moonshotai/Kimi-K2.5",
    trust_remote_code=True
)

# Load model
model = AutoModelForCausalLM.from_pretrained(
    "moonshotai/Kimi-K2.5",
    trust_remote_code=True,
    torch_dtype="auto",
    device_map="auto"
)

# Generate text
inputs = tokenizer("Explain quantum computing:", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=200)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# Load with device mapping across multiple GPUs
model = AutoModelForCausalLM.from_pretrained(
    "moonshotai/Kimi-K2.5",
    trust_remote_code=True,
    torch_dtype=torch.float16,
    device_map="auto",  # Automatically distribute across available GPUs
    max_memory={0: "80GiB", 1: "80GiB", 2: "80GiB", 3: "80GiB"}
)

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

# Configure 4-bit quantization
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=True
)

# Load quantized model
model = AutoModelForCausalLM.from_pretrained(
    "moonshotai/Kimi-K2.5",
    trust_remote_code=True,
    quantization_config=bnb_config,
    device_map="auto"
)

pip install vllm

# Start vLLM server
python -m vllm.entrypoints.openai.api_server \
    --model moonshotai/Kimi-K2.5 \
    --tensor-parallel-size 4 \
    --max-model-len 65536 \
    --dtype float16

from vllm import LLM, SamplingParams

# Initialize LLM
llm = LLM(
    model="moonshotai/Kimi-K2.5",
    tensor_parallel_size=4,
    max_model_len=65536,
    dtype="float16"
)

# Configure sampling
sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1000
)

# Generate
prompts = [
    "Explain machine learning:",
    "Write a Python function to sort a list:"
]
outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(f"Prompt: {output.prompt}")
    print(f"Response: {output.outputs[0].text}\n")

# After starting vLLM server
import openai

client = openai.OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"
)

response = client.chat.completions.create(
    model="moonshotai/Kimi-K2.5",
    messages=[
        {"role": "user", "content": "Hello, Kimi!"}
    ]
)

print(response.choices[0].message.content)

# Search and verify actively maintained GGUF repos before downloading
# https://huggingface.co/models?search=Kimi-K2.5%20GGUF

# Basic inference
./main \
    -m ./models/Kimi-K2.5.Q4_K_M.gguf \
    -p "Explain quantum computing:" \
    -n 512 \
    --temp 0.7

# Interactive mode
./main \
    -m ./models/Kimi-K2.5.Q4_K_M.gguf \
    --interactive \
    --temp 0.7 \
    -n 4096

from llama_cpp import Llama

# Load model
llm = Llama(
    model_path="./models/Kimi-K2.5.Q4_K_M.gguf",
    n_ctx=8192,
    n_threads=8
)

# Generate
output = llm(
    "Explain machine learning:",
    max_tokens=512,
    temperature=0.7
)
print(output["choices"][0]["text"])

from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    TrainingArguments,
    Trainer
)
from peft import LoraConfig, get_peft_model
import torch

# Load base model
model = AutoModelForCausalLM.from_pretrained(
    "moonshotai/Kimi-K2.5",
    trust_remote_code=True,
    torch_dtype=torch.float16,
    device_map="auto"
)

# Configure LoRA
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

# Apply LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

# Training setup
training_args = TrainingArguments(
    output_dir="./kimi-k2-5-finetuned",
    num_train_epochs=3,
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    save_steps=100,
    logging_steps=10,
    fp16=True
)

# Initialize trainer
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    tokenizer=tokenizer
)

# Train
trainer.train()

FROM nvidia/cuda:12.1-devel-ubuntu22.04

WORKDIR /app

# Install dependencies
RUN pip install torch transformers vllm huggingface-hub

# Download model
RUN huggingface-cli download moonshotai/Kimi-K2.5 --local-dir /models/kimi-k2-5

# Start vLLM server
CMD python -m vllm.entrypoints.openai.api_server \
    --model /models/kimi-k2-5 \
    --tensor-parallel-size 4 \
    --host 0.0.0.0 \
    --port 8000

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kimi-k2-5
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kimi-k2-5
  template:
    metadata:
      labels:
        app: kimi-k2-5
    spec:
      containers:
        - name: vllm
          image: vllm/vllm-openai:latest
          args:
            - --model
            - moonshotai/Kimi-K2.5
            - --tensor-parallel-size
            - '4'
          resources:
            limits:
              nvidia.com/gpu: '4'
          ports:
            - containerPort: 8000