Настройка векторизатора в индексе поиска

В службе "Поиск ИИ Azure" векторизатор преобразует текст или изображения в векторы во время выполнения запроса, что позволяет отправлять текстовые запросы к векторным полям без необходимости самостоятельно вычислять встраивания.

Векторизатор определяется в индексе поиска и назначается полям векторов через профиль вектора. Во время запроса векторизатор вызывает модель внедрения, чтобы создать вектор из входных данных запроса. Дополнительные сведения см. в статье "Использование интегрированной векторизации в запросах".

Чтобы добавить векторизатор в индекс, используйте мастер импорта или конструктор индексов на портале Azure, индексы — создание или обновление (REST API) или пакет azure SDK. В этой статье используется REST для иллюстрации.

Предварительные требования

• Индекс с полями векторов с возможностью поиска в службе поиска.

• (Необязательно) Ведение журнала диагностики в службе поиска для подтверждения выполнения векторного запроса.

• Поддерживаемое развертывание модели встраивания для векторизатора.

• Разрешения на обновление и запрос индекса. В этой статье используется рекомендуемая проверка подлинности без ключа. Назначьте роли вкладчик службы поиска и читатель данных индекса поиска вашему учетному аккаунту, войдите в Azure и получите маркер доступа. Если вместо этого используются ключи API , получите ключ администратора для операций обновления и ключ запроса для операций поиска.

• Разрешения на использование модели внедрения. Например, при использовании Azure OpenAI вызывающий объект должен иметь разрешения пользователя OpenAI Cognitive Services . Вы также можете использовать ключ API.

• Visual Studio Code с расширением клиента REST. Для отправки каждого запроса REST из этой статьи напрямую из редактора, создайте файл формата .rest или .http.

Поддерживаемые модели внедрения

Поиск по искусственному интеллекту Azure предлагает несколько типов векторизаторов, каждый из которых связан с соответствующим навыком. Навык генерирует эмбеддинги во время индексирования, а векторизатор — во время выполнения запроса. Для обеих моделей необходимо использовать одну и ту же модель встраивания, поэтому выберите пару векторизатор-навык, которая указывает на одно развертывание модели.

В следующей таблице перечислены векторизаторы и их поддерживаемые модели и связанные навыки.

¹ Можно указать embed-v-4-0 только программным способом с помощью векторизатора каталога моделей AML или векторизатора каталога моделей Microsoft Foundry, а не через портал Azure. Однако вы можете использовать портал для управления набором навыков или векторизатором после этого.

Определение векторизатора с помощью мастера

Мастер импорта данных на портале Azure может считывать файлы из хранилища BLOB-объектов Azure, создавать индекс с блоками и векторизованными полями и добавлять векторизатор. По умолчанию векторизатор, созданный мастером, использует ту же модель встраивания, которая применяется для индексирования содержимого BLOB.

Чтобы создать пример индекса с векторизатором с помощью мастера, выполните следующие действия.

1. Отправка файлов в контейнер в службе хранилища Azure. Мы использовали небольшие текстовые файлы из электронной книги NASA "Земля ночью" для тестирования этих инструкций на бесплатном поисковом сервисе.

2. Запустите мастер импорта данных. Выберите контейнер BLOB для источника данных.

   

3. Выберите тип векторизатора и, если применимо, развертывание модели. В этом примере используется Azure OpenAI и развертывание модели text-embedding-ada-002.

   

4. После завершения работы мастера и завершения всей обработки индексатора необходимо иметь индекс с полем вектора с возможностью поиска. Определение JSON поля выглядит следующим образом:

    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false,
      "key": false,
      "dimensions": 1536,
      "vectorSearchProfile": "vector-nasa-ebook-text-profile",
      "synonymMaps": []
    }
   

   У вас также должен быть векторный профиль, алгоритм векторного поиска и векторизатор. Их определения JSON выглядят следующим образом:

    "algorithms": [
      {
        "name": "vector-nasa-ebook-text-algorithm",
        "kind": "hnsw",
        "hnswParameters": {
          "metric": "cosine",
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500
        }
      }
    ],
   "profiles": [
      {
        "name": "vector-nasa-ebook-text-profile",
        "algorithm": "vector-nasa-ebook-text-algorithm",
        "vectorizer": "vector-nasa-ebook-text-vectorizer"
      }
    ],
    "vectorizers": [
      {
        "name": "vector-nasa-ebook-text-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://my-azure-openai-resource.openai.azure.com",
          "deploymentId": "text-embedding-ada-002",
          "modelName": "text-embedding-ada-002",
        },
      }
    ]
   

