Zelfstudie: Een aangepaste analyse voor telefoonnummers maken

In zoekoplossingen kunnen tekenreeksen met complexe patronen of speciale tekens lastig zijn om mee te werken, omdat met de standaardanalyse zinvolle delen van een patroon worden verwijderd of verkeerd worden geïnterpreteerd. Dit resulteert in een slechte zoekervaring waarbij gebruikers de verwachte informatie niet kunnen vinden. Telefoonnummers zijn een klassiek voorbeeld van tekenreeksen die moeilijk te analyseren zijn. Ze hebben verschillende indelingen en bevatten speciale tekens die de standaardanalyse negeert.

Met telefoonnummers als onderwerp gebruikt deze zelfstudie de REST API's van de Search Service om problemen met patroongegevens op te lossen met behulp van een aangepaste analyse. Deze benadering kan worden gebruikt als voor telefoonnummers of aangepast voor velden met dezelfde kenmerken (met speciale tekens), zoals URL's, e-mailberichten, postcodes en datums.

In deze handleiding leert u:

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken

• Een Azure AI Search-service.

• Visual Studio Code met de REST Client-extensie.

Bestanden downloaden

De broncode voor deze zelfstudie bevindt zich in het bestand custom-analyzer.rest in de GitHub-opslagplaats Azure-Samples/azure-search-rest-samples .

Een beheerderssleutel en -URL kopiëren

Voor de REST-aanroepen in deze zelfstudie is een zoekservice-eindpunt en een beheer-API-sleutel vereist. U kunt deze waarden ophalen uit Azure Portal.

1. Meld u aan bij Azure Portal en selecteer uw zoekservice.

2. Selecteer in het linkerdeelvenster Overzicht en kopieer het eindpunt. Deze moet de volgende indeling hebben: https://my-service.search.windows.net

3. Selecteer inhet linkerdeelvenster> en kopieer een beheerderssleutel voor volledige rechten op de service. Er zijn twee uitwisselbare beheersleutels, bedoeld voor bedrijfscontinuïteit voor het geval u er een moet vervangen. U kunt één van beide sleutels gebruiken om objecten toe te voegen, wijzigen of verwijderen.

   

Een initiële index maken

1. Open een nieuw tekstbestand in Visual Studio Code.

2. Stel variabelen in op het zoekeindpunt en de API-sleutel die u in de vorige sectie hebt verzameld.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
   

3. Sla het bestand op met een .rest bestandsextensie.

4. Plak het volgende voorbeeld om een kleine index te maken die wordt aangeroepen phone-numbers-index met twee velden: id en phone_number.

   ### Create a new index
   POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
   
   {
     "name": "phone-numbers-index",  
     "fields": [
       {
         "name": "id",
         "type": "Edm.String",
         "key": true,
         "searchable": true,
         "filterable": false,
         "facetable": false,
         "sortable": true
       },
       {
         "name": "phone_number",
         "type": "Edm.String",
         "sortable": false,
         "searchable": true,
         "filterable": false,
         "facetable": false
       }
     ]
   }
   

   U hebt nog geen analyse gedefinieerd, dus de standard.lucene analyse wordt standaard gebruikt.

5. Selecteer Verzoek verzenden. U moet een HTTP/1.1 201 Created antwoord hebben en de hoofdtekst van het antwoord moet de JSON-weergave van het indexschema bevatten.

6. Laad gegevens in de index met documenten die verschillende formats van telefoonnummers bevatten. Dit zijn uw testgegevens.

   ### Load documents
   POST {{baseUrl}}/indexes/phone-numbers-index/docs/index?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
   
   {
     "value": [
       {
         "@search.action": "upload",
         "id": "1",
         "phone_number": "425-555-0100"
       },
       {
         "@search.action": "upload",
         "id": "2",
         "phone_number": "(321) 555-0199"
       },
       {
         "@search.action": "upload",
         "id": "3",
         "phone_number": "+1 425-555-0100"
       },
       {
         "@search.action": "upload",
         "id": "4",
         "phone_number": "+1 (321) 555-0199"
       },
       {
         "@search.action": "upload",
         "id": "5",
         "phone_number": "4255550100"
       },
       {
         "@search.action": "upload",
         "id": "6",
         "phone_number": "13215550199"
       },
       {
         "@search.action": "upload",
         "id": "7",
         "phone_number": "425 555 0100"
       },
       {
         "@search.action": "upload",
         "id": "8",
         "phone_number": "321.555.0199"
       }
     ]
   }
   

