Как загрузить готовые embeddings в Azure AI Search без потери документов

Microsoft описывает загрузку готовых векторов через Documents - Index: POST /indexes/{index}/docs/index с массивом value. Каждый элемент должен содержать строковый ключ документа и соответствовать fields индекса. @search.action со значением upload означает создание либо замену документа, не частичное обновление; вектор и текст надо согласовывать с одной версией источника.

Это не обещание одинакового ранжирования для любого русского корпуса. Результат embedding зависит от deployment, подготовки текста, chunking, обновлений модели и состава индекса. Доступность предварительных функций и ограничения сверяйте с документацией и настройками собственного сервиса; цена и длительность операций здесь намеренно не указаны, потому что они не следуют из поискового ответа. Отделяйте успешный HTTP-запрос от оценки полезности найденного фрагмента.

Пошаговое выполнение

1. Постройте детерминированный id из идентификатора исходника и номера фрагмента; подготовьте журнал id и хеша content.
2. Проверьте числа массива: length соответствует dimensions, нет NaN, null или строк; целевой content согласован с тем же фрагментом.
3. Соберите value с @search.action=upload для каждого документа и отправьте в docs/index.
4. Разберите результат по каждому ключу, фиксируйте status и ошибку; не делайте вывод об успехе всего набора из одного HTTP-кода.
5. Сделайте точечный запрос и сравните возвращённый текст с версией исходника до масштабной загрузки.

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

Готовый REST-шаблон

POST /indexes/ru-kb/docs/index?api-version=2026-04-01
{"value":[{"@search.action":"upload","id":"policy-2026-01",
 "title":"Политика возвратов","content":"Возврат оформляется в течение 14 дней",
 "contentVector":[0.1,0.2,0.3]}]}
# ВАЖНО: [0.1,0.2,0.3] — иллюстрация формата; для ru-kb
# замените массив реальными 1536 числами выбранной модели.

Подставьте своё имя сервиса в https://<service>.search.windows.net, передайте Content-Type: application/json и авторизацию выбранным поддерживаемым способом. Демонстрационный массив из трёх чисел или строка <embedding массива> — только описание формы; они не являются реальным embedding для поля с 1536 измерениями. Перед отправкой проверьте JSON, размерность и отсутствие ключа в клиентском коде.

Входные данные и ожидаемый результат

Вход: policy-2026-01 с одним фрагментом текста и реальным embedding из 1536 чисел; второй документ shipment-2026-01 с 512 числами. Ожидается: локальная проверка отклоняет второй документ до отправки; ответ Index Documents подтверждает status первого ключа, после чего поиск или выборка позволяет проверить текст. HTTP-успех не следует приписывать неотправленному второму элементу.

Ожидаемый ID — проверяемая гипотеза на подготовленном тестовом наборе. При другом корпусе и другом embedding нельзя честно обещать конкретный score и порядок результатов. Сохраняйте как входное содержимое, так и текст возвращённого фрагмента: найденный ID без исходного подтверждения не годится для публикации ответа от имени компании.

Разбор и границы применения

Особенно важна семантика повторной отправки. Upload перезаписывает документ по ключу, поэтому повтор с урезанным набором полей способен затереть ранее полезный content или метаданные. Не используйте upload как патч; если нужен частичный апдейт, выберите документированную операцию merge или mergeOrUpload и проверьте её поведение на вашем индексе. При переиндексации источника не меняйте генератор ID между попытками: иначе появятся почти одинаковые фрагменты с разными ключами и один вопрос будет возвращать несколько дублей. Разделяйте ошибки формата полезной нагрузки, полномочий и отдельного документа. Запросить весь пакет повторно допустимо только после анализа последствий для идемпотентности и стоимости генерации embeddings. Векторная длина не подтверждает, что модель правильная: две разные embedding-модели могут обе давать 1536 чисел, но помещать слова в несовместимые пространства. Храните модель, revision и алгоритм разбиения рядом с manifest загрузки, а не в выдаваемом пользователю тексте. Контрольная выборка с нулевыми, слишком длинными и дублирующимися фрагментами выявит ошибки раньше загрузки миллионного корпуса.

Практический контроль именно этой задачи

Спроектируйте manifest каждой партии: id, идентификатор исходного документа, порядковый номер chunk, хеш текстового фрагмента, модель, длина vector и время версии источника. После ответа Documents - Index сверяйте множество отправленных ключей с множеством обработанных ключей; если ответ или сеть прерваны, сначала перечитайте фактические документы, затем решайте, что отправлять повторно. Наиболее опасный сбой — не ошибка сервера, а валидный устаревший payload: он перезапишет свежий документ тем же id. Поэтому до повторного upload сравнивайте хеш текста и версию исходника. Проведите два теста, один с изменением текста при сохранении ключа, другой с изменением только метаданных. Убедитесь, что программа не теряет вектор и контент на втором тесте. После удаления исходника отдельно запланируйте документированную операцию удаления по ключу; сам upload старых пакетов не очищает ненужные документы. Диагностика по id даст вам проверяемый аудит, а не субъективное впечатление от одного поиска.