Отладка инструкций

Раздел "Отладка инструкций" создан для того, чтобы помочь Вам проанализировать ответы бота, найти причины возникновения недочётов и внести корректировки для улучшения точности работы.

Когда возникает необходимость отладки

Отладка требуется в случаях, когда:

• Ответ бота кажется некорректным или не соответствует ожиданиям.

• Бот не вызывает функцию, хотя по логике должен это делать.

• Бот вызывает функцию, но получает неожиданный результат.

• Вы хотите оптимизировать работу бота, уточнив его ответы или действия.

Основные инструменты анализа:

• Журнал диалогов. Позволяет анализировать историю запросов и ответов.

• Продвинутый режим. Позволяет увидеть, какие функции были вызваны при ответе бота.

• Экспорт диалога и анализ данных. Доступен для детального изучения логов и их анализа вне платформы.

Ниже поговорим о каждом из этих способов.

Анализ журнала диалогов

Описание журнала: Журнал диалогов в Suvvy предоставляет детальную историю всех взаимодействий пользователя с ботом. Он отображает вопросы пользователя, ответы бота, а также вызовы функций, если таковые были задействованы.

Шаги для анализа журнала:

1. Слева, на панели управления, нажмите Чат:

1. Найдите нужный диалог из списка активных или завершённых и нажмите на него, чтобы открыть его журнал:

1. В журнале вы увидите сообщения пользователя и ответы бота.

Советы по анализу:

• Если бот ответил некорректно, обратите внимание на последние несколько сообщений:

  • Корректно ли бот интерпретировал сообщение?

  • Есть ли смысловые несоответствия между вопросом и ответом?

  • Какие детали взаимодействия можно увидеть (например, контекст запроса)?

  • Не нарушен ли порядок диалога (например, бот не задал уточняющий вопрос перед выдачей ответа)?

  • Были ли использованы релевантные данные из контекста диалога?

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

  • Правильно ли бот сопоставил ключевые слова (например, название товара) с данными в базе знаний.

  • Если бот использует подчинённого бота, убедитесь, что запрос к подчинённому прошёл без ошибок.

Анализ вызовов функций в продвинутом режиме

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

Как включить продвинутый режим:

• Перейдите в раздел Чаты.

• В верхней части интерфейса активируйте переключатель Продвинутый режим. (См. скриншот 1.)

Что отображается в продвинутом режиме:

Между строками диалога вы увидите блоки с информацией о вызовах функций. В этих блоках указывается:

• Название функции.

• Аргументы, переданные в функцию.

• Статус выполнения (например, "Функция выполнена успешно").

Пример анализа:

На скриншоте видно, что после запроса пользователя была вызвана функция get_file_text(file=Portrait Sizes (without photos)).

Бот корректно обработал запрос и вернул ожидаемый результат.

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

Если ответ бота не соответствует Вашим ожиданиям, проверьте содержимое функции:

Экспорт диалога и анализ данных

Раздел "Экспорт" предоставляет возможность сохранить всю историю диалога, включая вызовы функций, параметры и ответы, в формате веб-страницы.

Это можно сделать, нажав на кнопку экспорта в правом вернем углу выбранного диалога:

Возможности экспорта

• Формат экспортируемого файла:

  • Экспорт производится в виде веб-страницы (.html), которая отображает всю информацию о диалоге в структурированном виде.

• Содержимое экспортируемого файла:

  • _id — уникальный идентификатор, который позволяет идентифицировать конкретный диалог.

  • Email — адрес электронной почты учетной записи.

  • Bot — название бота, который отвечает за диалог.

  • Placeholders — имя клиента, с кем ведётся диалог.

  • Dialogue fields — диалоговые поля.

  • Функции — перечень вызванных функций с их параметрами и статус выполнения (например, yc_get_available_staff или yc_get_available_seances_by_dates, или get_file_text).

  • История переписки — сообщения между покупателем, ботом и сотрудником, если он включился в диалог. Экспорт диалога содержит полную историю, включая фото, аудио, видео и прочие отправленные или полученные файлы.

Анализ экспорта

Результаты вызова функции

Между реплик диалога можно увидеть строку вызова функции. Она содержит название функции и переданные параметры. Например:

⚙️ Выполняется функция yc_get_available_seances_by_dates(staff_id=null, service_id=16959981, dates=[2025-01-14])

Как анализировать

1. Название функции.

   • Оно указывает, какую именно задачу выполняет бот. Например, yc_get_available_seances_by_dates используется для получения доступных сеансов на указанные даты.

2. Переданные параметры.

   • staff_id – идентификатор мастера.

   • service_id – идентификатор услуги. Указывает, какая услуга запрашивается.

   • dates – массив дат. Показывает, для каких дат запрашивается информация.

