智能客服高频问题推荐分析

概述

本 Skill 用于智能客服业务中的千人千面高频问题推荐。通过语义聚类分析客服聊天记录，自动生成：

词云数据：用户提问的高频关键词，供前端渲染
高频问题 Top K：基于语义聚类的问题排行榜
猜你想问：按用户标签分组预计算的个性化推荐清单

何时使用

用户提到"客服分析"、"高频问题"、"猜你想问"、"千人千面"、"问题推荐"
需要从聊天记录中提取用户常见问题
需要基于用户标签提供个性化问题推荐
需要生成客服问题词云

快速开始

1. 安装依赖

cd .codebuddy/skills/customer-insight-analyzer
pip install -r requirements.txt

注意：首次运行会自动下载 all-MiniLM-L6-v2 模型（~80MB），需确保网络可访问 HuggingFace或ModelScope。

2. 准备数据

将客服聊天记录整理为 CSV 或 JSON 格式，放入数据目录。

3. 运行分析

python scripts/chat_analyzer.py --input your_data.csv --output result.json

使用方式

CLI 命令

# 基本用法
python scripts/chat_analyzer.py --input data.csv --output result.json

# 自定义 Top K
python scripts/chat_analyzer.py --input data.csv --output result.json --top-k 20

# 使用自定义配置
python scripts/chat_analyzer.py --input data.csv --output result.json --config my_config.yaml

# 开启调试日志
python scripts/chat_analyzer.py --input data.csv --output result.json --log-level DEBUG

参数说明

| 参数 | 简写 | 必填 | 说明 | |------|------|------|------| | --input | -i | 是 | 输入文件路径（CSV 或 JSON） | | --output | -o | 否 | 输出文件路径（默认: analysis_result.json） | | --config | -c | 否 | 配置文件路径（默认: 使用内置配置） | | --top-k | -k | 否 | 高频问题 Top K 数量（覆盖配置文件） | | --log-level | | 否 | 日志级别：DEBUG/INFO/WARNING/ERROR | | --log-file | | 否 | 日志文件路径 |

配置文件

可通过 config.yaml 自定义分析参数：

model:
  name: "all-MiniLM-L6-v2"  # 向量模型名称
  device: "cpu"              # 推理设备

clustering:
  min_cluster_size: 5        # 最小簇大小
  min_samples: 3              # 核心点邻域样本数
  metric: "cosine"            # 距离度量

analysis:
  top_k: 10                  # 高频问题数量
  wordcloud_top_n: 100        # 词云词数
  guess_you_ask_top_k: 5      # 猜你想问每组推荐数
  min_tag_group_size: 3       # 标签分组最小用户数

输入格式

支持 CSV 和 JSON 两种格式，详见 references/input_format.md。

CSV 格式

session_id,user_id,role,content,timestamp,user_tags
s001,u001,user,如何办理社保转移？,2026-05-20 10:00:00,"30-40岁|企业职工|北京"
s001,u001,agent,您可以携带身份证...,2026-05-20 10:01:00,

JSON 格式

{
  "conversations": [
    {
      "session_id": "s001",
      "user_id": "u001",
      "user_tags": ["30-40岁", "企业职工", "北京"],
      "messages": [
        {"role": "user", "content": "如何办理社保转移？", "timestamp": "2026-05-20 10:00:00"},
        {"role": "agent", "content": "您可以携带身份证...", "timestamp": "2026-05-20 10:01:00"}
      ]
    }
  ]
}

输出格式

输出为 JSON 文件，详见 references/output_format.md。

{
  "metadata": { "total_questions": 3500, "cluster_count": 45, ... },
  "wordcloud": [{"word": "社保", "count": 120}, ...],
  "top_questions": [{"rank": 1, "question": "如何办理社保转移？", "count": 85, "category": "社保转移"}, ...],
  "guess_you_ask": [{"tag_group": ["30-40岁", "企业职工"], "recommendations": [...]}]
}

技术架构

输入文件(CSV/JSON) → 数据解析 → 语义向量化 → HDBSCAN聚类 → 聚合分析 → JSON输出
                                      ↓                ↓
                                 词云数据生成      高频问题TopK
                                      ↓                ↓
                                 标签分组聚类  →  猜你想问推荐

向量化：sentence-transformers（all-MiniLM-L6-v2，CPU可跑，~80MB）
聚类：HDBSCAN 密度聚类，自动确定簇数
分词：jieba 中文分词
无GPU依赖：纯CPU本地执行

性能参考

| 数据量 | 处理耗时（CPU） | |--------|----------------| | 3,500条 | ~10秒 | | 25,000条 | ~60秒 | | 100,000条 | ~5分钟 |

模型替换

如果 all-MiniLM-L6-v2 对中文语义效果不佳，可在 config.yaml 中替换为：

model:
  name: "shibing624/text2vec-base-chinese"  # 中文语义模型，~400MB

Resources

scripts/

chat_analyzer.py - 主入口脚本，CLI命令行工具
data_parser.py - 数据解析模块
semantic_cluster.py - 语义聚类模块
wordcloud_generator.py - 词云数据生成模块
guess_you_ask.py - 猜你想问推荐模块
utils.py - 公共工具函数

references/

input_format.md - 输入数据格式规范
output_format.md - 输出数据格式规范

assets/

sample_input.csv - 示例CSV输入
sample_input.json - 示例JSON输入
sample_output.json - 示例输出结果
stopwords.txt - 中文停用词表