Dela via

Konfigurera integrerad vektorisering i Azure AI Search med HJÄLP av REST

I den här artikeln får du lära dig hur du använder en kompetensuppsättning för att segmentera och vektorisera innehåll från en datakälla som stöds. Kompetensuppsättningen anropar färdigheten Textdelning eller Dokumentlayout för segmentering och en inbäddningsfärdighet som är kopplad till en inbäddningsmodell som stöds för segmentvektorisering. Du får också lära dig hur du lagrar det segmenterade och vektoriserade innehållet i ett vektorindex.

Den här artikeln beskriver arbetsflödet från slutpunkt till slutpunkt för integrerad vektorisering med hjälp av REST. Portalbaserade instruktioner finns i Snabbstart: Vektorisera text och bilder i Azure-portalen.

Förutsättningar

Datakällor som stöds

Integrerad vektorisering fungerar med alla datakällor som stöds. Den här artikeln fokuserar dock på de vanligaste datakällorna, som beskrivs i följande tabell.

Datakälla som stöds Beskrivning
Azure Blob Storage Den här datakällan fungerar med blobar och tabeller. Du måste använda ett standardkonto för prestanda (generell användning v2). Åtkomstnivåerna kan vara heta, coola eller kalla.
Azure Data Lake Storage (ADLS) Gen2 Det här är ett Azure Storage-konto med ett hierarkiskt namnområde aktiverat. Kontrollera att du har Data Lake Storage genom att gå till fliken Egenskaper på sidan Översikt .

Skärmbild av ett Azure Data Lake Storage-konto i Azure-portalen.

Inbäddningsmodeller som stöds

För integrerad vektorisering måste du använda någon av följande inbäddningsmodeller på en Azure AI-plattform. Distributionsinstruktioner finns i ett senare avsnitt.

Leverantör Modeller som stöds
Azure OpenAI i Azure AI Foundry Models1, 2 text-embedding-ada-002
Textinbäddning-3-liten
text-inbäddning-3-stor
Azure AI-tjänster med flera tjänster, resurs3 För text och bilder: Azure AI Vision multimodal4

1 Slutpunkten för din Azure OpenAI-resurs måste ha en anpassad underdomän, till exempel https://my-unique-name.openai.azure.com. Om du skapade resursen i Azure-portalen genererades den här underdomänen automatiskt under resurskonfigurationen.

2 Azure OpenAI-resurser (med åtkomst till inbäddningsmodeller) som skapades i Azure AI Foundry-portalen stöds inte. Endast Azure OpenAI-resurser som skapats i Azure-portalen är kompatibla med Inbäddningsfärdigheten för Azure OpenAI.

3 I faktureringssyfte måste du koppla din Azure AI-resurs med flera tjänster till kompetensuppsättningen i din Azure AI Search-tjänst. Om du inte använder en nyckellös anslutning (förhandsversion) för att skapa färdighetssamlingen måste båda resurserna finnas i samma region.

4 Azure AI Vision multimodal inbäddningsmodell är tillgänglig i utvalda regioner.

Rollbaserad åtkomst

Du kan använda Microsoft Entra-ID med rolltilldelningar eller nyckelbaserad autentisering med anslutningssträngar med fullständig åtkomst. För Azure AI Search-anslutningar till andra resurser rekommenderar vi rolltilldelningar.

Så här konfigurerar du rollbaserad åtkomst för integrerad vektorisering:

  1. Aktivera roller i söktjänsten och konfigurera en systemtilldelad hanterad identitet.

  2. På datakällans plattform och inbäddningsmodellprovider skapar du rolltilldelningar som gör att din söktjänst kan komma åt data och modeller. Se Förbereda dina data och Förbered inbäddningsmodellen.

Anmärkning

Kostnadsfria söktjänster stöder rollbaserade anslutningar till Azure AI Search. De stöder dock inte hanterade identiteter vid utgående anslutningar till Azure Storage eller Azure AI Vision. Den här bristen på stöd kräver nyckelbaserad autentisering på anslutningar mellan kostnadsfria söktjänster och andra Azure-resurser.

Om du vill ha säkrare anslutningar använder du basic-nivån eller högre. Du kan sedan aktivera roller och konfigurera en hanterad identitet för auktoriserad åtkomst.

I detta avsnitt hämtar du slutpunkten och Microsoft Entra-token för din Azure AI Search-tjänst. Båda värdena är nödvändiga för att upprätta anslutningar i REST-begäranden .

