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

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

В данном разделе описаны методы работы с ассистентами InsightStream через API. Здесь вы найдете примеры создания ассистента (загрузка документов), проверки статуса, добавления/обновления документов, а также удаления как отдельных документов, так и всего ассистента.

Создание ассистента (загрузка набора документов)​

Для создания ассистента необходимо отправить запрос на создание нового индекса с указанием уникального идентификатора, пользовательской истории и списка документов для индексации.

Параметры запроса​

  • files (array, обязательный): Список файлов для индексации.
    Поддерживаемые форматы: .pdf, .docx, .txt и другие.
  • user_story (string, обязательный): Описание сценария использования ассистента.
    Рекомендуется отвечать на вопросы: Кто будет использовать ассистента и зачем? Что важно при формировании ответа?
  • sync (boolean, необязательный): Флаг приоритета индексации (1 - высокий приоритет). Запросы с этим флагом будут обработаны раньше обычных запросов на создание бота и раньше любых запросов на добавление документов в существующие боты.
  • time_to_eval (string, необязательный): Время, не раньше которого начнётся индексация в формате YYYY-MM-DD HH:MM.
примечание

Параметры sync и time_to_eval могут использоваться одновременно.

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

примечание

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

Пример запроса​

import requests
from contextlib import ExitStack
import os

assistant_id = "your_assistant_id"  # Уникальный идентификатор ассистента
token = "your_token"  # Токен доступа InsightStream

url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

data = {
    'user_story': 'Я, как инженер, хочу получать быстрые и точные ответы по техническим вопросам.',
    'sync': '1',  # Опционально: высокий приоритет индексации
    'time_to_eval': '2025-04-15 14:00'  # Опционально: отложенная индексация
}

# Путь к каталогу с документами для индексации
folder_path = '/path/to/your/documents'
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))

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)

print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Процесс индексации успешно запущен.
  • 422 Validation Error — Ошибка валидации входных данных.

Создание ассистента с документами по URL​

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

Документ должен находиться по указанному url адресу, например https://files.com/folder/doc3.pdf"

Параметры запроса:​

  • urls (array, form) — Список URL-документов.
  • user_story (string, form) — Пользовательская история.
  • is_force (boolean, form, optional) — Если ассистент уже существует, можно использовать is_force=true для принудительного добавления документов.
  • sync (boolean, необязательный) — Флаг приоритета индексации (1 - высокий приоритет).
  • time_to_eval (string, необязательный) — Время, не раньше которого начнётся индексация (формат: YYYY-MM-DD HH:MM).
import requests

assistant_id = "your_assistant_id"
token = "your_token"
url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}/urls"
headers = {
    "Authorization": f"Bearer {token}"
}
data = {
    "user_story": "Я, как специалист отдела кадров, хочу находить ответы на вопросы по трудовому законодательству.",
    "is_force": "true",
    "sync": "1",  # Опционально: высокий приоритет индексации
    "time_to_eval": "2025-04-15 14:00"  # Опционально: отложенная индексация
}
# Массив с URL документов
files = [
    ('urls', (None, 'https://example.com/doc1.pdf')),
    ('urls', (None, 'https://example.com/doc2.pdf'))
]

response = requests.put(url, headers=headers, data=data, files=files)
print(response.status_code)
print(response.text)

Ответы:

  • 202 Accepted — Индексация начата.

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

После запуска процесса индексации можно проверить текущий статус создания ассистента.

Пример запроса​

import requests

assistant_id = "your_assistant_id"
token = "your_token"

url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.status_code, response.text)

Ответы:

  • 200 OK — Возвращается статус процесса индексации (например, "processing").
  • 422 Validation Error — Ошибка валидации запроса.

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

Позволяет получить список всех созданных ассистентов и их текущий статус.

import requests

token = "your_token"
url = "http://адрес_или_доменное_имя_сервера:8080/indexapi/bots"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Возвращает JSON-объект со статусами всех ассистентов.

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

Чтобы полностью удалить ассистента вместе с его индексированными данными, используйте следующий запрос:

Пример запроса​

import requests

assistant_id = "your_assistant_id"
token = "your_token"

url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.delete(url, headers=headers)
print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Ассистент успешно удалён.
  • 404 Not Found — Ассистент не найден.
  • 409 Conflict — Ассистент находится в процессе создания; повторите запрос позже.

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

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

import requests

assistant_id = "your_assistant_id"
token = "your_token"
url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}/documents"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Возвращает список документов и их статус.
  • 404 Not Found — Бот не найден или документы отсутствуют.

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

Чтобы добавить новый документ или обновить уже существующий в индексе ассистента, используйте следующий запрос:

Пример запроса​

import requests

assistant_id = "your_assistant_id"
token = "your_token"
FILE_PATH = "/path/to/your/document.pdf"

url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}/document"
headers = {
    "Authorization": f"Bearer {token}"
}
files = {
    "file": open(FILE_PATH, "rb")
}

response = requests.put(url, headers=headers, files=files, data=data)
print(response.status_code)
print(response.text)

Ответы:

  • 202 Accepted — Документ успешно отправлен на обработку.
  • 404 Not Found — Ассистент не найден.
  • 409 Conflict — Документ или ассистент в процессе обработки, повторите запрос позже.

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

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

import requests

assistant_id = "your_assistant_id"
doc_name = "document.pdf"
token = "your_token"
url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}/document/{doc_name}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Возвращает текущий статус обработки документа.
  • 404 Not Found — Бот или документ не найдены.
  • 409 Conflict — Документ в процессе обработки.

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

Для удаления конкретного документа из ассистента выполните запрос по следующему шаблону.

Пример запроса​

import requests

assistant_id = "your_assistant_id"
doc_name = "document.pdf"  # Имя удаляемого документа
token = "your_token"

url = f"http://адрес_или_доменное_имя_сервера:8080/indexapi/bot/{assistant_id}/document/{doc_name}"
headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.delete(url, headers=headers)
print(response.status_code)
print(response.text)

Ответы:

  • 200 OK — Документ успешно удалён.
  • 404 Not Found — Ассистент или документ не найдены.
  • 409 Conflict — Документ в процессе обработки.