LinTO 转录服务

概述

转录服务是用于请求音视频转录的API服务。该服务允许您：

• 从多种音视频文件格式请求异步转录
• 指定转录子任务，如说话人分离和标点添加
• 跟踪转录任务的状态和进度
• 自动将转录结果存储在数据库中（避免同一音频文件被多次转录）
• 获取不同格式和选项的转录结果

目录

• 前提条件
• 部署
  • 使用 docker run
  • 使用 docker compose
  • 环境变量
• API
  • /list-services
    • 子服务解析
  • /transcribe
    • 转录配置
  • /job/{jobid}
  • /results/{result_id}
    • 转录结果
  • /job-log/{jobid}
  • /docs
• 使用示例
• 许可协议

前提条件

使用转录服务前，您必须至少具备：

• 一个或多个运行中的linto-stt实例，且配置了相同的SERVICE_NAME（LANGUAGE必须兼容）
• 一个运行在SERVICES_BROKER的REDIS broker
• 一个运行在MONGO_HOST:MONGO_PORT的MongoDB数据库

可选地，如需使用说话人分离或标点功能，还需：

• 一个或多个运行中的linto-diarization-worker（版本>1.2.0），用于说话人分离，需配置在同一服务broker上（LANGUAGE必须兼容）
• 一个或多个运行中的linto-punctuation-worker（版本>1.2.0），用于文本标点，需配置在同一服务broker上（LANGUAGE必须兼容）

为使不同服务间共享音频文件，它们必须配置相同的共享卷RESSOURCE_FOLDER。

部署

使用 docker run

1. 首先构建镜像：

bash
cd linto-transcription-service &&
docker build . -t transcription_service

2. 创建并填充.env文件

bash
cp .envdefault .env

按照环境变量部分描述填充.env文件

3. 启动容器：

bash
docker run --rm -it -p $SERVING_PORT:8080 \
    -v $YOUR_SHARED_FOLDER:/opt/audio \
    --env-file .env \
    --name my_transcription_api \
    transcription_service \
    /bin/bash

将SERVING_PORT和YOUR_SHARED_FOLDER替换为您的值。

使用 docker compose

1. 创建并填充.env文件

bash
cp .envdefault .env

按照环境变量部分描述填充.env文件

2. 启动compose

bash
docker-compose up .

环境变量

*: 参见子服务解析

心跳设置

API

转录服务提供REST API用于提交转录请求。

转录服务围绕两个概念展开：

• 由job_id标识的异步任务：job_id表示正在进行的转录任务
• 由result_id标识的转录结果

典型的转录流程如下：

1. 在/transcribe提交文件和转录配置。该路由返回201状态码和job_id
2. 使用/job/{job_id}路由跟踪任务进度。任务完成时，将返回201状态码和result_id
3. 使用/results/{result_id}路由获取转录结果，可指定所需格式和选项

/list-services

list-services GET路由用于获取可用的转录子服务。

返回一个JSON对象，包含按服务类型索引的已部署服务列表。列出的服务会根据设置的LANGUAGE参数进行过滤。

json
{
  "diarization": [ # 服务类型
    {
      "service_name": "diarization-1", # 服务名称。在转录配置中用作参数以调用此特定服务
      "service_type": "diarization", # 服务类型
      "service_language": "*", # 支持的语言
      "queue_name": "diarization-queue", # 此服务使用的Celery队列
      "info": "说话人分离服务", # 服务信息
      "instances": [ # 此特定服务的实例
        {
          "host_name": "feb42aacd8ad", # 实例唯一ID
          "last_alive": ***, # 最后心跳时间
          "version": "1.2.0", # 服务版本
          "concurrency": 1 # 实例并发数
        }
      ]
    }
  ],
  "punctuation": [
    {
      "service_name": "punctuation-1",
      "service_type": "punctuation",
      "service_language": "fr-FR",
      "queue_name": "punctuation-queue",
      "info": "标点服务",
      "instances": [
        {
          "host_name": "b0e9e24349a9",
          "last_alive": ***,
          "version": "1.2.0",
          "concurrency": 1
        }
      ]
    }
  ]
}

子服务解析

子服务解析是允许转录服务使用适当的可选子服务（如说话人分离或标点预测）的机制。当子任务配置中未传递serviceName时应用解析。

有三种解析服务名称的策略：

• ANY：使用任何兼容的子服务
• DEFAULT：使用服务的默认子服务（必须声明）
• STRICT：如果未指定服务，则引发错误

解析策略在启动时通过RESOLVE_POLICY环境变量声明：ANY | DEFAULT | STRICT（默认ANY）。

默认服务名称必须在启动时声明：<SERVICE_TYPE>_DEFAULT。例如，默认标点子服务为"punctuation-1"，则PUNCTUATION_DEFAULT=punctuation1。

语言兼容性

子服务兼容的条件是其子服务的语言与转录服务的语言兼容。

/transcribe

/transcribe路由接受包含音频文件的POST请求。

该路由接受multipart/form-data请求。

响应格式可以是application/json或text/plain，由请求头的accept字段指定。

如果请求被接受，响应应为201状态码，包含JSON或文本格式的jobid。

accept: application/json时：

json
{"jobid" : "the-job-id"}

accept: text/plain时：

the-job-id

如果force_sync标志设置为true，请求返回200状态码和转录结果（参见转录结果），使用与/result/{result_id}路由相同的accept选项。

不建议对大文件使用force_sync，因为它会在整个转录期间阻塞工作进程。

此外，还可以上传时间戳文件（与音频文件一起），其中包含要转录的片段时间戳。时间戳文件是文本文件，每行一个片段，可包含可选的说话人ID：