Tips/Råd

Följande steg förutsätter att du använder rollbaserad åtkomst för proof-of-concept-testning. Om du vill använda integrerad vektorisering för apputveckling kan du läsa Ansluta din app till Azure AI Search med hjälp av identiteter.

  1. Logga in på Azure-portalen och välj din Azure AI Search-tjänst.

  2. Om du vill hämta din sökslutpunkt kopierar du URL:en på sidan Översikt . En exempelslutpunkt för sökning är https://my-service.search.windows.net.

  3. Hämta din Microsoft Entra-token genom att köra följande kommando i det lokala systemet. Det här steget kräver slutförande av snabbstart: Anslut utan nycklar.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Förbereda dina data

I det här avsnittet förbereder du dina data för integrerad vektorisering genom att ladda upp filer till en datakälla som stöds, tilldela roller och hämta anslutningsinformation.

  1. Logga in på Azure-portalen och välj ditt Azure Storage-konto.

  2. I den vänstra rutan väljer duDatalagringscontainrar>.

  3. Skapa en container eller välj en befintlig container och ladda sedan upp filerna till containern.

  4. Så här tilldelar du roller:

    1. Välj Åtkomstkontroll (IAM) i den vänstra rutan.

    2. Välj Lägg till>Lägg till rolltilldelning.

    3. Under Jobbfunktionsroller väljer du Lagringsblobdataläsare och sedan Nästa.

    4. Under Medlemmar väljer du Hanterad identitet och sedan Välj medlemmar.

    5. Välj din prenumeration och söktjänstens hanterade identitet.

  5. Så här hämtar du en anslutningssträng:

    1. I den vänstra rutan väljer du Åtkomstnycklar för säkerhet + nätverk>.

    2. Kopiera någon av anslutningssträngarna, som du anger senare i Ange variabler.

  6. (Valfritt) Synkronisera borttagningar i containern med borttagningar i sökindexet. Så här konfigurerar du indexeraren för borttagningsidentifiering:

    1. Aktivera mjuk borttagning på ditt lagringskonto. Om du använder inbyggd mjuk borttagning krävs inte nästa steg.

    2. Lägg till anpassade metadata som en indexerare kan skanna för att avgöra vilka blobar som ska tas bort. Ge din anpassade egenskap ett beskrivande namn. Du kan till exempel ge egenskapen namnet "IsDeleted" och ställa in den på false. Upprepa det här steget för varje blob i containern. När du vill ta bort bloben ändrar du egenskapen till true. Mer information finns i Ändra och ta bort identifiering vid indexering från Azure Storage.

Förbered en inbäddningsmodell

I det här avsnittet förbereder du din Azure AI-resurs för integrerad vektorisering genom att tilldela roller, hämta en slutpunkt och distribuera en inbäddningsmodell som stöds.

Azure AI Search stöder textinbäddning-ada-002, textinbäddning-3-small och textinbäddning-3-large. Azure AI Search använder internt inbäddningsfärdigheten i Azure OpenAI för att ansluta till Azure OpenAI.

  1. Logga in på Azure-portalen och välj din Azure OpenAI-resurs.

  2. Så här tilldelar du roller:

    1. Välj Åtkomstkontroll (IAM) i den vänstra rutan.

    2. Välj Lägg till>Lägg till rolltilldelning.

    3. Under Jobbfunktionsroller väljer du Cognitive Services OpenAI-användare och sedan Nästa.

    4. Under Medlemmar väljer du Hanterad identitet och sedan Välj medlemmar.

    5. Välj din prenumeration och söktjänstens hanterade identitet.

  3. Så här hämtar du en slutpunkt:

    1. I den vänstra rutan väljer du Resurshanteringsnycklar>och Slutpunkt.

    2. Kopiera slutpunkten för din Azure OpenAI-resurs. Du anger den här URL:en senare i Ange variabler.

  4. Så här distribuerar du en inbäddningsmodell:

    1. Logga in på Azure AI Foundry-portalen och välj din Azure OpenAI-resurs.

    2. I den vänstra rutan väljer du Modellkatalog.

    3. Distribuera en inbäddningsmodell som stöds.

    4. Kopiera distributions- och modellnamnen som du anger senare i Ange variabler. Distributionsnamnet är det anpassade namn som du valde, medan modellnamnet är den modell som du distribuerade, till exempel text-embedding-ada-002.

Ange variabler