7. Probeer query's die vergelijkbaar zijn met wat een gebruiker kan typen. Een gebruiker kan bijvoorbeeld zoeken (425) 555-0100 in een willekeurig aantal indelingen en verwacht nog steeds dat resultaten worden geretourneerd. Start met zoeken (425) 555-0100.

   ### Search for a phone number
   POST {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
   
   {
     "search": "(425) 555-0100"
   }
   

   De query retourneert drie van de vier verwachte resultaten, maar retourneert ook twee onverwachte resultaten.

   {
       "value": [
           {
               "@search.score": 0.05634898,
               "phone_number": "+1 425-555-0100"
           },
           {
               "@search.score": 0.05634898,
               "phone_number": "425 555 0100"
           },
           {
               "@search.score": 0.05634898,
               "phone_number": "425-555-0100"
           },
           {
               "@search.score": 0.020766128,
               "phone_number": "(321) 555-0199"
           },
           {
               "@search.score": 0.020766128,
               "phone_number": "+1 (321) 555-0199"
           }
       ]
   }
   

8. Probeer het opnieuw zonder opmaak: 4255550100.

   ### Search for a phone number
   POST {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
   
   {
     "search": "4255550100"
   }
   

   Deze query presteert nog slechter en retourneert slechts één van de vier juiste resultaten.

   {
       "value": [
           {
               "@search.score": 0.6015292,
               "phone_number": "4255550100"
           }
       ]
   }
   

U bent niet de enige die deze resultaten verwarrend vindt. In de volgende sectie wordt uitgelegd waarom u deze resultaten krijgt.

Bekijken hoe analyzers werken

Als u deze zoekresultaten wilt begrijpen, moet u begrijpen wat de analyse doet. Hier kunt u de standaardanalyse testen met behulp van de Analyse-API, waarmee u een basis kunt bieden voor het ontwerpen van een analyseanalyse die beter aan uw behoeften voldoet.

Een analyse is een onderdeel van de zoekmachine voor volledige tekst die verantwoordelijk is voor het verwerken van tekst in queryreeksen en geïndexeerde documenten. Afhankelijk van het scenario manipuleren verschillende analyses tekst op verschillende manieren. Voor dit scenario gaan we een analyse maken die geschikt is voor telefoonnummers.

Analyses bestaan uit drie onderdelen:

• tekenfilters waarmee afzonderlijke tekens in de invoertekst worden verwijderd of vervangen.
• Een tokenizer die de invoertekst in tokens onderbreekt, die sleutels in de zoekindex worden.
• tokenfilters waarmee de tokens worden gemanipuleerd die door de tokenizer worden geproduceerd.

In het volgende diagram ziet u hoe deze drie onderdelen samenwerken om een zin te tokeniseren.

Deze tokens worden vervolgens opgeslagen in een omgekeerde index, waardoor snelle zoekopdrachten in volledige tekst mogelijk zijn. Met een omgekeerde index kunt u zoeken in volledige tekst toestaan door alle unieke termen die zijn geëxtraheerd tijdens de lexicale analyse, toe te wijzen aan de documenten waarin ze voorkomen. In het volgende diagram ziet u een voorbeeld:

Elke zoekopdracht komt neer op het zoeken naar de termen die in de omgekeerde index zijn opgeslagen. Wanneer een gebruiker een query opgeeft:

1. Wordt de query geparseerd en worden de querytermen geanalyseerd.
2. De omgekeerde index wordt gescand op documenten met overeenkomende termen.
3. Het score-algoritme rangschikt de opgehaalde documenten.

Als de querytermen niet overeenkomen met de termen in de omgekeerde index, worden de resultaten niet geretourneerd. Zie Zoeken in volledige tekst in Azure AI Search voor meer informatie over hoe query's werken.

Analyseanalyses testen met behulp van de Analyse-API

Azure AI Search biedt een Analyse-API waarmee u analyses kunt testen om te begrijpen hoe tekst wordt verwerkt.

Roep de Analyse-API aan met behulp van de volgende aanvraag:

### Test analyzer
POST {{baseUrl}}/indexes/phone-numbers-index/analyze?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}

{
  "text": "(425) 555-0100",
  "analyzer": "standard.lucene"
}

De API retourneert de tokens die zijn geëxtraheerd uit de tekst, met behulp van de analyse die u hebt opgegeven. De standaard Lucene Analyzer splitst het telefoonnummer in drie afzonderlijke tokens.

{
    "tokens": [
        {
            "token": "425",
            "startOffset": 1,
            "endOffset": 4,
            "position": 0
        },
        {
            "token": "555",
            "startOffset": 6,
            "endOffset": 9,
            "position": 1
        },
        {
            "token": "0100",
            "startOffset": 10,
            "endOffset": 14,
            "position": 2
        }
    ]
}

Omgekeerd wordt het telefoonnummer 4255550100 waarvan de indeling geen enkel leesteken bevat, in één enkele token getokeniseerd.

{
  "text": "4255550100",
  "analyzer": "standard.lucene"
}

Respons:

{
    "tokens": [
        {
            "token": "4255550100",
            "startOffset": 0,
            "endOffset": 10,
            "position": 0
        }
    ]
}

Houd er rekening mee dat zowel querytermen als de geïndexeerde documenten een analyse ondergaan. Als u terugdenkt naar de zoekresultaten uit de vorige stap, kunt u zien waarom deze resultaten worden geretourneerd.

In de eerste query worden onverwachte telefoonnummers geretourneerd omdat een van de tokens overeenkomt 555met een van de termen die u hebt doorzocht. In de tweede query wordt slechts één getal geretourneerd omdat dit de enige record is die een token heeft dat overeenkomt met 4255550100.

Een aangepaste analyse bouwen

Nu u de resultaten begrijpt die u ziet, bouwt u een aangepaste analyser om de tokenisatielogica te verbeteren.

Ons doel is om intuïtieve zoekacties te kunnen uitvoeren op telefoonnummers, ongeacht welke indeling de query of geïndexeerde tekenreeks heeft. Als u dit resultaat wilt bereiken, geeft u een tekenfilter, een tokenizer en een tokenfilter op.

Tekenfilters

Tekenfilters verwerken tekst voordat deze in de tokenizer wordt ingevoerd. Veelgebruikte toepassingen van tekenfilters zijn het filteren van HTML-elementen en het vervangen van speciale tekens.

Voor telefoonnummers wilt u witruimte en speciale tekens verwijderen, omdat niet alle notaties voor telefoonnummers dezelfde speciale tekens en spaties bevatten.

"charFilters": [
    {
      "@odata.type": "#Microsoft.Azure.Search.MappingCharFilter",
      "name": "phone_char_mapping",
      "mappings": [
        "-=>",
        "(=>",
        ")=>",
        "+=>",
        ".=>",
        "\\u0020=>"
      ]
    }
  ]

Het filter verwijdert -()+. en spaties uit de invoer.

Tokeniseerders

Met tokenizers wordt tekst opgesplitst in tokens en worden tegelijkertijd sommige tekens, zoals leestekens, verwijderd. Vaak is het doel van tokeniseren om een zin op te splitsen in afzonderlijke woorden.

Gebruik voor dit scenario een trefwoordtokenizer keyword_v2om het telefoonnummer vast te leggen als één term. Dit is niet de enige manier om dit probleem op te lossen, zoals wordt uitgelegd in de sectie Alternatieve benaderingen .

Keywordtokenizers geven altijd dezelfde tekst als één enkele term weer die hen wordt gegeven.

Tokenfilters

Tokenfilters wijzigen of filteren de tokens die door de tokenizer worden gegenereerd. Tokenfilters worden vaak gebruikt om alle tekens in kleine letters om te zetten met behulp van kleine-lettertokenfilter. Een ander veelvoorkomend gebruik is het filteren van stopwoorden, zoals the, andof is.

Hoewel u geen van deze filters voor dit scenario hoeft te gebruiken, gebruikt u een nGram-tokenfilter om gedeeltelijke zoekopdrachten van telefoonnummers mogelijk te maken.

"tokenFilters": [
  {
    "@odata.type": "#Microsoft.Azure.Search.NGramTokenFilterV2",
    "name": "custom_ngram_filter",
    "minGram": 3,
    "maxGram": 20
  }
]

NGramTokenFilterV2

Met het tokenfilter nGram_v2 worden tokens gesplitst in n-grammen van een bepaalde grootte op basis van de parameters minGram en maxGram.

Voor de telefoonanalyse wordt minGram ingesteld op 3 omdat dat de kortste subtekenreeks is waarvoor gebruikers naar verwachting zullen zoeken. maxGram is zo ingesteld 20 dat alle telefoonnummers, zelfs met extensies, in één n-gram passen.

Het ongelukkige neveneffect van n-grammen is dat sommige valse positieven worden opgeleverd. U lost dit in een latere stap op door een afzonderlijke analyse uit te bouwen voor zoekopdrachten die geen n-gram tokenfilter bevatten.

Analyser

Met de tekenfilters, tokenizer en tokenfilters kunt u de analyse definiëren.

"analyzers": [
  {
    "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
    "name": "phone_analyzer",
    "tokenizer": "keyword_v2",
    "tokenFilters": [
      "custom_ngram_filter"
    ],
    "charFilters": [
      "phone_char_mapping"
    ]
  }
]

Vanuit de Analyse-API, uitgaande van de volgende invoer, zijn de uitvoer van de aangepaste analyse als volgt:

Alle tokens in de uitvoerkolom bestaan in de index. Als uw query een van deze termen bevat, wordt het telefoonnummer geretourneerd.

Herbouwen met behulp van de nieuwe analyse

1. Verwijder de huidige index.

   ### Delete the index
   DELETE {{baseUrl}}/indexes/phone-numbers-index?api-version=2025-09-01 HTTP/1.1
   api-key: {{apiKey}}
   

2. Maak de index opnieuw met behulp van de nieuwe analyse. Dit indexschema voegt een aangepaste analysedefinitie en een aangepaste analysetoewijzing toe aan het telefoonnummerveld.

   ### Create a new index
   POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}
   
   {
       "name": "phone-numbers-index-2",  
       "fields": [
         {
             "name": "id",
             "type": "Edm.String",
             "key": true,
             "searchable": true,
             "filterable": false,
             "facetable": false,
             "sortable": true
         },
         {
             "name": "phone_number",
             "type": "Edm.String",
             "sortable": false,
             "searchable": true,
             "filterable": false,
             "facetable": false,
             "analyzer": "phone_analyzer"
         }
       ],
       "analyzers": [
           {
             "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
             "name": "phone_analyzer",
             "tokenizer": "keyword_v2",
             "tokenFilters": [
             "custom_ngram_filter"
           ],
           "charFilters": [
             "phone_char_mapping"
             ]
           }
       ],
       "charFilters": [
           {
             "@odata.type": "#Microsoft.Azure.Search.MappingCharFilter",
             "name": "phone_char_mapping",
             "mappings": [
               "-=>",
               "(=>",
               ")=>",
               "+=>",
               ".=>",
               "\\u0020=>"
             ]
           }
         ],
         "tokenFilters": [
           {
             "@odata.type": "#Microsoft.Azure.Search.NGramTokenFilterV2",
             "name": "custom_ngram_filter",
             "minGram": 3,
             "maxGram": 20
         }
       ]
   }
   

