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:

bash

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#

bash

# 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#

python

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#

ConfigUse Caseconfigs/default_config.yamlSubstitution-only CSC (v1.0.0 style)configs/c2ec_config.yamlFull C2EC with insert/delete support (v2.0.0)configs/demo_config.yamlSame 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#

bash

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 check
• POST /correction — {"input": "...", "stream": false, "contexts": null}

bash

# 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:

1. Using an LLM as a pure language model (left-to-right generation)
2. At each step, computing a distortion probability for each candidate token based on how "similar" it is to the observed (possibly erroneous) character
3. Combining LM probability with distortion probability via beam search
4. 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.