I det här avsnittet anger du anslutningsinformation för din Azure AI Search-tjänst, din datakälla som stöds och din inbäddningsmodell som stöds.

  1. I Visual Studio Code klistrar du in följande platshållare i din .rest eller .http fil.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE

  2. Ersätt @baseUrl med sökslutpunkten och @token med den Microsoft Entra-token som du fick i Hämta anslutningsinformation för Azure AI Search.

  3. Beroende på din datakälla lägger du till följande variabler.

    Datakälla Variabler Ange den här informationen
    Azure Blob Storage-lagringstjänst @storageConnectionString och @blobContainer Anslutningssträngen och namnet på containern som du skapade i Förbered dina data.
    ADLS Gen2 @storageConnectionString och @blobContainer Anslutningssträngen och namnet på containern som du skapade i Förbered dina data.

  4. Beroende på din inbäddningsmodellprovider lägger du till följande variabler.

    Inbäddningsmodellprovider Variabler Ange den här informationen
    Azure OpenAI @aoaiEndpoint, @aoaiDeploymentName och @aoaiModelName Slutpunkten, distributionsnamnet och modellnamnet som du fick i Förbered inbäddningsmodellen.
    Azure AI Vision @aiMultiServiceEndpoint Slutpunkten som du fick i Förbered inbäddningsmodellen.

  5. Skicka följande begäran för att verifiera variablerna.

    ### List existing indexes by name
GET {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    Ett svar bör visas i ett intilliggande fönster. Om du har befintliga index visas de. Annars är listan tom. Om HTTP-koden är 200 OKär du redo att fortsätta.

Anslut till dina data

I det här avsnittet ansluter du till en datakälla som stöds för indexerarbaserad indexering. En indexerare i Azure AI Search kräver en datakälla som anger typ, autentiseringsuppgifter och container.

  1. Använd Skapa datakälla för att definiera en datakälla som tillhandahåller anslutningsinformation under indexeringen.

    ### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "name": "my-data-source",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
        "connectionString": "{{storageConnectionString}}"
    },
    "container": {
        "name": "{{blobContainer}}",
        "query": null
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null
  }

  2. Ange type till din datakälla: azureblob eller adlsgen2.

  3. Om du vill skapa datakällan väljer du Skicka begäran.

Skapa en kompetens

I det här avsnittet skapar du en kompetensuppsättning som anropar en inbyggd färdighet för att segmentera ditt innehåll och en inbäddningsfärdighet för att skapa vektorrepresentationer av segmenten. Färdighetsuppsättningen utförs under indexeringen i ett senare avsnitt.

Anropa en inbyggd färdighet för att segmentera ditt innehåll

Genom att partitionera innehållet i segment kan du uppfylla kraven i inbäddningsmodellen och förhindra dataförlust på grund av trunkering. Mer information om segmentering finns i Segmentera stora dokument för vektorsökningslösningar.

För inbyggd datasegmentering erbjuder Azure AI Search kunskaper om textdelning och dokumentlayout. Färdigheten Dela upp text delar upp text i meningar eller sidor med en viss längd, medan färdigheten Dokumentlayout bryter innehåll baserat på styckegränser.

  1. Använd Skapa kompetensuppsättning för att definiera en kompetensuppsättning.

    ### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "name": "my-skillset",
    "skills": []
  }

  2. I matrisen skills anropar du färdigheten Textdelning eller Dokumentlayout. Du kan klistra in någon av följande definitioner.

        "skills": [
     {
       "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
       "name": "my-text-split-skill",
       "textSplitMode": "pages",
       "maximumPageLength": 2000,
       "pageOverlapLength": 500,
       "maximumPagesToTake": 0,
       "unit": "characters",
       "defaultLanguageCode": "en",
       "inputs": [
        {
          "name": "text",
          "source": "/document/text",
          "inputs": []
        }
       ],
       "outputs": [
        {
          "name": "textItems"
        }
       ]
     },
     {
       "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
       "name": "my-document-layout-skill",
       "context": "/document",
       "outputMode": "oneToMany",
       "markdownHeaderDepth": "h3",
       "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
       ],
       "outputs": [
        {
          "name": "markdown_document"
        }
       ]
     }
    ]

    Anmärkning

    Kunskaper om dokumentlayout finns i offentlig förhandsversion. Om du vill anropa den här färdigheten använder du ett förhandsversions-API, till exempel 2025-03-01-preview.

Anropa en inbäddningsfärdighet för att vektorisera segmenten

