# voice-qa-platform

**Repository Path**: jiang_dn/voice-qa-platform

## Basic Information

- **Project Name**: voice-qa-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音质检平台

面向呼叫中心录音分析的企业级语音质检平台。
基于 FunASR + Kafka + FastAPI + PostgreSQL 构建。

---

## 概述

语音质检平台通过一条 7 阶段 AI 流水线自动分析呼叫中心录音：
预处理、语音活动检测、说话人分离、语音识别、情感分析、指标计算以及规则化质检评分。

```text
  音频文件 ──▶ API ──▶ Kafka ──▶ Worker 流水线 ──▶ 质检报告
                                     │
                           ┌─────────┼─────────┐
                           ▼         ▼         ▼
                          VAD       ASR      情感
                        (FSMN)  (Paraformer) (emotion2vec+)
```

### 核心特性

- **7 阶段分析流水线**：覆盖 VAD、分离、ASR、情感、指标、规则、评分
- **FunASR 模型栈**：以中文语音场景为核心的统一模型框架
- **事件驱动架构**：通过 Kafka 将 API 与 GPU 密集型 Worker 解耦
- **质检规则引擎**：支持关键词、情感、语速、合规四类规则
- **PII 脱敏**：自动屏蔽手机号、身份证号、邮箱、银行卡号
- **优雅降级**：非关键阶段失败时不阻塞整条流水线
- **Prometheus 监控**：暴露请求延迟、流水线时长、错误指标

---

## 快速开始

### 前置要求

- Python 3.11+
- Docker 与 Docker Compose
- 推荐为 Worker 提供 GPU（CPU 也可运行，但速度更慢）

### 1. 克隆并安装

```bash
git clone <repository-url>
cd voice-qa-platform
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### 2. 启动基础设施

```bash
docker compose up -d postgres redis kafka minio
```

### 3. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，并设置强随机的 VQA_JWT_SECRET_KEY
```

### 4. 执行数据库迁移

```bash
alembic upgrade head
```

### 5. 启动 API

```bash
uvicorn src.api.app:create_app --factory --host 0.0.0.0 --port 8000
```

### 6. 启动 Worker

```bash
python -m src.worker.consumer
```

### 7. Mac M5 本地验证（A100 接口契约 / CPU 模型验证）

这条路径只用于 Apple Silicon 本地验证，目标是“同接口 / 同模型集 / CPU 本地验证”。
它不会修改现有 A100 GPU 镜像，也不等同于 A100/CUDA 运行环境。
模型默认落在仓库本地 `./.cache/mac-models`，中断后可以继续复用，不需要重新构建镜像。

```bash
# 构建依赖镜像
docker compose -f docker-compose.mac.yml build voice-qa-mac-verify

# 首次运行会把模型下载到 ./.cache/mac-models 并做 CPU 验证
docker compose -f docker-compose.mac.yml run --rm voice-qa-mac-verify

# 启动本地 API 并检查模型接口
docker compose -f docker-compose.mac.yml build voice-qa-mac-api
docker compose -f docker-compose.mac.yml up -d voice-qa-mac-api
curl -sS http://localhost:8000/v1/models

# 黑盒转写验证
curl -sS http://localhost:8000/v1/audio/transcriptions \
  -F "file=@/Users/jiangdn/Downloads/voice/20250207082937-13304106728-123450410-2-245.wav" \
  -F "model=paraformer-large" \
  -F "speaker_enabled=true" \
  -F "emotion_enabled=true"

# 对照 2026-04-09 远端升级后基准做结构黑盒校验
./.venv/bin/python scripts/compare_a100_blackbox_baseline.py \
  --base-url http://127.0.0.1:8000 \
  --baseline ./.worktrees/mac-m5-a100-api-local-validation/docs/a100_remote_postupgrade_fullresponses_20260409

# 本地 CPU Docker 可用短音频做结构校验（仍对照远端基准的接口字段）
./.venv/bin/python scripts/compare_a100_blackbox_baseline.py \
  --base-url http://127.0.0.1:8000 \
  --baseline ./.worktrees/mac-m5-a100-api-local-validation/docs/a100_remote_postupgrade_fullresponses_20260409 \
  --max-cases 1 \
  --override-file tests/fixtures/audio/mono_16k_30s.wav

# 如果 Docker Hub 拉取 python:3.11-slim 超时，可以先用本机已有镜像打一个本地 tag，
# 再用 PYTHON_BASE_IMAGE 覆盖 compose build。
```

---

## API 参考

除 `/health` 与 `/metrics` 外，其余接口均要求 JWT Bearer 认证。

### 系统接口

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| GET | `/health` | 存活探针 |
| GET | `/metrics` | Prometheus 指标 |

### 通话接口

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| POST | `/api/v1/calls` | 提交通话分析任务 |
| GET | `/api/v1/calls/{call_id}` | 查询通话状态 |

### 结果接口

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| GET | `/api/v1/calls/{call_id}/result` | 查询质检结果 |

### 规则接口

| 方法 | 路径 | 说明 |
|--------|------|-------------|
| GET | `/api/v1/rules` | 列出全部规则 |
| POST | `/api/v1/rules` | 创建规则 |
| PUT | `/api/v1/rules/{rule_id}` | 更新规则 |
| DELETE | `/api/v1/rules/{rule_id}` | 删除规则 |

---

## 配置

所有运行配置均使用 `VQA_` 前缀，可通过环境变量或 `.env` 文件提供。

