AI Platform Docs

Для кого предназначено

Platform RAG предназначен для трёх ролей:

Роль	Основная задача	Используемый путь
Автор Low-code-агента	Использует готовые коллекции в визуальном редакторе	Кастом-компонент Langflow
Разработчик SDK	Встраивает поиск по базе знаний в агента	Platform SDK
Владелец знаний	Управляет коллекциями и следит за доступностью	Platform SDK или Control Plane

Важно: Platform RAG поставляется как самостоятельный сервис и не интегрирован с другими компонентами платформы в релизе 2026.3.3.

Коллекция — управляемый контейнер документов с закреплённым профилем эмбеддинга, моделью ACL и стратегией чанкинга. Все документы в коллекции индексируются единым способом, что обеспечивает консистентный поиск.

Гибридный поиск

Сервис выполняет поиск по двум критериям одновременно: по смыслу (векторное сходство) и по точным формулировкам (BM25). Результаты сливаются с помощью алгоритма RRF (Reciprocal Rank Fusion) для оптимального ранжирования.

Фильтрация по правам

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

Цитаты и атрибуция

Каждый результат поиска содержит ссылку на источник — doc_id, chunk_id и URL. Это позволяет проверить достоверность ответа и проследить происхождение информации.

Работа с коллекциями

Создание коллекции

Коллекция создаётся через Platform SDK или Control Plane. Для создания необходимо указать:

Имя коллекции — уникальное в рамках рабочего пространства.
Профиль эмбеддинга — идентификатор модели преобразования текста в вектор, заданный администратором.
Модель ACL — определяет, как применяются права доступа: document (по умолчанию) — права на каждый документ отдельно, collection — единые права на всю коллекцию.
Стратегия чанкинга — как документы разбиваются на фрагменты: recursive_text (по умолчанию) — рекурсивная разбивка по разделам, размер и перекрытие настраиваются.

Пример создания коллекции через SDK:

from platform_rag import RagClient

rag = RagClient()

collection = rag.create_collection(
    name="handbook",
    embedding_profile="text-default-v1",
    acl_model="document",
    chunking={"strategy": "recursive_text", "size": 800, "overlap": 120}
)

Просмотр коллекции

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

collection = rag.get_collection("handbook")
print(collection.status)  # ready
print(collection.doc_count)  # количество документов
print(collection.chunk_count)  # количество чанков

Переиндексация

Если необходимо изменить профиль эмбеддинга или стратегию чанкинга, выполняется версионируемая переиндексация. Старая версия индекса сохраняется до завершения новой. In-place изменение профиля не допускается.

Приём документов

Документы попадают в коллекцию через интеграционные сервисы. Интеграционный сервис извлекает данные из источника (Confluence, базы данных, S3), приводит их к каноническому виду и передаёт в Platform RAG через метод submit_documents.

Каноническая форма документа

Каждый документ содержит:

Содержимое — заголовок, разделы с текстом, таблицы.
Метаданные — источник, URL, метки, даты актуальности.
ACL — группы и субъекты, имеющие доступ к документу.
Хеш и ключ идемпотентности — для предотвращения дублирования.

Важно: Права доступа (ACL) должны выводиться из источника данных, а не из внешнего события. Доверять правам, переданным в событии, не допускается.

Статусы заданий

После приёма документа сервис регистрирует задание с одним из статусов:

Статус	Значение
`PENDING`	Документ принят, ожидает обработки воркером
`RUNNING`	Воркер обрабатывает документ
`DONE`	Документ проиндексирован и доступен для поиска
`FAILED`	Ошибка обработки

Проверить статус можно через SDK:

job = rag.ingest_status(job_id)
print(job.status)  # PENDING → RUNNING → DONE / FAILED

Поиск

Запрос на поиск

Потребитель вызывает поиск через Platform SDK или кастом-компонент Langflow. Необходимо указать:

Коллекцию — имя или идентификатор.
Текст запроса — вопрос или фраза для поиска.
Опционально — режим поиска, количество результатов, включение реранка и переписывания запроса.

Пример поиска через SDK:

from platform_rag import RagClient

rag = RagClient()

hits = rag.query(
    collection="handbook",
    text="Правила оформления отпуска",
    mode="hybrid",
    rerank=True,
    top_k=8
)

for hit in hits.items:
    print(f"[{hit.doc_id}] {hit.title}")
    print(f"  {hit.content}")
    print(f"  Источник: {hit.source_url}")

Упаковка контекста

Для передачи контекста в LLM используется метод retrieve_and_pack. Он автоматически подбирает наиболее релевантные фрагменты, укладываясь в заданный бюджет токенов:

ctx = rag.retrieve_and_pack(
    collection="handbook",
    text="Правила оформления отпуска",
    token_budget=3000,
    rerank=True
)

print(ctx.packed_context)  # готовый контекст для LLM
print(ctx.token_count)     # количество токенов
print(ctx.mode)            # full_document или relevance_search

Цитаты

Каждый результат содержит цитату — ссылку на источник, которая обеспечивает:

Атрибуцию — возможность проверить, откуда взята информация.
Оценку заземлённости — проверка, что ответ модели основан на реальных документах, а не на вымысле.

from platform_rag import RagClient

# Инициализация клиента
rag = RagClient()

# Поиск
hits = rag.query(collection="handbook", text=q, mode="hybrid")

# Упаковка контекста
ctx = rag.retrieve_and_pack(collection="handbook", text=q, token_budget=3000)

Безопасная работа

Не передавайте токены и учётные данные через сообщения, снимки экрана и журналы.
Не пытайтесь обойти фильтрацию ACL, подменяя идентификатор коллекции или параметры запроса.
Сообщая об ошибке, передавайте безопасный traceId, время, название коллекции и код ошибки, но не исходный токен и не полный текст запроса.
Секреты источников данных (учётные записи, ключи API) хранятся в платформенном сервисе Secrets и используются только интеграционными сервисами на этапе приёма. В пути запроса и во флоу они отсутствуют.

Ограничения

Platform RAG в релизе 2026.3.3 не интегрирован с другими компонентами платформы и поставляется как самостоятельный сервис.
Поддержка новых источников данных реализуется отдельным интеграционным сервисом; встроенного механизма плагинов внутри Сервиса нет.
Прямая запись в OpenSearch, S3 или RabbitMQ из флоу или SDK не допускается.
Модели эмбеддинга и реранка вызываются исключительно через AI Gateway. Сервис не имеет прямого доступа к инференс-эндпойнтам.
Переписывание запроса и реранк включаются на уровне коллекции или запроса из числа одобренных профилей. Указание произвольной внешней модели не допускается.

Перед началом работы ознакомьтесь с известными ограничениями.

Руководство по Platform RAG