Python脚本头文件生成器

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Text Classification Trainer — 文本分类训练脚本
======================================================================
用途
    面向生产与研究场景的一体化文本分类训练脚本。完成数据加载、中文分词与去噪、
    样本划分、特征工程、超参网格搜索/随机搜索、早停与模型评估；自动导出最佳模型、
    指标报告与可复现实验配置；支持一键复训与推断示例。

适用场景
    - 企业级NLP分类任务（舆情监控、工单路由、意图识别、内容审核等）
    - 学术/教学演示的标准化ML训练流程
    - 开源项目的基线文本分类器

核心特性
    - 数据读取：CSV/TSV/JSONL；指定文本列与标签列；支持外部划分或分层随机划分
    - 文本预处理：中文分词（jieba）、大小写与全/半角规范化、去标点/去噪、停用词过滤、长度裁剪
    - 特征工程：TF-IDF（默认，支持 n-gram/子词）、可选 HashingVectorizer
    - 模型族：
        * 线性基线：LogisticRegression、LinearSVC、SGDClassifier(可早停)
        * 梯度提升：XGBoostClassifier(可早停，可选安装)
    - 超参搜索：GridSearchCV 或 RandomizedSearchCV；支持并行与交叉验证
    - 早停策略：
        * SGDClassifier(early_stopping=True)
        * XGBoost(early_stopping_rounds, eval_set，支持 GPU 加速)
    - 评估与报告：准确率、精确率、召回率、F1（微/宏/加权）、ROC-AUC(二分类)、混淆矩阵、
      classification_report；保存学习曲线和混淆矩阵图（可选）
    - 产出工件：
        * 模型：best_model.joblib（含分类器）
        * 向量器/标签器：vectorizer.joblib, label_encoder.joblib
        * 指标与报告：metrics.json, report.txt, confusion_matrix.png（可选）
        * 复现配置：config.yaml（含随机种子、预处理、搜索空间、最佳超参）
        * 预测样例：predictions.csv（验证集或测试集）
        * 日志：training.log
    - 复现与一键复训：--resume-config 指向历史 config.yaml 即可重跑
    - 推断示例：infer 子命令对单条或文件批量文本进行预测

输入数据约定
    - 至少包含：
        * 文本列：--text-col 指定（默认 text）
        * 标签列：--label-col 指定（默认 label）
    - 支持文件类型：.csv（默认逗号分隔）、.tsv、.jsonl
    - 可选：外部分割文件（train/valid 列或独立文件），或通过 --val-ratio 自动分层划分

命令行用法示例
    1) 基础训练（自动分层划分 + 网格搜索 + 保存最佳模型）：
        python train_text_cls.py train \
          --data ./data/labeled.csv \
          --text-col text --label-col label \
          --val-ratio 0.2 --random-state 42 \
          --model xgboost \
          --search grid \
          --grid '{"max_depth":[4,6], "learning_rate":[0.05,0.1], "n_estimators":[200,400]}' \
          --early-stopping-rounds 20 \
          --metric f1_macro \
          --outdir ./outputs/run_$(date +%Y%m%d_%H%M%S)

    2) 使用 SGDClassifier（内置早停）+ 随机搜索：
        python train_text_cls.py train \
          --data ./data/labeled.csv \
          --model sgd --search random --n-iter 30 \
          --metric f1_weighted --random-state 123 \
          --outdir ./outputs/sgd_run

    3) 一键复训（使用历史 config.yaml）：
        python train_text_cls.py retrain --resume-config ./outputs/run_xxx/config.yaml

    4) 推断（单条文本）：
        python train_text_cls.py infer \
          --model-path ./outputs/run_xxx/best_model.joblib \
          --vectorizer-path ./outputs/run_xxx/vectorizer.joblib \
          --label-encoder-path ./outputs/run_xxx/label_encoder.joblib \
          --text "示例文本：这是一条需要分类的句子。"

    5) 批量推断（CSV 输入 -> 追加预测列）：
        python train_text_cls.py infer \
          --model-path ./outputs/run_xxx/best_model.joblib \
          --vectorizer-path ./outputs/run_xxx/vectorizer.joblib \
          --label-encoder-path ./outputs/run_xxx/label_encoder.joblib \
          --data ./data/unlabeled.csv --text-col text --output ./outputs/pred.csv

主要参数（节选）
    - 模式：
        * 子命令：train | retrain | infer
    - 数据与列：
        * --data              训练/推断数据路径（CSV/TSV/JSONL）
        * --text-col          文本列名（默认：text）
        * --label-col         标签列名（默认：label，推断时可省略）
        * --val-ratio         验证集比例（默认：0.2），与 --cv 互斥
        * --cv                交叉验证折数（如 5），与 --val-ratio 互斥
        * --sep               分隔符（默认：,；TSV 自动识别）
        * --encoding          文件编码（默认：utf-8）
    - 预处理：
        * --lang              语言（zh|en，默认：zh）
        * --lowercase         转小写（默认：开启）
        * --normalize-width   全/半角规范化（默认：开启）
        * --rm-punct          去标点（默认：开启）
        * --rm-stopwords      去停用词（默认：开启）
        * --max-len           最大分词数（默认：不裁剪）
    - 特征工程：
        * --vectorizer        tfidf | hashing（默认：tfidf）
        * --ngram             n-gram 上界（默认：1；如 2 表示 1-2gram）
        * --max-features      词表上限（默认：50000）
    - 模型与搜索：
        * --model             logreg | linearsvc | sgd | xgboost（默认：logreg）
        * --search            grid | random | none（默认：grid）
        * --grid              网格（JSON 字符串）
        * --n-iter            随机搜索迭代次数（默认：30）
        * --n-jobs            并行线程（默认：-1 使用全部）
        * --early-stopping-rounds  早停轮数（xgboost 有效）
    - 评估与输出：
        * --metric            优化目标（accuracy|f1_macro|f1_weighted 等）
        * --outdir            输出目录
        * --save-proba        保存预测概率（如需绘制 ROC）
    - 复现：
        * --random-state      随机种子（默认：42）
        * --resume-config     复现配置路径（retrain 模式）
    - 推断：
        * --model-path        训练产出的模型路径
        * --vectorizer-path   向量器路径
        * --label-encoder-path 标签编码器路径
        * --output            推断输出文件（CSV）

依赖与环境
    - 运行环境：
        * Python 3.9–3.12，Linux/macOS/Windows（x86_64）
        * 可选 GPU（XGBoost 支持 'gpu_hist'）
    - 必需依赖：
        * pandas>=1.5, numpy>=1.22, scipy>=1.8
        * scikit-learn>=1.2
        * jieba>=0.42  （中文分词）
        * pyyaml>=6.0  （导出 config.yaml）
        * joblib>=1.2  （模型持久化）
        * tqdm>=4.64   （进度条）
    - 可选依赖：
        * xgboost>=1.7 （提升树 + 早停 + 可选 GPU）
    - 安装示例：
        pip install -U pandas numpy scipy scikit-learn jieba pyyaml joblib tqdm
        # 可选
        pip install -U xgboost

输出工件（默认约定）
    outdir/
      ├─ best_model.joblib
      ├─ vectorizer.joblib
      ├─ label_encoder.joblib
      ├─ metrics.json
      ├─ report.txt
      ├─ predictions.csv
      ├─ config.yaml
      └─ training.log

复现性与随机性
    - 固定 random_state，设置 Python/numpy 的随机种子，确保可复结果
    - 导出完整 config.yaml（含预处理、搜索空间、最佳超参、数据源摘要）
    - 可选记录依赖快照（pip freeze）至 requirements.txt（实现层处理）

性能与资源建议
    - 合理设置 --max-features 与 --ngram；避免 n-gram 过大导致内存膨胀
    - 并行搜索使用 --n-jobs，必要时通过 OMP_NUM_THREADS 控制线程
    - XGBoost 可通过 --model xgboost 并在内部选择树方法 'hist' 或 'gpu_hist'

异常与退出码
    - 0：成功
    - 2：参数错误（缺失必需参数、不合法组合）
    - 3：数据/文件 I/O 错误
    - 4：训练或搜索失败
    - 5：推断失败

日志
    - 训练过程写入 training.log，包括参数、数据摘要、评估指标、最佳超参与路径
    - 对敏感文本不做原文日志输出（仅记录统计与摘要）

作者与项目信息
    - 作者：王珂
    - 邮箱：ke.wang@example.com
    - GitHub：https://github.com/wangkedev

