Поиск и ответы в своём приложении

Задача: у вас есть продукт, в нём — документы пользователей, и нужно, чтобы по ним можно было спрашивать словами. Обычно это означает разбор PDF и DOCX, нарезку на фрагменты, эмбеддинги, векторную базу, гибридный поиск и промпт с цитатами — недели работы и постоянное сопровождение. Всё это уже сделано.

Что делает ваш код

from agentum_cloud import AgentumClient

cloud = AgentumClient(base_url="https://api.cloud.agentums.ru", api_key="ak_…")

# 1. Приняли файл от пользователя — положили в облако
obj = await cloud.upload(upload.filename, await upload.read())

# 2. Обработка идёт фоном; покажите пользователю «обрабатывается»
await cloud.wait_until_ready(obj.id)

# 3. Дальше — вопросы
answer = await cloud.ask(question, session_id=session_id)

Три вызова вместо конвейера. Разбор форматов, определение типа документа, векторы и ранжирование — на нашей стороне.

Сузить ответ до нужных файлов

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

answer = await cloud.ask(question, object_ids=[obj.id], session_id=session_id)

Если работа идёт внутри папки, есть и папочный скоуп — тогда поиск ограничивается её содержимым.

Показать источники

answer.citations — фрагменты, на которых построен ответ; answer.primary — файл, закреплённый под запрос целиком. Для интерфейса это разные вещи: цитаты идут сносками под ответом, primary — карточкой сверху, потому что на запрос «найди договор с Ромашкой» пользователю нужен сам файл, а не рассуждение о нём.

answer.used_context == False означает, что в документах ничего не нашлось. Это стоит показывать явно: иначе общий ответ модели выглядит как ответ по документам.

Отдать файл пользователю

link = await cloud.get_content(obj.id)   # временная ссылка в хранилище

Ссылка подписана и живёт недолго — её отдают человеку или загрузчику, но не сохраняют. Она ведёт напрямую в хранилище, поэтому наших CORS-заголовков на ней нет: браузерному коду нужен get_raw / get_thumbnail / get_page_image, которые отдают байты через API.

Разделение данных между вашими пользователями

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

Передать «чужой owner_id» параметром нельзя: скоуп берётся из токена, и это не настройка, а устройство.

Что почитать дальше

• Как устроено облако — что скрыто в списках по умолчанию
• Лимиты и расход — что дорого, а что бесплатно
• Справочник API