Konfigurace vektorizátoru v indexu vyhledávání

Ve službě Azure AI Vyhledávač vektorizátor převede během provádění dotazu text nebo obrázky na vektory, což vám umožní odesílat prosté textové dotazy proti vektorovým polím bez toho, abyste museli sami vytvářet embeddingy.

Vektorizátor je definován v indexu vyhledávání a přiřazen k vektorovým polím prostřednictvím vektorového profilu. V době dotazu vektorizátor volá vložený model, který vygeneruje vektor ze vstupu dotazu. Další informace naleznete v tématu Použití integrované vektorizace v dotazech.

Pokud chcete do indexu přidat vektorizátor, použijte průvodce importem nebo návrhář indexu na webu Azure Portal, indexy – vytvoření nebo aktualizaci (REST API) nebo balíček sady Azure SDK. Tento článek používá REST jako příklad.

Požadavky

• Index s prohledávatelnými vektorovými poli ve vyhledávací službě

• (Volitelné) Protokolování diagnostiky povolené ve vyhledávací službě pro potvrzení provádění vektorových dotazů

• Podporované nasazení modelu vkládání pro vektorizátor.

• Oprávnění k aktualizaci a dotazování indexu Tento článek používá doporučené ověřování bez klíčů. Přiřaďte role Přispěvatel vyhledávací služby a Čtenář dat indexu vyhledávání k vašemu uživatelskému účtu, přihlaste se k Azure a získejte přístupový token. Pokud místo toho používáte klíče rozhraní API , získejte klíč správce pro operace aktualizace a klíč dotazu pro operace vyhledávání.

• Oprávnění k použití modelu vkládání Například u Azure OpenAI musí volající mít uživatelská oprávnění Cognitive Services OpenAI . Můžete také použít klíč rozhraní API.

• Visual Studio Code s rozšířením REST Client Vytvořte soubor .rest nebo .http pro odeslání každého požadavku REST v tomto článku přímo z editoru.

Podporované modely vkládání

Azure AI Vyhledávač nabízí několik typů vektorizátorů, z nichž každá je spárovaná s odpovídající dovedností. Dovednost generuje vkládání během indexování, zatímco vektorizátor generuje vkládání v době dotazu. Pro oba musíte použít stejný model vkládání, proto zvolte dvojici vektorizátoru dovedností, která odkazuje na stejné nasazení modelu.

Následující tabulka uvádí vektorizátory a jejich podporované modely a související dovednosti.

^{1 Prostřednictvím}embed-v-4-0 nebo vektorizátoru katalogu modelů Microsoft Foundry můžete zadat pouze programově, nikoli prostřednictvím webu Azure Portal. Pomocí portálu ale můžete sadu dovedností nebo vektorizátor následně spravovat.

Definování vektorizátoru pomocí průvodce

Průvodce importem dat v Azure portalu může číst soubory ze služby Azure Blob Storage, vytvořit index s dílovanými a vektorizovanými poli a přidat vektorizátor. Vektorizátor generovaný průvodcem je záměrně nastavený na stejný model vkládání, který se používá k indexování obsahu objektu blob.

Vytvoření ukázkového indexu pomocí vektorizátoru pomocí průvodce:

1. Nahrajte soubory do kontejneru ve službě Azure Storage. K otestování těchto pokynů na bezplatné vyhledávací službě jsme použili malé textové soubory z NASA Earth at Night e-book .

2. Spusťte průvodce importem dat. Zvolte blob kontejner pro zdroj dat.

   

3. Zvolte druh vektorizátoru a v případě potřeby nasazení modelu. V tomto příkladu se používá nasazení Azure OpenAI a text-embedding-ada-002.

   

4. Po dokončení průvodce a veškerého zpracování indexeru byste měli mít index s prohledávatelným vektorovým polem. Definice JSON pole vypadá takto:

    {
      "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": []
    }
   

   Měli byste mít také vektorový profil, algoritmus vektorového vyhledávání a vektorizátor. Jejich definice JSON vypadají takto:

    "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",
        },
      }
    ]
   

Definování vektorizátoru prostřednictvím kódu programu

Pokud jste nepoužívali průvodce portálem nebo chcete přidat vektorizátor do existujícího indexu, můžete vektorizátor a profil vektoru definovat programově. Vektorový profil odkazuje vektorizátor na jedno nebo více vektorových polí a určuje algoritmus vektorového vyhledávání, který se používá pro navigační struktury.

Definování vektorizátoru a vektorového profilu v existujícím indexu:

1. Načtěte definici indexu pomocí indexů – Get (REST API). Nahraďte název služby, název indexu a přístupový token vlastními hodnotami.

   ### 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>
   

   Warning

   Načtený vektorizátor vlastního rozhraní Web API obsahuje <redacted> pro každou hodnotu httpHeaders. Při aktualizaci stejného vektorizátoru beze změny jeho name, kindnebo urimůžete znovu odeslat <redacted> odpovídající existující názvy hlaviček. Pokud změníte uri, odešlete skutečné hodnoty pro každou httpHeaders položku. Další pravidla aktualizací najdete v tématu Vlastní vektorizátor webového rozhraní API.

