README.md

---
license: apache-2.0
language:
- zh
- en
base_model:
- Qwen/Qwen3-8B
---

# TableGPT-R1

## Model details

We developed and released TableGPT-R1, a specialized large language model optimized for complex tabular reasoning and data analysis. Unlike traditional models that rely solely on Supervised Fine-Tuning (SFT), TableGPT-R1 is trained using a systematic Reinforcement Learning (RL) framework. It is designed to bridge the gap between natural language understanding and professional data science requirements, such as multi-step logic, robust code execution, and autonomous environment interaction.

**Model Developers**  

Zhejiang University & Institute of Computing Innovation, Zhejiang University

**Key Technical Breakthroughs**

* **Autonomous Agentic Reasoning**: The model is trained to "think" before acting. It generates a visible reasoning chain within `<think>` tags, plans Python-based data manipulations, and refines its strategy based on environment feedback (Code Interpreter).
* **Unified Reward System**: We introduced a hybrid reward mechanism that combines rule-based verification (for deterministic SQL/Code tasks) with a **Criteria-Injected Reward Model** (for open-ended analytical questions), ensuring both accuracy and interpretability.
* **GRPO++ Framework**: Utilizing an enhanced version of Group Relative Policy Optimization, the model optimizes its decision-making process across diverse table structures while maintaining its general-purpose reasoning capabilities.
* **Cold-Start Data Engineering**: Bootstrapped with high-quality, long-chain reasoning trajectories, allowing the model to handle extreme table heterogeneity and complex multi-table joins.

**Input**

TableGPT-R1 accepts both natural language instructions and tabular data. It uniquely supports **table-path inputs**, enabling the model to autonomously load and retrieve information from files using a built-in code interpreter.

**Output** 

TableGPT-R1 supports two output behaviors depending on the task:

For tasks requiring logical deduction, metadata explanation, or semantic understanding without external execution.
* **Format**: `<think> ... </think> [Answer]`
* **Behavior**: The model performs internal "Chain-of-Thought" to verify its logic before presenting the final result.

For data-intensive tasks requiring precise calculation, visualization, or large-scale data processing.
* **Format**: 
  1.  **Plan**: `<think> ... </think>` (Analyze the goal and plan the code)
  2.  **Act**: `<tool_call> ... </tool_call>` (Generate Python/SQL code)
  3.  **Observe**: `<observation> ... </observation>` (Receive environment feedback)
  4.  **Finalize**: `<answer> ... </answer>` (Summarize results)

* **Behavior**: The model operates as an autonomous agent, reacting to execution errors or intermediate data results to ensure accuracy.

Additionally, to enforce model thinking, the default chat template automatically includes `<think>`. Therefore, it is normal for the model's output to contain only `</think>` without an explicit opening `<think>` tag.

**Language**  

Our model places a strong emphasis on Chinese corpora, and currently, queries in other languages may have limited support.

**Model Architecture** 

TableGPT-R1 is built upon the **Qwen3-8B** transformer architecture, significantly enhanced for long-context tabular understanding and agentic workflows.

* **Base Backbone**: Qwen3-8B (Dense Transformer).
* **Context Window**: 128K tokens, optimized for processing large-scale table schemas, extensive metadata, and long execution logs.
* **Specialized Tokenizer**: Enhanced to handle structural delimiters, whitespace in tables, and code-specific syntax (Python/SQL) more efficiently.
* **Agentic Loop Integration**: The architecture is designed to support a seamless **"Think-Act-Observe"** cycle. It treats the environment's feedback (Code Interpreter output) as a first-class sequence input, allowing for real-time error correction and iterative reasoning.
* **Instruction Following**: Optimized via RL to strictly adhere to formatting constraints, distinguishing between internal thought process and external tool calls.

**Status**  

This model is static, trained on an offline dataset. Future versions may be released to enhance its performance on specialized tasks.

**QuickStart**

This code snippet demonstrates how to build a prompt with table information, and shows how to load the tokenizer, load the model, and generate content.

> Note that you need `transformers>=4.51.0` to use `TableGPT-R1`:
> ```sh
> pip install transformers>=4.51.0
> ```


```python
from transformers import AutoModelForCausalLM, AutoTokenizer

# Using pandas to read some structured data
import pandas as pd
from io import StringIO

# single table
EXAMPLE_CSV_CONTENT = """
"Loss","Date","Score","Opponent","Record","Attendance"
"Hampton (14–12)","September 25","8–7","Padres","67–84","31,193"
"Speier (5–3)","September 26","3–1","Padres","67–85","30,711"
"Elarton (4–9)","September 22","3–1","@ Expos","65–83","9,707"
"Lundquist (0–1)","September 24","15–11","Padres","67–83","30,774"
"Hampton (13–11)","September 6","9–5","Dodgers","61–78","31,407"
"""

csv_file = StringIO(EXAMPLE_CSV_CONTENT)
df = pd.read_csv(csv_file)

model_name = "tablegpt/TableGPT-R1"

model = AutoModelForCausalLM.from_pretrained(
    model_name, torch_dtype="auto", device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

example_prompt_template = """Given access to several pandas dataframes, write the Python code to answer the user's question.

/*
"{var_name}.head(5).to_string(index=False)" as follows:
{df_info}
*/

Question: {user_question}
"""
question = "哪些比赛的战绩达到了40胜40负？"

prompt = example_prompt_template.format(
    var_name="df",
    df_info=df.head(5).to_string(index=False),
    user_question=question,
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"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=8192)
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]
```

