Перейти к основному содержимому

Создание и управление ботами по API

В этой документации описаны методы API для создания поисковых (RAG) ботов и управления ими. Например, вы можете проверить статус ботов, посмотреть их список или добавить / удалить документы. Полный список доступных методов описан ниже.

Создание с загрузкой файлов​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F "files=@/path/to/test.pdf" \
     -F "files=@/path/to/test2.pdf" \
     -F "user_story=write_your_user_story_here" \
     -F "sync=1" \
     -F "time_to_eval=2025-04-02 14:49"

Параметры:

  • YOUR_TOKEN_HERE - токен для доступа по API
  • bot_id - имя индекса, по которому будет доступен созданный бот
  • user_story - краткое описание сценария использования (пользовательской истории)
  • sync (необязательно) - флаг приоритета индексации (1 - высокий приоритет, индексация будет выполнена раньше запросов на создание бота без флага и раньше любых документов, которые добавляем в уже существующих ботов)
  • time_to_eval (необязательно) - время, не раньше которого начнётся индексация (формат: YYYY-MM-DD HH:MM)
к сведению

Параметры sync и time_to_eval могут быть указаны одновременно.

примечание

Внутри данного метода есть параметр user_story, это описание сценария использования ассистента. Пользовательская история напрямую влияет на качество индексации и последующих ответов ассистента.

Для написания пользовательской истории рекомендуется отвечать на вопросы: Кто будет использовать ассистента и зачем? Что важно при формировании ответа?

Примеры user_story:​

Пример 1: "Я, как инженер проектного отдела корпорации, хочу выяснить как действовать в сложной рабочей ситуации. Описав рабочую ситуацию, я хочу получить инструкцию что делать и к кому обратиться. Для меня важно получить контакты людей. Важно получить объяснения что можно делать и что нельзя. Мне не нравятся общие ответы - я давно в компании и общие моменты знаю."

Пример 2: "Я как сотрудник организации, который работает с разными корпоративными IT системами, хочу выяснить нужную мне информацию по работе одной из систем, получить помощь по своему вопросу, узнать как действовать в конкретной ситуации. Задав вопрос я хочу увидеть короткий и исчерпывающий ответ, содержащий всю необходимую информацию. Искажение фактов для меня самая серьезная проблема. В зависимости от вопроса не полное изложение фактов тоже может быть проблемой."

Ответы:​

  • 202 Accepted – команда на создание бота принята в обработку. Ответ будет содержать command_id. 
    {
      "command_id": "some-unique-command-id"
    }

Для отслеживания статуса выполнения используйте эндпоинты статуса команд (см. раздел "Отслеживание статусов команд").

Создание с указанием файлов по URL​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "direct_link", "url": "https://example.com/doc1.pdf"}' \
     -F "user_story=write_your_user_story_here" \
     -F "sync=1" \
     -F "time_to_eval=2025-04-02 14:49"