3. Проблемы в параметрах

Если какой-либо из параметров передан некорректно (например, staff_id=null), бот не сможет корректно обработать запрос. В данном случае ID мастера отсутствует, что делает запрос невалидным.

Что делать при ошибке

1. Проверить параметры.

   • Убедиться, что все обязательные параметры переданы.

   • Например, если staff_id=null, нужно выяснить, почему ID мастера отсутствует, и передать корректные данные.

2. Отладка.

   • Сравнить фактические параметры с ожидаемыми для данной функции.

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

3. Проверка и корректировка промпта.

   • Убедиться, что инструкции соответствуют задаче, которую должен выполнять бот.

   • Проверить, чтобы инструкции следовали логической последовательности

   • Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.

   Например, если в одной части промпта указано, что нужно искать "все доступные сеансы", а в другой – "только для одного мастера", это может привести к ошибкам.

Проверка ответа функции

Результаты вызова функции

При нажатии на информационную кнопку под функцией открывается результат выполнения этой функции.

Этот результат может быть представлен в виде:

1. Текста

Пример: There are no available seances on the selected dates. Этот текст сообщает, что на выбранные даты нет доступных сеансов.

Пример: дата и время указывают на успешный возврат ответа вызова функции.

1. XML-документа

Пример: XML-document указывает на то, что файл базы знаний был успешно вызван и возвращён в ответе.

Files sent successfully. Также указывает на успешную отправку данных.

Этапы анализа функций

1. Определение типа результата.

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

   • Если это XML-документ, проверяем структуру и данные в нем.

2. Проверка логики работы.

   • Сопоставляем ожидаемый результат функции с фактическим.

   • Если результат не соответствует ожиданиям, анализируем переданные параметры (видны в вызове функции).

3. Проверка и корректировка промпта.

   • Убедиться, что инструкции соответствуют задаче, которую должен выполнять бот.

   • Проверить, чтобы инструкции следовали логической последовательности

   • Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.

Вызов таблиц

Что такое вызов таблиц? Таблицы используются для хранения структурированных данных, к которым бот может обращаться для выполнения задач. Это могут быть данные о пользователях, услугах, расписании, ценах и т.д. Подробнее о работе с таблицами можно почитать в разделе Таблицы (CSV-XLS / Google).

При обращении бота к таблице, Вы увидите функцию вида:

Если вызов таблицы не сработал или результаты некорректны, проверьте следующие моменты:

1. Отсутствие данных в таблице

• Убедитесь, что таблица содержит данные, которые соответствуют запросу.

2. Не учтены параметры для поиска

Некорректный результат может быть вызван пропущенными параметрами. Обратите внимание на следующие настройки внутри таблицы:

• "Поиск по части строки": если запрос ищет полное совпадение, а в таблице значение записано частично. Пример: вместо "Москва" может быть записано "Москва, РФ".

• "Не учитывать регистр": если запрос чувствителен к регистру, "москва" не найдётся вместо "Москва".

• "Всегда строка": Т.е. отбор на данное поле будет накладываться ни как на число, а как на строку. Пример: если мы укажем, Всегда строка, то отбор на поле "Количество > 0" не сработает, т.к. запрос предполагает поиск по числам.

3. Перегруженность таблицы

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

• Симптомы: данные расположены в рандомных ячейках, строки или колонки дублируются, отсутствует логическая структура.

• Решение: Проведите предварительную очистку таблицы и настройте её структуру.

4. Неверное описание таблицы

Если бот не понимает, в какой момент обращаться к таблице, проверьте:

• Описание таблицы в настройках.

• Логику вызова таблицы в инструкциях.

Описание очень важная составляющая, т.к. она определяет поведение и запрос, который будет формироваться к таблице.

5. Ошибка в "Предварительном SQL-запросе"

Проверьте настройки таблицы:

• Убедитесь, что предварительный SQL-запрос корректен и возвращает ожидаемый результат.

• Пример неправильного запроса:

  SELECT * FORM price_table

  (Опечатка в ключевом слове FROM).

6. Простота структуры таблицы

Для корректной работы таблица должна быть:

• Без объединения ячеек.

• С заполненной первой строкой (заголовками колонок).

Пример корректной таблицы:

Номер инвойса	Клиент	Сумма
590FV	Иванов И.	5000
591FV	Петров А.	7000

Проверка и отладка

1. Сравните результаты функции с ожидаемыми:

   • Если результат пуст, уточните SQL-запрос.

   • Если результат содержит ошибочные данные, проверьте настройки таблицы.