För att vektorisera segmenterat innehåll behöver kompetensuppsättningen en inbäddningsfärdighet som pekar på en inbäddningsmodell som stöds.

  1. Efter den inbyggda segmenteringsfärdigheten i matrisen skills anropar du Azure OpenAI-inbäddningsfärdigheten eller Azure AI Vision-färdigheten. Du kan klistra in någon av följande definitioner.

         {
       "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
       "resourceUri": "{{aoaiEndpoint}}",
       "deploymentId": "{{aoaiDeploymentName}}",
       "modelName": "{{aoaiModelName}}",
       "dimensions": 1536,
       "inputs": [
         {
           "name": "text",
           "source": "/document/text"
         }
       ],
       "outputs": [
         {
           "name": "embedding"
         }
       ]
     },
     {
       "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
       "context": "/document",
       "modelVersion": "2023-04-15", 
       "inputs": [
         {
           "name": "url",
           "source": "/document/metadata_storage_path"
         },
         {
           "name": "queryString",
           "source": "/document/metadata_storage_sas_token"
         }
       ],
       "outputs": [
         {
           "name": "vector"
         }
       ]
     }

    Anmärkning

    Azure AI Vision-funktionen är i offentlig förhandsversion. Om du vill anropa den här färdigheten använder du ett förhandsversions-API, till exempel 2025-03-01-preview.

  2. Om du använder Azure OpenAI-inbäddningsfärdigheten anger dimensions du antalet inbäddningar som genereras av inbäddningsmodellen.

  3. Om du använder Azure AI Vision-färdigheten kopplar du din Azure AI-resurs för flera tjänster efter matrisen skills . Den här bifogade filen är i faktureringssyfte.

        "skills": [ ... ],
    "cognitiveServices": {
      "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
      "subdomainUrl": "{{aiMultiServiceEndpoint}}"
     }

  4. För att skapa färdigheterna väljer du Skicka begäran.

Skapa ett vektorindex

I det här avsnittet konfigurerar du fysiska datastrukturer i Azure AI Search-tjänsten genom att skapa ett vektorindex. Schemat för ett vektorindex kräver följande:

  • Namn
  • Nyckelfält (sträng)
  • Ett eller flera vektorfält
  • Vektorkonfiguration

Vektorfält lagrar numeriska representationer av segmenterade data. De måste vara sökbara och hämtningsbara, men de kan inte vara filterbara, fasettbara eller sorterbara. De kan inte heller ha analysverktyg, normaliserare eller synonymmappningstilldelningar.

Förutom vektorfält innehåller exempelindexet i följande steg icke-bevektorfält för innehåll som kan läsas av människor. Det är vanligt att inkludera oformaterade motsvarigheter till det innehåll som du vill vektorisera. Mer information finns i Skapa ett vektorindex.

  1. Använd Skapa index för att definiera schemat för ett vektorindex.

    ### Create a vector index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "name": "my-vector-index",
    "fields": [],
    "vectorSearch": []
  }

  2. Lägg till en vektorsökningskonfiguration i vectorSearch avsnittet.

        "vectorSearch": {
      "algorithms": [
        {
          "name": "hnsw-algorithm",
          "kind": "hnsw",
          "hnswParameters": {
            "m": 4,
            "efConstruction": 400,
            "efSearch": 100,
            "metric": "cosine"
          }
        }
      ],
      "profiles": [
        {
          "name": "vector-profile-hnsw",
          "algorithm": "hnsw-algorithm",
        }
      ]
    }

    vectorSearch.algorithms anger den algoritm som används för indexering och frågekörning av vektorfält, medan vectorSearch.profiles algoritmkonfigurationen kopplas till en profil som du kan tilldela till vektorfält.

  3. Beroende på din inbäddningsmodell uppdaterar du vectorSearch.algorithms.metric. Giltiga värden för avståndsmått är cosine, dotproduct, euclideanoch hamming.

  4. Lägg till fält i fields matriserna. Inkludera ett nyckelfält för dokumentidentifiering, icke-bevektorfält för innehåll som kan läsas av människor och vektorfält för inbäddningar.

        "fields": [
      {
        "name": "id",
        "type": "Edm.String",
        "key": true,
        "filterable": true
      },
      {
        "name": "title",
        "type": "Edm.String",
         "searchable": true,
         "filterable": true,
         "sortable": true,
         "retrievable": true
      },
      {
        "name": "titleVector",
        "type": "Collection(Edm.Single)",
         "searchable": true,
         "retrievable": false,
         "stored": true,
         "dimensions": 1536,
         "vectorSearchProfile": "vector-profile-hnsw"
      },
      {
        "name": "content",
        "type": "Edm.String",
         "searchable": true,
         "retrievable": true
      },
      {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
         "searchable": true,
         "retrievable": false,
         "stored": false,
         "dimensions": 1536,
         "vectorSearchProfile": "vector-profile-hnsw"
      }
    ]

  5. Beroende på din inbäddningsfärdighet anger du dimensions följande värde för varje vektorfält.

    Inbäddningsfärdighet Ange det här värdet
    Azure OpenAI Antalet inbäddningar som genereras av inbäddningsmodellen.
    Azure AI Vision 1024

