Oktatóanyag: Egyéni elemző létrehozása telefonszámokhoz
A keresési megoldásokban az összetett mintákkal vagy speciális karakterekkel rendelkező sztringek használata kihívást jelenthet, mivel az alapértelmezett elemző eltávolítja vagy félreértelmezi a minta értelmes részeit, ami rossz keresési élményt eredményez, ha a felhasználók nem találják meg a várt információkat. A telefonszámok olyan klasszikus sztringek, amelyeket nehéz elemezni. Különböző formátumúak, és olyan speciális karaktereket tartalmaznak, amelyeket az alapértelmezett elemző figyelmen kívül hagy.
Ez az oktatóanyag a telefonszámok témáját tekinti át, és bemutatja a mintás adatok problémáit, és bemutatja, hogy ezt a problémát egy egyéni elemzővel oldhatja meg. Az itt ismertetett megközelítés használható telefonszámokhoz, vagy olyan mezőkhöz, amelyek azonos jellemzőkkel rendelkeznek (mintás, speciális karakterekkel), például URL-címekhez, e-mailekhez, irányítószámokhoz és dátumokhoz.
Ebben az oktatóanyagban egy REST-ügyfelet és az Azure AI Search REST API-kat használ a következőkre:
- A probléma ismertetése
- Kezdeti egyéni elemző fejlesztése telefonszámok kezeléséhez
- Az egyéni elemző tesztelése
- Iteráció az egyéni elemzők tervezésénél az eredmények további javítása érdekében
Előfeltételek
Az oktatóanyaghoz az alábbi szolgáltatásokra és eszközökre van szükség.
Visual Studio Code REST-ügyféllel.
Azure AI Search. Hozzon létre vagy keressen egy meglévő Azure AI Search-erőforrást az aktuális előfizetése alatt. Ehhez a rövid útmutatóhoz ingyenes szolgáltatást használhat.
Fájlok letöltése
Az oktatóanyag forráskódja az Azure-Samples/azure-search-rest-samples GitHub-adattár custom-analyzer.rest fájlja.
Kulcs és URL másolása
Az oktatóanyagBAN szereplő REST-hívásokhoz keresési szolgáltatásvégpontra és rendszergazdai API-kulcsra van szükség. Ezeket az értékeket az Azure Portalon szerezheti be.
Jelentkezzen be az Azure Portalra, lépjen az Áttekintés lapra, és másolja ki az URL-címet. A végpontok például a következőképpen nézhetnek ki:
https://mydemo.search.windows.net.A Beállítások>kulcsok területen másolja ki a rendszergazdai kulcsot. A rendszergazdai kulcsok objektumok hozzáadására, módosítására és törlésére szolgálnak. Két felcserélhető rendszergazdai kulcs van. Másolja valamelyiket.
Az érvényes API-kulcs kérésenként megbízhatóságot hoz létre a kérelmet küldő alkalmazás és az azt kezelő keresési szolgáltatás között.
Kezdeti index létrehozása
Nyisson meg egy új szövegfájlt a Visual Studio Code-ban.
Állítsa be a változókat a keresési végpontra és az előző lépésben összegyűjtött API-kulcsra.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE @apiKey = PUT-YOUR-ADMIN-API-KEY-HEREMentse a fájlt fájlkiterjesztéssel
.rest.Illessze be a következő példába egy kis, két mezőből álló
phone-numbers-indexindex létrehozásához:idésphone_number. Még nem határoztunk meg elemzőt, ezért alapértelmezés szerint azstandard.luceneelemzőt használja a rendszer.### Create a new index POST {{baseUrl}}/indexes?api-version=2024-07-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 } ] }Válassza a Kérés elküldése elemet. Válasznak kell lennie
HTTP/1.1 201 Created, és a válasz törzsének tartalmaznia kell az indexséma JSON-ábrázolását.Adatok betöltése az indexbe különböző telefonszámformátumokat tartalmazó dokumentumok használatával. Ezek a tesztadatok.
### Load documents POST {{baseUrl}}/indexes/phone-numbers-index/docs/index?api-version=2024-07-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" } ] }Próbálkozzunk néhány lekérdezéssel, hasonlóan ahhoz, amit egy felhasználó beírhat. A felhasználók tetszőleges számú formátumban kereshetnek
(425) 555-0100, és továbbra is számíthatnak az eredmények visszaadására. Kezdje a kereséssel(425) 555-0100:### Search for a phone number GET {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2024-07-01&search=(425) 555-0100 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}A lekérdezés négy várt eredményből hármat ad vissza, de két váratlan eredményt is ad vissza:
{ "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" } ] }Próbálkozzunk újra formázás nélkül:
4255550100.### Search for a phone number GET {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2024-07-01&search=4255550100 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Ez a lekérdezés még rosszabb, és a négy helyes egyezés közül csak egyet ad vissza.
{ "value": [ { "@search.score": 0.6015292, "phone_number": "4255550100" } ] }
Ha zavarónak találja ezeket az eredményeket, nem egyedül van. A következő szakaszban vizsgáljuk meg, hogy miért kapjuk meg ezeket az eredményeket.
Az elemzők működésének áttekintése
A keresési eredmények megértéséhez meg kell értenünk, hogy az elemző mit csinál. Innen tesztelhetjük az alapértelmezett elemzőt az Analyze API-val, ami az igényeinknek jobban megfelelő elemző megtervezésének alapja.
Az elemző a lekérdezési sztringek és indexelt dokumentumok szövegének feldolgozásáért felelős teljes szöveges keresőmotor összetevője. A különböző elemzők a forgatókönyvtől függően különböző módon módosítják a szöveget. Ebben a forgatókönyvben egy telefonszámokra szabott elemzőt kell létrehoznunk.
Az elemzők három összetevőből állnak:
- Karakterszűrők , amelyek eltávolítják vagy lecserélik az egyes karaktereket a bemeneti szövegből.
- Tokenizer, amely jogkivonatokra bontja a bemeneti szöveget, amelyek kulcsokká válnak a keresési indexben.
- Jogkivonatszűrők , amelyek a tokenizer által előállított jogkivonatokat módosítják.
Az alábbi ábrán láthatja, hogyan működik együtt ez a három összetevő egy mondat jogkivonata érdekében:
Ezek a jogkivonatok ezután egy fordított indexben vannak tárolva, amely lehetővé teszi a gyors, teljes szöveges keresést. Az invertált indexek lehetővé teszik a teljes szöveges keresést úgy, hogy a lexikális elemzés során kinyert összes egyedi kifejezést leképezik azokat a dokumentumokat, amelyekben előfordulnak. A következő ábrán egy példa látható:
Az összes keresés az invertált indexben tárolt kifejezések kereséséhez szükséges. Amikor egy felhasználó lekérdezést ad ki:
- A rendszer elemzi a lekérdezést, és elemzi a lekérdezési kifejezéseket.
- Az invertált index ezután egyező kifejezésekkel rendelkező dokumentumokat keres.
- Végül a lekért dokumentumokat a pontozási algoritmus rangsorolja.
Ha a lekérdezési kifejezések nem felelnek meg a fordított indexben szereplő feltételeknek, a függvény nem ad vissza eredményeket. Ha többet szeretne megtudni a lekérdezések működéséről, olvassa el ezt a teljes szöveges keresést ismertető cikket.
Feljegyzés
A részleges kifejezéses lekérdezések fontos kivételt jelentenek ebben a szabályban. Ezek a lekérdezések (előtag lekérdezés, helyettesítő lekérdezés, regex lekérdezés) megkerülik a lexikális elemzési folyamatot, ellentétben a hagyományos kifejezéses lekérdezésekkel. A részleges kifejezések csak kisbetűsek az indexben szereplő feltételekkel való egyeztetés előtt. Ha egy elemző nincs konfigurálva az ilyen típusú lekérdezések támogatására, gyakran váratlan eredményeket fog kapni, mert az indexben nem léteznek egyező kifejezések.
Elemzők tesztelése az Analyze API használatával
Az Azure AI Search egy Analyze API-t biztosít, amely lehetővé teszi az elemzők tesztelését, hogy megértse, hogyan dolgozzák fel a szöveget.
Az Analyze API meghívása a következő kéréssel történik:
POST {{baseUrl}}/indexes/phone-numbers-index/analyze?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"text": "(425) 555-0100",
"analyzer": "standard.lucene"
}
Az API a szövegből kinyert jogkivonatokat adja vissza a megadott elemző használatával. A standard Lucene-elemző három különálló jogkivonatra osztja fel a telefonszámot:
{
"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
}
]
}
Ezzel szemben az írásjelek nélkül formázott telefonszámot 4255550100 a rendszer egyetlen jogkivonatba rendezi.
{
"text": "4255550100",
"analyzer": "standard.lucene"
}
Válasz:
{
"tokens": [
{
"token": "4255550100",
"startOffset": 0,
"endOffset": 10,
"position": 0
}
]
}
Ne feledje, hogy a lekérdezési kifejezések és az indexelt dokumentumok elemzése is folyamatban van. Visszatérve az előző lépés keresési eredményeire, láthatjuk, hogy miért adták vissza ezeket az eredményeket.
Az első lekérdezésben váratlan telefonszámokat adtunk vissza, 555mert az egyik jogkivonatuk megfelelt a keresett kifejezések egyikének. A második lekérdezésben csak az egy szám lett visszaadva, mert ez volt az egyetlen rekord, amely jogkivonattal egyezik 4255550100.
Egyéni elemző létrehozása
Most, hogy megértettük a látott eredményeket, hozzunk létre egy egyéni elemzőt a tokenizálási logika továbbfejlesztéséhez.
A cél az, hogy intuitív keresést biztosítson a telefonszámok között, függetlenül attól, hogy milyen formátumban van a lekérdezés vagy az indexelt sztring. Az eredmény eléréséhez meg kell adnia egy karakterszűrőt, egy tokenizert és egy jogkivonatszűrőt.
Karakterszűrők
A karakterszűrők a szöveg feldolgozására szolgálnak, mielőtt betáplálják a tokenizerbe. A karakterszűrők gyakran használják a HTML-elemek szűrését vagy a speciális karakterek cseréjét.
A telefonszámok esetében el szeretnénk távolítani a szóközöket és a speciális karaktereket, mert nem minden telefonszámformátum tartalmazza ugyanazokat a speciális karaktereket és szóközöket.
"charFilters": [
{
"@odata.type": "#Microsoft.Azure.Search.MappingCharFilter",
"name": "phone_char_mapping",
"mappings": [
"-=>",
"(=>",
")=>",
"+=>",
".=>",
"\\u0020=>"
]
}
]
A szűrő eltávolítja és szóközöket - + ( ) . távolít el a bemenetből.
| Bevitel | Hozam |
|---|---|
(321) 555-0199 |
3215550199 |
321.555.0199 |
3215550199 |
Tokenizers
A tokenizerek jogkivonatokra osztják a szöveget, és elvetnek néhány karaktert, például írásjeleket. A tokenizálás célja sok esetben az, hogy egy mondatot külön szavakra bontsunk.
Ebben a forgatókönyvben egy kulcsszó jogkivonat-szabályzót használunk, keyword_v2mert a telefonszámot egyetlen kifejezésként szeretnénk rögzíteni. Vegye figyelembe, hogy nem ez az egyetlen módja a probléma megoldásának. Lásd az alábbi Alternatív megközelítések szakaszt .
A kulcsszó jogkivonat-szabályzói mindig ugyanazt a szöveget adják ki, mint egyetlen kifejezés.
| Bevitel | Hozam |
|---|---|
The dog swims. |
[The dog swims.] |
3215550199 |
[3215550199] |
Jogkivonatszűrők
A jogkivonatszűrők kiszűrik vagy módosítják a jogkivonat-létrehozó által létrehozott jogkivonatokat. A jogkivonatszűrők egyik gyakori használata, ha az összes karaktert kisbetűs jogkivonat-szűrővel kisbetűsre csökkentik. Egy másik gyakori felhasználási terület az olyan stopszavak kiszűrése, mint az the, andvagy is.
Bár ehhez a forgatókönyvhöz egyik szűrőt sem kell használni, egy nGram-jogkivonat-szűrővel lehetővé tesszük a telefonszámok részleges keresését.
"tokenFilters": [
{
"@odata.type": "#Microsoft.Azure.Search.NGramTokenFilterV2",
"name": "custom_ngram_filter",
"minGram": 3,
"maxGram": 20
}
]
NGramTokenFilterV2
A nGram_v2 jogkivonatszűrő a tokeneket egy adott méret n-grammjára osztja fel a paraméterek és maxGram a minGram paraméterek alapján.
A telefonelemző esetében azért állítottuk be minGram 3 , mert ez a legrövidebb részszűkítés, amelyet a felhasználóktól elvárunk a kereséshez. maxGram úgy van beállítva 20 , hogy az összes telefonszám, még a bővítményekkel is, egyetlen n-grammba illeszkedjen.
Az n-gramm szerencsétlen mellékhatása, hogy néhány hamis pozitív eredményt ad vissza. Ezt egy későbbi lépésben kijavítjuk, ha létrehozunk egy külön elemzőt olyan keresésekhez, amelyek nem tartalmazzák az n-gram token szűrőt.
| Bevitel | Hozam |
|---|---|
[12345] |
[123, 1234, 12345, 234, 2345, 345] |
[3215550199] |
[321, 3215, 32155, 321555, 3215550, 32155501, 321555019, 3215550199, 215, 2155, 21555, 215550, ... ] |
Elemző
A karakterszűrőink, a tokenizer és a tokenszűrőink segítségével készen állunk az elemző definiálására.
"analyzers": [
{
"@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
"name": "phone_analyzer",
"tokenizer": "keyword_v2",
"tokenFilters": [
"custom_ngram_filter"
],
"charFilters": [
"phone_char_mapping"
]
}
]
Az Analyze API-ból az alábbi bemenetek alapján az egyéni elemző kimenetei jelennek meg az alábbi táblázatban.
| Bevitel | Hozam |
|---|---|
12345 |
[123, 1234, 12345, 234, 2345, 345] |
(321) 555-0199 |
[321, 3215, 32155, 321555, 3215550, 32155501, 321555019, 3215550199, 215, 2155, 21555, 215550, ... ] |
A kimeneti oszlopban lévő összes jogkivonat az indexben található. Ha a lekérdezés tartalmaz ilyen kifejezéseket, a rendszer visszaadja a telefonszámot.
Újraépítés az új elemzővel
Törölje az aktuális indexet:
### Delete the index DELETE {{baseUrl}}/indexes/phone-numbers-index?api-version=2024-07-01 HTTP/1.1 api-key: {{apiKey}}Hozza létre újra az indexet az új elemzővel. Ez az indexséma hozzáad egy egyéni elemződefiníciót és egy egyéni elemző-hozzárendelést a telefonszám mezőhöz.
### Create a new index POST {{baseUrl}}/indexes?api-version=2024-07-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 } ] }
Az egyéni elemző tesztelése
Az index újraépítése után az alábbi kéréssel tesztelheti az elemzőt:
POST {{baseUrl}}/indexes/tutorial-first-analyzer/analyze?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"text": "+1 (321) 555-0199",
"analyzer": "phone_analyzer"
}
Ekkor látnia kell a telefonszámból származó jogkivonatok gyűjteményét:
{
"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
},
...
...
...
]
}
Az egyéni elemző módosítása a hamis pozitív értékek kezeléséhez
Miután minta lekérdezéseket végzett az indexen az egyéni elemzővel, azt fogja tapasztalni, hogy a visszahívás javult, és az összes egyező telefonszámot visszaadja a rendszer. Az n-gram jogkivonat szűrője azonban hamis pozitívumokat is visszaad. Ez az n-gram jogkivonat-szűrő gyakori mellékhatása.
A hamis pozitív értékek elkerülése érdekében létrehozunk egy külön elemzőt a lekérdezéshez. Ez az elemző megegyezik az előzőével, azzal a kivételel, hogy kihagyja a custom_ngram_filter.
{
"@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
"name": "phone_analyzer_search",
"tokenizer": "custom_tokenizer_phone",
"tokenFilters": [],
"charFilters": [
"phone_char_mapping"
]
}
Az indexdefinícióban ezután egy és egy searchAnalyzerértéket is indexAnalyzer megadunk.
{
"name": "phone_number",
"type": "Edm.String",
"sortable": false,
"searchable": true,
"filterable": false,
"facetable": false,
"indexAnalyzer": "phone_analyzer",
"searchAnalyzer": "phone_analyzer_search"
}
Ezzel a módosítással minden beállítás be van állítva. A következő lépések az alábbiak:
Törölje az indexet.
Hozza létre újra az indexet, miután hozzáadta az új egyéni elemzőt (
phone_analyzer-search) és hozzárendelte az elemzőt aphone-numbermező tulajdonságáhozsearchAnalyzer.Töltse be újra az adatokat.
A lekérdezések újrateszteléséhez ellenőrizze, hogy a keresés a várt módon működik-e. Ha a mintafájlt használja, ez a lépés létrehozza a harmadik indexet
phone-number-index-3.
Alternatív megközelítések
Az előző szakaszban ismertetett elemző úgy lett kialakítva, hogy maximalizálja a keresési rugalmasságot. Ennek azonban az az ára, hogy sok, esetleg nem lényeges kifejezést tárol az indexben.
Az alábbi példa egy alternatív elemzőt mutat be, amely hatékonyabb a tokenizálásban, de hátrányai vannak.
A bemenetet 14255550100figyelembe véve az elemző nem tudja logikailag beszedni a telefonszámot. Például nem tudja elkülöníteni az országkódot a 1körzetszámtól. 425 Ez az eltérés azt eredményezné, hogy a telefonszám nem lesz visszaadva, ha egy felhasználó nem tartalmaz országkódot a keresésben.
"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": ""
}
]
Az alábbi példában láthatja, hogy a telefonszám fel van osztva azokra az adattömbökre, amelyeket általában elvárna a felhasználótól, hogy keressen.
| Bevitel | Hozam |
|---|---|
(321) 555-0199 |
[321, 555, 0199, 321555, 5550199, 3215550199] |
A követelményektől függően ez a probléma hatékonyabb megközelítése lehet.
Legfontosabb ismeretek
Ez az oktatóanyag bemutatta az egyéni elemzők létrehozásának és tesztelésének folyamatát. Létrehozott egy indexet, indexelt adatokat, majd lekérdezte az indexet, hogy lássa, milyen keresési eredmények lettek visszaadva. Innen az Analyze API használatával látta a lexikális elemzési folyamatot működés közben.
Bár az ebben az oktatóanyagban definiált elemző egyszerű megoldást kínál a telefonszámok keresésére, ugyanez a folyamat használható egyéni elemző létrehozására minden olyan forgatókönyvhöz, amely hasonló jellemzőkkel rendelkezik.
Az erőforrások eltávolítása
Ha a saját előfizetésében dolgozik, érdemes eltávolítania azokat az erőforrásokat, amelyekre a projekt végén már nincs szüksége. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.
A portálon a bal oldali navigációs panel Minden erőforrás vagy Erőforráscsoport hivatkozásával kereshet és kezelhet erőforrásokat.
Következő lépések
Most, hogy már ismeri az egyéni elemzők létrehozásának módját, vessünk egy pillantást az összes elérhető szűrőre, tokenizerre és elemzőre, hogy gazdag keresési élményt nyújtsunk.