2. Проверьте текст инструкций:

   • Убедитесь, что бот точно понимает, какой запрос отправлять к таблице.

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

Обращение к подчинённому боту

Описание: Подчинённые боты используются для повышения качества ответов и уменьшения контекста диалога. Подробнее об этом можно почитать в разделе инструкции Мультиагентность.

Анализ в продвинутом режиме внутри диалога

Между строк внутри диалога содержатся различные элементы, которые помогают понять ход выполнения функции и взаимодействие с подчинённым ботом:

• Функция вызова подчинённого бота - invoices_search(date=, summ_usd=, summ_zl=, number_invoices=590FV).Здесь параметр 590FV передаётся для поиска информации в таблицах.

• "Таблицы" — это название вызванного подчинённого бота.

При нажатии на кнопку "Таблицы" (название подчинённого бота), справа всплывает контекстное окно, содержащее следующую информацию:

Пройдёмся по содержимому контекстного окна:

• User: отображается переданный параметр (590FV).

• Результат выполнения функции: Рядом с текстом "Функция выполнена" расположена функциональная иконка "" При её нажатии выводится полный текст с результатами функции в формате JSON:

• SQL-запрос: Функция внутри подчинённого бота: get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV')

На этапе выполнения SQL-запрос был модифицирован: $SQL запрос был заменён на SELECT * FROM data WHERE LOWER(number_invoices) LIKE '%590fv%'

Объяснение:

• Запрос ищет данные в таблице (data), фильтруя строки, где значение в поле (number_invoices) соответствует указанному параметру (590FV), без учёта регистра символов.

• Оператор LIKE используется для поиска подстрок, добавляя гибкость при вводе данных.

• Ответ от подчинённого бота: После успешного выполнения функции подчинённый бот "Таблицы" возвращает следующий ответ:

• В случае ошибки ответ будет вроде:

Здесь же мы можем заметить, что между строк не отображается оповещение о выполнении функции и SQL запроса.

Анализ экспорта диалога.

1. Данные результата вызова функции: При нажатии на иконку ℹ️ можно получить информацию о результатах выполнения функции.

• Пример успешного результата:

В данном случае, мы получили ответ со всеми данными, относящимися к инвойсу 590FV с таблицы, хранящейся в подчинённом боте.

• Пример ответа при ошибке:

В данном случае мы получили запрос на предоставление более подробной информации о том, что мы ищем.

Это может быть связано с тем, что данных, которые мы запрашиваем, в таблице (а следовательно, у подчинённого бота) нет.

2. Распознавание вызовов подчинённых ботов: В экспортируемом документе, если функция представляет собой вызов подчинённого бота, рядом с иконкой информации (ℹ️) отображается дополнительная иконка в виде головы робота. При нажатии на иконку головы робота откроется модальное окно:

В этом окне отображается отдельный экспорт, содержащий данные, относящиеся только к подчинённому боту:

Т.е. функция get_price_table(sql_query=SELECT * FROM data WHERE number_invoices = '590FV') была выполнена уже внутри подчинённого бота.

Сводная информация по анализу вызова подчинённых ботов

Основные аспекты анализа:

1. Этапы взаимодействия:

   • Вызов функции подчинённого бота через основного.

   • Передача аргументов для выполнения запроса (например, number_invoices=590FV).

   • Выполнение запроса (например, SQL-запрос или get_file_text() и т.д.) и получение результата.

   • Отображение данных или ошибок пользователю в удобном формате (JSON, текст).

2. Элементы интерфейса:

   • Кнопка с названием подчинённого бота (например, "Таблицы").

   • Иконка "ℹ️" или "" для доступа к результатам выполнения функции.
   • Контекстное окно с данными или сообщением об ошибке.

3. Анализ ошибок:

   • Проверка выполнения функции (оповещение "Функция выполнена" или сообщение об ошибке).

   • Проверка запроса на корректность.

   • Анализ данных, возвращаемых подчинённым ботом.

Часто встречающиеся ошибки и рекомендации по их анализу и устранению

1. Ошибка: не назначены аргументы действия при создании действия

• Проблема: забыли указать передаваемые параметры для вызова подчинённого бота (например, number_invoices).

• Как заметить: в результате функция подчинённого бота не будет вызвана, и в логах экспорта не появится параметр запроса.

• Как исправить:

  • Проверить настройки вызова функции.

  • Убедиться, что в аргументах действия указаны все необходимые параметры.

2. Ошибка: не выбраны аргументы действия в настройке шага

• Ошибка: В поле "Текст запроса в бот" не указаны аргументы для передачи.

• Как заметить: Подчинённый бот получает пустой запрос или запрос с некорректным форматом.

