FST ITN-ZH WebUI二次开发：添加新功能模块

FST ITN-ZH WebUI二次开发：添加新功能模块

1. 引言

1.1 项目背景与业务需求

随着中文逆文本标准化（Inverse Text Normalization, ITN）在语音识别、自然语言处理和智能客服等场景中的广泛应用，对系统可扩展性和定制化能力的需求日益增长。FST ITN-ZH 是一个基于有限状态转换器（Finite State Transducer, FST）实现的高效中文ITN工具，其原始版本已支持日期、时间、数字、货币等多种常见格式的标准化转换。

然而，在实际落地过程中，不同行业客户常有特定领域的表达需要处理，例如化学式读法（“H二O” → “H₂O”）、编程术语口语化输入（“int三十二” → “int32”）或医学计量单位（“五毫克每毫升” → “5mg/mL”）。这些需求超出了默认功能范围，亟需通过WebUI的二次开发来拓展系统能力。

本文将围绕如何在现有FST ITN-ZH WebUI基础上进行模块化扩展，详细介绍新增自定义功能模块的技术路径、代码结构设计及工程实践要点，为开发者提供一套可复用的二次开发方案。

1.2 方案概述与技术价值

本次二次开发的核心目标是：在不破坏原有架构的前提下，以插件化方式集成新功能模块，并保持界面一致性与用户体验流畅性。我们采用Gradio作为前端框架，利用其组件化特性实现标签页动态注册机制。

该方案具备以下技术优势：

• 低侵入性：无需修改主流程逻辑，仅通过配置即可启用新模块
• 高可维护性：功能模块独立封装，便于团队协作与后期迭代
• 易部署性：兼容原生启动脚本，无需额外依赖管理
• 用户友好性：统一交互风格，降低学习成本

最终成果不仅满足了特定场景下的业务需求，也为后续持续集成更多领域规则奠定了坚实基础。

2. 系统架构与扩展机制解析

2.1 原有系统结构分析

FST ITN-ZH WebUI基于Python + Gradio构建，整体架构分为三层：

1. 表现层（UI Layer）：由Gradio Blocks构建的可视化界面，包含「📝 文本转换」与「📦 批量转换」两个Tab
2. 逻辑层（Logic Layer）：调用底层FST模型执行具体转换任务，封装为独立函数接口
3. 数据层（Data Layer）：预编译的FST规则文件（.fst），定义各类表达式的映射关系

当前系统的入口文件为app.py，其中通过gr.Tab()注册功能页面，核心结构如下：

with gr.Blocks() as demo: with gr.Tab("📝 文本转换"): # 输入输出组件与按钮绑定 pass with gr.Tab("📦 批量转换"): # 文件上传与处理逻辑 pass

这种结构清晰但缺乏灵活性，新增功能需直接编辑主文件，不利于模块解耦。

2.2 模块化扩展设计思路

为了支持灵活的功能扩展，我们引入“模块注册中心”模式，将各功能模块抽象为独立单元，通过统一接口接入主应用。关键改动包括：

• 创建modules/目录存放所有功能模块
• 定义标准模块接口：必须暴露title和build_interface()方法
• 在主程序中动态扫描并加载模块

此设计实现了关注点分离，使得每个功能模块可以独立开发、测试和部署。

3. 新增功能模块的实现步骤

3.1 技术选型与环境准备

开发环境要求

确保本地或服务器环境满足以下条件：

# Python 版本 python --version # 推荐 3.8+ # 必需依赖库 pip install gradio==3.50.2 openfst-python

项目目录结构调整

在项目根目录下创建模块化结构：

fst-itn-zh/ ├── app.py # 主程序入口 ├── run.sh # 启动脚本 ├── modules/ # 功能模块目录 │ ├── __init__.py │ ├── text_normalization.py # 原有文本转换模块 │ ├── batch_processing.py # 批量处理模块 │ └── custom_chemistry.py # 新增化学式模块 └── models/ └── itn_zh.fst

3.2 编写自定义功能模块

以“化学式标准化”为例，新建modules/custom_chemistry.py文件：

