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

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

Аутентификация

Все запросы к облачному API InsightStream требуют токен аутентификации, который должен быть передан в заголовке Authorization в формате:

Authorization: Bearer YOUR_TOKEN

Токен предоставляется нашей командой по запросу.

Базовый URL

https://bot.insightstream.ru

Методы API

Создание ассистента с файлами

Этот метод создает нового ассистента и загружает набор файлов из вашей папки для индексации.

примечание

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

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

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

Какие поддерживаются форматы файлов? На текущий момент в API поддерживаются файлы формата .pdf, .docx, .txt. Если вам необходима поддержка других форматов — напишите нашей команде.

Python
cURL

import requests
from contextlib import ExitStack
import os

def create_bot_with_files(bot_id, token, user_story, folder_path):
    """
    Создает нового ассистента с указанным ID и загружает в него файлы из указанной папки.
    
    Параметры:
        bot_id (str): Уникальный идентификатор ассистента
        token (str): Токен аутентификации
        user_story (str): Описание/инструкция для ассистента
        folder_path (str): Путь к папке с файлами для загрузки
    
    Возвращает:
        dict: Ответ сервера в формате JSON
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    data = {
        'user_story': user_story
    }

    # Получаем список файлов из указанной папки
    file_list = []
    for file_name in os.listdir(folder_path):
        file_path = os.path.join(folder_path, file_name)
        # Добавляем только файлы (игнорируем подпапки)
        if os.path.isfile(file_path):
            file_list.append((file_name, file_path))

    # Используем ExitStack для открытия всех файлов и поддержания их открытыми до завершения запроса
    with ExitStack() as stack:
        files = []
        for filename, filepath in file_list:
            file_obj = stack.enter_context(open(filepath, 'rb'))
            files.append(('files', (filename, file_obj)))
        
        response = requests.put(url, headers=headers, data=data, files=files)
    
    return response.json()

# Пример использования
bot_id = "my_search_bot"
token = "YOUR_TOKEN"
user_story = "Ты полезный ассистент"
folder_path = '/path/to/your/documents'

response = create_bot_with_files(bot_id, token, user_story, folder_path)
print(response)
# Ожидаемый ответ: {"status":"success","message":"Indexing started","bot_id":"my_search_bot"}

# Для загрузки нескольких файлов через curl используйте следующий формат
curl -X PUT "https://bot.insightstream.ru/indexapi/bot/my_search_bot" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "user_story=Ты полезный ассистент" \
  -F "files=@/path/to/file1.pdf" \
  -F "files=@/path/to/file2.docx" \
  -F "files=@/path/to/file3.txt"

Ответ:

{
  "status": "success",
  "message": "Indexing started",
  "bot_id": "my_search_bot"
}

Коды ответов:

202 - Ассистент создан и индексация началась
409 - Конфликт: ассистент с таким ID уже существует
400 - Ошибка в запросе (неправильные параметры)
401 - Ошибка авторизации

примечание

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

Получение списка ассистентов

Этот метод возвращает список всех созданных ассистентов.

Python
cURL

import requests

def get_all_bots(token):
    """
    Получает список всех созданных ассистентов.
    
    Параметры:
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Словарь, где ключ - ID ассистента, значение - URL для доступа к ассистенту
    """
    url = "https://bot.insightstream.ru/indexapi/bots"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.get(url, headers=headers)
    return response.json()

# Пример использования
token = "YOUR_TOKEN"
bots = get_all_bots(token)
print(bots)
# Ожидаемый ответ: {"bot_id1":"https://bot.insightstream.ru/bot_id1", "bot_id2":"https://bot.insightstream.ru/bot_id2"}

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

Ответ:

{
  "bot_id1": "https://bot.insightstream.ru/bot_id1",
  "bot_id2": "https://bot.insightstream.ru/bot_id2"
}

Коды ответов:

200 - Успешное получение списка ассистентов
401 - Ошибка авторизации

Проверка статуса ассистента

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

Python
cURL

import requests

def check_bot_status(bot_id, token):
    """
    Проверяет статус ассистента.
    
    Параметры:
        bot_id (str): ID ассистента для проверки
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Ответ сервера в формате JSON с информацией о статусе ассистента
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.get(url, headers=headers)
    return response.json()

# Пример использования
bot_id = "my_search_bot"
token = "YOUR_TOKEN"
status = check_bot_status(bot_id, token)
print(status)
# Ожидаемый ответ: {"status":"processing"}

curl -X GET "https://bot.insightstream.ru/indexapi/bot/my_search_bot" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

{
  "status": "https://bot.insightstream.ru/my_search_bot"
}

Коды ответов:

200 - Успешное получение статуса ассистента
404 - Ассистент не найден
401 - Ошибка авторизации

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

Этот метод позволяет добавить один новый документ к существующему ассистенту.

Python
cURL

import requests