Определение векторизатора программным способом

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

Определение векторизатора и профиля вектора в существующем индексе:

1. Получение определения индекса с помощью Indexes - Get (REST API). Замените имя службы, имя индекса и маркер доступа собственными значениями.

   ### Get index definition
   GET https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-04-01 HTTP/1.1
   Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
   

   Предупреждение

   Полученный пользовательский векторизатор Web API содержит <redacted> для каждого значения httpHeaders. Если вы обновляете один и тот же векторизатор, не изменяя его name, kind или uri, вы можете повторно отправить <redacted> для сопоставления с существующими именами заголовков. При изменении uriотправьте фактические значения для каждой httpHeaders записи. Сведения о других правилах обновления см. в разделе Пользовательский векторизатор Web API.

2. Используйте индексы— создание или обновление (REST API) для обновления определения индекса. Вставьте полное определение индекса в текст запроса.

   ### Update index definition
   PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-04-01 HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>
   
   // Paste your index definition here
   

3. Добавьте раздел vectorizers в объект vectorSearch. В этом разделе указываются сведения о подключении к развернутой модели внедрения. Следующий пример включает как Azure OpenAI, так и пользовательский веб API для сравнения.

   "vectorSearch": {
       "vectorizers": [
         {
           "name": "my_azure_open_ai_vectorizer",
           "kind": "azureOpenAI",
           "azureOpenAIParameters": {
             "resourceUri": "https://url.openai.azure.com",
             "deploymentId": "text-embedding-ada-002",
             "modelName": "text-embedding-ada-002",
             "apiKey": "<your-azure-openai-api-key>"
           }
         },
         {
           "name": "my_custom_vectorizer",
           "kind": "customWebApi",
           "customWebApiParameters": {
             "uri": "https://contoso.embeddings.com",
             "httpMethod": "POST",
             "authResourceId": null,
             "authIdentity": null
           }
         }
       ]
     }
   

4. Добавьте algorithms раздел в vectorSearch. В этом разделе определяется алгоритм векторного поиска , используемый для структур навигации.

   "algorithms": [
     {
       "name": "my_hnsw_algorithm",
       "kind": "hnsw",
       "hnswParameters": {
         "m": 4,
         "efConstruction": 400,
         "efSearch": 500,
         "metric": "cosine"
       }
     }
   ]
   

5. Добавьте раздел profiles в vectorSearch. В этом разделе ссылается алгоритм векторизатора и векторного поиска, определенный на предыдущих шагах.

   "profiles": [ 
     { 
       "name": "my_vector_profile", 
       "algorithm": "my_hnsw_algorithm", 
       "vectorizer": "my_azure_open_ai_vectorizer" 
     }
   ]
   

6. В массиве fields назначьте профиль вектора одному или нескольким полям вектора, указав vectorSearchProfile свойство.

   "fields": [
       ... // Trimmed for brevity
       {
         "name": "vector",
         "type": "Collection(Edm.Single)",
         "dimensions": 1536,
         "vectorSearchProfile": "my_vector_profile",
         "searchable": true,
         "retrievable": true
       },
       {
         "name": "my_second_vector",
         "type": "Collection(Edm.Single)",
         "dimensions": 1536,
         "vectorSearchProfile": "my_vector_profile",
         "searchable": true,
         "retrievable": true
       }
   ]
   

7. Отправьте запрос PUT для обновления определения индекса. Если запрос выполнен успешно, вы должны получить 204 No Content ответ.

