# meeting

**Repository Path**: xhyym/meeting

## Basic Information

- **Project Name**: meeting
- **Description**: 流式语音服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 会议语音转写与分析服务

这是一个基于 FastAPI 和 FunASR 模型库构建的后端服务，提供语音转写、声纹识别、用户管理和历史记录等功能。

## ✨ 主要功能

- **实时语音转写**: (新增) 支持通过 WebSocket 进行高性能、低延迟的实时语音识别，并能动态识别说话人角色。
- **离线文件转写**: 支持通过文件上传或 URL 链接的方式提交音频，进行语音到文本的转换。
- **声纹识别**: 支持用户注册声纹，并在转写结果中识别出对应的说话人。
- **用户系统**: 包含用户注册、登录、权限管理等功能。
- **历史记录**: 保存用户的每一次转写任务，并提供查询和编辑接口。
- **后台处理**: 使用多进程工作池（Worker）处理耗时的转写任务，避免阻塞 API。
- **模块化设计**: 项目代码经过重构，具有清晰的模块化结构，易于维护和扩展。
- **配置分离**: 应用的核心参数通过 YAML 文件进行统一管理。

---

## 实时转写核心架构解析

新增的实时语音转写功能通过 WebSocket 实现，其后端架构由四个核心模块协同工作，构成一个高效的流式处理管道。

```mermaid
graph TD
    A[客户端] -- 原始音频流 --> B["app/api/ws.py<br>(调度中心)"];
    B -- receive_bytes() --> C["app/core/vad_processor.py<br>(智能音频切分员)"];
    C -- 检测到完整语音片段 --> D[回调 handle_segmented_audio];
    B -.-> D;
    D -- submit(语音片段) --> E["app/core/worker.py<br>(计算中心)<br>ProcessPoolExecutor"];
    D -- create_task() --> F["ws.py 内部的 process_pipeline 任务"];
    E -- 执行 execute_stream_asr<br>返回 {text, embedding} --> G[future 对象];
    F -- await future --> H[拿到识别结果];
    H -- 使用结果和历史 --> I["app/core/stream_state.py<br>(决策与记忆大脑)"];
    I -- 判断角色/更新状态 --> F;
    F -- 最终结果 --> B;
    B -- send_text() --> A[客户端];

    subgraph "主进程 (FastAPI Event Loop)"
        B
        C
        D
        F
        H
        I
    end

    subgraph "独立的 Worker 子进程"
        E
    end
```

### 1. `app/api/ws.py` - 调度中心

- **角色**: 整个实时处理流程的总指挥和调度员。
- **职责**:
    - 维护与客户端的 WebSocket 连接。
    - 接收原始音频流，并将其传递给 `vad_processor`。
    - 定义 `handle_segmented_audio` 回调函数，在收到切分好的音频片段后，将其提交到 `worker` 进程池进行计算。
    - 创建并管理 `process_pipeline` 异步任务，该任务负责等待 `worker` 的计算结果，并调用 `stream_state` 进行业务逻辑处理。
    - 将最终处理好的文本和角色信息发送回客户端。

### 2. `app/core/vad_processor.py` - 智能音频切分员

- **角色**: 流水线的“第一道关卡”，负责将原始、连续的音频流“粗加工”成高质量的“半成品”。
- **职责**:
    - **缓冲音频**: 持续接收并缓冲来自 `ws.py` 的音频数据。
    - **智能切分**: 利用 VAD (Voice Activity Detection) 模型检测语音活动，但并非简单地切分。它采用一系列高级策略来寻找最佳切割点：
        - **最小发送时长**: 避免切分出不利于 ASR 模型识别的超短句（如“嗯”）。
        - **安全静音填充**: 确保在用户一句话说完后等待一小段静音再切割，防止切断句末的词。
    - **上下文重叠 (Overlapping)**: 这是提升准确率的关键策略。它会保留上一个片段的尾音，并拼接到下一个片段的开头，以解决单词被切割在两个片段之间的问题。

### 3. `app/core/worker.py` - 重计算引擎

