add quickstart

README.md

@@ -130,6 +130,72 @@ KU/DFI's role is to build that open commons. The program now spans the key layer
 - **Model weights.** [KU-DFI/TelecomGPT-R1](https://huggingface.co/KU-DFI/TelecomGPT-R1/tree/main)
 - **Unified benchmark.** [GSMA Open Telco Leaderboard](https://huggingface.co/spaces/GSMA/open-telco-leaderboard)
 
+### Quickstart
+
+Here is a code snippet demonstrating how to load TelecomGPT-R1 with `transformers` and generate a telecom-grounded response:
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "KU-DFI/TelecomGPT-R1"
+
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype="auto",
+    device_map="auto",
+)
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+prompt = (
+    "A 5G NR cell is observing repeated random-access failures from cell-edge UEs. "
+    "Drive-test capture shows: average RSRP = -108 dBm, average RSRQ = -16 dB, "
+    "PRACH preamble attempts averaging 8 with no Msg2 (RAR) received within "
+    "ra-ResponseWindow, UE timing-advance range 4-7 km, and PRACH configuration "
+    "uses preamble format A1 with zeroCorrelationZoneConfig = 8. "
+    "Diagnose the most likely root cause and propose a configuration change."
+)
+messages = [
+    {
+        "role": "system",
+        "content": (
+            "You are TelecomGPT-R1, an open 27B telecom reasoning model from "
+            "KU/DFI. Reason step-by-step over 3GPP standards, RAN logs, RF and "
+            "network derivations, and telecom code."
+        ),
+    },
+    {"role": "user", "content": prompt},
+]
+text = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True,
+)
+model_inputs = tokenizer([text], return_tensors="pt").to(model.device)
+
+generated_ids = model.generate(
+    **model_inputs,
+    max_new_tokens=2048,
+)
+generated_ids = [
+    output_ids[len(input_ids):]
+    for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
+]
+
+response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
+print(response)
+```
+
+For production / batch serving on operator-confidential data, host with [vLLM](https://github.com/vllm-project/vllm):
+
+```bash
+vllm serve KU-DFI/TelecomGPT-R1 \
+    --tensor-parallel-size 4 \
+    --max-model-len 32768 \
+    --gpu-memory-utilization 0.90
+```
+
+**Hardware**: TelecomGPT-R1 (27B, bf16) fits on a single H100 80GB or MI300X; for high-throughput inference behind an operator firewall a single H100/MI300 node serves the model end-to-end.
+
 ### Citation
 
 ```bibtex
@@ -153,4 +219,4 @@ KU/DFI's role is to build that open commons. The program now spans the key layer
 
 ### Acknowledgements
 
-This work was supported by the Digital Future Institute of Khalifa University; the College of Information Science and Electronic Engineering, Zhejiang University; the College of Computer Science and Technology, Zhejiang University; and the Research Computing team of Khalifa University. 
+This work was supported by the Digital Future Institute of Khalifa University; the College of Information Science and Electronic Engineering, Zhejiang University; the College of Computer Science and Technology, Zhejiang University; and the Research Computing team of Khalifa University.