De aangepaste analyse testen

Nadat u de index opnieuw hebt gemaakt, test u de analyse met behulp van de volgende aanvraag:

### Test custom analyzer
POST {{baseUrl}}/indexes/phone-numbers-index-2/analyze?api-version=2025-09-01  HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}} 

{
  "text": "+1 (321) 555-0199",
  "analyzer": "phone_analyzer"
}

U ziet nu de verzameling tokens die het gevolg zijn van het telefoonnummer.

{
    "tokens": [
        {
            "token": "132",
            "startOffset": 1,
            "endOffset": 17,
            "position": 0
        },
        {
            "token": "1321",
            "startOffset": 1,
            "endOffset": 17,
            "position": 0
        },
        {
            "token": "13215",
            "startOffset": 1,
            "endOffset": 17,
            "position": 0
        },
        ...
        ...
        ...
    ]
}

De aangepaste analyzer aanpassen om om te gaan met fout-positieven

Nadat u de aangepaste analyzer hebt gebruikt om voorbeeldquery's uit te voeren op de index, ziet u dat het terughaalvermogen is verbeterd en dat alle overeenkomende telefoonnummers nu worden geretourneerd. Het n-gram-tokenfilter zorgt er echter ook voor dat het vals positieven als resultaat teruggeeft. Dit is een veelvoorkomend neveneffect van een n-gram-tokenfilter.

