Improve model card with paper link, system requirements, and sample usage

README.md

@@ -1,10 +1,10 @@
 ---
-license: mit
 language:
 - en
 - zh
-pipeline_tag: text-generation
 library_name: transformers
+license: mit
+pipeline_tag: text-generation
 ---
 
 # GLM-4.5-Air-Base
@@ -21,7 +21,9 @@ library_name: transformers
     <br>
     👉 One click to <a href="https://chat.z.ai">GLM-4.5</a>.
 </p>
-  
+
+This repository contains the base model presented in the paper [GLM-4.5: Agentic, Reasoning, and Coding (ARC) Foundation Models](https://huggingface.co/papers/2508.06471).
+
 ## Model Introduction
 
 The **GLM-4.5** series models are foundation models designed for intelligent agents. GLM-4.5 has **355** billion total parameters with **32** billion active parameters, while GLM-4.5-Air adopts a more compact design with **106** billion total parameters and **12** billion active parameters. GLM-4.5 models unify reasoning, coding, and intelligent agent capabilities to meet the complex demands of intelligent agent applications.
@@ -30,7 +32,7 @@ Both GLM-4.5 and GLM-4.5-Air are hybrid reasoning models that provide two modes:
 
 We have open-sourced the base models, hybrid reasoning models, and FP8 versions of the hybrid reasoning models for both GLM-4.5 and GLM-4.5-Air. They are released under the MIT open-source license and can be used commercially and for secondary development.
 
-As demonstrated in our comprehensive evaluation across 12 industry-standard benchmarks, GLM-4.5 achieves exceptional performance with a score of **63.2**, in the **3rd** place among all the proprietary and open-source  models. Notably, GLM-4.5-Air delivers competitive results at **59.8** while maintaining superior efficiency.
+As demonstrated in our comprehensive evaluation across 12 industry-standard benchmarks, GLM-4.5 achieves exceptional performance with a score of **63.2**, in the **3rd** place among all the proprietary and open-source models. Notably, GLM-4.5-Air delivers competitive results at **59.8** while maintaining superior efficiency.
 
 ![bench](https://raw.githubusercontent.com/zai-org/GLM-4.5/refs/heads/main/resources/bench.png)
 
@@ -39,8 +41,155 @@ our [technical blog](https://z.ai/blog/glm-4.5). The technical report will be re
 
 The model code, tool parser and reasoning parser can be found in the implementation of [transformers](https://github.com/huggingface/transformers/tree/main/src/transformers/models/glm4_moe), [vLLM](https://github.com/vllm-project/vllm/blob/main/vllm/model_executor/models/glm4_moe_mtp.py) and [SGLang](https://github.com/sgl-project/sglang/blob/main/python/sglang/srt/models/glm4_moe.py).
 
+## System Requirements
+
+### Inference
+
+We provide minimum and recommended configurations for "full-featured" model inference. The data in the table below is
+based on the following conditions:
+
+1.  All models use MTP layers and specify
+    `--speculative-num-steps 3 --speculative-eagle-topk 1 --speculative-num-draft-tokens 4` to ensure competitive
+    inference speed.
+2.  The `cpu-offload` parameter is not used.
+3.  Inference batch size does not exceed `8`.
+4.  All are executed on devices that natively support FP8 inference, ensuring both weights and cache are in FP8 format.
+5.  Server memory must exceed `1T` to ensure normal model loading and operation.
+
+The models can run under the configurations in the table below:
+
+| Model | Precision | GPU Type and Count | Test Framework |
+|---|---|---|---|
+| GLM-4.5 | BF16 | H100 x 16 / H200 x 8 | sglang |
+| GLM-4.5 | FP8 | H100 x 8 / H200 x 4 | sglang |
+| GLM-4.5-Air | BF16 | H100 x 4 / H200 x 2 | sglang |
+| GLM-4.5-Air | FP8 | H100 x 2 / H200 x 1 | sglang |
+
+Under the configurations in the table below, the models can utilize their full 128K context length:
+
+| Model | Precision | GPU Type and Count | Test Framework |
+|---|---|---|---|
+| GLM-4.5 | BF16 | H100 x 32 / H200 x 16 | sglang |
+| GLM-4.5 | FP8 | H100 x 16 / H200 x 8 | sglang |
+| GLM-4.5-Air | BF16 | H100 x 8 / H200 x 4 | sglang |
+| GLM-4.5-Air | FP8 | H100 x 4 / H200 x 2 | sglang |
+
+### Fine-tuning
+
+The code can run under the configurations in the table below
+using [Llama Factory](https://github.com/hiyouga/LLaMA-Factory):
+
+| Model | GPU Type and Count | Strategy | Batch Size (per GPU) |
+|---|---|---|---|
+| GLM-4.5 | H100 x 16 | Lora | 1 |
+| GLM-4.5-Air | H100 x 4 | Lora | 1 |
+
+The code can run under the configurations in the table below using [Swift](https://github.com/modelscope/ms-swift):
+
+| Model | GPU Type and Count | Strategy | Batch Size (per GPU) |
+|---|---|---|---|
+| GLM-4.5 | H20 (96GiB) x 16 | Lora | 1 |
+| GLM-4.5-Air | H20 (96GiB) x 4 | Lora | 1 |
+| GLM-4.5 | H20 (96GiB) x 128 | SFT | 1 |
+| GLM-4.5-Air | H20 (96GiB) x 32 | SFT | 1 |
+| GLM-4.5 | H20 (96GiB) x 128 | RL | 1 |
+| GLM-4.5-Air | H20 (96GiB) x 32 | RL | 1 |
+
 ## Quick Start
 
 **Note**: This is a base model, not for chat.
 
-Please refer to our [github page](https://github.com/zai-org/GLM-4.5) for more details.
+Please install the required packages according to `requirements.txt`.
+
+```bash
+pip install -r requirements.txt
+```
+
+### transformers
+
+Here's a basic example to use the model with the `transformers` library for text generation:
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
+
+model_id = "zai-org/GLM-4.5-Air-Base"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+# Ensure to load with the correct dtype, e.g., bfloat16 as specified in config.json
+model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.bfloat16)
+
+prompt = "Hello, I'm a language model,"
+inputs = tokenizer(prompt, return_tensors="pt")
+
+# Generate
+generate_ids = model.generate(inputs.input_ids, max_new_tokens=100)
+print(tokenizer.batch_decode(generate_ids, skip_special_tokens=True)[0])
+```
+
+The GitHub repository provides more detailed examples, including `trans_infer_cli.py`.
+
+### vLLM
+
+Both BF16 and FP8 can be started with the following code:
+
+```bash
+vllm serve zai-org/GLM-4.5-Air \
+    --tensor-parallel-size 8 \
+    --tool-call-parser glm45 \
+    --reasoning-parser glm45 \
+    --enable-auto-tool-choice \
+    --served-model-name glm-4.5-air
+```
+
+If you're using 8x H100 GPUs and encounter insufficient memory when running the GLM-4.5 model, you'll need
+`--cpu-offload-gb 16` (only applicable to vLLM).
+
+If you encounter `flash infer` issues, use `VLLM_ATTENTION_BACKEND=XFORMERS` as a temporary replacement. You can also
+specify `TORCH_CUDA_ARCH_LIST='9.0+PTX'` to use `flash infer` (different GPUs have different TORCH_CUDA_ARCH_LIST
+values, please check accordingly).
+
+### SGLang
+
++ BF16
+
+```bash
+python3 -m sglang.launch_server \
+  --model-path zai-org/GLM-4.5-Air \
+  --tp-size 8 \
+  --tool-call-parser glm45  \
+  --reasoning-parser glm45 \
+  --speculative-algorithm EAGLE \
+  --speculative-num-steps 3 \
+  --speculative-eagle-topk 1 \
+  --speculative-num-draft-tokens 4 \
+  --mem-fraction-static 0.7 \
+  --served-model-name glm-4.5-air \
+  --host 0.0.0.0 \
+  --port 8000
+```
+
++ FP8
+
+```bash
+python3 -m sglang.launch_server \
+  --model-path zai-org/GLM-4.5-Air-FP8 \
+  --tp-size 4 \
+  --tool-call-parser glm45  \
+  --reasoning-parser glm45  \
+  --speculative-algorithm EAGLE \
+  --speculative-num-steps 3  \
+  --speculative-eagle-topk 1  \
+  --speculative-num-draft-tokens 4 \
+  --mem-fraction-static 0.7 \
+  --disable-shared-experts-fusion \
+  --served-model-name glm-4.5-air-fp8 \
+  --host 0.0.0.0 \
+  --port 8000
+```
+
+### Request Parameter Instructions
+
++ When using `vLLM` and `SGLang`, thinking mode is enabled by default when sending requests. If you want to disable the
+  thinking switch, you need to add the `extra_body={"chat_template_kwargs": {"enable_thinking": False}}` parameter.
++ Both support tool calling. Please use OpenAI-style tool description format for calls.
++ For specific code, please refer to `api_request.py` in the `inference` folder.