Simple CSC
A training-free approach to Chinese Spelling Correction using LLMs as pure language models with beam search and distortion modeling.
Prerequisites
This skill is a usage guide for the simple-csc repository. Before using any commands or APIs described here, clone the repository and work from its root:
git clone https://github.com/Jacob-Zhou/simple-csc.git
cd simple-csc
All paths referenced below (e.g., configs/, scripts/, data/, eval/, datasets/) are relative to this repository root. The repository contains the actual code, config files, data dictionaries, and scripts — this skill provides the knowledge of how to use them.
Quick Reference
Environment Setup
# Standard setup (creates venv, installs deps)
bash scripts/set_environment.sh
# For Qwen3 models
bash scripts/set_environment_qwen3.sh
# Recommended: install flash-attn for better performance and lower VRAM
pip install flash-attn --no-build-isolation
Qwen2/Qwen2.5 warning: Without flash-attn, set torch_dtype=torch.bfloat16 to avoid unexpected behavior.
Python API
import torch
from lmcsc import LMCorrector
corrector = LMCorrector(
model="Qwen/Qwen2.5-7B",
prompted_model="Qwen/Qwen2.5-7B", # use same model to save VRAM
config_path="configs/c2ec_config.yaml", # or "configs/default_config.yaml" for substitution-only
torch_dtype=torch.bfloat16, # recommended for Qwen2/2.5 without flash-attn
)
# Single sentence
outputs = corrector("完善农产品上行发展机智。")
# => [('完善农产品上行发展机制。',)]
# Batch
outputs = corrector(["句子一", "句子二"])
# With context (same length lists)
outputs = corrector(["未挨前兆"], contexts=["患者提问："])
# Streaming (batch_size=1 only)
for output in corrector("完善农产品上行发展机智。", stream=True):
print(output[0][0], end="\r", flush=True)
Config Selection
| Config | Use Case |
|---|
configs/default_config.yaml | Substitution-only CSC (v1.0.0 style) |
configs/c2ec_config.yaml | Full C2EC with insert/delete support (v2.0.0) |
configs/demo_config.yaml | Same as c2ec_config, used by demo app |
Key difference: c2ec_config.yaml includes ROR (reorder), MIS (missing char), RED (redundant char) distortion types and length_immutable_chars data file.
Recommended Models
- v2.0.0 (C2EC):
Qwen/Qwen2.5-7B or Qwen/Qwen2.5-14B — best performance/speed balance
- v1.0.0 (CSC):
baichuan-inc/Baichuan2-13B-Base — best performance
- Always prefer
Base models over Instruct/Chat variants
RESTful API Server
python api_server.py \
--model "Qwen/Qwen2.5-7B" \
--prompted_model "Qwen/Qwen2.5-7B" \
--config_path "configs/c2ec_config.yaml" \
--host 127.0.0.1 --port 8000 --workers 1 --bf16
Endpoints:
GET /health — health checkPOST /correction — {"input": "...", "stream": false, "contexts": null}
# Non-streaming
curl -X POST 'http://127.0.0.1:8000/correction' \
-H 'Content-Type: application/json' \
-d '{"input": "完善农产品上行发展机智。"}'
# With context
curl -X POST 'http://127.0.0.1:8000/correction' \
-H 'Content-Type: application/json' \
-d '{"input": "未挨前兆", "contexts": "患者提问："}'
For detailed API parameters, config options, evaluation pipeline, and dataset formats, see references/details.md.
Key Architecture Concepts
The approach works by:
- Using an LLM as a pure language model (left-to-right generation)
- At each step, computing a distortion probability for each candidate token based on how "similar" it is to the observed (possibly erroneous) character
- Combining LM probability with distortion probability via beam search
- Distortion types encode the relationship between observed and candidate characters (identical, same pinyin, similar shape, etc.)
The prompted_model parameter adds a second probability source: a prompt-based LLM that scores candidates given the full input sentence as context, improving correction quality.
