Работа с AI-ассистентом в SpeechSense

Вы можете получить из диалога информацию, извлеченную с помощью AI-ассистента. Его можно подключать к аудиодиалогам и к чатам. В этом руководстве рассмотрено подключение к чатам. В качестве примера приведена переписка клиента с турагентством.

Чтобы получить нужную информацию из чата с помощью AI-ассистента:

1. Подготовьте облако к работе.
2. Подготовьте инфрастуктуру.
3. Создайте AI-ассистента.
4. Загрузите данные в проект.
5. Проверьте результат работы AI-ассистента в интерфейсе SpeechSense.
6. Получите информацию о диалоге с помощью API.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работеПодготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

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

Подробнее об облаках и каталогах.

Для управления платежным аккаунтом у пользователя должна быть назначена роль billing.accounts.editor, billing.accounts.admin или billing.accounts.owner на нужный платежный аккаунт.

Необходимые платные ресурсыНеобходимые платные ресурсы

• Сервис SpeechSense: количество символов в каждом текстовом диалоге (см. тарифы SpeechSense).
• AI-ассистент: генерация текста (см. тарифы Yandex AI Studio). Тарификация за использование ассистента начинается с момента его включения.

Подготовьте инфраструктуруПодготовьте инфраструктуру

Создайте сервисный аккаунтСоздайте сервисный аккаунт

Создайте API-ключ для сервисного аккаунтаСоздайте API-ключ для сервисного аккаунта

Создайте пространство и привяжите платежный аккаунтСоздайте пространство и привяжите платежный аккаунт

Добавьте сервисный аккаунт в пространствоДобавьте сервисный аккаунт в пространство

Создайте подключение для чатаСоздайте подключение для чата

Создайте проектСоздайте проект

Создайте AI-ассистентаСоздайте AI-ассистента

Загрузите данные в проектЗагрузите данные в проект

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

1. Клонируйте репозиторий cloudapi:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

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

   pip install grpcio-tools
   

3. Перейдите в папку с репозиторием 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
   

4. В папке upload_data создайте Python-скрипт upload_text.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 text_pb2
   from google.protobuf.timestamp_pb2 import Timestamp
   
   def upload_talk(connection_id: str, metadata: Dict[str, str], api_key: str, text_data):
      credentials = grpc.ssl_channel_credentials()
      channel = grpc.secure_channel('api.speechsense.yandexcloud.net:443', credentials)
   
      talk_service_stub = talk_service_pb2_grpc.TalkServiceStub(channel)
   
      messageList = []
      for message in text_data['messages']:
         timestamp = Timestamp()
         timestamp.FromJsonString(value=str(message['timestamp']))
         messageProto = text_pb2.Message(
            user_id=str(message['user_id']),
            text=text_pb2.TextPayload(text=str(message['text'])),
            timestamp=timestamp
         )
         messageList.append(messageProto)
   
      # Формирование запроса к API
      request = talk_service_pb2.UploadTextRequest(
         metadata=talk_service_pb2.TalkMetadata(
            connection_id=str(connection_id),
            fields=metadata),
         text_content=text_pb2.TextContent(
            messages=messageList)
      )
   
      # Тип аутентификации — API-ключ
      response = talk_service_stub.UploadText(request, metadata=(
         ('authorization', f'Api-Key {api_key}'),
      ))
   
      # Вывести идентификатор диалога
      print(f'Dialog ID: {response.talk_id}')
   
   if __name__ == '__main__':
      parser = argparse.ArgumentParser()
      parser.add_argument('--key', required=True, help='API key', type=str)
      parser.add_argument('--connection-id', required=True, help='Connection ID', type=str)
      parser.add_argument('--text-path', required=True, help='JSON with text chat data', type=str)
      parser.add_argument('--meta-path', required=False, help='JSON with the dialog metadata', type=str, default=None)
      args = parser.parse_args()
   
      with open(args.meta_path, 'r') as fp:
         metadata = json.load(fp)
   
      with open(args.text_path, 'r') as fp:
         text_data = json.load(fp)
      upload_talk(args.connection_id, metadata, args.key, text_data)
   

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

   {
      "operator_name": "Светлана",
      "operator_id": "24",
      "client_name": "Михаил",
      "client_id": "145",
      "date": "2025-12-01T12:34:19+03:00",
      "direction_outgoing": "false",
      "language": "ru-ru"
   }
   

