Работа с 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: количество символов в каждом текстовом диалоге и анализ диалогов с помощью AI-ассистента (тарифы SpeechSense).

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

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

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

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

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

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

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

Создайте пустой проект с именем chats-travel-agency и подключением chats-default-metadata:

На странице созданного проекта нажмите в левом верхнем углу кнопку ID, чтобы скопировать его идентификатор. Сохраните этот идентификатор, он понадобится далее для работы с API.

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

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

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

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

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

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

2. Создайте и активируйте виртуальное окружение, затем установите пакет grpcio-tools с помощью менеджера пакетов pip:

   python3 -m venv .venv
   source .venv/bin/activate
   python3 -m pip install grpcio-tools
   

   Остальные команды Python выполняйте в этом окружении.

3. В папке с репозиторием API Yandex Cloud создайте папку 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 google.protobuf.timestamp_pb2 import Timestamp
   
   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
   
   
   def upload_talk(connection_id: str, metadata: Dict[str, str], token: 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)
   
       messages = []
       for message in text_data['messages']:
           timestamp = Timestamp()
           timestamp.FromJsonString(message['timestamp'])
           messages.append(text_pb2.Message(
               user_id=str(message['user_id']),
               text=text_pb2.TextPayload(text=message['text']),
               timestamp=timestamp
           ))
   
       request = talk_service_pb2.UploadTextRequest(
           metadata=talk_service_pb2.TalkMetadata(
               connection_id=connection_id,
               fields=metadata
           ),
           text_content=text_pb2.TextContent(messages=messages)
       )
       response = talk_service_stub.UploadText(request, metadata=(('authorization', token),))
       print(f'Dialog ID: {response.talk_id}')
   
   
   if __name__ == '__main__':
       parser = argparse.ArgumentParser()
       parser.add_argument('--key', required=True, help='API key or IAM token')
       parser.add_argument('--key-type', choices=['api-key', 'iam-token'], default='api-key', help='Credentials type')
       parser.add_argument('--connection-id', required=True, help='Connection ID')
       parser.add_argument('--text-path', required=True, help='JSON with text chat data')
       parser.add_argument('--meta-path', required=True, help='JSON with the dialog metadata')
       args = parser.parse_args()
   
       with open(args.meta_path, encoding='utf-8') as fp:
           metadata = json.load(fp)
       with open(args.text_path, encoding='utf-8') as fp:
           text_data = json.load(fp)
   
       token = f'Bearer {args.key}' if args.key_type == 'iam-token' else f'Api-Key {args.key}'
       upload_talk(args.connection_id, metadata, token, text_data)
   

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

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

   Замените дату и имена на данные своего диалога. Дата в метаданных и время сообщений в следующем файле должны соответствовать друг другу.

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

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

   Параметр --key-type по умолчанию равен api-key. Чтобы использовать IAM-токен, передайте --key-type iam-token --key ${IAM_TOKEN}.

   Результат:

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

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

   AI-ассистент обрабатывает диалог асинхронно. Если результат еще не появился, повторите проверку позднее. Готовность анализа отражается в поле talk_state.processing_state в ответе REST API и talkState.processingState в выводе grpcurl: значение PROCESSING_STATE_PROCESSING означает, что обработка продолжается, а PROCESSING_STATE_SUCCESS — что она завершена.

Проверьте результат работы 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" \
    --header "Content-Type: application/json" \
    --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 — идентификатор поля Тематика.

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

В запросе укажите идентификатор диалога, который сохранили после загрузки, и идентификатор проекта. Маска assistants ограничит ответ результатами работы AI-ассистентов и базовыми данными диалога.

curl \
    --request POST \
    --header "Authorization: Api-Key $API_KEY" \
    --header "Content-Type: application/json" \
    --url 'https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/get' \
    --data '{
              "projectId": "<идентификатор_проекта>",
              "talkIds": [
                "<идентификатор_диалога>"
              ],
              "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.speechsense.v1.TalkService.Get

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

Получите результаты для нескольких диалоговПолучите результаты для нескольких диалогов

Чтобы получить данные нескольких диалогов, передайте их идентификаторы одним массивом в запросе Get. Рекомендуемый размер пакета — до 100 диалогов. Если ответ получается слишком большим, уменьшите пакет или ограничьте результаты анализа маской resultsMask в REST API или results_mask в gRPC API.

Каждый вызов Get расходует квоту на получение диалогов. Например, данные 100 диалогов можно получить одним запросом с массивом из 100 ID. При запросе каждого диалога отдельно потребуется 100 запросов. Квоты действуют на проект и учитывают как запросы API, так и просмотр диалогов в интерфейсе SpeechSense.

В этом сценарии загружен один диалог. Если в проекте есть другие диалоги, получите результаты ассистента сразу для нескольких: в приведенных выше командах Get замените тело запроса на один из шаблонов ниже. Укажите идентификаторы проекта и нужных диалогов.

{
  "projectId": "<идентификатор_проекта>",
  "talkIds": [
    "<идентификатор_первого_диалога>",
    "<идентификатор_второго_диалога>"
  ],
  "resultsMask": {
    "paths": ["assistants"]
  }
}

{
  "project_id": "<идентификатор_проекта>",
  "talk_ids": [
    "<идентификатор_первого_диалога>",
    "<идентификатор_второго_диалога>"
  ],
  "results_mask": {
    "paths": ["assistants"]
  }
}

В ответе массив talk будет содержать данные найденных диалогов. Сопоставляйте результаты с диалогами по полю talk.id.

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

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