- **角色**: 应用的“引擎室”，一个由多个独立进程组成的计算集群，负责执行所有CPU和GPU密集型任务。
- **职责**:
    - **环境隔离**: 通过 `ProcessPoolExecutor` 创建进程池，每个 Worker 进程在启动时独立加载 AI 模型 (`init_worker_process`)，与主服务进程完全隔离。
    - **执行 `execute_stream_asr`**: 这是为实时流定制的核心函数。它在 Worker 进程中运行，接收 `vad_processor` 切分好的音频片段，完成两项主要工作：
        1.  **ASR 推理**: 调用 FunASR 模型将音频转换为文本。
        2.  **声纹提取**: 调用声纹模型，从音频中提取声纹向量 (Embedding)。
    - **返回纯数据**: 执行完毕后，它将 `text` 和 `embedding` 打包成一个字典返回给主进程，不参与任何业务逻辑。

### 4. `app/core/stream_state.py` - 决策与记忆大脑

- **角色**: 为每一次独立的 WebSocket 连接提供记忆和决策能力。
- **职责**:
    - **状态机管理**: 将会话分为 `COLD_START`（冷启动）和 `CRUISING`（巡航）两个阶段。
        - **冷启动**: 在会话之初，负责收集信息，判断何时触发 LLM 进行角色“锚定”。
        - **巡航**: 角色锚定后，优先通过快速的声纹比对 (`match_role_by_voice`) 识别说话人。
    - **记忆存储**: 维护 `buffer_history` (对话历史) 和 `spk_clusters` (按角色分类的声纹库)。
    - **决策支持**: 提供 `check_trigger_condition` 等方法，帮助 `ws.py` 判断是否应该调用昂贵的 LLM，并通过 `register_voiceprints`、`update_anchor` 等方法动态更新声纹库。

---

## 📂 项目结构

项目的主要代码都在 `app` 目录下，结构如下：

```
app/
├─── api/           # API 接口模块 (按功能划分)
│    ├─── auth.py
│    ├─── history.py
│    ├─── transcription.py
│    └─── ws.py (实时接口)
├─── core/          # 核心共享组件
│    ├─── globals.py
│    ├─── stream_state.py
│    ├─── vad_processor.py
│    └─── worker.py
├─── db/            # 数据库连接逻辑
│    └─── db.py
├─── service/       # 业务逻辑服务 (如登录、注册)
│    └─── ...
├─── config/        # 配置文件
│    └─── base.yaml
└─── app.py         # FastAPI 应用主入口
```

## 🚀 快速开始

请按照以下步骤在您的本地环境中设置和运行本项目。

### 1. 环境准备

推荐使用 Conda 创建一个独立的 Python 3.10 环境。

```bash
# 创建环境
conda create -n meeting python=3.10

# 激活环境
conda activate meeting
```

### 2. 安装依赖

在激活 Conda 环境后，使用 `pip` 安装 `requirements.txt` 中列出的所有依赖。

```bash
pip install -r requirements.txt
```
> **注意**: `requirements.txt` 中已为部分仅支持 Linux 的库（如 `triton`, `modelscope`）添加了平台标记，使其在 macOS 上安装时会被自动跳过。

### 3. 数据库设置

- **导入数据表**: 将项目根目录下的 `scripts/meeting.sql` 文件导入到您的 MySQL 数据库中。
- **修改连接信息**: **重要！** 打开 `app/config/mac_local.yaml` 或对应环境配置文件，在 `db` 节点下修改 `host`, `port`, `user`, `password`, `database` 等参数，以匹配您自己的数据库配置。

### 4. 模型和应用配置

- **下载模型**: 项目所需的 ASR, VAD, Punc, SPK 等模型需要您从 ModelScope 或 FunASR 官方渠道下载。
- **修改配置**: 打开 `app/config/base.yaml` 文件，在 `paths` 部分，将 `asr_model`, `vad_model` 等路径修改为您本地存放模型的实际路径。您也可以在此文件中调整服务器端口等其他设置。

### 5. 运行服务

完成以上所有步骤后，在项目根目录运行以下命令来启动应用：

```bash
uvicorn app.app:app --host 0.0.0.0 --port 8000
```

服务启动后，您可以通过 `http://<host>:<port>/docs` 访问自动生成的 API 文档页面。

## 📚 API 概览

本项目 API 按照功能被划分到不同的模块中，主要包括：

- **Authentication**: 用户认证 (登录、注册、登出)
- **User Management**: 用户管理 (查询、编辑、删除)
- **Voiceprint Management**: 声纹管理 (注册、查询、删除)
- **Transcription History**: 转写历史记录 (查询、详情、更新)
- **Transcription**: 核心转写服务 (提交转写任务、查询结果)
- **WebSocket**: 实时语音转写服务。