| 变量 | 默认值 | 说明 |
|----------|---------|-------------|
| `VQA_DATABASE_URL` | 无（必填） | PostgreSQL 连接串 |
| `VQA_KAFKA_BOOTSTRAP_SERVERS` | 无（必填） | Kafka broker 地址 |
| `VQA_JWT_SECRET_KEY` | 无（必填） | JWT 签名密钥 |
| `VQA_MINIO_ENDPOINT` | `localhost:9000` | MinIO endpoint |
| `VQA_MINIO_BUCKET` | `voice-qa` | 音频存储 bucket |
| `VQA_REDIS_URL` | `redis://localhost:6379/0` | Redis 地址 |
| `VQA_SCORE_PASS_THRESHOLD` | `80.0` | `pass` 状态阈值 |
| `VQA_SCORE_WARNING_THRESHOLD` | `60.0` | `warning` 状态阈值 |

完整配置请见 [`.env.example`](.env.example)。

---

## 项目结构

```text
voice-qa-platform/
├── src/
│   ├── api/                    # FastAPI 应用
│   │   ├── app.py              # 应用工厂、/health、/metrics
│   │   ├── auth.py             # JWT 认证
│   │   ├── db.py               # 异步 session 工厂
│   │   ├── routes/             # API 路由处理器
│   │   └── schemas/            # 请求/响应模型
│   ├── core/                   # 共享基础设施
│   │   ├── config.py           # Pydantic Settings
│   │   ├── kafka.py            # 消息模型与序列化
│   │   ├── metrics.py          # Prometheus 采集器
│   │   ├── storage.py          # MinIO 客户端封装
│   │   └── types.py            # 共享数据类型
│   ├── models/                 # SQLAlchemy ORM 模型
│   │   ├── call.py             # 通话模型
│   │   ├── result.py           # 质检结果模型
│   │   └── rule.py             # 规则模型
│   ├── services/               # 业务逻辑层
│   │   ├── call_service.py     # 通话 CRUD
│   │   ├── result_service.py   # 结果 CRUD
│   │   └── rule_service.py     # 规则 CRUD
│   └── worker/                 # Kafka 消费端与流水线
│       ├── consumer.py         # 任务消费
│       ├── model_manager.py    # FunASR 惰性模型加载
│       ├── pipeline.py         # 7 阶段编排
│       └── stages/             # 各分析阶段
│           ├── preprocess.py   # 音频格式处理与重采样
│           ├── vad.py          # 语音活动检测
│           ├── diarize.py      # 说话人分离
│           ├── asr.py          # 语音识别
│           ├── emotion.py      # 情感识别
│           ├── metrics.py      # 通话指标
│           ├── rules.py        # 规则评估
│           ├── pii.py          # PII 脱敏
│           └── result_assembly.py  # 评分与结果装配
├── alembic/                    # 数据库迁移
├── tests/
│   ├── unit/                   # 单元测试
│   └── contract/               # 契约测试
├── docs/                       # 文档
│   ├── markdown/               # 所有 Markdown 文档统一目录
│   ├── a100-transcriptions-dataflow.drawio
│   ├── a100-transcriptions-dataflow.puml
│   └── a100-transcriptions-dataflow.svg
├── docker-compose.yml          # 基础设施服务定义
├── Dockerfile                  # API / Worker 镜像
└── pyproject.toml              # 构建与测试配置
```

---

## 测试

```bash
# 全量测试
.venv/bin/pytest tests/ --tb=short -q

# 只跑 unit
.venv/bin/pytest tests/ -m unit

# 覆盖率
.venv/bin/pytest tests/ --cov=src --cov-report=term-missing
```

当前接口演进、部署验证与黑盒记录请查看 [docs/A100模型安装部署报告.md](docs/A100模型安装部署报告.md)。

---

## 文档

| 文档 | 说明 |
|----------|-------------|
| [文档状态模型.md](docs/文档状态模型.md) | 文档中“当前可用 / 历史快照 / 规划文档”的边界说明 |
| [A100 接口解释](docs/A100接口逐项解释.md) | 当前 A100 转写/分析接口、字段和数据流解释 |
| [A100 部署报告](docs/A100模型安装部署报告.md) | 当前部署、黑盒、现网验证与接口演进记录 |
| [Mac 本地 Docker 验证手册](docs/Mac本地Docker验证操作手册.md) | Apple Silicon 本地 CPU 验证与黑盒命令 |
| [统一文档索引](docs/README.md) | 所有计划、ADR、规格、报告的统一目录 |
| [百万级接口优化计划](docs/2026-04-05-百万级音频质检接口优化计划.md) | 当前仍可执行的接口优化路线 |

当前态文档与目标态文档是刻意分离的。
状态标签与解释规则见 [docs/文档状态模型.md](docs/文档状态模型.md)。

### 架构决策记录

| ADR | 决策 |
|-----|----------|
| [ADR-001](docs/ADR-001-FunASR统一模型框架.md) | 采用 FunASR 作为统一模型框架 |
| [ADR-002](docs/ADR-002-Kafka事件流处理.md) | 采用 Kafka 做事件驱动任务处理 |
| [ADR-003](docs/ADR-003-异步SQLAlchemy.md) | 采用异步 SQLAlchemy 与 FastAPI |
| [ADR-004](docs/ADR-004-惰性模型加载.md) | 采用惰性模型加载 |
| [ADR-005](docs/ADR-005-PII脱敏策略.md) | 采用 PII 脱敏策略 |
| [ADR-006](docs/ADR-006-优雅降级.md) | 非关键阶段采用优雅降级 |
| [ADR-007](docs/ADR-007-Kafka批量刷新.md) | Kafka 生产者按任务批量刷新 |
| [ADR-008](docs/ADR-008-GPU缓存清理.md) | GPU 缓存清理策略 |

---

## 许可证

专有。保留所有权利。