Lägga till en vektoriserare i indexet

I det här avsnittet aktiverar du vektorisering vid frågetillfället genom att definiera en vektoriserare i ditt index. Vektoriseraren använder inbäddningsmodellen som indexerar dina data för att avkoda en söksträng eller bild till en vektor för vektorsökning.

  1. Lägg till Azure OpenAI-vektoriseraren eller Azure AI Vision-vektoriseraren efter vectorSearch.profiles. Du kan klistra in någon av följande definitioner.

          "profiles": [ ... ],
      "vectorizers": [
        {
          "name": "my-openai-vectorizer",
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
            "resourceUri": "{{aoaiEndpoint}}",
            "deploymentId": "{{aoaiDeploymentName}}",
            "modelName": "{{aoaiModelName}}"
          }
        },
        {
          "name": "my-ai-services-vision-vectorizer",
          "kind": "aiServicesVision",
          "aiServicesVisionParameters": {
            "resourceUri": "{{aiMultiServiceEndpoint}}",
            "modelVersion": "2023-04-15"
          }
        }
      ]

    Anmärkning

    Azure AI Vision-vektoriseraren finns i offentlig förhandsversion. Om du vill anropa den här vektoriseraren använder du ett förhandsversions-API, till exempel 2025-03-01-preview.

  2. Ange vektoriseraren i vectorSearch.profiles.

          "profiles": [
        {
          "name": "vector-profile-hnsw",
          "algorithm": "hnsw-algorithm",
          "vectorizer": "my-openai-vectorizer"
        }
      ]

  3. Om du vill skapa vektorindexet väljer du Skicka begäran.

Skapa en indexerare

I det här avsnittet skapar du en indexerare för att driva hela vektoriseringspipelinen, från datahämtning till körning av kompetensuppsättningar till indexering. Vi rekommenderar att du kör indexeraren enligt ett schema för att bearbeta ändringar eller dokument som missades på grund av begränsningar.

  1. Använd Skapa indexerare för att definiera en indexerare som kör vektoriseringspipelinen.

    ### Create an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "name": "my-indexer",
    "dataSourceName": "my-data-source",
    "targetIndexName": "my-vector-index",
    "skillsetName": "my-skillset",
    "schedule": {
      "interval": "PT2H"
    },
    "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null
    }
  }

  2. Om du vill skapa indexeraren väljer du Skicka begäran.

Köra en vektorfråga för att bekräfta indexering

I det här avsnittet kontrollerar du att innehållet har indexerats genom att skapa en vektorfråga. Eftersom du har konfigurerat en vektoriserare i ett tidigare avsnitt kan sökmotorn avkoda oformaterad text eller en bild till en vektor för frågekörning.

  1. Använd Dokument – Sökpost för att definiera en fråga som är vektorbaserad vid frågetillfället.

    ### Run a vector query
POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "count": true,
    "select": "title, content",
    "vectorQueries": [
        {
          "kind": "text",
          "text": "a sample text string for integrated vectorization",
          "fields": "titleVector, contentVector",
          "k": "3"
        }
    ]
  }

    Anmärkning

    Azure AI Vision-vektoriseraren finns i offentlig förhandsversion. Om du tidigare har använt den här vektoriseraren, använd ett förhandsvisnings-API, till exempel 2025-03-01-preview.

    För frågor som anropar integrerad vektorisering kind måste anges till text, och text måste ange en textsträng. Den här strängen skickas till vektoriseraren som tilldelats vektorfältet. Mer information finns i Fråga med integrerad vektorisering.

  2. Om du vill köra vektorfrågan väljer du Skicka begäran.

Relaterat innehåll