Связаться с намиПодключиться

Загрузка аудиоданных с разбиением через gRPC API

Статья создана
Обновлена 28 мая 2025 г.

Эта инструкция поможет вам загрузить в SpeechSense данные для распознавания и анализа речи через API. В примере заданы параметры:

  • формат аудио — WAV;
  • метаданные диалога хранятся в файле metadata.json.

Аутентификация происходит от имени сервисного аккаунта с помощью IAM-токена или API-ключа.

Для ознакомления с функциональностью SpeechSense вы можете использовать быструю загрузку аудиоданных через консоль управления.

Если вы хотите загрузить переписку из чата вместо аудиозаписи разговора, обратитесь к инструкции.

Перед началом работы

Для работы с API Yandex Cloud потребуется Git, Python 3.6 или старше и пакет grpcio-tools. Узнайте, как установить Python.

Чтобы подготовиться к загрузке аудиоданных:

  1. Создайте подключение типа Одноканальное аудио с дополнительными настройками разбиения диалога.

    Если вы хотите загрузить связанные диалоги, добавьте в общие метаданные подключения строковый ключ ticket_id. По этому ключу диалоги будут связаны.

  2. Создайте проект с новым подключением.

    В созданный проект и подключение будут загружены аудиозаписи разговоров.

  3. В консоли управления создайте сервисный аккаунт.

  4. Добавьте сервисный аккаунт в пространство с ролью Data editor. Это позволит сервисному аккаунту загружать данные в SpeechSense.

  5. Чтобы аутентифицироваться в API Yandex Cloud, создайте API-ключ или IAM-токен для сервисного аккаунта.

  6. Склонируйте репозиторий API Yandex Cloud:

    git clone https://github.com/yandex-cloud/cloudapi

  7. Установите пакет grpcio-tools с помощью менеджера пакетов pip:

    pip install grpcio-tools

Загрузить данные

Примечание

Даты указываются в формате ISO 8601 UTC с нулевым смещением времени. Если необходимо указать московское время, добавьте +03:00 вместо Z в конец строки: 2025-04-24T14:34:19+03:00.

Максимальная длительность аудио — 4 часа.

  1. Перейдите в папку с репозиторием API Yandex Cloud, создайте папку upload_data, сгенерируйте в ней код интерфейса клиента и перейдите в папку upload_data:

    cd <путь_к_папке_cloudapi> && \
mkdir upload_data && \
python3 -m grpc_tools.protoc -I . -I third_party/googleapis \
     --python_out=./upload_data/ \
     --grpc_python_out=./upload_data/ \
     google/api/http.proto \
     google/api/annotations.proto \
     yandex/cloud/api/operation.proto \
     google/rpc/status.proto \
     yandex/cloud/operation/operation.proto \
     yandex/cloud/validation.proto \
     yandex/cloud/speechsense/v1/*.proto \
     yandex/cloud/speechsense/v1/*/*.proto
cd upload_data

  2. В папке upload_data создайте Python-скрипт upload_grpc.py, который загрузит данные в подключение SpeechSense. Файл будет передаваться через чанки:

    import argparse
import json
from typing import Dict

import grpc

from yandex.cloud.speechsense.v1 import talk_service_pb2
from yandex.cloud.speechsense.v1 import talk_service_pb2_grpc
from yandex.cloud.speechsense.v1 import audio_pb2


# Настройте размер передаваемого чанка
CHUNK_SIZE_BYTES = 1 * 1024 * 1024


def upload_audio_requests_iterator(connection_id: str, metadata: Dict[str, str], audio_path: str):
    # Передайте общие метаданные диалога
    yield talk_service_pb2.StreamTalkRequest(
        metadata=talk_service_pb2.TalkMetadata(
            connection_id=connection_id,
            fields=metadata
        )
    )
    # Передайте метаданные аудиозаписи
    yield talk_service_pb2.StreamTalkRequest(
        audio=audio_pb2.AudioStreamingRequest(
            audio_metadata=audio_pb2.AudioMetadata(
                container_audio=audio_pb2.ContainerAudio.ContainerAudioType.CONTAINER_AUDIO_TYPE_WAV
            )
        )
    )
    with open(audio_path, mode='rb') as fp:
        data = fp.read(CHUNK_SIZE_BYTES)
        while len(data) > 0:
            # Передайте очередной чанк байт аудиофайла
            yield talk_service_pb2.StreamTalkRequest(
                audio=audio_pb2.AudioStreamingRequest(
                    chunk=audio_pb2.AudioChunk(data=data)
                )
            )
            data = fp.read(CHUNK_SIZE_BYTES)