Als u vals-positieven wilt voorkomen, maakt u een afzonderlijke analyzer voor query's. Deze analyzer is identiek aan de vorige, behalve dat het de custom_ngram_filter weglaat.

    {
      "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
      "name": "phone_analyzer_search",
      "tokenizer": "custom_tokenizer_phone",
      "tokenFilters": [],
      "charFilters": [
        "phone_char_mapping"
      ]
    }

Specificeer in de indexdefinitie zowel een indexAnalyzer als een searchAnalyzer.

    {
      "name": "phone_number",
      "type": "Edm.String",
      "sortable": false,
      "searchable": true,
      "filterable": false,
      "facetable": false,
      "indexAnalyzer": "phone_analyzer",
      "searchAnalyzer": "phone_analyzer_search"
    }

Nadat u deze wijziging hebt aangebracht, bent u klaar. Dit zijn de volgende stappen:

1. Verwijder de index.

2. Maak de index opnieuw nadat u de nieuwe aangepaste analyzer (phone_analyzer-search) hebt toegevoegd en wijs die analyzer toe aan de phone-number-eigenschap van het searchAnalyzer-veld.

3. Laad de gegevens opnieuw.

4. Test de query's opnieuw om te controleren of de zoekopdracht werkt zoals verwacht. Als u het voorbeeldbestand gebruikt, maakt u met deze stap de derde index met de naam phone-number-index-3.

