FST ITN-ZH与Python集成：API调用与二次开发指南

1. 引言

1.1 场景背景

在自然语言处理（NLP）的实际工程落地中，中文逆文本标准化（Inverse Text Normalization, ITN）是一项关键的预处理任务。它负责将口语化、非结构化的中文数字表达转换为标准格式，例如将“二零零八年八月八日”转为“2008年08月08日”，或将“一百二十三”转为“123”。这一过程广泛应用于语音识别后处理、智能客服、数据清洗和信息抽取等场景。

FST ITN-ZH 是一个基于有限状态转导器（Finite State Transducer, FST）实现的高效中文ITN工具，具备高精度、低延迟的特点。其WebUI版本由开发者“科哥”进行二次开发，提供了直观的图形界面，极大降低了使用门槛。然而，在实际项目中，仅依赖WebUI难以满足自动化、批量化和系统集成的需求。

因此，如何将 FST ITN-ZH 的核心能力通过 API 接口暴露，并实现与 Python 应用系统的深度集成，成为提升其工程价值的关键。本文将围绕API 调用机制解析和二次开发实践路径两大方向，提供一套完整的技术方案。

1.2 核心问题

尽管 WebUI 提供了便捷的操作方式，但在生产环境中仍面临以下挑战：

无法自动化：人工操作无法嵌入CI/CD流程或定时任务。
性能瓶颈：批量处理需手动上传文件，效率低下。
系统孤岛：难以与其他服务（如ASR、NLU）形成数据闭环。

本文旨在解决上述痛点，指导开发者如何突破WebUI限制，实现 FST ITN-ZH 的程序化调用与定制化扩展。

1.3 方案概述

本文提出的解决方案包含两个层次：

API 层集成：分析 WebUI 后端服务接口，利用 HTTP 请求实现远程调用；
代码层二次开发：深入项目源码结构，封装核心 ITN 模块为可导入的 Python 包，支持本地调用与功能增强。

该方案兼顾灵活性与稳定性，适用于从快速验证到生产部署的全阶段需求。

2. API 调用实现详解

2.1 服务启动与端点确认

根据提供的运行指令：

/bin/bash /root/run.sh

可知该应用通过run.sh脚本启动 Flask 或 Gradio 类型的服务。默认监听端口为7860，访问地址为http://<服务器IP>:7860。

首先确保服务已正常运行，并可通过浏览器访问 WebUI 界面。随后使用开发者工具（F12）捕获网络请求，定位核心转换接口。

经分析，文本转换功能对应的 API 端点如下：

URL:http://<服务器IP>:7860/api/predict/
Method:POST
Content-Type:application/json

2.2 请求结构解析

发送 JSON 格式请求体，示例如下：

{ "data": [ "二零零八年八月八日早上八点半", true, true, false ] }

其中data数组含义如下：

第一项：待转换的原始文本；
第二项：是否启用“转换独立数字”；
第三项：是否启用“转换单个数字 (0-9)”；
第四项：是否启用“完全转换'万'”。

这些参数与 WebUI 中“高级设置”一一对应。

2.3 Python 客户端实现

以下为完整的 Python 封装类，支持同步调用与异常处理：

import requests import json from typing import Dict, Any, Optional class FSTITNZHClient: """ FST ITN-ZH WebUI API 客户端 """ def __init__(self, base_url: str = "http://localhost:7860"): self.base_url = base_url.rstrip("/") self.endpoint = f"{self.base_url}/api/predict/" self.session = requests.Session() def normalize( self, text: str, convert_standalone_digits: bool = True, convert_single_digits: bool = True, fully_convert_wan: bool = False ) -> Optional[str]: """ 执行中文逆文本标准化 Args: text: 输入文本 convert_standalone_digits: 是否转换独立数字（如“幸运一百”→“幸运100”） convert_single_digits: 是否转换单个数字（如“零和九”→“0和9”） fully_convert_wan: 是否完全展开“万”单位（如“六百万”→“6000000”） Returns: 标准化后的文本，失败时返回 None """ payload = { "data": [ text, convert_standalone_digits, convert_single_digits, fully_convert_wan ] } try: response = self.session.post( self.endpoint, data=json.dumps(payload), headers={"Content-Type": "application/json"}, timeout=10 ) response.raise_for_status() result = response.json() if "data" in result and len(result["data"]) > 0: return result["data"][0] else: print(f"Unexpected response format: {result}") return None except requests.exceptions.RequestException as e: print(f"Request failed: {e}") return None def batch_normalize( self, texts: list, **kwargs ) -> list: """ 批量处理文本 Args: texts: 文本列表 **kwargs: 传递给 normalize 的参数 Returns: 结果列表，顺序与输入一致 """ results = [] for text in texts: result = self.normalize(text, **kwargs) results.append(result or "") return results

2.4 使用示例

# 初始化客户端 client = FSTITNZHClient("http://192.168.1.100:7860") # 单条转换 output = client.normalize("二零一九年九月十二日的晚上八点半", fully_convert_wan=True) print(output) # 输出: 2019年09月12日的晚上8:30 # 批量处理 texts = [ "一百二十三元", "早上七点一刻", "京A一二三四五" ] results = client.batch_normalize(texts) for inp, outp in zip(texts, results): print(f"{inp} → {outp}")

3. 二次开发与模块化封装

3.1 项目结构分析

典型 WebUI 项目的目录结构如下：

/root/ ├── app.py # 主应用入口 ├── run.sh # 启动脚本 ├── itn_core/ # 核心 ITN 模块 │ ├── __init__.py │ ├── fst_engine.py # FST 引擎封装 │ └── rules/ # 转换规则定义 └── utils/ └── config.py # 参数配置

关键在于提取itn_core模块，使其脱离 WebUI 框架独立运行。

3.2 核心引擎抽象

创建itn_module.py文件，封装可复用的 ITN 处理器：

# itn_module.py from typing import Dict, Any import importlib.util import sys import os class ITNProcessor: """ 中文逆文本标准化处理器（独立模块） """ def __init__(self, rules_dir: str = "/root/itn_core/rules"): self.rules_dir = rules_dir self._engine = None self._load_engine() def _load_engine(self): """动态加载 FST 引擎""" engine_path = "/root/itn_core/fst_engine.py" if not os.path.exists(engine_path): raise FileNotFoundError(f"FST engine not found at {engine_path}") spec = importlib.util.spec_from_file_location("fst_engine", engine_path) engine = importlib.util.module_from_spec(spec) sys.modules["fst_engine"] = engine spec.loader.exec_module(engine) self._engine = engine.FSTEngine(rules_dir=self.rules_dir) def process(self, text: str, options: Dict[str, Any] = None) -> str: """ 执行标准化处理 Args: text: 输入文本 options: 配置选项 Returns: 标准化结果 """ if options is None: options = {} # 默认配置 default_opts = { "convert_standalone_digits": True, "convert_single_digits": True, "fully_convert_wan": False } merged_opts = {**default_opts, **options} return self._engine.transform(text, **merged_opts)

3.3 本地调用示例

# local_usage.py from itn_module import ITNProcessor processor = ITNProcessor() text = "这件事发生在二零一九年九月十二日的晚上，大概八点半左右，涉及金额为一万二千元。" result = processor.process( text, options={"fully_convert_wan": True} ) print(result) # 输出: 这件事发生在2019年09月12日的晚上，大概8:30左右，涉及金额为12000元。