2. K aktualizaci definice indexu použijte indexy – Vytvoření nebo aktualizace (REST API). Vložte úplnou definici indexu do textu požadavku.

   ### 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. Do objektu vectorizers přidejte oddíl vectorSearch. Tato část určuje informace o připojení k nasazenému embeddingovému modelu. Následující příklad obsahuje Azure OpenAI i vlastní webové API pro porovnání.

   "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. Přidejte algorithms oddíl do vectorSearch. Tato část definuje algoritmus vektorového vyhledávání , který se používá pro navigační struktury.

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

5. Přidejte profiles oddíl do vectorSearch souboru. Tato část odkazuje na vektorizátor a algoritmus vyhledávání vektorů definovaný v předchozích krocích.

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

6. V poli fields přiřaďte profil vektoru k jednomu nebo více vektorovým polím zadáním vlastnosti 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. Odešlete požadavek PUT pro aktualizaci definice indexu. Pokud je požadavek úspěšný, měli byste obdržet 204 No Content odpověď.

8. Pokud chcete ověřit vektorizátor a profil vektoru, spusťte znovu požadavek GET z prvního kroku. Potvrďte, že:

   • Pole vectorSearch.vectorizers obsahuje definici vektorizátoru se správnými kind parametry a parametry připojení.

   • Pole vectorSearch.profiles obsahuje profil, který odkazuje na váš vektorový analyzátor dle jména.

   • Pole vectorSearch.algorithms obsahuje algoritmus vektorového vyhledávání, na který odkazuje váš profil.

   • Vlastnost vectorSearchProfile vektorových polí v fields poli odpovídá názvu profilu.

Testování vektorizátoru

Pokud chcete potvrdit, že vektorizátor funguje, odešlete vektorový dotaz , který předá textový řetězec místo vektoru. Následující příklad cílí na ukázkový index z Definice vektorizátoru pomocí průvodce, ale můžete otestovat vlastní index úpravou názvů polí a parametrů dotazu.

K odeslání požadavku použijte dokumenty – Vyhledávací příspěvek (REST API). Nahraďte název služby, název indexu a přístupový token vlastními hodnotami.

### 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
        }
    ]
}

Klíčové body:

• "kind": "text" říká vyhledávacímu modulu, že vstup je textový řetězec a použít vektorizátor přidružený k vyhledávacímu poli.

• "text" je řetězec prostého jazyka, který se má vektorizovat.

• "fields": "text_vector" je název pole, na které se má dotazovat. Pokud použijete ukázkový index vytvořený průvodcem, vygenerované vektorové pole má název text_vector.

• "exhaustive": true obchází graf HNSW a provádí vyhledávání hrubou silou u všech vektorů. Toto nastavení je užitečné pro přesnost testování, ale je pomalejší než výchozí přibližné vyhledávání. Odeberte tento parametr v produkčních dotazech, aby se zlepšil výkon.

• Dotaz nenastavuje žádné vlastnosti vektorizátoru. Vyhledávací web je načte automaticky z vektorového profilu přiřazeného k poli.

Pokud je vektorizátor správně nakonfigurovaný, vrátí odpověď odpovídající dokumenty seřazené podle podobnosti. Měli byste získat tři výsledky (k: 3), z nichž první je nejrelevavantnější.

{
    "@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
    ]
}

Řešení problémů

Pokud vektorizátor nefunguje podle očekávání, začněte tabulkou běžných chyb a zkontrolujte diagnostické protokoly, kde najdete další podrobnosti.

Běžné chyby

Následující tabulka uvádí běžné chyby vektorizátoru a jejich řešení.

Kontrola protokolů

Pokud jste pro vyhledávací službu povolili protokolování diagnostiky, spusťte následující dotaz Kusto a potvrďte provádění dotazu ve vektorovém poli.

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

Osvědčené postupy

• Použijte spravovanou identitu místo klíčů rozhraní API v produkčním prostředí. Spravované identity jsou bezpečnější a vyhněte se režijním nákladům na obměnu klíčů. Další informace najdete v tématu Konfigurace vyhledávací služby pro připojení pomocí spravované identity.

• Nasaďte model vkládání ve stejné oblasti jako vyhledávací služba. Kolokace snižuje latenci a zlepšuje rychlost přenosu dat mezi službami. Vektorizátory jsou dostupné ve všech oblastech, kde je služba Azure AI Vyhledávač dostupná, ale dostupnost modelu se liší podle poskytovatele.

• Pro indexování a dotazy použijte samostatná nasazení stejného modelu vkládání. Vyhrazená nasazení umožňují přidělit kvótu TPM nezávisle pro každou úlohu a usnadnit identifikaci zdrojů provozu.

• Monitorujte kvótu TPM pro Azure OpenAI. Pokud dosáhnete limitu TPM, zkontrolujte limity kvót a zvažte žádost o vyšší limit prostřednictvím podpůrného případu.

• Projděte si osvědčené postupy pro dovednosti vkládání v Azure OpenAI. Stejné pokyny platí pro vektorizátor Azure OpenAI.

Související obsah

• Vektorové vyhledávání ve službě Azure AI Vyhledávač
• Integrované vkládání vektorů
• Vytvoření vektorového dotazu