def add_document_to_bot(bot_id, token, file_path, user_story=None):
    """
    Добавляет один документ к существующему ассистенту.
    
    Параметры:
        bot_id (str): ID ассистента
        token (str): Токен аутентификации
        file_path (str): Путь к файлу для загрузки
        user_story (str, optional): Обновленное описание/инструкции для ассистента
    
    Возвращает:
        dict: Ответ сервера в формате JSON
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}/document"
    
    headers = {
        "Authorization": f"Bearer {token}"
    }

    # Открываем файл для отправки
    files = {
        "file": open(file_path, "rb")
    }

    try:
        # Выполняем PUT-запрос
        response = requests.put(url, headers=headers, files=files)
        return {"status_code": response.status_code, "response": response.json() if response.text else None}
    finally:
        # Закрываем файл
        files["file"].close()

# Пример использования
bot_id = "my_search_bot"
token = "YOUR_TOKEN"
file_path = "/path/to/document.pdf"

response = add_document_to_bot(bot_id, token, file_path, user_story)
print(response)
# Ожидаемый ответ при успехе: {"status_code": 202, "response": {"status": "success"}}

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

Ответ:

{
  "status": "success"
}

Коды ответов:

202 - Документ успешно принят на обработку
404 - Ассистент не найден
409 - Ассистент или документ в данный момент обрабатывается, попробуйте позже
401 - Ошибка авторизации

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

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

Python
cURL

import requests

def check_document_status(bot_id, doc_name, token):
    """
    Проверяет статус обработки документа.
    
    Параметры:
        bot_id (str): ID ассистента
        doc_name (str): Имя документа
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Информация о статусе документа
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}/document/{doc_name}"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.get(url, headers=headers)
    return response.json()

# Пример использования
bot_id = "my_search_bot"
doc_name = "document.pdf"
token = "YOUR_TOKEN"

status = check_document_status(bot_id, doc_name, token)
print(status)
# Ожидаемый ответ при успешной обработке: {"status": "success"}

curl -X GET "https://bot.insightstream.ru/indexapi/bot/my_search_bot/document/document.pdf" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

{
  "status": "success"
}

Коды ответов:

200 - Успешное получение статуса документа
404 - Ассистент или документ не найден
409 - При обработке документа возникла проблема
401 - Ошибка авторизации

Получение списка всех документов ассистента

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

Python
cURL

import requests

def get_all_documents(bot_id, token):
    """
    Получает список всех документов, связанных с ассистентом.
    
    Параметры:
        bot_id (str): ID ассистента
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Словарь, где ключ - имя документа, значение - статус обраассистентки или URL
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}/documents"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.get(url, headers=headers)
    return response.json()

# Пример использования
bot_id = "my_search_bot"
token = "YOUR_TOKEN"

documents = get_all_documents(bot_id, token)
print(documents)
# Ожидаемый ответ: {"document1.pdf":"success","document2.pdf":"http://bot.insightstream.ru/documents/document2.pdf"}

curl -X GET "https://bot.insightstream.ru/indexapi/bot/my_search_bot/documents" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

{
  "document1.pdf": "success",
  "document2.pdf": "https://bot.insightstream.ru/documents/document2.pdf"
}

Коды ответов:

200 - Успешное получение списка документов
404 - Ассистент не найден
401 - Ошибка авторизации

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

Этот метод позволяет удалить документ из ассистента.

Python
cURL

import requests

def delete_document(bot_id, doc_name, token):
    """
    Удаляет документ из ассистента.
    
    Параметры:
        bot_id (str): ID ассистента
        doc_name (str): Имя документа для удаления
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Ответ сервера в формате JSON
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}/document/{doc_name}"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.delete(url, headers=headers)
    return response.json()

# Пример использования
bot_id = "my_search_bot"
doc_name = "document.pdf"
token = "YOUR_TOKEN"

result = delete_document(bot_id, doc_name, token)
print(result)
# Ожидаемый ответ: {"status": "success"}

curl -X DELETE "https://bot.insightstream.ru/indexapi/bot/my_search_bot/document/document.pdf" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

{
  "status": "success"
}

Коды ответов:

200 - Документ успешно удален
404 - Ассистент или документ не найден
401 - Ошибка авторизации

Удаление ассистента

Этот метод позволяет полностью удалить ассистента и все его документы.

Python
cURL

import requests

def delete_bot(bot_id, token):
    """
    Удаляет ассистента и все его документы.
    
    Параметры:
        bot_id (str): ID ассистента для удаления
        token (str): Токен аутентификации
    
    Возвращает:
        dict: Ответ сервера в формате JSON
    """
    url = f"https://bot.insightstream.ru/indexapi/bot/{bot_id}"
    headers = {
        "Authorization": f"Bearer {token}"
    }

    response = requests.delete(url, headers=headers)
    return response.json()

# Пример использования
bot_id = "my_search_bot"
token = "YOUR_TOKEN"

result = delete_bot(bot_id, token)
print(result)
# Ожидаемый ответ: {"status": "success"}

curl -X DELETE "https://bot.insightstream.ru/indexapi/bot/my_search_bot" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

{
  "status": "success"
}

Коды ответов:

200 - Ассистент успешно удален
404 - Ассистент не найден
401 - Ошибка авторизации

Аутентификация​

Базовый URL​

Методы API​

Создание ассистента с файлами​

Получение списка ассистентов​

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

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

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

Получение списка всех документов ассистента​

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

Удаление ассистента​

Аутентификация

Базовый URL

Методы API

Создание ассистента с файлами

Получение списка ассистентов

Проверка статуса ассистента

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

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

Получение списка всех документов ассистента

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

Удаление ассистента