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

AI Assistant API

Статья создана
Обновлена 30 апреля 2025 г.

Функциональность AI Assistant API находится на стадии Preview.

AI Assistant API — это инструмент создания AI-ассистентов. С его помощью можно создать персонализированных помощников, реализовывать сценарий генеративного ответа с учетом информации из внешних источников (RAG, Retrieval Augmented Generation), а также сохранять контекст запросов к модели.

Вы можете создать своего AI-ассистента с помощью Yandex Cloud ML SDK или реализуя запросы к API на языке программирования.

Чтобы использовать AI Assistant API в Yandex Foundation Models, необходимы роли ai.assistants.editor и ai.languageModels.user или выше на каталог.

Из чего состоят AI-ассистенты

AI Assistant API предоставляет несколько абстракций для реализации чат-ботов и AI-ассистентов.

Ассистент определяет, к какой модели нужно обратиться, а также какие параметры и инструкции использовать. Это позволяет настроить модель один раз и использовать эти настройки в будущем без необходимости каждый раз передавать их.

Для хранения контекста истории общения используются треды. Каждый тред — это отдельный диалог с пользователем. Запустив ассистента для треда, вы вызовете модель и передадите весь сохраненный в нем контекст. Вы можете получить промежуточные результаты генерации, прослушивая текущий запуск, а итоговый результат генерации будет добавлен к треду.

Совет

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

Подробнее о стоимости использования ассистентов см. Правила тарификации ассистентов.

Работа с внешними источниками информации

Чтобы модель использовала внешние источники информации для ответов на запросы, вы можете загрузить файлы с дополнительной информацией с помощью Files API и создать для них поисковый индекс. Загрузить можно до 10 000 файлов, максимальный размер каждого файла — 128 МБ. Один и тот же файл может содержаться в нескольких поисковых индексах сразу.

Со всеми ограничениями AI Assistant API можно ознакомиться в разделе Квоты и лимиты в Yandex Foundation Models.

Для загрузки поддерживаются следующие MIME-типы:

  • application/json
  • application/msword
  • application/pdf
  • application/vnd.ms-excel
  • application/vnd.ms-excel.sheet.2
  • application/vnd.ms-excel.sheet.3
  • application/vnd.ms-excel.sheet.4
  • application/vnd.ms-excel.workspace.3
  • application/vnd.ms-excel.workspace.4
  • application/vnd.ms-outlook
  • application/vnd.ms-powerpoint
  • application/vnd.ms-project
  • application/vnd.ms-word2006ml
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/x-latex
  • application/x-ms-owner
  • application/xhtml+xml
  • text/csv
  • text/html
  • text/markdown
  • text/plain
  • text/xml
  • application/rtf

В качестве источника для поискового индекса эффективнее всего использовать формат Markdown, так как многие модели обучаются именно на этом формате, и, следовательно, должны понимать его лучше. Вы можете преобразовывать файлы, в том числе содержащие сложное форматирование, в формат Markdown с помощью библиотеки docling для Python. Подробнее см. в разделе Создать AI-ассистента с поиском по PDF-файлам со сложным форматированием.

Примечание

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

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

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

Подтверждение источников

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

При работе через ML SDK ссылки на источники можно получить из свойства citations объекта run. Получить ссылки на источники через API можно по идентификатору запуска, воспользовавшись методом REST API Run.Get или вызовом gRPC API RunService/Get. Кроме того, секция со ссылками на источники прикрепляется ко всем сообщениям ассистента, хранящимся в треде.

Структура секции citations

Секция citations, содержащая ссылки на источники, имеет следующую структуру:

  • sources — массив из одного или более фрагментов файлов-источников, использованных при генерации ответа:

    • chunk — информация об использованном при генерации ответа фрагменте файла-источника:

      • searchIndex — блок полей с информацией о поисковом индексе, содержащем использованный фрагмент файла-источника. Блок содержит идентификатор, тип, метаданные (labels) и другую информацию об индексе и его настройках.
      • sourceFile — блок полей с информацией об исходном файле-источнике, фрагмент которого использован при генерации ответа. Блок содержит идентификатор, метаданные (labels) и другую информацию о файле-источнике.
      • content — блок полей, содержащий текст фрагмента, который использовался при генерации ответа.

Подробнее о структуре секции citations см. в справочнике API.

Метаданные файлов-источников и поисковых индексов

Чтобы более эффективно использовать подтверждение источников и данные, возвращаемые в секции citations, для каждого файла-источника и поискового индекса вы можете задавать метаданные. Например, с помощью метаданных можно осуществлять дополнительную фильтрацию результатов или присваивать источникам более полные и осмысленные названия и описания.

Метаданные файлов-источников задаются при создании файлов с помощью метода REST API File.Create, вызова gRPC API FileService/Create или Yandex Cloud ML SDK. Метаданные файлов-источников передаются в виде объектов, содержащих пары <ключ>:<значение>.

Метаданные поисковых индексов задаются при создании индексов с помощью метода REST API SearchIndex.Create, вызова gRPC API SearchIndexService/Create или Yandex Cloud ML SDK. Метаданные поисковых индексов передаются в виде объектов, содержащих пары <ключ>:<значение>.

Метаданные каждого файла-источника и поискового индекса могут содержать одну или более пар <ключ>:<значение>.

Подробнее об использовании метаданных файлов-источников и поисковых индексов см. в разделе Создать ассистента для поиска с указанием метаданных исходных файлов и индексов.

Совет

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

Примеры работы со ссылками на источники с помощью SDK и API, а также примеры вывода см. в разделе Создать ассистента с поисковым индексом.

Примеры использования

Предыдущая
Дообучение
Следующая
Поисковые индексы