8. Чтобы проверить векторизатор и профиль вектора, повторно запустите запрос GET с первого шага. Убедитесь, что:

   • Массив vectorSearch.vectorizers содержит определение вашего векторизатора и правильные kind параметры подключения.

   • Массив vectorSearch.profiles содержит профиль, ссылающийся на векторизатор по имени.

   • Массив vectorSearch.algorithms включает алгоритм векторного поиска, на который ссылается ваш профиль.

   • Свойство vectorSearchProfile векторных полей в массиве fields соответствует имени профиля.

Тестирование векторизатора

Чтобы подтвердить работу векторизатора, отправьте векторный запрос , который передает текстовую строку вместо вектора. В следующем примере используется пример индекса из определения векторизатора с помощью мастера, но можно протестировать собственный индекс, изменив имена полей и параметры запроса.

Используйте Документы - Search Post (REST API) для отправки запроса. Замените имя службы, имя индекса и маркер доступа собственными значениями.

### Test a vectorizer with a vector query
POST https://my-search-service.search.windows.net/indexes/vector-nasa-ebook-txt/docs/search?api-version=2026-04-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-query-api-key>

{
    "count": true,
    "select": "title, chunk",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "what cloud formations exist in the troposphere",
            "fields": "text_vector",
            "k": 3,
            "exhaustive": true
        }
    ]
}

Основные моменты:

• "kind": "text" сообщает поисковой системе, что входные данные являются текстовой строкой и используют векторизатор, связанный с полем поиска.

• "text" — это строка обычного языка для векторизации.

• "fields": "text_vector" — имя поля для запроса. При использовании примера индекса, созданного мастером, создается векторное поле text_vector.

• "exhaustive": true минует граф HNSW и выполняет поиск методом перебора по всем векторам. Этот параметр полезен для проверки точности, но медленнее, чем приблизительный поиск по умолчанию. Удалите этот параметр в рабочих запросах для повышения производительности.

• Запрос не задает свойства векторизатора. Поисковая система автоматически считывает их из профиля вектора, назначенного полю.

Если векторизатор настроен правильно, ответ возвращает соответствующие документы, ранжированные по сходству. Вы должны получить три результата (k3), первое из которых наиболее актуально.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.66195244,
            "chunk": "Cloud Shadow\tGermany\nIn November 2012, the Earth Observing...",
            "title": "page-25.txt"
        },
        ... // Trimmed for brevity
    ]
}

Устранение неполадок

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

Распространенные ошибки

В следующей таблице перечислены распространенные ошибки векторизатора и способы их устранения.

Проверка журналов

Если вы включили ведение журнала диагностики для службы поиска, выполните следующий запрос Kusto, чтобы подтвердить выполнение запроса в поле вектора.

OperationEvent
| where TIMESTAMP > ago(30m)
| where Name == "Query.Search" and AdditionalInfo["QueryMetadata"]["Vectors"] has "TextLength"

Лучшие практики

• Используйте управляемое удостоверение вместо ключей API в рабочей среде. Управляемые удостоверения являются более безопасными и избегают затрат на смену ключей. Дополнительные сведения см. в статье "Настройка службы поиска для подключения с помощью управляемого удостоверения".

• Разверните модель внедрения в том же регионе, что и служба поиска. Совместное размещение уменьшает задержку и повышает скорость передачи данных между службами. Векторизаторы доступны во всех регионах, где доступен поиск ИИ Azure, но доступность модели зависит от поставщика.

• Используйте отдельные развертывания одной и той же модели внедрения для индексирования и запросов. Выделенные развертывания позволяют выделять квоту TPM независимо для каждой загрузки и упростить определение источников трафика.

• Отслеживайте квоту Azure OpenAI TPM. Если вы достигаете предела вашего TPM, просмотрите ограничения квоты и попробуйте запросить более высокий предел, обратившись в службу поддержки.

• Ознакомьтесь с рекомендациями по внедрению Azure OpenAI. Это же руководство относится к векторизатору Azure OpenAI.

Связанный контент

• Векторный поиск в поиске ИИ Azure
• Внедрение встроенного вектора
• Создание векторного запроса