6. В папке upload_data создайте файл chat.json с текстовыми сообщениями:

   {
      "messages": [
         {
            "user_id": 145,
            "text" : "Здравствуйте, есть ли у вас экскурсионные туры?",
            "timestamp" : "2025-12-01T12:34:19+03:00"
         },
         {
            "user_id": 24,
            "text" : "Здравствуйте, Михаил. Да, есть экскурсионные туры в Европу и Азию. Какое направление вас интересует?",
            "timestamp" : "2025-12-01T12:35:45+03:00"
         },
         {
            "user_id": 145,
            "text" : "А в какие страны Азии можно поехать без визы?",
            "timestamp" : "2025-12-01T12:37:14+03:00"
         },
         {
            "user_id": 24,
            "text" : "Южная Корея.",
            "timestamp" : "2025-12-01T12:38:55+03:00"
         },
         {
            "user_id": 145,
            "text" : "Спасибо, я подумаю. До свидания.",
            "timestamp" : "2025-12-01T12:41:21+03:00"
         },
         {
            "user_id": 24,
            "text" : "До свидания.",
            "timestamp" : "2025-12-01T12:41:50+03:00"
         }
      ]
   }
   

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

   export API_KEY=<секретная_часть_API-ключа>
   

8. Запустите скрипт upload_text.py:

   python3 upload_text.py \
      --text-path chat.json \
      --meta-path metadata.json \
      --connection-id <идентификатор_подключения> \
      --key ${API_KEY}
   

   Результат:

   Dialog ID: audh5bbnrstk********
   

   Сохраните идентификатор созданного диалога, он понадобится далее для работы с API.

Проверьте результат работы AI-ассистента в интерфейсе SpeechSenseПроверьте результат работы AI-ассистента в интерфейсе SpeechSense

Чтобы посмотреть, какую тематику определил AI-ассистент для диалога:

1. Откройте главную страницу SpeechSense.
2. Перейдите в нужное пространство, затем выберите проект chats-travel-agency.
3. На вкладке Диалоги включите опцию Ассистенты.

Под строкой диалога отобразится строка с указанием тематики Экскурсии. Эту тематику AI-ассистент определил как наиболее подходящую диалогу.

Получите информацию о диалоге с помощью APIПолучите информацию о диалоге с помощью API

Получите идентификаторы AI-ассистента и его поляПолучите идентификаторы AI-ассистента и его поля

curl \
    --request POST \
    --header "Authorization: Api-Key $API_KEY" \
    --url 'https://rest-api.speechsense.yandexcloud.net/speechsense/v1/assistants/list' \
    --data '{
              "projectId": "<идентификатор_проекта>"
            }'

{
  "assistants": [
    {
      "id": "eagdf4es87u0********",
      "project_id": "eags34o1skdi********",
      "model_id": "YGPT_LITE",
      "name": "Тематика диалога",
      "description": "",
      "prompt": "Ты оцениваешь диалог оператора и клиента контактного центра. Будь крайне внимателен при ответе. \nОпредели тематику, с которой обращается клиент, на основе следующего списка: Виза, Страна, Экскурсии. \nЕсли ничего из перечисленного не подходит, укажи значение «Иное».",
      "fields": [
        {
          "id": "eagldsqk9fp4********",
          "name": "Тематика",
          "description": "Наиболее подходящая тематика.",
          "type": "ASSISTANT_FIELD_TYPE_STRING"
        }
      ],
      "enabled": true,
      "labels": {},
      "created_at": "2025-11-13T23:38:00.686738Z",
      "created_by": "ajegrmkclceh********",
      "modified_at": "2025-11-14T01:32:48.358727Z",
      "modified_by": "ajegrmkclceh********"
    }
  ]
}

grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/speechsense/v1/assistants_service.proto \
  -rpc-header "Authorization: Api-Key $API_KEY" \
  -d '{
        "project_id": "<идентификатор_проекта>"
      }' \
  api.speechsense.yandexcloud.net:443 \
  yandex.cloud.speechsense.v1.AssistantsService.List

{
  "assistants": [
    {
      "id": "eagdf4es87u0********",
      "projectId": "eags34o1skdi********",
      "modelId": "YGPT_LITE",
      "name": "Тематика диалога",
      "prompt": "Ты оцениваешь диалог оператора и клиента контактного центра. Будь крайне внимателен при ответе. \nОпредели тематику, с которой обращается клиент, на основе следующего списка: Виза, Страна, Экскурсии. \nЕсли ничего из перечисленного не подходит, укажи значение «Иное».",
      "fields": [
        {
          "id": "eagldsqk9fp4********",
          "name": "Тематика",
          "description": "Наиболее подходящая тематика.",
          "type": "ASSISTANT_FIELD_TYPE_STRING"
        }
      ],
      "enabled": true,
      "createdAt": "2025-11-13T23:38:00.686738Z",
      "createdBy": "ajegrmkclceh********",
      "modifiedAt": "2025-11-14T01:32:48.358727Z",
      "modifiedBy": "ajegrmkclceh********"
    }
  ]
}

Сохраните значения полей:

• assistants.id — идентификатор AI-ассистента Тематика диалога.
• assistants.fields.id — идентификатор поля Тематика.

Получите информацию о диалогеПолучите информацию о диалоге

curl \
    --request POST \
    --header "Authorization: Api-Key $API_KEY" \
    --url 'https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/get' \
    --data '{
              "projectId": "<идентификатор_проекта>",
              "talkIds": [
                "string"
              ],
              "resultsMask": 
                {
                  "paths": [
                    "assistants"
                  ]
                }
            }'

{
  "talk": [
    {
      "id": "audh5bbnrstk********",
      "organization_id": "********",
      "space_id": "f3fuclf1kufs********",
      "connection_id": "eagojm8e3bfv********",
      "project_ids": [
        "eags34o1skdi********"
      ],
      ...
      "assistants": {
        "assistant_results": [
          {
            "assistant_id": "eagdf4es87u0********",
            "results": [
              {
                "field_id": "eagldsqk9fp4********",
                "string_result": "Экскурсии"
              }
            ]
          }
        ]
      },
      ...
    }
  ]
}

grpcurl \
    -format json \
    -import-path ~/cloudapi/ \
    -import-path ~/cloudapi/third_party/googleapis/ \
    -proto ~/cloudapi/yandex/cloud/speechsense/v1/talk_service.proto \
    -rpc-header "Authorization: Api-Key $API_KEY" \
    -d '{
          "project_id": "<идентификатор_проекта>",
          "talk_ids": [
            <идентификатор_диалога>
          ],
          "results_mask": 
            {
              "paths": [
                "assistants"
              ]
            }
        }' \
    api.speechsense.yandexcloud.net:443 \
    yandex.cloud.api.speechsense.v1.TalkService.Get

{
  "talk": [
    {
      "id": "audh5bbnrstk********",
      "organizationId": "********",
      "spaceId": "f3fuclf1kufs********",
      "connectionId": "eagojm8e3bfv********",
      "projectIds": [
        "eags34o1skdi********"
      ],
      ...
      "assistants": {
        "assistantResults": [
          {
            "assistantId": "eagdf4es87u0********",
            "results": [
              {
                "fieldId": "eagldsqk9fp4********",
                "stringResult": "Экскурсии"
              }
            ]
          }
        ]
      },
      ...
    }
  ]
}

Удалите ресурсыУдалите ресурсы

Некоторые ресурсы платные. Чтобы за них не списывалась плата, удалите проект SpeechSense, если вы больше не будете его использовать. AI-ассистент будет удален при удалении проекта.