| name | faq-mining-pipeline |
| description | 从客服通话记录挖掘 FAQ 候选：QA 提取 → 语义聚类 → 分类 + 入FAQ 判断。 离线批处理工具链，产出 FAQ 库供坐席助手检索服务使用。需提供通话记录语料与问题分类定义，不得编造分类。 |
| compatibility | 离线运行于宿主机/有外网环境（需调 LLM 与 BGE-M3 向量服务）。 非 Agent 沙箱内实时调用。依赖见 tools/faq-mining-pipeline/requirements.txt。 |
| metadata | {"author":"marketing-assistant","version":"1.0.0","schema_version":"1.0","variant":"external","shared_files":["../../tools/faq-mining-pipeline/batch_process.py","../../tools/faq-mining-pipeline/qa_clustering.py","../../tools/faq-mining-pipeline/classify_cluster.py","../../tools/faq-mining-pipeline/run_pipeline.py","../../tools/faq-mining-pipeline/requirements.txt","../../tools/faq-mining-pipeline/references/config.example.env","references/sample-classification.csv","references/test-cases.md"]} |
FAQ 挖掘流水线
何时使用
触发词：FAQ 挖掘、FAQ 候选提取、通话记录聚类、QA 聚类、坐席语料聚类、问题分类入库。
适用：坐席助手 faq-retrieval 的 FAQ 库离线生产侧——从历史通话记录批量产出 FAQ 候选，供检索服务入库。
安装后配置
- 进入
../../tools/faq-mining-pipeline/
pip install -r requirements.txt- 复制
references/config.example.env 为 references/config.local.env，填入三个服务地址（均为 OpenAI 兼容接口）：
- QA 提取 LLM（
LLM_QA_HOST/PORT/MODEL，需支持 response_format=json_object）
- 分类 LLM（
LLM_CLASSIFY_HOST/PORT/MODEL）
- BGE-M3 向量服务（
BGE_M3_HOST/PORT/MODEL_PATH，/v1/embeddings）
config.local.env 已 gitignore，勿提交真实地址。
第一步：QA 提取
将通话记录（.txt，一文件一条通话 ASR 文本）批量提取为 QA 对：
python batch_process.py --input-dir records/ --output QA.csv
失败记录写 fail.csv，可加 --retry 重跑。
第二步：语义聚类
对 QA 对做 BGE-M3 向量化 + HDBSCAN 分批聚类 + 全局合并 + 精炼分配：
python qa_clustering.py --csv QA.csv --output 聚类结果_详细.csv --summary 聚类结果_摘要.csv
支持检查点恢复（cluster_cache/）；--no-resume 强制重跑；--refine-threshold 调相似度阈值。
第三步：分类 + 入 FAQ 判断
对聚类摘要用 LLM 分类，并按答案质量 + 聚类大小判断是否入 FAQ：
python classify_cluster.py --input 聚类结果_摘要.csv --classification-file 问题分类.csv --output 分类结果.csv --full
--test-size N 先串行测前 N 条观察；--full 跑全量（跳过交互）。
一键全流程
python run_pipeline.py --input-dir records/ --classification-file 问题分类.csv --work-dir ./work
--start-step 2 支持断点续跑（跳过已完成的 QA 提取）。
输出与入 FAQ 判断
聚类结果_分类结果.csv 含：问题类型 / 一级分类 / 是否建议入FAQ / 分类理由
入 FAQ 判断（determine_faq，答案质量优先 + 聚类大小辅助）：
- 是：强烈推荐入 FAQ
- 可选：建议人工审核
- 否：不推荐
禁止
- 在未提供语料前编造 FAQ
- 提交真实服务地址（须走
config.local.env，已 gitignore）
- 提交未脱敏通话记录语料
