ETC 客服问答智能体 | ETC Customer Service Q&A Agent

基于 22,286 条江西 ETC（赣通卡/赣通宝）历史客服问答数据构建的多模态智能客服系统：三路融合检索 + 情绪识别 + 语音交互 + 联网搜索兜底。

A multimodal intelligent customer service system built on 22,286 historical Jiangxi ETC Q&A records: hybrid retrieval + emotion recognition + voice interaction + web-search fallback.

中文

项目简介

本项目为北京航空航天大学2026年智慧交通专业暑期实习项目，目标是把一个真实业务问题做成完整产品：可运行、可体验、可评测的 ETC 客服问答智能体。

系统核心策略（严格二分）：

知识库命中 → 返回问答对中的答案（LLM 不参与改写）
知识库未命中 → 联网搜索（Bing → DuckDuckGo → 百度三级回退）+ LLM 自主思考生成回答

在此之上，系统提供全链路情绪能力：输入端识别用户情绪（文本 + 语音双通道），输出端调整助手语气、开场白与 TTS 语速。

详细报告见 docs/PROJECT_REPORT.md，系统设计见 docs/开发方案.md。

核心特性

特性	说明
三路融合检索	TF-IDF(0.50) + 向量相似度(0.15) + 关键词匹配(0.35)，Question-Centric 设计让"问题匹配问题"
答案零改写	知识库命中即返回原始答案，情绪开场白作为独立字段，答案本体不变
情绪识别	8 类情绪（愤怒/焦虑/焦急/失落/困惑/满意/感谢/中性）；语音走 MOSS-Audio-4B-Instruct，文本走 LLM
语气适配	愤怒→抱歉、焦虑→安抚、困惑→友好、中性→专业（静态映射，可审计）
语音交互	浏览器 Web Speech API 输入 + Edge TTS 情感语音播报（语速可调、可打断、数字逐位念出）
联网搜索	知识库无匹配时自动联网，三引擎回退，无需 API Key
内容安全	敏感词输入拦截 + LLM 输出脱敏（零依赖纯标准库，文本归一化防绕过）
多端同步	网页端 ↔ Android 客户端（WebView）SSE 实时同步，多会话管理
图片识别	GLM-4V 视觉模型，支持截图/照片提问
优雅降级	MOSS-Audio → LLM 文本情绪 → neutral；百度 ASR → Deepgram → faster-whisper；任何组件失效不阻塞服务
系统评测	220 条测试用例、多维指标（准确率/相关性/完整性/响应时间）、历史记录与随机抽查

系统截图

智能对话（含情绪识别/语音交互）	知识库检索	系统评测

系统架构

┌──────────────────────────────────────────────────────────────┐
│                         用户终端                              │
│   网页端(单HTML)              Android 客户端(WebView)          │
│  ┌──────────────────┐      ┌──────────────────────────┐      │
│  │ 对话/知识库/评测  │      │ 文本/语音对话 · TTS播报   │      │
│  │ 多会话·语速调节   │      │ 情绪轮询 · 设置           │      │
│  └────────┬─────────┘      └─────────────┬────────────┘      │
└───────────┼──────────────────────────────┼───────────────────┘
            │ REST API                     │ REST API + SSE
┌───────────▼──────────────────────────────▼───────────────────┐
│                   后端 (FastAPI + Python)                      │
│                                                                │
│  意图识别器 ── 对话管理器 ── 答案生成器                          │
│         └───────────────┬────────────────────┘                │
│  ┌──────────────────────▼─────────────────────┐               │
│  │        三路融合检索器 (Hybrid Retriever)     │               │
│  │   TF-IDF(0.50) + 向量(0.15) + 关键词(0.35)   │               │
│  │            Question-Centric 检索             │               │
│  └──────────────────────┬─────────────────────┘               │
│  ┌──────────────────────▼─────────────────────┐               │
│  │   知识库 22,286问答对 → 16,308去重知识条目    │               │
│  └────────────────────────────────────────────┘               │
│                                                                │
│  情绪识别(MOSS-Audio+LLM) │ 情感TTS(Edge TTS) │ 敏感词过滤      │
│  ASR(百度/Deepgram/Whisper) │ 图片识别(GLM-4V) │ 联网搜索        │
└──────────────────────────────────────────────────────────────┘

