Как создать векторный индекс Azure AI Search с верной размерностью

Каждому документу требуется строковый key. Поле embedding задаётся как Collection(Edm.Single), searchable:true, dimensions равен фактической длине embedding, vectorSearchProfile указывает существующий профиль. У векторного поля filterable, facetable и sortable должны быть false. Для Azure OpenAI в руководстве указан cosine; профиль связывает поле с алгоритмом hnsw.

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

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

1. Зафиксируйте deployment и один контрольный embedding; проверьте len(vector) до создания схемы. Не смешивайте уменьшенную и исходную размерности.
2. Создайте текстовые id, title, content и числовое vector поле; оставьте title и content retrievable для диагностики.
3. Добавьте vectorSearch.algorithms с hnsw и metric cosine и vectorSearch.profiles с именем p1.
4. Отправьте POST /indexes с api-version=2026-04-01 с правами изменения индекса.
5. Прочтите GET определения индекса: профиль и dimensions должны совпасть с отправленными; только затем грузите реальные embeddings.

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

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

POST /indexes?api-version=2026-04-01
{"name":"ru-kb","fields":[{"name":"id","type":"Edm.String","key":true},
 {"name":"title","type":"Edm.String","searchable":true,"retrievable":true},
 {"name":"content","type":"Edm.String","searchable":true,"retrievable":true},
 {"name":"contentVector","type":"Collection(Edm.Single)","searchable":true,
  "retrievable":false,"dimensions":1536,"vectorSearchProfile":"p1"}],
 "vectorSearch":{"algorithms":[{"name":"h1","kind":"hnsw",
  "hnswParameters":{"metric":"cosine"}}],"profiles":[{"name":"p1","algorithm":"h1"}]}}

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

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

Входной документ id=refund-7, title=Возврат, content=Срок возврата 14 дней и вектор из 1536 чисел. Ожидается, что определение индекса принимает схему, а загрузка полного вектора не выдаёт ошибку размерности. Если локальная модель вернула 512 чисел, правильный результат проверки — остановка загрузки, не дописывание нулей до 1536.

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

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

Размерность — свойство пары «поле/модель», а не удобное число для JSON. Проверьте три контрольных фразы и сохраните lengths и идентификатор deployment вместе с версией схемы. При миграции на модель с другой длиной создайте новую схему или новое поле и переиндексируйте корпус: отдельные документы в одном vector field не могут иметь разную длину. Наличие одного загруженного документа не доказывает, что большой корпус однороден. Проверяйте долю ошибочных документов в ответе индексатора. HNSW строит структуру для приблизительного поиска; маленькая коллекция может выглядеть идеально при неправильных параметрах, поэтому тестируйте и на репрезентативной выборке. Храните человекочитаемый content рядом с вектором: числовые компоненты нельзя превратить обратно в цитату для RAG. Если источники содержат секреты, решите вопрос доступа до создания индекса; retrievable:false для вектора само по себе не защищает текст content. Выбирайте аналитику по запросам после загрузки, когда у вас есть документные ID и ожидаемые релевантные фрагменты.

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

План теста схемы: создайте два независимых набора данных с похожими названиями полей, но разными версиями модели. Первый идёт в ru-kb, второй храните вне загрузки до явной миграции. Для трёх коротких русских предложений запишите реальную длину массива и значения первых нескольких компонент, не публикуя пользовательский текст с персональными сведениями. Сравните field dimensions, output генератора и сведения о deployment: все три должны согласоваться. Проверка массива до сети сокращает число частично принятых пакетов. Отдельно создайте неверный тестовый payload с отсутствующим id: он должен быть отклонён вашей локальной валидацией ключа. После создания индекса выполните GET и сравните не только имя, но и algorithm и profile. Документируйте способ повторного развёртывания схемы в чистом окружении: иначе исправление параметров в живом индексе может потребовать переиндексации. Смысл теста — доказать воспроизводимость структуры, а не превосходство HNSW над другими индексами.