• Как исправить:

  • Зайти в настройки шага.

  • Убедиться, что аргументы действия корректно выбраны и передаются в поле запроса.

3. Излишнее описание функции подчинённого бота или отсутствие описания

• Ошибка: в настройке действия не прописано или наоборот излишне прописано Описание функции.

• Как заметить: главный бот не вызывает функцию подчинённого бота.

• Как справляться:

  • Удалить излишнее описание подчинённого бота.

  • Проверить, чтобы описание функции чётко соответствовало задуманной роли подчинённого бота.

4. Ошибка в данных (опечатка пользователя)

• Описание: Пользователь вводит неверный параметр, например, 5590FV вместо 590FV.

• Как заметить: Подчинённый бот возвращает сообщение об отсутствии данных или просит уточнить запрос. Пример:

"Please provide more details about what you are looking for. Are you searching for a specific date, transaction amount, or invoice number related to "5590FV"?"

• Как исправить:

  • Проверить корректность введённых данных.

  • Предусмотреть логику уточнения запроса у пользователя.

5. Отсутствие данных в подчинённом боте

• Ошибка: В подчинённом боте нет данных, соответствующих запросу.

• Как заметить: В логах или интерфейсе отображается сообщение об отсутствии данных. Пример:

"No records found for the invoice number 590FV."

• Как исправить:

  • Убедиться, что запрос корректный.

  • Проверить исходную базу данных подчинённого бота.

7. Общая ошибка в логике вызова

• Ошибка: Вызов функции подчинённого бота выполнен неправильно (например, передача лишних или несоответствующих параметров).

• Как заметить: Подчинённый бот возвращает неожиданный ответ или не выполняет функцию.

• Как справляться:

  • Перепроверить логику работы основного и подчинённого ботов.

  • Убедиться, что передаваемые параметры соответствуют требованиям подчинённого бота.

8. Ошибка в описании логики при вызове подчинённого бота.

• Ошибка: некорректно описанная логика вызова подчинённого бота в промпте

• Описание: Промпт содержит неясные или противоречивые инструкции для подчинённого бота, что приводит к ошибкам в выполнении функций. Например:

  • Не указано, в какой момент стоит обращаться к подчинённому боту.

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

• Как заметить:

1. Подчинённый бот возвращает некорректный результат или просит уточнить запрос, несмотря на наличие корректных данных. В логах или интерфейсе можно увидеть ошибки выполнения.

2. Главный бот вообще не вызывает подчинённого бота.

• Как исправить:

  • Проверить промпт главного бота на наличие лишних деталей или неоднозначностей.

  • Проверить промпт подчинённого бота на наличие лишних деталей или неоднозначностей.

  • Убедиться, что логика промпта чётко описывает последовательность выполнения запроса.

  • Протестировать промпт с разными входными данными, чтобы убедиться, что бот понимает запрос и выполняет его правильно.

Основные советы по отладке инструкций

Эффективная отладка инструкций требует системного подхода и внимательного анализа на всех этапах взаимодействия с ботом. Чтобы быстро находить и устранять проблемы, следуйте этим рекомендациям:

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

2. Используйте журнал диалогов Проверьте, какие шаги выполнялись, какие параметры передавались, и какие ответы получены. Это поможет локализовать проблему на уровне диалога.

3. Проводите анализ вызовов функций В продвинутом режиме или с помощью экспорта изучайте запросы и результаты выполнения функций. Убедитесь, что запросы правильно сформулированы, а функции возвращают ожидаемые данные.

4. Работайте с экспортом диалогов Экспорт помогает более детально изучить структуру запросов, параметры вызовов и ответы бота. Используйте эти данные для диагностики и коррекции.

5. Проверяйте настройки Убедитесь, что в шагах диалога корректно назначены аргументы действий, а текст запроса точно передаёт логику вызова функции или подчинённого бота.

6. Отлаживайте взаимодействие с подчинёнными ботами Проверяйте, что промпты подчинённых ботов чётко описывают логику вызова, переданные данные соответствуют требованиям, а сами боты настроены на работу с актуальной информацией.

7. Внимательно относитесь к данным Ошибки в данных или их отсутствии — частая причина некорректной работы функций. Убедитесь, что вводимые значения точны, а необходимые данные доступны в базе.

8. Тестируйте и анализируйте результат После внесения изменений проверяйте, как они влияют на выполнение функций и ответы бота. Постоянное тестирование помогает убедиться в стабильной работе системы.

Главный секрет успешной отладки — последовательность и внимание к деталям. Работая шаг за шагом, вы сможете быстро находить и устранять проблемы, обеспечивая надёжную работу системы.