技术栈

模块	技术
后端	FastAPI + Python（无 Node.js/npm 依赖）
前端	单 HTML 文件（FastAPI 托管）+ Web Speech API + MediaRecorder
文本检索	TF-IDF（jieba + numpy，问答数据上自训练）
向量检索	sentence-transformers（shibing624/text2vec-base-chinese）+ 余弦相似度
LLM	OpenAI 兼容接口（默认 DeepSeek）
视觉模型	GLM-4V-Flash（OpenAI 兼容）
语音情绪	MOSS-Audio-4B-Instruct（transformers 懒加载）
语音合成	Edge TTS 神经网络语音（zh-CN-XiaoxiaoNeural，prosody 情感调节）
语音识别	百度 ASR → Deepgram → faster-whisper 三级回退
联网搜索	requests + BeautifulSoup（Bing/DuckDuckGo/百度）
移动端	Android WebView（复用网页前端）
内容安全	纯标准库敏感词过滤
部署	Docker / docker-compose

快速开始

前置条件

Python 3.10+
（可选）DeepSeek API Key —— 用于 LLM 自主思考与文本情绪识别
（可选）torch + transformers —— 用于 MOSS-Audio 语音情绪识别（未安装自动降级）

1. 数据已随仓库分发

原始数据 ETC问答对.xlsx（22,286 条问答对，1MB）已包含在仓库根目录，格式说明见 docs/DATA.md，可直接进入下一步。

2. 数据预处理

cd scripts
python prepare_data.py

该脚本读取 Excel，清洗答案文本（保留原始排版，HTML 标签转换），去重合并，生成 backend/data/ 下的知识库文件。

3. 安装依赖并启动

cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

或使用一键启动脚本：scripts\start.bat

或 Docker 部署：docker-compose up -d

4. 访问

前端页面：http://localhost:8000
API 文档：http://localhost:8000/docs

5. 环境变量配置

复制 .env.example 为 .env，填入你自己的 Key：

copy .env.example .env

变量	说明	默认值
LLM_API_KEY	DeepSeek API 密钥（启用自主思考与文本情绪）	sk-your-api-key
LLM_BASE_URL	OpenAI 兼容接口地址	https://api.deepseek.com
LLM_MODEL	LLM 模型名称	deepseek-chat
LLM_VISION_API_KEY	视觉模型 API 密钥（智谱 GLM）	LLM_API_KEY
LLM_VISION_MODEL	视觉模型名称	glm-4v-flash
WEB_SEARCH_ENABLED	知识库无匹配时是否联网搜索	true
AUTONOMOUS_THINKING	是否用 LLM 回答数据外问题	true
SIMILARITY_THRESHOLD	知识库匹配门槛	0.30
EMOTION_ENABLED	情绪识别总开关	true
MOSS_AUDIO_ENABLED	MOSS-Audio 语音情绪开关（懒加载）	true
MOSS_AUDIO_DEVICE	推理设备：auto/cpu/cuda	auto
EMBEDDING_MODEL	向量检索 embedding 模型	shibing624/text2vec-base-chinese

完整配置见 .env.example。

安卓端验证（无需编译）

仓库内置 Debug APK，可直接安装体验安卓客户端：

安装 APK：把根目录 app-debug.apk（6MB）传到安卓手机，允许"安装未知来源应用"后安装"ETC 客服助手"；也可用 adb install -r app-debug.apk；
启动后端：python -m uvicorn app.main:app --host 0.0.0.0 --port 8000；
启动内网穿透：双击根目录 run_natapp.bat（仓库已含 natapp.exe，把本机 8000 端口映射到公网隧道）；
手机 App 默认连接演示隧道 http://h796e536.natappfree.cc，进入后即与网页端共用同一后端：智能对话、语音输入、TTS 播报、实时同步全部可用。

