Отладка инструкций
Раздел "Отладка инструкций" создан для того, чтобы помочь Вам проанализировать ответы бота, найти причины возникновения недочётов и внести корректировки для улучшения точности работы.
Когда возникает необходимость отладки
Отладка требуется в случаях, когда:
Ответ бота кажется некорректным или не соответствует ожиданиям.
Бот не вызывает функцию, хотя по логике должен это делать.
Бот вызывает функцию, но получает неожиданный результат.
Вы хотите оптимизировать работу бота, уточнив его ответы или действия.
Основные инструменты анализа:
Журнал диалогов. Позволяет анализировать историю запросов и ответов.
Продвинутый режим. Позволяет увидеть, какие функции были вызваны при ответе бота.
Экспорт диалога и анализ данных. Доступен для детального изучения логов и их анализа вне платформы.
Ниже поговорим о каждом из этих способов.
Анализ журнала диалогов
Описание журнала: Журнал диалогов в Suvvy предоставляет детальную историю всех взаимодействий пользователя с ботом. Он отображает вопросы пользователя, ответы бота, а также вызовы функций, если таковые были задействованы.
Шаги для анализа журнала:
Слева, на панели управления, нажмите Чат:
Найдите нужный диалог из списка активных или завершённых и нажмите на него, чтобы открыть его журнал:
В журнале вы увидите сообщения пользователя и ответы бота.
Советы по анализу:
Если бот ответил некорректно, обратите внимание на последние несколько сообщений:
Корректно ли бот интерпретировал сообщение?
Есть ли смысловые несоответствия между вопросом и ответом?
Какие детали взаимодействия можно увидеть (например, контекст запроса)?
Не нарушен ли порядок диалога (например, бот не задал уточняющий вопрос перед выдачей ответа)?
Были ли использованы релевантные данные из контекста диалога?
Не содержал ли запрос клиента неоднозначных формулировок, которые могли быть неправильно интерпретированы.
Правильно ли бот сопоставил ключевые слова (например, название товара) с данными в базе знаний.
Если бот использует подчинённого бота, убедитесь, что запрос к подчинённому прошёл без ошибок.
Анализ вызовов функций в продвинутом режиме
Продвинутый режим позволяет пользователям видеть дополнительные технические детали внутри диалогов, включая вызовы функций, которые были выполнены ботом. Это может быть полезно для отладки и анализа корректности обработки запросов.
Как включить продвинутый режим:
Что отображается в продвинутом режиме:
Пример анализа:
На скриншоте видно, что после запроса пользователя была вызвана функция 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])
Как анализировать
Название функции.
Оно указывает, какую именно задачу выполняет бот. Например,
yc_get_available_seances_by_datesиспользуется для получения доступных сеансов на указанные даты.
Переданные параметры.
staff_id– идентификатор мастера.service_id– идентификатор услуги. Указывает, какая услуга запрашивается.dates– массив дат. Показывает, для каких дат запрашивается информация.
Проблемы в параметрах
Если какой-либо из параметров передан некорректно (например, staff_id=null), бот не сможет корректно обработать запрос. В данном случае ID мастера отсутствует, что делает запрос невалидным.
Что делать при ошибке
Проверить параметры.
Убедиться, что все обязательные параметры переданы.
Например, если
staff_id=null, нужно выяснить, почему ID мастера отсутствует, и передать корректные данные.
Отладка.
Сравнить фактические параметры с ожидаемыми для данной функции.
Если бот автоматически формирует запрос, необходимо проверить логику его формирования.
Проверка и корректировка промпта.
Убедиться, что инструкции соответствуют задаче, которую должен выполнять бот.
Проверить, чтобы инструкции следовали логической последовательности
Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.
Например, если в одной части промпта указано, что нужно искать "все доступные сеансы", а в другой – "только для одного мастера", это может привести к ошибкам.
Проверка ответа функции
Результаты вызова функции
При нажатии на информационную кнопку под функцией открывается результат выполнения этой функции.
Этот результат может быть представлен в виде:
Текста
XML-документа
Этапы анализа функций
Определение типа результата.
Если результат представлен текстом, анализируем его смысловое значение.
Если это XML-документ, проверяем структуру и данные в нем.
Проверка логики работы.
Сопоставляем ожидаемый результат функции с фактическим.
Если результат не соответствует ожиданиям, анализируем переданные параметры (видны в вызове функции).
Проверка и корректировка промпта.
Убедиться, что инструкции соответствуют задаче, которую должен выполнять бот.
Проверить, чтобы инструкции следовали логической последовательности
Внимательно проверить текст инструкций на наличие ошибок, подменных понятий и, особенно, противоречий.
Вызов таблиц
Что такое вызов таблиц? Таблицы используются для хранения структурированных данных, к которым бот может обращаться для выполнения задач. Это могут быть данные о пользователях, услугах, расписании, ценах и т.д. Подробнее о работе с таблицами можно почитать в разделе Таблицы (CSV-XLS / Google).
При обращении бота к таблице, Вы увидите функцию вида:
Если вызов таблицы не сработал или результаты некорректны, проверьте следующие моменты:
1. Отсутствие данных в таблице
Убедитесь, что таблица содержит данные, которые соответствуют запросу.
2. Не учтены параметры для поиска
Некорректный результат может быть вызван пропущенными параметрами. Обратите внимание на следующие настройки внутри таблицы:
"Поиск по части строки": если запрос ищет полное совпадение, а в таблице значение записано частично. Пример: вместо
"Москва"может быть записано"Москва, РФ"."Не учитывать регистр": если запрос чувствителен к регистру,
"москва"не найдётся вместо"Москва"."Всегда строка": Т.е. отбор на данное поле будет накладываться ни как на число, а как на строку. Пример: если мы укажем, Всегда строка, то отбор на поле "Количество > 0" не сработает, т.к. запрос предполагает поиск по числам.
3. Перегруженность таблицы
Если таблица содержит беспорядочную, неструктурированную информацию, запросы могут быть некорректны.
Симптомы: данные расположены в рандомных ячейках, строки или колонки дублируются, отсутствует логическая структура.
Решение: Проведите предварительную очистку таблицы и настройте её структуру.
4. Неверное описание таблицы
Если бот не понимает, в какой момент обращаться к таблице, проверьте:
Описание таблицы в настройках.
Логику вызова таблицы в инструкциях.
5. Ошибка в "Предварительном SQL-запросе"
Проверьте настройки таблицы:
Убедитесь, что предварительный SQL-запрос корректен и возвращает ожидаемый результат.
Пример неправильного запроса:
SELECT * FORM price_table(Опечатка в ключевом слове
FROM).
6. Простота структуры таблицы
Для корректной работы таблица должна быть:
Без объединения ячеек.
С заполненной первой строкой (заголовками колонок).
Пример корректной таблицы:
590FV
Иванов И.
5000
591FV
Петров А.
7000
Проверка и отладка
Сравните результаты функции с ожидаемыми:
Если результат пуст, уточните SQL-запрос.
Если результат содержит ошибочные данные, проверьте настройки таблицы.
Проверьте текст инструкций:
Убедитесь, что бот точно понимает, какой запрос отправлять к таблице.
Если запрос некорректен, уточните формат команды в инструкции.
Тестируйте таблицы в изолированном режиме. Перед интеграцией убедитесь, что запросы к таблице работают без ошибок.
Обращение к подчинённому боту
Описание: Подчинённые боты используются для повышения качества ответов и уменьшения контекста диалога. Подробнее об этом можно почитать в разделе инструкции Мультиагентность.
Анализ в продвинутом режиме внутри диалога
Между строк внутри диалога содержатся различные элементы, которые помогают понять ход выполнения функции и взаимодействие с подчинённым ботом:
Функция вызова подчинённого бота -
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') была выполнена уже внутри подчинённого бота.
Сводная информация по анализу вызова подчинённых ботов
Основные аспекты анализа:
Этапы взаимодействия:
Вызов функции подчинённого бота через основного.
Передача аргументов для выполнения запроса (например,
number_invoices=590FV).Выполнение запроса (например, SQL-запрос или get_file_text() и т.д.) и получение результата.
Отображение данных или ошибок пользователю в удобном формате (JSON, текст).
Элементы интерфейса:
Кнопка с названием подчинённого бота (например, "Таблицы").
Иконка "ℹ️" или "
" для доступа к результатам выполнения функции.Контекстное окно с данными или сообщением об ошибке.
Анализ ошибок:
Проверка выполнения функции (оповещение "Функция выполнена" или сообщение об ошибке).
Проверка запроса на корректность.
Анализ данных, возвращаемых подчинённым ботом.
Часто встречающиеся ошибки и рекомендации по их анализу и устранению
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. Ошибка в описании логики при вызове подчинённого бота.
Ошибка: некорректно описанная логика вызова подчинённого бота в промпте
Описание: Промпт содержит неясные или противоречивые инструкции для подчинённого бота, что приводит к ошибкам в выполнении функций. Например:
Не указано, в какой момент стоит обращаться к подчинённому боту.
Инструкции содержат ненужные детали или лишние шаги, которые мешают боту правильно выполнить запрос.
Как заметить:
Подчинённый бот возвращает некорректный результат или просит уточнить запрос, несмотря на наличие корректных данных. В логах или интерфейсе можно увидеть ошибки выполнения.
Главный бот вообще не вызывает подчинённого бота.
Как исправить:
Проверить промпт главного бота на наличие лишних деталей или неоднозначностей.
Проверить промпт подчинённого бота на наличие лишних деталей или неоднозначностей.
Убедиться, что логика промпта чётко описывает последовательность выполнения запроса.
Протестировать промпт с разными входными данными, чтобы убедиться, что бот понимает запрос и выполняет его правильно.
Основные советы по отладке инструкций
Эффективная отладка инструкций требует системного подхода и внимательного анализа на всех этапах взаимодействия с ботом. Чтобы быстро находить и устранять проблемы, следуйте этим рекомендациям:
Понимание необходимости отладки Начинайте с понимания, в какой момент требуется вмешательство. Если результаты работы функций или ответы бота кажутся некорректными, это сигнал для анализа.
Используйте журнал диалогов Проверьте, какие шаги выполнялись, какие параметры передавались, и какие ответы получены. Это поможет локализовать проблему на уровне диалога.
Проводите анализ вызовов функций В продвинутом режиме или с помощью экспорта изучайте запросы и результаты выполнения функций. Убедитесь, что запросы правильно сформулированы, а функции возвращают ожидаемые данные.
Работайте с экспортом диалогов Экспорт помогает более детально изучить структуру запросов, параметры вызовов и ответы бота. Используйте эти данные для диагностики и коррекции.
Проверяйте настройки Убедитесь, что в шагах диалога корректно назначены аргументы действий, а текст запроса точно передаёт логику вызова функции или подчинённого бота.
Отлаживайте взаимодействие с подчинёнными ботами Проверяйте, что промпты подчинённых ботов чётко описывают логику вызова, переданные данные соответствуют требованиям, а сами боты настроены на работу с актуальной информацией.
Внимательно относитесь к данным Ошибки в данных или их отсутствии — частая причина некорректной работы функций. Убедитесь, что вводимые значения точны, а необходимые данные доступны в базе.
Тестируйте и анализируйте результат После внесения изменений проверяйте, как они влияют на выполнение функций и ответы бота. Постоянное тестирование помогает убедиться в стабильной работе системы.
Главный секрет успешной отладки — последовательность и внимание к деталям. Работая шаг за шагом, вы сможете быстро находить и устранять проблемы, обеспечивая надёжную работу системы.
Last updated
Was this helpful?