Andere manieren

De analyse die in de vorige sectie wordt beschreven, is ontworpen om de flexibiliteit voor zoeken te maximaliseren. Dit gaat echter ten koste gaan van de mogelijkheid om veel, mogelijk onbelangrijke termen in de index te kunnen opslaan.

In het volgende voorbeeld ziet u een alternatieve analyse die efficiënter is in tokenisatie, maar dit heeft nadelen.

Uitgaande van een invoer van 14255550100, kan de analyse het telefoonnummer niet logisch segmenten. Het kan bijvoorbeeld het landnummer 1 niet scheiden van het netnummer 425. Deze discrepantie leidt ertoe dat het telefoonnummer niet wordt geretourneerd als een gebruiker geen landcode in de zoekopdracht opneemt.

"analyzers": [
  {
    "@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
    "name": "phone_analyzer_shingles",
    "tokenizer": "custom_tokenizer_phone",
    "tokenFilters": [
      "custom_shingle_filter"
    ]
  }
],
"tokenizers": [
  {
    "@odata.type": "#Microsoft.Azure.Search.StandardTokenizerV2",
    "name": "custom_tokenizer_phone",
    "maxTokenLength": 4
  }
],
"tokenFilters": [
  {
    "@odata.type": "#Microsoft.Azure.Search.ShingleTokenFilter",
    "name": "custom_shingle_filter",
    "minShingleSize": 2,
    "maxShingleSize": 6,
    "tokenSeparator": ""
  }
]

In het volgende voorbeeld wordt het telefoonnummer gesplitst in de segmenten waarnaar u normaal gesproken verwacht dat een gebruiker zoekt.

Afhankelijk van uw vereisten kan dit een efficiëntere benadering van het probleem zijn.

Belangrijke punten

Deze handleiding toonde het proces van het bouwen en testen van een aangepaste analyzer. U hebt een index gemaakt, gegevens geïndexeerd en vervolgens een query uitgevoerd op basis van de index om te zien welke zoekresultaten werden geretourneerd. Van daaruit hebt u de Analyse-API gebruikt om het lexicale analyseproces in actie te zien.

Hoewel de analyse die in deze zelfstudie is gedefinieerd, een eenvoudige oplossing biedt voor het zoeken naar telefoonnummers, kan hetzelfde proces worden gebruikt om een aangepaste analyse te maken voor elk scenario dat vergelijkbare kenmerken deelt.

Hulpbronnen opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project de resources te verwijderen die u niet meer nodig hebt. Ressources die actief blijven draaien, kunnen geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in de Azure Portal met behulp van de koppeling Alle resources of Resourcegroepen in het linkernavigatiedeelvenster.

Volgende stappen

Nu u weet hoe u een aangepaste analyse maakt, bekijkt u alle verschillende filters, tokenizers en analysefuncties die beschikbaar zijn voor het bouwen van een uitgebreide zoekervaring: