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

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

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

curl -X PUT http://base_url:8080/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 http://base_url:8080/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"
  }

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

ваш_url

Создание с указанием документов из Jive

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "jive", "url": "https://ваш_url/docs/DOC-3085", "login": "your_login", "password": "your_password"}' \
     -F "user_story=write_your_user_story_here"

Параметры аналогичны запросу с загрузкой файлов по URL, однако в поле urls для документа указывается JSON, параметры которого описаны ниже. Обратите внимание, что для корректной работы curl параметр urls должен указываться в одинарных кавычках, а ключи и значения json - в двойных.

Параметры JSON для Jive:

• type: "jive" - указывает тип источника
• url - ссылка на документ Jive
• login и password - учетные данные для доступа к Jive

Обрабатываются ссылки документации в формате {ссылка на jive}/docs/DOC-{id документа}. Оттуда выкачиваются документы и далее обрабатываются в стандартном процессе индексации файлов.

Для каждого документа необходимо заново указывать логин/пароль.

Есть возможность создать один индекс из разных пространств Jive.

Создание с указанием ссылки на пространство из Jive

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "jive", "url": "https://ваш_url/community/knowledge/edu/docs", "login": "your_login", "password": "your_password"}' \
     -F "user_story=write_your_user_story_here"

Примеры ссылок на пространство: https://ваш_url/community/knowledge/edu/docs https://ваш_url/groups/platforma

ссылки должны быть именно на корень пространства (без фильтров и /content)

Работаем с blogs groups projects spaces community вынимаем все файлы из этих типов пространств (файлы по прямой ссылке и файлы из вложений).

Параметры JSON для Jive:

• type: "jive" - указывает тип источника
• url - ссылка на пространство Jive
• login и password - учетные данные для доступа к Jive

Создание с указанием документов из Confluence

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "confluence", "url": "https://ваш_url/display/dotNet", "api_key": "YOUR_CONFLUENCE_API_KEY"}' \
     -F "user_story=write_your_user_story_here"

Параметры аналогичны запросу с загрузкой файлов по URL, однако в поле urls для документа указывается JSON.

Параметры JSON для Confluence:

• type: "confluence" - указывает тип источника
• url - ссылка на документ или пространство Confluence
• api_key - токен для доступа к Confluence (Personal Access Token)

Для Confluence поддерживается 2 вида ссылок:

• Текстовые (https://ваш_url/display/dotNet/Concurrency)
• С pageid (https://ваш_url/pages/viewpage.action?pageId=244450657)

Каждая ссылка может быть как простой страницей, содержание которой выкачивается, так и пространством/подпространством ссылок. Все страницы, зависимые вниз по иерархии от указанной страницы, выкачиваются в индекс вместе с ней. Страницы скачиваются в формате PDF, в верхней части документа прописывается путь в иерархии. Далее документы обрабатываются в стандартном процессе индексации файлов.

Для каждого документа необходимо заново указывать токен Confluence. Есть возможность создать один индекс из разных пространств Confluence.

Создание с указанием документов из Google Drive

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "google_drive", "url": "https://drive.google.com/drive/folders/your_folder_id_or_file_id"}' \
     -F "user_story=write_your_user_story_here"

Параметры аналогичны запросу с загрузкой файлов по URL, однако в поле urls для документа указывается JSON. Обратите внимание, что для корректной работы curl параметр urls должен указываться в одинарных кавычках, а ключи и значения json - в двойных.

Параметры JSON для Google Drive:

• type: "google_drive" - указывает тип источника
• url - ссылка на файл или папку в Google Drive. Если указана папка, все файлы из нее (и подпапок рекурсивно) будут включены.

Настройка доступа к Google Drive:

Для работы с Google Drive необходим файл google_credentials.json с учетными данными сервисного аккаунта Google Cloud. Подробнее - в документации Google

При запуске сервиса индексации (indexer) этот файл должен быть доступен. По умолчанию, indexer ищет его по пути /app/google_credentials.json внутри контейнера. Этот путь можно переопределить с помощью переменной окружения GOOGLE_CREDENTIALS_PATH.

Пример google_credentials.json:

{
  "type": "service_account",
  "project_id": "example-project-12345",
  "private_key_id": "your_private_key_id",
  "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
  "client_email": "your-service-account-email@example-project-12345.iam.gserviceaccount.com",
  "client_id": "your_client_id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-service-account-email%40example-project-12345.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Создание с указанием документов из Yandex Disk

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/urls \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'urls={"type": "yandex_disk", "url": "https://disk.yandex.ru/d/your_public_file_or_folder_link"}' \
     -F "user_story=write_your_user_story_here"

Параметры аналогичны запросу с загрузкой файлов по URL, однако в поле urls для документа указывается JSON. Обратите внимание, что для корректной работы curl параметр urls должен указываться в одинарных кавычках, а ключи и значения json - в двойных.

Параметры JSON для Yandex Disk:

• type: "yandex_disk" - указывает тип источника
• url - публичная ссылка на файл или папку на Яндекс.Диске. Если указана папка, все файлы из нее (и подпапок рекурсивно) будут включены.

Настройка доступа к Yandex Disk:

Для работы с Yandex Disk необходимо указать OAuth-токен через переменную окружения YANDEX_DISK_TOKEN.

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

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

curl -X DELETE http://base_url:8080/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 http://base_url:8080/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"
  ]
}

После создания бота в Qdrant также будет доступна непустая коллекция с соответствующим именем (bot_id):

https://localhost:6333/dashboard#/collections

Помимо созданных индексов в Qdrant находится служебная коллекция botsinfo (нельзя удалять, без неё невозможна корректная работа).

Все боты

curl -X GET http://base_url:8080/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 http://base_url:8080/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 http://base_url:8080/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.

Аналогично созданию бота с урл можно передать не только прямую ссылку но и json для Jive/Яндекс/Google Drive

Добавление или обновление документа с Яндекс.Диска

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/document_by_url \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'url={"type": "yandex_disk", "url": "https://disk.yandex.ru/d/your_file_id"}'

Параметры JSON для Yandex Disk:

• type: "yandex_disk" - указывает тип источника
• url - публичная ссылка на файл или папку на Яндекс.Диске. Если указана папка, все файлы из нее (и подпапок рекурсивно) будут включены.

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

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/document_by_url \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'url={"type": "jive", "url": "https://ваш_url/docs/DOC-3345", "login": "your_login", "password": "your_password"}'

Параметры JSON для Jive:

• type: "jive" - указывает тип источника
• url - ссылка на документ Jive
• login и password - учетные данные для доступа к Jive

Обрабатываются ссылки документации в формате {ссылка на jive}/docs/DOC-{id документа}. Оттуда выкачиваются документы и далее обрабатываются в стандартном процессе индексации файлов.

Для каждого документа необходимо заново указывать логин/пароль.

Добавление или обновление пространства с jive

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/document_by_url \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'url={"type": "jive", "url": "https://ваш_url/groups/platforma_test", "login": "your_login", "password": "your_password"}'

Параметры JSON для Jive:

• type: "jive" - указывает тип источника
• url - ссылка на пространство Jive
• login и password - учетные данные для доступа к Jive

Ссылки нужны именно на корень пространства (без фильтров и /content)

работаем с blogs groups projects spaces community вынимаем все файлы из этих типов пространств (файлы по прямой ссылке и файлы из вложений) и далее обрабатываем в стандартном процессе индексации файлов.

Добавление или обновление документа с Google Drive

curl -X PUT http://base_url:8080/indexapi/bot/bot_id/document_by_url \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -F 'url={"type": "google_drive", "url": "https://drive.google.com/file/d/your_file_id"}'

Параметры JSON для Google Drive:

• type: "google_drive" - указывает тип источника
• url - ссылка на файл или папку в Google Drive. Если указана папка, все файлы из нее (и подпапок рекурсивно) будут включены.

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

curl -X DELETE http://base_url:8080/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 http://base_url:8080/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 http://base_url:8080/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 http://base_url:8080/indexapi/bot/bot_id/documents -H "Authorization: Bearer YOUR_TOKEN_HERE"

Описание

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

Параметры

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

Ответы

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

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

curl http://base_url:8080/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 – ошибка при обработке документа.