def upload_talk(endpoint: str, connection_id: str, metadata: Dict[str, str], token: str, audio_path: str):
    # Установите соединение с сервером
    credentials = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel(endpoint, credentials)
    talk_service_stub = talk_service_pb2_grpc.TalkServiceStub(channel)

    # Передайте итератор по запросам и получите ответ от сервера
    response = talk_service_stub.UploadBadge(
        upload_audio_requests_iterator(connection_id, metadata, audio_path, audio_type),
        metadata=(('authorization', token),)
    )

    print(f'Talk id: {response.talk_id}')


if __name__ == '__main__':
    parser = argparse.ArgumentParser()

    parser.add_argument('--endpoint', required=False, help='API Endpoint', type=str, default='api.speechsense.yandexcloud.net:443')
    parser.add_argument('--token', required=True, help='IAM token', type=str)
    parser.add_argument('--token-type', required=False, help='Token type', choices=['iam-token', 'api-key'], default='iam-token', type=str)
    parser.add_argument('--connection-id', required=True, help='Connection Id', type=str)
    parser.add_argument('--audio-path', required=True, help='Audio file path', type=str)
    parser.add_argument('--meta-path', required=False, help='Talk metadata json', type=str, default=None)
args = parser.parse_args()

    required_keys = [
        "operator_name",
        "operator_id",
        "date"
    ]
    with open(args.meta_path, 'r') as fp:
        metadata = json.load(fp)
    for required_key in required_keys:
        if required_key not in metadata:
            raise ValueError(f"Metadata doesn't contain one of the reqiured keys: {required_key}.")

    if args.token_type == 'iam-token':
        token = f'Bearer {args.token}'
    elif args.token_type == 'api-key':
        token = f'Api-Key {args.token}'

    if args.audio_type is None:
        file_extension = args.audio_path.split('.')[-1]
        if file_extension not in ['wav', 'ogg', 'mp3']:
            raise ValueError(f"Unknown file extension: {file_extension}. Specify the --audio-type argument.")
        audio_type = file_extension
    else:
        audio_type = args.audio_type

    upload_talk(args.endpoint, args.connection_id, metadata, token, args.audio_path, audio_type)

  3. В папке upload_data создайте файл metadata.json с метаданными разговора:

    {
    "operator_name": "<имя_оператора>",
    "operator_id": "<идентификатор_оператора>",
    "date": "<дата_начала>",
    "language": "<язык>",
    <дополнительные_параметры_подключения>
}

    Поля в файле должны соответствовать параметрам подключения, в которое вы загружаете аудиозаписи. В шаблоне выше указаны обязательные поля для подключений типа Одноканальное аудио. Если вы добавляли другие параметры в подключение, укажите их в файле metadata.json. Например, если вы загружаете связанные диалоги, добавьте в файл параметр:

    {
   ...
   "ticket_id": "<номер_задачи>"
}

  4. Задайте API-ключ сервисного аккаунта:

    export API_KEY=<API-ключ_сервисного_аккаунта>

    Если вы используете IAM-токен, передайте его вместо API-ключа:

    export IAM_TOKEN=<IAM-токен_сервисного_аккаунта>

  5. Запустите скрипт upload_grpc.py, передав нужные параметры:

    python3 upload_grpc.py \
   --audio-path <аудиофайл> \
   --meta-path <метаданные> \
   --connection-id <идентификатор_подключения> \
   --key ${API_KEY}

    Где:

    • --audio-path — путь к файлу с аудиозаписью диалога.
    • --meta-path — путь к файлу с метаданными диалога.
    • --connection-id — идентификатор подключения, в которое вы загружаете данные.
    • --key — API-ключ для аутентификации. Если вы используете IAM-токен, укажите переменную окружения IAM_TOKEN вместо API_KEY.
Предыдущая
Загрузка аудиоданных через gRPC API
Следующая
Загрузка переписки из чата