本文件记录在examples下完成的训练/标注流水线：从 PDF 提取、自动建议（词典+模型）、生成优先 CSV、导入 Label Studio 到自动合并并微调模型的完整命令和脚本说明。
关键脚本（工作区相对路径）
spacy_pdf_ner.py — 训练与推理入口（spaCy）。
apply_annotations.py — 把
extractionJSON 转为 spaCy 训练 JSON（可选自动标注 TECH 词典）。save_extraction_suggest.py — 生成带
suggested_entities的 extraction（若不存在请参考项目中的对应脚本）。export_top_suggestions.py — 从
*_extraction_suggested.json导出 top-N 建议 CSV。convert_top_to_annotator.py — 把 top CSV 转为标注器友好 CSV。
auto_ingest_top.py — 自动把 top-N 建议注入 extraction JSON（生成带实体的注释 JSON）。
merge_model_and_suggestions.py — 用模型推理并将模型实体与建议合并（去重/避免重叠）。
export_merged_top.py — 从合并后的 extraction 导出带来源(
MODEL/SUGGESTED)的 top-N CSV。batch_process_pdfs.py — 批量对目录内 PDF 运行模型并输出 suggested/merged JSON。
annotator_csv_to_labelstudio.py — 把 annotator CSV 转为 Label Studio 可导入的 JSONL。
环境准备（示例）
建议在examples下使用虚拟环境：
cd examples python3 -m venv .venv source .venv/bin/activate # 安装依赖（仓库可能包含 requirements-spacy.txt） .venv/bin/pip install --upgrade pip .venv/bin/pip install -r requirements-spacy.txt如果没有 requirements 文件，请确保安装：spacy,pdfminer.six,PyPDF2等。
常用命令及流程
下面给出典型顺序与可复制的命令片段（相对路径基于examples）：
从 PDF 生成初始建议（若已有建议可跳过）
运行脚本或工具生成
Pxxx_extraction_suggested.json（示例文件：P020260202487301304903_extraction_suggested.json）。
2.导出 top-N 建议 CSV（频率优先）
source .venv/bin/activate python3 export_top_suggestions.py -i P020260202487301304903_extraction_suggested.json -o tech_suggestions_top100.csv -n 100 -c 1203.转为标注器友好 CSV（人工审阅）
python3 convert_top_to_annotator.py -t tech_suggestions_top100.csv -e P020260202487301304903_extraction_suggested.json -o tech_suggestions_top100_annotator.csv4.（可选）把 top-N 自动合并进 extraction（生成注释 JSON）
python3 auto_ingest_top.py -t tech_suggestions_top100.csv -e P020260202487301304903_extraction_suggested.json -o P020260202487301304903_autoingest_top100.json5.把注释 JSON 转为 spaCy 训练 JSON
python3 apply_annotations.py P020260202487301304903_autoingest_top100.json P020260202487301304903_training_autoingest_top100.json --auto-tag --tech-terms tech_terms.json --freq-csv tech_terms_freq.csv6.用 spaCy 微调模型（示例 10 iters）
python3 spacy_pdf_ner.py --train P020260202487301304903_training_autoingest_top100.json --output-model test_model_auto_ingest --iters 107.合并模型输出与建议（保留源信息）
python3 merge_model_and_suggestions.py -m test_model_auto_ingest -s P020260202487301304903_extraction_suggested.json -o P020260202487301304903_extraction_merged_model.json python3 export_merged_top.py -i P020260202487301304903_extraction_merged_model.json -o tech_suggestions_merged_top100.csv -n 1008.将标注内容转换为 Label Studio JSONL 以便人工标注（每个文档一个任务）
python3 convert_top_to_annotator.py -t tech_suggestions_merged_top100.csv -e P020260202487301304903_extraction_merged_model.json -o tech_suggestions_merged_top100_annotator.csv python3 annotator_csv_to_labelstudio.py -c tech_suggestions_merged_top100_annotator.csv -o tech_suggestions_merged_top100_labelstudio.jsonl在 Label Studio 中：Project → Import Tasks → 选择生成的*.jsonl。
批量处理示例
对目录中所有 PDF 使用已训练模型并生成 suggested/merged JSON：
python3 batch_process_pdfs.py -d . -m test_model_auto_ingest -t tech_terms.json -o ./batch_out # 会为每个 PDF 生成 <stem>_extraction_suggested.json 和 <stem>_extraction_merged.json人工确认与再次训练（建议流程）
在 Label Studio 中完成确认后，导出为 JSONL。将已确认的标注转换回
extraction格式（或手动合并）并运行apply_annotations.py生成训练 JSON。将新的训练 JSON 与原训练集合并（或直接替换少量样本），再运行
spacy_pdf_ner.py做下一轮微调（建议 10–40 次，视数据量而定）。
文件与产物清单（本次运行产物）
标注器 CSV（优先 top 100）：examples/tech_suggestions_top100.csv
Annotator CSV：examples/tech_suggestions_top100_annotator.csv
自动合并注释 JSON：examples/P020260202487301304903_autoingest_top100.json
训练用 JSON：examples/P020260202487301304903_training_autoingest_top100.json
新模型目录：examples/test_model_auto_ingest
合并后的优先 CSV（含来源）：examples/tech_suggestions_merged_top100.csv
Label Studio 可导入 JSONL：examples/tech_suggestions_merged_top100_labelstudio.jsonl
通过训练模型提取pdf文件中的“问题,缺陷,错误”：
.venv/bin/python spacy_pdf_ner.py --model test_model_final --pdf P020260202487301304903.pdf --keywords 问题,缺陷,错误 --lang zh返回的部分实体与问题句子：
注意与建议
避免训练示例中实体跨度重叠（spaCy Example.from_dict 对重叠会报错）。脚本中已有去重/避让逻辑。
小样本微调（几十到几百条）时，训练次数不宜过多（会过拟合）。先做 10–40 次，观察损失与验证样本表现。
自动合并建议会引入噪声，建议把
SUGGESTED项先人工过一遍，再合并入训练集。