natapp 为第三方免费内网穿透工具（natapp.cn），不包含在本项目 MIT 许可范围内；如需自己的隧道，替换 run_natapp.bat 中的 authtoken 即可。详细步骤见 APK安装与natapp联调说明.md。

API 一览

接口	方法	说明
`/api/chat`	POST	文本对话（含情绪识别）
`/api/chat/voice`	POST	语音对话，异步启动 MOSS-Audio 情绪识别
`/api/chat/image`	POST	图片识别对话
`/api/chat/stream`	POST	流式对话（SSE）
`/api/audio-emotion/{task_id}`	GET	轮询异步音频情绪结果
`/api/tts`	POST	Edge TTS 情感语音合成
`/api/asr/transcribe`	POST	手机端录音转文字
`/api/knowledge/search`	POST	知识库检索
`/api/eval`	POST	运行评测集
`/api/live/stream`	GET	多端实时同步（SSE）

完整列表见 http://localhost:8000/docs。

评测结果

220 条测试用例（覆盖 11+ 业务类别）：

指标	数值
通过率	88.6%（195/220）
平均响应时间	0.53 s
答案质量	0.85
完整性	0.81
平均置信度	0.82

详见 evaluation/results.json 与 docs/PROJECT_REPORT.md 的评测章节（含成功/失败案例分析）。

项目结构

ETC/
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── main.py         # 主应用与 API 端点
│   │   ├── config.py       # 配置（环境变量）
│   │   ├── agent/          # 意图识别 / 对话管理 / 答案生成
│   │   ├── knowledge/      # 三路融合检索（TF-IDF/向量/关键词）
│   │   ├── tools/          # 情绪识别/TTS/ASR/敏感词/联网搜索
│   │   ├── models/         # Pydantic 请求/响应模型
│   │   └── evaluation/     # 评测器与历史存储
│   ├── data/               # 运行时生成（不入库）
│   └── requirements.txt
├── frontend/               # 单 HTML 前端（FastAPI 托管）
├── etc-assistant-android/  # Android WebView 客户端
├── scripts/                # 数据预处理与测试脚本
├── evaluation/             # 测试集与评测结果
├── vendor/moss-audio/      # MOSS-Audio 模型加载代码
├── docs/                   # 项目报告与开发文档
└── docker-compose.yml

项目要求与交付物

本实习项目要求交付三件成果（详见 docs/PROJECT_REPORT.md）：

一套系统源代码 —— 可复现、可体验核心功能（本仓库）
一份系统开发方案 —— 问题定义、架构、选型、风险（docs/开发方案.md）
一套测评集和结果 —— 测试问题、评价标准、结果与案例分析（evaluation/）

许可证

MIT License。原始问答数据（ETC问答对.xlsx）已随仓库分发供复现，natapp.exe 为第三方工具不包含在 MIT 许可范围内。

English

Overview

This project was built as an 8-week, 3-person internship project at Beihang University (BUAA). The goal: turn a real business problem into a complete product — a runnable, experienceable, and evaluable ETC customer service agent.

The system follows a strict binary strategy:

Knowledge base hit → return the original answer from the Q&A pair verbatim (no LLM rewriting)
Knowledge base miss → web search (Bing → DuckDuckGo → Baidu fallback chain) + LLM autonomous reasoning

On top of that, the system provides end-to-end emotion capabilities: user emotion recognition on the input side (text + voice dual channel), and tone / opening phrase / TTS speaking-rate adaptation on the output side.

Full report: docs/PROJECT_REPORT.md (bilingual).

Key Features

