README.md

---
license: mit
language:
  - zh
  - en
tags:
  - punctuation
  - punctuation-restoration
  - chinese
  - ax650
  - axmodel
  - npu
  - sherpa-onnx
  - ct-transformer
library_name: sherpa-punct-sdk
pipeline_tag: text-generation
---

# Sherpa Punctuation CT Transformer for AX650 NPU

Character-level punctuation restoration model for Chinese text, compiled as AXMODEL for the AX650 NPU.
Based on [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) punct CT Transformer architecture.

## Model Description

- **Architecture**: CT Transformer (Connectionist Temporal Classification)
- **Input**: Raw Chinese text (may include English words)
- **Output**: Punctuation-annotated text with `，` `。` `？` `、`
- **Vocab Size**: 272,727 tokens
- **Max Input Length**: 64 tokens per window (long text uses sliding window with 4-token overlap)
- **Output Classes**: 6 — `<unk>`, `_`, `，`, `。`, `？`, `、`

## Quick Start

```bash
git clone https://huggingface.co/AXERA-TECH/punc-ct-transformer
cd punc-ct-transformer
```

### Python

```bash
# Install dependencies
pip install numpy
git clone https://github.com/AXERA-TECH/pyaxengine.git
cd pyaxengine && pip install . && cd ..

# Run
cd python && python3 example.py
```

### C++

```bash
cd cpp && ./demo -m ../model.axmodel -t ../tokens.json
```

### Python SDK API

```python
import sys
sys.path.insert(0, "python")
from sherpa_punct_sdk import PunctuationPipeline

pipeline = PunctuationPipeline("model.axmodel", "tokens.json")
result = pipeline("你好吗how are you我很好谢谢")
print(result)  # 你好吗？how are you我很好，谢谢。
```

## Example Output

| Input | Output |
|-------|--------|
| 你好吗how are you我很好谢谢 | 你好吗？how are you我很好，谢谢。 |
| 今天天气真不错我们出去走走吧 | 今天天气真不错，我们出去走走吧， |
| 这个方案有三个优点第一成本低第二效率高第三维护简单 | 这个方案有三个优点，第一，成本低，第二效率高。第三，维护简单， |

## File Structure

```
.
├── model.axmodel              # Compiled AXMODEL for AX650 NPU
├── tokens.json                # Vocabulary (272,727 tokens)
├── python/
│   ├── example.py             # Demo script (run from python/ dir)
│   ├── requirements.txt       # Python dependencies
│   └── sherpa_punct_sdk/      # Python inference SDK
│       ├── pipeline.py        # End-to-end text → punctuation pipeline
│       ├── inference.py       # AX Engine inference wrapper
│       ├── preprocess.py      # Character-level tokenizer
│       └── postprocess.py     # Logits → punctuation decoder
└── cpp/
    ├── demo                   # C++ demo (aarch64, run from cpp/ dir)
    └── libsherpa_punct.a      # Static library
```

## Requirements

- **Hardware**: AX650 NPU (or compatible chip)
- **Python**: 3.8+
- **Python deps**: `numpy`, `pyaxengine`
- **C++**: aarch64 Linux with `libax_engine.so`

## License

MIT