Параметры аналогичны запросу с загрузкой файлов, кроме:

  • urls – JSON-объект с URL-адресами. Непосредственно сам документ должен открываться по указанному URL (например, https://example.com/doc1.pdf).

Ответы:​

  • 202 Accepted – команда на создание бота c указанием URL принята в обработку. Ответ будет содержать command_id. 
    {
      "command_id": "some-unique-command-id"
    }

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

Удаление бота​

Удаление бота по его идентификатору.

curl -X DELETE https://bot.insightstream.ru/indexapi/bot/bot_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

Описание​

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

Параметры​

  • bot_id (string, path) – идентификатор бота.

Заголовки​

  • Authorization: Bearer YOUR_TOKEN_HERE – токен доступа к API.

Ответы​

  • 202 Accepted – команда на удаление бота принята в обработку. Ответ будет содержать command_id.

    {
      "command_id": "some-unique-command-id"
    }

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

  • 404 Not Found – бот не найден.

  • 409 Conflict – бот в процессе выполнения другой критической операции (например, удаление уже запущено), попробуйте позже.

Получение информации о существующих ботах

Конкретный бот​

Для получения информации о конкретном боте используйте следующий запрос:

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

Этот эндпоинт возвращает подробную информацию о боте, включая его настройки и список файлов.

Пример ответа:

{
  "name": "bot_id",
  "hello_text": "\n<h1>Рад знакомству!</h1>\n<h1>Я ваш личный ИИ-ассистент.</h1>\n<p>Меня обучили отвечать на вопросы по вашим документам.</p>\n",
  "retrive_n": 5,
  "support_n": 3,
  "example_questions": [],
  "user_story": "test",
  "bot_creator_credentials": "qwe",
  "files": [
    "http://is.local/documents/bot_id/bob.txt",
    "http://is.local/documents/bot_id/alice.txt"
  ]
}

Все боты​

curl -X GET https://bot.insightstream.ru/indexapi/bots -H "Authorization: Bearer YOUR_TOKEN_HERE"

Этот эндпоинт предоставляет подробную информацию обо всех ботах.

Пример ответа:

{
  "bot_id_1": {
    "name": "bot_id_1",
    "hello_text": "\n<h1>Рад знакомству!</h1>\n<h1>Я ваш личный ИИ-ассистент.</h1>\n<p>Меня обучили отвечать на вопросы по вашим документам.</p>\n",
    "retrive_n": 5,
    "support_n": 3,
    "example_questions": [],
    "user_story": "test",
    "bot_creator_credentials": "qwe",
    "files": [
      "http://is.local/documents/snark.txt",
      "http://is.local/documents/alice.txt"
    ]
  },
  "bot_id_2": {
    // Аналогичная информация для других ботов
  }
}

Работа с документами внутри бота

Добавление или обновление документа в боте​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/document \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F "file=@/path/to/document.pdf" \

Описание​

Позволяет инициировать добавление нового документа или обновление существующего в индексе бота.

Параметры​

  • bot_id (string, path) – идентификатор бота.
  • file (file, form) – файл документа.

Заголовки​

  • Authorization: Bearer YOUR_TOKEN_HERE – токен доступа к API.

Ответы​

  • 202 Accepted – команда на добавление/обновление документа принята. Ответ будет содержать command_id.

    {
      "command_id": "some-unique-command-id-for-doc-upsert"
    }

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

  • 404 Not Found – бот не найден.

  • 409 Conflict – бот или данный документ в процессе обработки другой командой, попробуйте позже.

Добавление или обновление документа в боте по URL​

curl -X PUT https://bot.insightstream.ru/indexapi/bot/bot_id/document_by_url
-H "Authorization: Bearer YOUR_TOKEN_HERE"
-F "url=https://example.com/doc1.pdf" \

Описание​

Позволяет инициировать добавление нового документа или обновление существующего в индексе бота по URL.

Параметры​

  • bot_id (string, path) – идентификатор бота.
  • url (file, form) – прямая ссылка на документ.

Заголовки​

  • Authorization: Bearer YOUR_TOKEN_HERE – токен доступа к API.

Удаление документа из бота​

curl -X DELETE https://bot.insightstream.ru/indexapi/bot/bot_id/document/doc_name -H "Authorization: Bearer YOUR_TOKEN_HERE"

Описание​

Инициирует удаление указанного документа из индекса бота. Операция асинхронная.

Параметры​

  • bot_id (string, path) – идентификатор бота.
  • doc_name (string, path) – имя документа.

Заголовки​

  • Authorization: Bearer YOUR_TOKEN_HERE – токен доступа к API.

Ответы​

  • 202 Accepted – команда на удаление документа принята. Ответ будет содержать command_id.

    {
      "command_id": "some-unique-command-id-for-doc-delete"
    }

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

  • 404 Not Found – бот или документ не найдены.

  • 409 Conflict – бот или документ в процессе обработки другой командой, попробуйте позже.

Отслеживание статусов операций

Операции создания/удаления бота (ассистента) или добавления/удаления документа являются асинхронными. При успешном принятии запроса API возвращает command_id. Предпочтительно использовать этот универсальный идентификатор для отслеживания статуса выполнения команды.

Получение статуса всех операций для бота​

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id/commands -H "Authorization: Bearer YOUR_TOKEN_HERE"

Возвращает список JSON-объектов с описаниями всех активных или недавно завершенных команд для указанного bot_id.

Пример ответа:​

{
  "command_id_1": {
    "status": "processing",
    "progress": {
      "documents": { 
        "total": 98, 
        "complete": 76 
      },
      "current_document": { 
        "total": 54, 
        "complete": 32 
      }
    }
  },
  "command_id_2": {
    "status": "complete"
  }
}

Описание полей ответа:​

  • command_id: Уникальный идентификатор команды
  • status: Текущий статус команды (возможные значения: "processing", "complete" и др.)
  • progress: Информация о прогрессе выполнения команды (присутствует только для индексации бота или новых документов в процессе выполнения)
    • documents: Прогресс обработки на уровне документов в боте
      • total: Общее количество документов для обработки
      • complete: Количество уже обработанных документов
    • current_document: Прогресс обработки на уровне одного документа
      • total: Общее количество чанков в текущем документе
      • complete: Количество уже обработанных чанков в текущем документе

Получение статуса конкретной команды​

curl -X GET https://bot.insightstream.ru/indexapi/bot/bot_id/command/your_command_id -H "Authorization: Bearer YOUR_TOKEN_HERE"

Где your_command_id - идентификатор команды, полученный при ее инициации.

Формат ответа: JSON-объект, содержащий следующие поля:

  • status (string): Текущий статус команды. Возможные значения:
    • pending: Команда ожидает начала выполнения.
    • processing: Команда в процессе выполнения.
    • complete: Команда успешно выполнена.
    • error: При выполнении команды произошла ошибка.
    • canceled: Команда была отменена.

Важное замечание по статусам complete, error, canceled: Статусы complete, error, canceled показываются только один раз, после этого считается, что статус уже просмотрен и дальше при запросе статуса этой команды может возвращаться {"error": "not found"}

Другие инструменты отслеживания статусов

Проверка статуса всех документов бота​

curl https://bot.insightstream.ru/indexapi/bot/bot_id/documents -H "Authorization: Bearer YOUR_TOKEN_HERE"

Описание​

Возвращает статусы всех документов, загруженных в бота.

Параметры​

  • index_id (string, path) – идентификатор бота.

Ответы​

  • 200 OK – список статусов успешно получен.
  • 404 Not Found – бот не найден или у бота нет загруженных документов.

Проверка статуса документа​

curl https://bot.insightstream.ru/indexapi/bot/bot_id/document/doc_name -H "Authorization: Bearer YOUR_TOKEN_HERE"

Описание​

Возвращает текущий статус обработки документа в боте.

Параметры​

  • index_id (string, path) – идентификатор бота.
  • doc_name (string, path) – имя документа.

Ответы​

  • 200 OK – статус успешно получен.
  • 404 Not Found – бот или документ не найдены.
  • 409 Conflict – ошибка при обработке документа.