中文 AI 文本检测器教程：本地推理、模型训练与结果验证

项目简介

Chinese Guba AI Detector 是一个中文 AI 文本二分类工具。项目以 hfl/chinese-roberta-wwm-ext 为基础，并使用 C-ReD 语料进行微调，曾用于股吧文本的研究性测量。当前仓库公开训练、推理、测试脚本以及相关说明文档。

该工具在本地加载模型，不会调用外部 API。需要特别注意：仓库目前不提供训练后的权重和分词器文件，使用者必须自行合法取得模型并放入指定目录。

重要限制：这不是 C-ReD 官方模型，本次微调没有使用股吧帖子，也没有经过金融论坛领域的人工标注测试。模型分数不能证明文本的真实作者身份，不应被当作个人身份认定或内容处罚的唯一依据。

主要功能

• 对 UTF-8 CSV 中的中文文本执行 AI 与人工文本二分类。
• 输出 AI 类别的 softmax 分数和基于阈值的分类结果。
• 默认读取 帖子内容文本，也支持自定义文本列和股票代码列。
• 将 股吧代码 规范为六位文本并保留先导零。
• 保留输入文件中的其他列，不主动改变其文本内容。
• 通过临时文件和原子替换降低输出文件损坏的风险。
• 支持完整性校验、覆盖重算和单进程写入保护。
• 提供训练、单元测试和公开内容审计脚本。

安装运行环境

1. 准备 Python 与 PyTorch

项目测试环境为 Python 3.10。建议使用独立虚拟环境，并根据 CPU 或 CUDA 设备，先按照 PyTorch 官方说明安装适合设备的 PyTorch 2.5.1。

在 Windows PowerShell 中进入仓库根目录，然后创建并激活虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

CPU 可以运行推理，但 CUDA GPU 通常更快。如果出现显存不足，应优先把 --batch-size 从默认或较大的值降到 8 或 4。

2. 准备本地模型

将合法取得的已训练模型放入 models/detector。该目录需要包含以下文件：

• model.safetensors
• config.json
• tokenizer.json
• tokenizer_config.json
• special_tokens_map.json
• vocab.txt

这些权重和分词器文件不包含在公开仓库中。如果目录不完整，推理脚本将无法正常加载模型。

运行第一次检测

1. 准备输入 CSV

输入文件必须是 UTF-8 CSV。默认文本列名为 帖子内容文本，默认股票代码列名为 股吧代码。仓库提供的示例均为虚构文本，不包含真实用户、真实帖子或人工与 AI 真值标签。

2. 执行批量推理

模型准备完成后，在仓库根目录运行：

python scripts/predict.py --model-dir models/detector --input examples/synthetic_posts.csv --output outputs/demo.csv --batch-size 32

命令会从 models/detector 加载本地模型，读取示例 CSV，并将检测结果写入 outputs/demo.csv。整个检测过程不调用外部 API。

3. 理解输出字段

输出文件会保留原始列，并新增以下字段：

• 是否AI生成：未四舍五入的模型分数大于等于阈值时为 1，否则为 0；空文本保持为空。
• AI生成概率：AI 类别的 softmax 分数。该分数未经概率校准，不能直接视为真实概率。
• AI检测模型：公开模型标识，不会写入本机模型路径。
• AI检测阈值：默认值为 0.7。这是项目配置，不是论文认定的最优阈值。
• AI检测状态：ok 表示已完成检测，empty_text 表示输入文本为空。

使用自定义 CSV 列

如果文本列名为 text，股票代码列名为 id，可以显式指定：

python scripts/predict.py --model-dir models/detector --input input.csv --output outputs/result.csv --text-column text --stock-column id

如果输入文件没有股票代码列，则传入空字符串：

python scripts/predict.py --model-dir models/detector --input input.csv --output outputs/result.csv --text-column text --stock-column ""

股票代码列存在时，程序会将其规范为六位文本并保留先导零。输入中的其他列会按文本原样保留。

覆盖、校验与并行处理

重新生成完整结果

