bulgakov

API, структурированный вывод и RAG

После урока

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

От чата к API

Чат удобен для ручной работы. API позволяет приложению формировать запрос, получать результат, измерять затраты и включать модель в повторяемый процесс. Но вместе с API появляются обязанности: тайм-ауты, лимиты, ошибки сети, контроль схемы, обработка отказов, журналирование и защита ключа.

Запрос должен хранить идентификатор операции, модель, версию промпта, параметры и ссылку на входные данные. Секретный ключ находится на серверной стороне или в принятом менеджере секретов; его нельзя встраивать в публичный frontend. Переменная окружения удобнее строки в коде, но не делает секрет недоступным всем процессам и агентам в той же среде.

Для новых интеграций OpenAI важно читать текущий API: в документации GPT-6 Astra и GPT-6.1 Sol использование инструментов требует Responses API. Старые примеры Chat Completions нельзя механически переносить на новые модели. Выбор между прямыми Responses, Agents SDK и управляемым Agents API зависит от того, кто контролирует цикл, состояние и среду исполнения. S24, S26

Структурированный ответ

Для классификации обращения полезно получить объект с полями category, urgency, needs_human и evidence_ids. JSON Schema описывает допустимые типы и значения. Режим structured outputs помогает соблюсти поддерживаемую схему, но не гарантирует правильную категорию и существование основания. Нужны отдельные проверки фактов и бизнес-ограничений. S25

JSON
{
  "category": "delivery",
  "urgency": "normal",
  "needs_human": false,
  "evidence_ids": ["shipping_public"]
}

Строка shipping_public должна существовать в списке документов, доступных этому пользователю и полученных в данном запросе. Произвольный идентификатор, придуманный моделью, отклоняется. Если ответ обрезан, модель отказала или сеть вернула ошибку, это отдельные состояния, а не «пустой успешный JSON».

В templates/structured_output_schema.json дана учебная схема, в templates/response_request.example.json — пример тела запроса Responses. Это документационный пример, а не выполненный платный вызов. Перед реальным запуском сверяйте поддержку полей и модели по текущей документации.

Вызов функции не равен её выполнению

Модель может предложить вызов get_order(order_id=42). Приложение должно проверить имя инструмента, структуру аргументов, права пользователя, состояние заказа и лимиты. Только затем выполняется функция. Результат возвращается модели как данные с идентификатором вызова. При нескольких вызовах важно правильно связать ответы с запросами. S24

Не предоставляйте универсальный run_any_sql или execute_shell там, где достаточно get_order_status. Узкий инструмент проще тестировать и ограничивать. Он может внутри пользоваться сложной системой, но внешние аргументы должны отражать предметное действие. Определение tenant_id лучше брать из доверенной сессии, а не из текста модели.

Когда нужен RAG

Retrieval-augmented generation — генерация с предварительным извлечением подходящих материалов. Модель отвечает, опираясь на найденные фрагменты внешней базы. Такой подход полезен, когда знания меняются, имеют происхождение или должны учитывать права доступа. Историческая работа Lewis и соавторов описывает сочетание параметрической модели и внешнего поиска; сегодняшние реализации значительно разнообразнее. S41

RAG не обязательно означает векторную базу. Для короткого справочника достаточно полнотекстового поиска; для кодов товаров полезно точное совпадение; для смысловых перефразирований — embeddings; для сложных случаев — сочетание методов и reranker. Выбирайте архитектуру по измеренному провалу простого решения.

Путь документа

Сначала документ поступает с владельцем, правами, версией и датой действия. Затем извлекается текст, сохраняются заголовки и ссылки на оригинал. Документ делится на фрагменты, индексируется, ищется по запросу пользователя, фильтруется по доступам и актуальности, ранжируется. В модель передаются ограниченные фрагменты с идентификаторами. Ответ проверяется и связывается с источниками.

От документа к ответу

Права и актуальность проверяются до передачи фрагментов модели.

  1. ДокументыВладелец, версия, дата, права.
  2. ИзвлечениеТекст, таблицы, границы разделов.
  3. ИндексЛексический, векторный или гибридный поиск.
  4. Поиск с фильтрамиЗапрос пользователя, права и дата действия.
  5. ФрагментыРанжирование, идентификаторы и происхождение.
  6. Ответ и проверкаОснования и полнота; отказ от ответа, если данных мало.
Сначала оценивайте качество найденных оснований, затем — качество ответа.

Не режьте текст механически так, чтобы определение осталось в одном фрагменте, а исключение — в другом. Размер и overlap подбирайте на вопросах, а не по универсальному числу. Для таблиц сохраняйте заголовки столбцов; для PDF проверяйте порядок чтения; для изображения страницы может понадобиться OCR и визуальная проверка.

Embeddings отображают фрагменты в числовые представления, где близость помогает искать похожее. Близость не означает истинность, актуальность или право доступа. Результат может быть тематически подходящим, но относиться к прошлому тарифу или другому клиенту. Reranker уточняет порядок кандидатов, однако не устраняет необходимость метаданных и фильтров.

Авторизация до раскрытия

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

Удаление документа требует обработки индекса, копий, кэшей и журнала согласно вашим правилам хранения. Простое удаление исходного PDF не обязательно удаляет его embedding и извлечённый текст. Документируйте происхождение фрагментов, чтобы можно было найти и обновить производные данные.

Оценка поиска отдельно от ответа

Если ответ неверный, сначала спросите, был ли нужный фрагмент среди найденных. Recall@k измеряет, насколько часто релевантный материал попадает в первые k кандидатов при определённом эталоне. Затем оцените, использовала ли модель его верно, не добавила ли неподтверждённое и правильно ли указала источник.

Нужны вопросы четырёх типов: обычные; с перефразированием; требующие нескольких фрагментов; без ответа в базе. Добавьте конфликт версий и закрытый материал. Система, всегда выдающая уверенный текст, может получить приятную оценку стиля и провалить главную задачу.

В малом учебном наборе один правильный документ на вопрос; в реальности релевантных документов может быть несколько. Поэтому интерпретация recall и полноты зависит от разметки. Эталон тоже проверяется человеком: автоматически сгенерированный вопрос может ссылаться на несуществующее основание.

Практикум без облака

labs/retrieval_lab.py реализует небольшой лексический поиск по учебным документам. Он фильтрует доступ и дату, ранжирует по словам и выдаёт найденные фрагменты. Это не семантический поиск и не генеративная модель. Намеренная простота позволяет проверить свойства до подключения дорогого компонента.

Запустите python3 labs/retrieval_lab.py. В публичном режиме вопрос о возврате должен вести к действующему правилу 14 дней, а не закрытому VIP-правилу 30 дней и не старому правилу 7 дней. Вопрос без подходящих данных должен дать пустой результат. Файл с атакующей инструкцией используется как недоверенный текст для следующей главы, а не как команда к исполнению.

Усложнение: добавьте embeddings или полнотекстовый движок и сравните на тех же вопросах. Не называйте изменение улучшением, пока не измерены качество, задержка и отсутствие утечек. Более сложный pipeline может ухудшить поиск точных кодов и исключений.

Критерий: вы можете локализовать ошибку в загрузке, поиске, фильтре, ранжировании, генерации или проверке. Утверждение «RAG убирает галлюцинации» заменено измеримыми свойствами конкретной системы.


Скачать практикумы и рабочие шаблоны.