faq-mining-pipeline

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 候选，供检索服务入库。

安装后配置

1. 进入 ../../tools/faq-mining-pipeline/
2. pip install -r requirements.txt
3. 复制 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）
• 提交未脱敏通话记录语料