Feature	Description
Hybrid 3-way retrieval	TF-IDF (0.50) + vector similarity (0.15) + keyword matching (0.35), with a Question-Centric design ("questions match questions")
Zero-rewrite answers	KB hits return the original answer verbatim; emotional prefixes are separate fields
Emotion recognition	8 emotion classes; voice via MOSS-Audio-4B-Instruct, text via LLM
Tone adaptation	angry→apologetic, anxious→soothing, confused→friendly, neutral→professional (static, auditable mapping)
Voice interaction	Web Speech API input + Edge TTS emotional output (adjustable rate, interruptible, digit-by-digit number reading)
Web search	Auto-triggered on KB miss; three-engine fallback, no API key required
Content safety	Sensitive-word input blocking + LLM output masking (pure stdlib, normalization-robust)
Multi-device sync	Web ↔ Android (WebView) via SSE; multi-session management
Image understanding	GLM-4V vision model for screenshot/photo questions
Graceful degradation	MOSS-Audio → LLM text emotion → neutral; Baidu ASR → Deepgram → faster-whisper; no single failure blocks the service
Evaluation	220 test cases, multi-dimensional metrics, history and random sampling

Screenshots

Smart Chat (emotion / voice)	Knowledge Base	Evaluation

Architecture

See the diagram in the Chinese section above — the system consists of: user terminals (single-file web frontend + Android WebView client), a FastAPI backend (intent recognition → dialogue management → answer generation → hybrid retriever → 22,286 Q&A knowledge base), plus emotion recognition, emotional TTS, sensitive-word filtering, ASR, image recognition, and web search modules.

Tech Stack

Module	Technology
Backend	FastAPI + Python (no Node.js/npm dependency)
Frontend	Single HTML file (FastAPI-hosted) + Web Speech API + MediaRecorder
Text retrieval	TF-IDF (jieba + numpy, trained on the Q&A data)
Vector retrieval	sentence-transformers (shibing624/text2vec-base-chinese) + cosine similarity
LLM	OpenAI-compatible API (DeepSeek by default)
Vision	GLM-4V-Flash (OpenAI-compatible)
Voice emotion	MOSS-Audio-4B-Instruct (transformers, lazy-loaded)
TTS	Edge TTS neural voices with prosody-based emotion adjustment
ASR	Baidu → Deepgram → faster-whisper fallback chain
Web search	requests + BeautifulSoup (Bing/DuckDuckGo/Baidu)
Mobile	Android WebView reusing the web frontend
Deployment	Docker / docker-compose

Quick Start

Prerequisites

Python 3.10+
(Optional) a DeepSeek API key — enables LLM autonomous reasoning and text emotion recognition
(Optional) torch + transformers — enables MOSS-Audio voice emotion (auto-degrades if absent)

1. The data is included

The original dataset ETC问答对.xlsx (22,286 Q&A pairs, 1 MB) is included in the repository root. See docs/DATA.md for the format; proceed directly to the next step.

2. Preprocess

cd scripts
python prepare_data.py

This script reads the Excel file, cleans answer text (preserving original layout, converting HTML tags), deduplicates, and generates the knowledge base files under backend/data/.

3. Install & Run

cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Or via Docker: docker-compose up -d

4. Access

Frontend: http://localhost:8000
API docs: http://localhost:8000/docs

5. Configuration

Copy .env.example to .env and fill in your keys. Key variables: LLM_API_KEY (DeepSeek), LLM_VISION_API_KEY (Zhipu GLM), WEB_SEARCH_ENABLED, EMOTION_ENABLED. See .env.example for the full list.

Android Verification (no build required)

A debug APK is bundled in the repository root for direct installation:

Install the APK: transfer app-debug.apk (6 MB) to your Android phone, allow "install from unknown sources", and install "ETC 客服助手" (or use adb install -r app-debug.apk);
Start the backend: python -m uvicorn app.main:app --host 0.0.0.0 --port 8000;
Start the tunnel: double-click run_natapp.bat in the repo root (natapp.exe is bundled; it maps local port 8000 to a public tunnel);
The app connects to the demo tunnel http://h796e536.natappfree.cc by default and shares the same backend as the web frontend: smart chat, voice input, TTS, and real-time sync all work.