txt
# start stop [speakerid]
0.0 7.05 1
7.05 13.0

转录配置

转录配置描述请求的转录输入参数和标志。它允许设置：

• 转录目标语言
• 语音活动检测（VAD）参数
• 说话人分离参数
• 标点参数

结构如下：

json
{
  "language": "fr-FR",          # 转录目标语言（默认：null）
  "vadConfig": {
    "enableVad": true,          # 启用语音活动检测（默认：true）
    "methodName": "WebRTC",     # VAD方法（默认：WebRTC）
    "minDuration": 30,          # 语音片段最小持续时间（默认：0）
    "maxDuration": 1200         # 语音片段最大持续时间（默认：1200）
  },
  "diarizationConfig": {
    "enableDiarization": true,  # 是否启用说话人分离（默认：false）
    "numberOfSpeaker": null,    # 如果设置，强制说话人数量
    "maxNumberOfSpeaker": 50,   # 如果设置且未设置numberOfSpeaker，限制最大说话人数量
    "speakerIdentification": null,  # 要识别的说话人名称（取决于说话人分离worker的安装）
    "serviceName": null         # 强制服务名称（参见子服务解析）
  },
  "punctuationConfig": {
    "enablePunctuation": false, # 是否添加标点（默认：false）
    "serviceName": null         # 强制服务名称（参见子服务解析）
  }
}

serviceName可用于指定特定的子服务版本。可用服务可在/list-services查看。

target language可以是""（自动语言检测），或描述语言的常用标签（"fr"、"fr-FR"、"French"——参见[**] 注意，此参数的作用与用于文本标准化的环境变量LANGUAGE不同（后者仅限于BCP-47代码）。

要启用说话人识别，可将说话人分离配置的speakerIdentification字段设置为通配符"*"（启用所有说话人）或说话人名称列表（JSON格式，例如："["John Doe", "Bob"]"）。说话人分离worker必须已配置为可匹配所有说话人名称与一组语音样本。

/job/{jobid}

/job/{jobid} GET路由用于获取给定转录任务的状态。

响应格式为application/json。

• 如果任务状态为started，返回102状态码和进度信息
• 如果任务状态为done，返回201状态码和result_id
• 如果任务状态为pending，返回404状态码。pending可能表示：转录工作进程尚未可用或jobid不存在
• 如果任务状态为failed，返回400状态码

json
{
  # 任务待处理或jobid错误：404
  {"state": "pending"}

  # 任务已开始：102
  {"state": "started", "progress": {"current": 1, "total": 3, "step": "Transcription (75%)"}}

  # 任务已完成：201
  {"state": "done", "result_id" : "result_id"}

  # 任务失败：400
  {"state": "failed", "reason": "Something went wrong"}
}

/results/{result_id}

/results/{result_id} GET路由用于获取与result_id关联的转录结果。

转录结果

accept请求头指定结果格式：

• application/json 返回完整的JSON对象结果；

json
{
  "raw_transcription": "bonjour est-ce que vous allez bien mais oui et vous",                       # 原始转录文本
  "transcription_result": "spk1: Bonjour ! Est-ce que vous allez bien ?\nspk2: Mais oui et vous ?", # 最终转录文本
  "language": "fr",  # 整体转录语言（请求中指定或音频中检测到的主要语言）
  "confidence": 0.9, # 整体转录置信度分数
  "segments": [ # 单个说话人连续语音的片段
    {
      "raw_segment": "bonjour est-ce que vous allez bien", # 语音片段的原始转录
      "segment": "Bonjour ! Est-ce que vous allez bien ?", # 片段的处理后转录（标点、标准化等）
      "start": 0,       # 片段开始时间
      "end": 5.26,      # 片段结束时间
      "duration": 5.26, # 片段持续时间
      "language": "fr", # 片段语言（检测到的主要语言或请求中指定）
      "spk_id": "spk1", # 片段说话人ID
      "words": [        # 片段词语信息
        {
          "word": "bonjour", # 词语
          "start": 0.0,      # 词语开始时间
          "end": 1.02,       # 词语结束时间
          "conf": 0.49       # 词语置信度分数
        },
        {
          "word": "est-ce",
          "start": 3.0,
          "end": 3.84,
          "conf": 0.63
        },
        ...
      ]
    },
    ...
  ]
}

• text/plain 返回纯文本格式的最终转录结果

spk1: Bonjour ! Est-ce que vous allez bien ?
spk2: Mais oui et vous ?

• text/vtt 返回WEBVTT字幕格式的转录结果

WEBVTT Kind: captions; Language: fr

00:00.000 --> 00:05.260
Bonjour ! Est-ce que vous allez bien ?

00:05.270 --> 00:06.710
Mais oui et vous ?

• text/srt 返回SubRip字幕格式的转录结果

1
00:00:00,000 --> 00:00:05,260
Bonjour ! Est-ce que vous allez bien ?

2
00:00:05,270 --> 00:00:06,710
Mais oui et vous ?

查询字符串选项

还可以使用查询字符串指定选项：

• return_raw: 如果设置为true，返回原始转录文本（无标点和后处理）
• convert_number: 如果设置为true，将数字从文字转换为数字
• wordsub: 接受多个格式为originalWord:substituteWord的值，用于在最终转录结果中替换词语

/job-log/{jobid}

/job-log/{jobid} GET路由用于检索任务详情以进行调试。返回原始文本格式的日志。

/docs

/docs路由提供Swagger-UI界面，包含API规范（OAS3）。

还允许使用预填充的可修改参数直接测试请求。

使用示例