lintoai/linto-diarization-pyannote

LinTO-diarization 技术文档

1. 镜像概述和主要用途

LinTO-diarization 是 LinTO 平台的说话人分轨服务，具备猜测说话人数以及在提供目标说话人语音样本时识别特定说话人的能力。该服务可作为独立分轨服务部署，也可作为微服务集成到分布式系统中。

2. 核心功能和特性

• 灵活部署模式：支持独立 HTTP API 服务或微服务（通过 Celery 与消息代理）两种部署方式
• 说话人分轨能力：自动猜测说话人数或指定固定/最大说话人数
• 说话人识别：在提供目标说话人语音样本时，可识别特定说话人身份
• 多接口支持：提供 HTTP API（含 OpenAPI 文档）和消息队列两种调用方式
• 资源优化：通过共享文件夹处理大音频文件，避免消息代理数据拥塞
• GPU 加速：支持 CPU/GPU 运行，可配置多设备资源

3. 使用场景和适用范围

• 独立分轨服务：需通过 HTTP API 直接调用说话人分轨功能的场景
• 微服务架构：集成到基于消息队列的分布式语音处理系统（如 LinTO 生态）
• 语音内容分析：会议记录、访谈录音等场景的说话人分离与统计
• 语音转写后处理：为语音转写结果添加说话人标签

4. 前提条件

4.1 基础依赖

• Docker：需安装并运行 Docker 环境
• 网络：部署微服务模式时需消息代理（如 Redis）
• 存储：需共享文件夹（挂载至容器 /opt/audio）存储音频文件，避免大文件通过消息代理传输

4.2 说话人识别依赖

若启用说话人识别功能，需部署 Qdrant 向量数据库存储说话人嵌入向量：

bash
docker run \
    -p 6333:6333 \  # Qdrant 默认端口
    -v ./qdrant_storage:/qdrant/storage:z \
    qdrant/qdrant

5. 部署指南

5.1 镜像获取

5.1.1 构建镜像

bash
git clone https://github.com/linto-ai/linto-diarization.git
cd linto-diarization
docker build . -t linto-diarization-pyannote:latest -f pyannote/Dockerfile 

5.1.2 拉取镜像

bash
docker pull lintoai/linto-diarization-pyannote

5.2 HTTP 独立服务模式

通过 HTTP API 提供独立分轨服务。

5.2.1 配置 .env 文件

参考 https://github.com/linto-ai/linto-diarization/blob/master/pyannote/.envdefault 创建 .env 文件，配置参数见 6. 配置参数说明。

5.2.2 运行容器

bash
docker run --rm \
-v <宿主机共享文件夹路径>:/opt/audio \  # 挂载共享音频文件夹
-p <宿主机端口>:80 \  # 映射容器 80 端口到宿主机（如 8080:80）
--env-file .env \  # 加载环境变量
# 启用 GPU（如有）
--gpus all \  # 可选，启用所有 GPU
linto-diarization-pyannote:latest

5.2.3 启用说话人识别

需挂载说话人语音样本文件夹（样本需按说话人名称命名文件/文件夹）：

bash
docker run ... -v </path/to/speaker/samples>:/opt/speaker_samples  # 或自定义路径（通过 SPEAKER_SAMPLES_FOLDER 指定）

若需复用 Qdrant 现有向量集合，设置环境变量 QDRANT_RECREATE_COLLECTION=false。

5.3 Celery 微服务模式

作为微服务部署，通过 Celery 监听消息代理中的分轨任务。

5.3.1 前置条件

• 消息代理（如 Redis）已部署，地址通过 SERVICES_BROKER 配置
• 共享文件夹已挂载（同 4.1）

5.3.2 配置 .env 文件

基础参数同 HTTP 模式，额外添加微服务特有参数（见 6. 配置参数说明）。

5.3.3 启动容器（docker-compose）

创建 docker-compose.yml：

yaml
version: '3.7'

services:
  diarization-service:
    image: linto-diarization-pyannote:latest
    volumes:
      - /path/to/shared/folder:/opt/audio  # 共享音频文件夹
    env_file: .env  # 加载环境变量
    deploy:
      replicas: 1  # 根据需求调整副本数
    networks:
      - your-net  # 连接至微服务网络

networks:
  your-net:
    external: true  # 使用现有网络

启动服务：

bash
docker stack deploy --resolve-image always --compose-file docker-compose.yml your_stack

6. 配置参数说明

6.1 通用环境变量

6.2 微服务模式特有变量

7. 使用方法

7.1 HTTP API

7.1.1 健康检查 /healthcheck

• 方法：GET
• 描述：返回服务状态
• 响应："1"（服务正常）

7.1.2 分轨接口 /diarization

• 方法：POST

• 请求参数：

  • file：WAV 音频文件（必填）
  • speaker_count：固定说话人数（可选，整数，自动聚类时留空）
  • max_speaker：最大说话人数（可选，整数，当 speaker_count 未指定时生效）
  • speaker_names：目标说话人名称（可选，仅在提供语音样本时生效）：
    • 空字符串 ""：禁用识别
    • "*"：识别所有说话人
    • JSON 数组或 | 分隔字符串：指定说话人列表（如 ["spk1","spk2"] 或 "spk1|spk2"）

• 响应示例（application/json）：

json
{
  "speakers": [
    {"spk_id": "spk5", "duration": 2.2, "nbr_seg": 1}
  ],
  "segments": [
    {"seg_id": 1, "spk_id": "spk5", "seg_begin": 0.0, "seg_end": 2.2}
  ]
}

7.1.3 API 文档 /docs

• 描述：提供 OpenAPI/Swagger 交互式文档界面

7.2 消息代理调用（微服务模式）

通过消息代理（如 Redis）提交分轨任务，参数同 HTTP API，区别在于 file 为共享文件夹中的相对路径。

任务参数

• file：共享文件夹中音频文件的相对路径（字符串，必填）
• speaker_count、max_speaker、speaker_names：同 HTTP API（可选）

响应格式

同 /diarization 接口响应（JSON 结构）。

8. 测试示例

8.1 HTTP API 测试（curl）

bash
curl -X POST "http://<服务地址>:<端口>/diarization" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test.wav;type=audio/x-wav" \
  -F "speaker_count=2"

9. 许可证

本项目基于 AGPLv3 许可证开源（详见 https://github.com/linto-ai/linto-diarization/blob/master/LICENSE%EF%BC%89%E3%80%82

10. 依赖说明

• 基于 https://github.com/pyannote/pyannote-audio 分轨框架（MIT 许可证）。