natapp is a third-party free tunneling tool (natapp.cn) not covered by this project's MIT license; replace the authtoken in run_natapp.bat to use your own tunnel. Full instructions in APK安装与natapp联调说明.md (in Chinese).

API Overview

Main endpoints: POST /api/chat (text), POST /api/chat/voice (voice + async audio emotion), POST /api/chat/image (vision), POST /api/chat/stream (SSE streaming), GET /api/audio-emotion/{task_id} (emotion polling), POST /api/tts (emotional TTS), POST /api/knowledge/search, POST /api/eval, GET /api/live/stream (multi-device sync). Full list at http://localhost:8000/docs.

Evaluation Results

220 test cases across 11+ business categories:

Metric	Value
Pass rate	88.6% (195/220)
Avg. response time	0.53 s
Answer quality	0.85
Completeness	0.81
Avg. confidence	0.82

See evaluation/results.json and the evaluation chapter of docs/PROJECT_REPORT.md (including success/failure case analyses).

Project Structure

ETC/
├── backend/                # FastAPI backend
│   ├── app/
│   │   ├── main.py         # Main application & API endpoints
│   │   ├── config.py       # Configuration (env vars)
│   │   ├── agent/          # Intent / dialogue / answer generation
│   │   ├── knowledge/      # Hybrid retrieval (TF-IDF/vector/keyword)
│   │   ├── tools/          # Emotion / TTS / ASR / sensitive filter / web search
│   │   ├── models/         # Pydantic schemas
│   │   └── evaluation/     # Evaluator & history store
│   ├── data/               # Generated at runtime (not committed)
│   └── requirements.txt
├── frontend/               # Single-HTML frontend (FastAPI-hosted)
├── etc-assistant-android/  # Android WebView client
├── scripts/                # Preprocessing & test scripts
├── evaluation/             # Test set & evaluation results
├── vendor/moss-audio/      # MOSS-Audio model loading code
├── docs/                   # Project report & development docs
└── docker-compose.yml

Requirements & Deliverables

The internship project requires three deliverables (details in docs/PROJECT_REPORT.md):

System source code — reproducible, experienceable (this repository)
Development plan — problem definition, architecture, choices, risks (docs/开发方案.md, in Chinese)
Evaluation set & results — test questions, criteria, results, case analyses (evaluation/)

License

MIT License. The original Q&A dataset (ETC问答对.xlsx) is included for reproducibility; natapp.exe is a third-party tool not covered by the MIT license.

作者 | Authors

致谢 | Acknowledgments

数据提供方：江西 ETC 客服中心 | Data provider: Jiangxi ETC Customer Service Center
开源组件：FastAPI、Edge TTS、MOSS-Audio、sentence-transformers、jieba、faster-whisper
北京航空航天大学实习项目指导老师 | Internship mentors at Beihang University (BUAA)

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
etc-assistant-android		etc-assistant-android
evaluation		evaluation
frontend		frontend
scripts		scripts
vendor/moss-audio/src		vendor/moss-audio/src
系统屏幕截图		系统屏幕截图
.env.example		.env.example
.gitignore		.gitignore
APK安装与natapp联调说明.md		APK安装与natapp联调说明.md
CONTRIBUTING.md		CONTRIBUTING.md
ETC问答对.xlsx		ETC问答对.xlsx
LICENSE		LICENSE
README.md		README.md
app-debug.apk		app-debug.apk
docker-compose.yml		docker-compose.yml
etc-internship-brief.html		etc-internship-brief.html
natapp.exe		natapp.exe
run_natapp.bat		run_natapp.bat

Latest commit

History

Folders and files

Repository files navigation