**Deployment**

For deployment, you can use `sglang>=0.5.2` or `vllm>=0.8.5` or to create an OpenAI-compatible API endpoint:
- SGLang:
    ```shell
    python -m sglang.launch_server --model-path tablegpt/TableGPT-R1 --served-model-name TableGPT-R1 --reasoning-parser qwen3
    ```
- vLLM:
    ```shell
    vllm serve tablegpt/TableGPT-R1 --served-model-name TableGPT-R1 --enable-reasoning --reasoning-parser deepseek_r1
    ```

Then you can access the Chat API by:

```bash
curl http://localhost:xxx/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
    "model": "TableGPT-R1",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "xxxxx?"}
    ]
    }'

```

**License**  

TableGPT-R1 is under apache-2.0 license.

**Research Paper**  

TableGPT-R1 is introduced and validated in the paper "[TableGPT-R1: Advancing Tabular Reasoning Through Reinforcement Learning](https://arxiv.org/xxxx)" available on arXiv.

**Where to send questions or comments about the model**  

Inquiries and feedback are welcome at [j.zhao@zju.edu.cn](mailto:j.zhao@zju.edu.cn).

## Evaluation Results

 Performance comparison grouped by model scale. Left Group: Models with comparable
parameters to TableGPT-R1. Right Group: Significantly larger models and proprietary closed-source
models. Bold indicates the best result within each group. Gray background highlights TableGPT-R1. Abbreviations: Q3: Qwen3; QwQ: QwQ-32B; DS-V3: DeepSeek-V3; Q-Plus: Qwen-Plus;
T-LLM: TableLLM; Llama: Llama-3.1-8B; TGPT2: TableGPT2-7B; TGPT-R1: TableGPT-R1-8B;
FC: Fact Checking; NR: Numerical Reasoning; SC: Structure Comprehending; DA: Data Analysis;
CG: Chart Generation.

| Benchmark | Task | Met. | Q3-8B | T-LLM | Llama | TGPT2 | **TGPT-R1 (8B)** | Q3-14B | Q3-32B | Q3-70B | QwQ | GPT-4o | DS-V3 | Q-Plus |
| :--- | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| **Internal Bench** | Table Info | Acc | 69.20 | 0.97 | 37.26 | - | **82.00** | 66.10 | 72.58 | 51.10 | 69.68 | 67.26 | 66.00 | **76.90** |
| | Table Path | Acc | 73.90 | 0.65 | 31.77 | - | **85.00** | 74.70 | 78.55 | 60.50 | 75.00 | - | 72.90 | **81.50** |
| **NL2SQL** | Spider | EX | 86.07 | 65.30 | 73.59 | 74.38 | **86.73** | 87.61 | 87.80 | 61.71 | 85.33 | 87.98 | 88.54 | **89.19** |
| | BIRD | EX | 61.67 | 30.64 | 40.03 | 49.28 | **63.04** | 61.80 | 63.04 | 53.91 | 54.30 | 65.25 | 65.65 | **68.32** |
| **Holistic Table** | TableBench DP | Rge | 42.10 | 3.63 | 18.04 | 42.10 | **47.58** | 47.41 | **52.18** | 48.61 | 49.33 | 40.91 | 36.56 | 31.01 |
| **Evaluation** | PoT | Rge | 28.01 | 0.00 | 6.73 | **39.80** | 34.86 | 36.61 | 37.78 | 27.72 | 40.03 | **51.96** | 33.05 | 41.79 |
| | SCoT | Rge | 41.86 | 1.99 | 21.94 | 40.70 | **48.68** | 47.36 | 47.47 | 45.68 | 44.84 | 41.43 | **50.11** | 44.06 |
| | TCoT | Rge | 41.71 | 3.18 | 15.26 | 46.19 | **48.16** | 46.07 | 51.74 | 47.63 | 48.83 | 45.71 | **54.28** | 52.07 |
| **RealHitBench** | FC | EM | 58.83 | 33.44 | 30.32 | 43.06 | **62.85** | 62.36 | **65.00** | 60.23 | 28.95 | 55.22 | **65.08** | 56.53 |
| | NR | EM | 39.43 | 13.51 | 18.25 | 31.75 | **44.91** | 45.62 | 47.45 | 42.82 | 42.61 | 48.66 | **53.89** | 49.88 |

## Citation

If you find our work helpful, please cite us by

```bibtex

```