import gradio as gr import re def normalize_chemical_formula(text): """ 将口语化的化学式转换为标准格式 示例: H二O -> H₂O, CO二 -> CO₂ """ element_map = { '零': '₀', '一': '₁', '二': '₂', '三': '₃', '四': '₄', '五': '₅', '六': '₆', '七': '₇', '八': '₈', '九': '₉' } def replace_subscript(match): chars = match.group(1) return ''.join(element_map.get(c, c) for c in chars) # 匹配括号内的数字或紧跟元素后的数字 pattern = r'([一二三四五六七八九零]+)(?=\)|$|[A-Z])' result = re.sub(pattern, replace_subscript, text) return result title = "🧪 化学式转换" def build_interface(): with gr.Tab(title): gr.Markdown("### 将中文数字表示的化学式转换为标准下标格式") with gr.Row(): with gr.Column(): input_text = gr.Textbox( label="输入化学式", placeholder="例如：H二O、CO二、NaCl三" ) convert_btn = gr.Button("开始转换") with gr.Column(): output_text = gr.Textbox(label="输出结果", interactive=False) # 绑定事件 convert_btn.click( fn=normalize_chemical_formula, inputs=input_text, outputs=output_text ) # 快速示例 gr.Examples( examples=[ ["H二O"], ["CO二"], ["CH四"], ["NaCl三"] ], inputs=input_text )

3.3 主程序集成与动态加载

修改app.py实现模块自动注册：

import gradio as gr import importlib import os from pathlib import Path # 动态加载 modules 目录下的所有模块 def load_modules(): modules_dir = Path("modules") interfaces = [] for file in modules_dir.glob("*.py"): if file.name.startswith("__"): continue module_name = f"modules.{file.stem}" spec = importlib.util.spec_from_file_location(module_name, file) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) if hasattr(module, "build_interface"): interfaces.append((module.title, module.build_interface)) return interfaces # 构建主界面 with gr.Blocks(title="中文逆文本标准化 (ITN)") as demo: gr.Markdown("# 中文逆文本标准化 (ITN)") gr.Markdown("*webUI二次开发 by 科哥 | 微信：312088415*") # 动态注册所有模块 for title, builder in load_modules(): builder() # 启动服务 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860)

3.4 验证与调试

启动服务前确认权限设置：

chmod +x /root/run.sh

运行启动脚本：

/bin/bash /root/run.sh

访问http://<服务器IP>:7860，应能看到新增的「🧪 化学式转换」标签页，点击后可正常输入并获得预期输出。

4. 工程优化与最佳实践

4.1 错误处理与健壮性增强

在生产环境中，必须考虑异常输入和边界情况。改进normalize_chemical_formula函数：

def normalize_chemical_formula(text): if not text or not isinstance(text, str): return "" try: element_map = { ... } # 同上 def replace_subscript(match): chars = match.group(1) return ''.join(element_map.get(c, c) for c in chars) pattern = r'([一二三四五六七八九零]+)(?=\)|$|[A-Z])' result = re.sub(pattern, replace_subscript, text) return result.strip() except Exception as e: return f"[错误] 处理失败: {str(e)}"

同时在Gradio中添加错误提示：

output_text = gr.Textbox(label="输出结果", interactive=False, show_label=True)

4.2 配置化管理建议

建议将模块启用状态交由配置文件控制，避免每次都需要物理删除文件。创建config.yaml：

modules: - name: text_normalization enabled: true - name: batch_processing enabled: true - name: custom_chemistry enabled: false # 暂时不对外开放

并在load_modules()中读取配置决定是否加载。

4.3 性能与资源考量

由于Gradio应用为单进程，默认情况下每次转换都会重新加载模型。若新增模块涉及复杂计算，建议：

• 使用gr.State()缓存模型实例
• 对高频调用函数添加@lru_cache装饰器
• 在批量处理时启用多线程加速

5. 总结

5. 总结

本文系统阐述了在FST ITN-ZH WebUI中实现功能模块二次开发的完整路径。通过引入模块化设计理念，我们将原本紧耦合的界面逻辑拆分为可插拔的独立单元，显著提升了系统的可扩展性与可维护性。

核心收获包括： 1.架构层面：掌握了基于Gradio的动态Tab注册机制，实现了功能模块的低侵入式集成； 2.工程实践：完成了从环境搭建、代码编写到服务部署的全流程操作，验证了方案可行性； 3.可复用模式：所提出的模块注册中心模式适用于任意基于Gradio的WebUI项目，具有广泛推广价值。

未来可进一步探索的方向包括：支持热插拔机制、增加模块间通信能力、以及构建可视化模块管理后台。对于希望在此基础上继续开发的团队，建议优先完善配置管理和日志追踪体系，以支撑更复杂的生产级应用场景。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。