推理结果会先写入临时文件，成功后再原子替换目标文件。重新运行相同命令时，只有输入、模型、参数和完整输出的校验值全部匹配，程序才会跳过已有结果。

如需忽略已有结果并重新生成完整文件，请加入 --overwrite：

python scripts/predict.py --model-dir models/detector --input examples/synthetic_posts.csv --output outputs/demo.csv --batch-size 32 --overwrite

处理中断与并行任务

中断后，程序会从该文件开头重新计算，而不是根据已有行数盲目续写。同一个输出路径同时只允许一个进程写入。如果要并行处理，应为每个进程分配不同的输入文件和输出文件。

长度限制与结果解释

默认情况下，每条文本最多输入 256 个 token，超过的部分会被截断。token 数量不等于汉字数量，因此不能将该限制理解为 256 个汉字。

原研究中的部分股吧正文仅包含约 203 个字符的已采集片段，所以检测对象可能只是原始正文的一部分。解释结果时，应同时考虑文本截断、领域差异和上下文缺失。

AI生成概率 是未经校准的 softmax 分数，而默认阈值 0.7 只是项目设置。更改阈值会改变二分类结果，但 README 没有将任何阈值声明为经过论文验证的最优值。

使用 C-ReD 数据训练模型

许可前提

训练前必须自行核实并取得 C-ReD 数据的合法使用许可。上游仓库未发现明确许可证，引用论文不等于获得数据使用或再分发授权。本项目不会镜像 C-ReD 数据，仓库的 MIT 许可也不覆盖 C-ReD 数据及其衍生权重。

安装训练依赖

python -m pip install -r requirements-train.txt

启动训练

假设合法取得的数据已放入 data/C-ReD，可以运行：

python scripts/train.py --data-root data/C-ReD --output-dir models/detector --epochs 3 --batch-size 8 --eval-batch-size 16 --no-fp16

训练程序读取文件名中包含 CReD_ 的 CSV，并使用其中的 text 和 label 列。源数据标签定义为 0=AI、1=人工，训练时会转换为 0=人工、1=AI。

训练协议和历史指标记录在 MODEL_CARD.md。重新训练时会使用完整的随机种子初始化，但历史训练在模型初始化前没有显式设置全局种子，因此不能保证逐位复现旧权重。

测试与发布审计

运行全部单元测试：

python -m unittest discover -s tests -v

单元测试使用虚构数据和模拟预测，因此不需要下载模型。真实模型的冒烟测试只能说明模型可以被加载并执行推理，不能证明预测结果正确。

运行公开内容审计：

python scripts/audit_release.py

公开仓库使用文件白名单和敏感信息模式进行检查。股吧原始 CSV、发布者 ID、昵称、IP、帖子 URL、论文面板、商业数据库、缓存、日志、Notebook 输出、训练中间检查点和历史 Git 记录均不应进入仓库。具体脱敏范围见 PRIVACY.md，发布流程见 docs/PUBLISHING.md。

进阶使用建议

1. 先用虚构数据验证流程：确认环境、列名、模型目录和输出路径正确后，再处理自己的合法数据。
2. 显存不足时减小批量：优先尝试 --batch-size 8 或 --batch-size 4。
3. 避免共享输出路径：并行任务必须使用不同输出文件，以免触发单进程写入限制。
4. 保存运行参数：模型、输入、参数和输出校验值会影响结果复用，调整任一项后都应重新检查输出。
5. 谨慎解释长文本：超过 256 token 的内容会被截断，模型可能没有看到结尾部分。
6. 不要把分数当作身份凭证：softmax 分数未经校准，且项目缺少金融论坛领域的人工标注验证。
7. 发布权重前确认许可：代码与文档采用 MIT 许可，基础模型采用 Apache-2.0，但 C-ReD 数据和衍生权重需要单独确认授权。

结语

Chinese Guba AI Detector 提供了一套可在本地运行的中文 AI 文本分类流程，涵盖 CSV 推理、模型训练、单元测试和发布审计。实际使用时，应先合法取得模型或训练数据，并把输出视为研究性模型分数，而不是文本作者身份的确定性证据。