版本与许可
    - 版本：1.0.0
    - 创建日期：2025-12-10
    - Python：>=3.9
    - 许可协议：Apache-2.0

变更记录
    - 1.0.0：初始版本，支持分词去噪、网格/随机搜索、早停、评估与复现导出

"""
__title__ = "text_cls_trainer"
__description__ = "一体化文本分类训练脚本：预处理、划分、特征工程、超参搜索、早停、评估与可复现实验导出。"
__version__ = "1.0.0"
__author__ = "王珂"
__email__ = "ke.wang@example.com"
__url__ = "https://github.com/wangkedev"
__license__ = "Apache-2.0"
__status__ = "Production/Stable"  # 可选：Prototype | Development | Production/Stable

# 入口说明（示例）：
# if __name__ == "__main__":
#     main()
#
# 注意：本头文件仅为脚本元信息与使用说明，具体实现请在主体代码中完成：
# - 参数解析（argparse/typer）
# - 预处理流水线（jieba/正则/停用词）
# - 特征工程（TF-IDF/HashingVectorizer）
# - 模型与搜索（sklearn / xgboost）
# - 早停逻辑（SGDClassifier / XGBoost）
# - 评估与导出（metrics.json/config.yaml/joblib）

功能描述摘要

• 面向生产的文本分类训练脚本，覆盖从数据读取、中文分词和清洗、分层划分/交叉验证、TF-IDF/Hashing 特征工程，到网格/随机超参搜索、早停训练与多指标评估的完整流程。自动导出最佳模型、评估报告与 config.yaml 以保证实验可复现，并提供 retrain 与 infer 子命令实现一键复训与推断示例。

关键参数说明

• 数据与列
  • --data: 训练/推断数据文件路径（CSV/TSV/JSONL）
  • --text-col / --label-col: 文本与标签列名（默认 text/label）
  • --val-ratio: 验证集比例（与 --cv 互斥）
  • --cv: 交叉验证折数（与 --val-ratio 互斥）
• 预处理
  • --lang: 语言标识（zh/en）；中文默认启用 jieba 分词
  • --lowercase/--normalize-width/--rm-punct/--rm-stopwords: 常见清洗选项
  • --max-len: 分词后的最大长度裁剪
• 特征工程
  • --vectorizer: tfidf 或 hashing
  • --ngram: n-gram 上界
  • --max-features: 词表规模上限
• 模型与搜索
  • --model: logreg | linearsvc | sgd | xgboost
  • --search: grid | random | none；--grid/--n-iter 配置搜索空间
  • --early-stopping-rounds: xgboost 早停轮数；sgd 内置 early_stopping
  • --n-jobs: 并行线程数
• 评估与输出
  • --metric: 优化指标（如 f1_macro）
  • --outdir: 输出目录；保存模型、向量器、label 编码器、metrics、config 等
  • --save-proba: 是否保存预测概率
• 复现与推断
  • --random-state: 随机种子
  • --resume-config: 指向历史 config.yaml 进行一键复训
  • --model-path/--vectorizer-path/--label-encoder-path: 推断所需工件路径
  • --output: 推断结果导出路径

使用注意事项

• 数据质量
  • 确认文本列/标签列无大量缺失；类别极度不均衡时建议使用分层划分并关注宏平均 F1
  • 中文任务默认使用 jieba 分词；如需自定义分词或使用词典，请在实现层扩展
• 资源与性能
  • 大规模 n-gram 或超大 --max-features 可能导致内存压力；请结合 --n-jobs 与 OMP_NUM_THREADS 控制并发
  • XGBoost 如使用 GPU，请确保正确安装支持 GPU 的版本并设置 tree_method=gpu_hist（实现层）
• 早停配置
  • SGDClassifier 的 early_stopping 依赖验证分割；XGBoost 需提供 eval_set（实现层会从验证集自动注入）
• 复现性
  • 固定 --random-state，并保留 config.yaml 与训练日志；跨平台/不同 BLAS 实现可能产生微小数值差异
• 合规与隐私
  • 日志与报告不应包含原始敏感文本；建议仅输出统计信息与示例片段（如有必要，在实现层做脱敏）
• 版本与兼容
  • 建议 Python≥3.9 与 scikit-learn≥1.2；不同版本在 API 与指标行为上可能有所差异
  • 可选依赖 xgboost 未安装时，请勿选择 --model xgboost 或在实现层做异常处理