Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Arama çözümlerinde, karmaşık desenlere veya özel karakterlere sahip dizelerin çalışması zor olabilir çünkü varsayılan çözümleyici bir desenin anlamlı bölümlerini çıkarır veya yanlış yorumlar. Bu, kullanıcıların bekledikleri bilgileri bulamadıkları kötü bir arama deneyimine neden olur. Telefon numaraları, analiz etmek zor olan dizelerin klasik bir örneğidir. Bunlar çeşitli biçimlerde gelir ve varsayılan çözümleyicinin yoksaydığı özel karakterleri içerir.
Konusu telefon numaraları olan bu öğretici, özel çözümleyici kullanarak desenli veri sorunlarını çözmek için Arama Hizmeti REST API'lerini kullanır. Bu yaklaşım, telefon numaraları için olduğu gibi kullanılabilir veya URL'ler, e-postalar, posta kodları ve tarihler gibi aynı özelliklere (özel karakterlerle desenli) sahip alanlar için uyarlanabilir.
Bu eğitimde, siz:
- Sorunu anlama
- Telefon numaralarını işlemek için ilk özel çözümleyici geliştirme
- Özel çözümleyiciyi test etme
- Sonuçları daha da geliştirmek için özel çözümleyici tasarımını yineleyin
Önkoşullar
Aktif bir aboneliğe sahip bir Azure hesabı. Ücretsiz hesap oluşturun.
Dosyaları indirme
Bu öğreticinin kaynak kodu, Azure-Samples/azure-search-rest-samples GitHub deposundaki custom-analyzer.rest dosyasında yer alır.
Yönetici anahtarını ve URL'sini kopyalama
Bu öğreticideki REST çağrıları için bir arama hizmeti uç noktası ve bir yönetici API anahtarı gerekir. Bu değerleri Azure portalından alabilirsiniz.
Sol bölmeden Genel Bakış'ı seçin ve uç noktayı kopyalayın. Şu biçimde olmalıdır:
https://my-service.search.windows.netSol bölmeden Ayarlar>Anahtarları'nı seçin ve hizmette tam haklar için bir yönetici anahtarı kopyalayın. İş sürekliliğini sağlamak için, birini değiştirmeniz gerektiğinde iki değiştirilebilir yönetici anahtarı sağlanmıştır. İsteklerde nesneleri eklemek, değiştirmek veya silmek için iki anahtardan birini kullanabilirsiniz.
İlk dizin oluşturma
Visual Studio Code'da yeni bir metin dosyası açın.
Değişkenleri arama uç noktasına ve önceki bölümde topladığınız API anahtarına ayarlayın.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE @apiKey = PUT-YOUR-ADMIN-API-KEY-HEREDosyayı bir
.restdosya uzantısıyla kaydedin.aşağıdaki örneği yapıştırarak adlı iki alan içeren küçük bir dizin
phone-numbers-indexoluşturun:idvephone_number.### Create a new index POST {{baseUrl}}/indexes?api-version=2026-04-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 } ] }Henüz bir çözümleyici tanımlamadığınız için
standard.luceneçözümleyici varsayılan olarak kullanılır.İstek gönder’i seçin. Bir
HTTP/1.1 201 Createdyanıtınız olmalıdır ve yanıt gövdesi dizin şemasının JSON gösterimini içermelidir.Çeşitli telefon numarası biçimleri içeren belgeleri kullanarak dizine veri yükleyin. Bu sizin test verilerinizdir.
### Load documents POST {{baseUrl}}/indexes/phone-numbers-index/docs/index?api-version=2026-04-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" } ] }Kullanıcının yazabileceğine benzer sorguları deneyin. Örneğin, bir kullanıcı, herhangi bir sayıda biçimde
(425) 555-0100araştırabilir ve sonuçların döndürülmesini bekleyebilir. Aramaya(425) 555-0100ile başlayın.### Search for a phone number POST {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2026-04-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "(425) 555-0100" }Sorgu, dört beklenen sonuçtan üç tane döndürür, ancak aynı zamanda iki beklenmeyen sonuç döndürür.
{ "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" } ] }Biçimlendirme olmadan yeniden deneyin:
4255550100.### Search for a phone number POST {{baseUrl}}/indexes/phone-numbers-index/docs/search?api-version=2026-04-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "4255550100" }Bu sorgu daha da kötü olur ve dört doğru eşleşmeden yalnızca birini döndürür.
{ "value": [ { "@search.score": 0.6015292, "phone_number": "4255550100" } ] }
Bu sonuçları kafa karıştırıcı bulursanız yalnız değilsiniz demektir. Sonraki bölümde bu sonuçları neden elde ettiğiniz açıklanmaktadır.
Çözümleyicilerin nasıl çalıştığını gözden geçirin
Bu arama sonuçlarını anlamak için çözümleyicinin ne yaptığını anlamanız gerekir. Buradan Analiz API'sini kullanarak varsayılan çözümleyiciyi test edebilir ve gereksinimlerinizi daha iyi karşılayan bir çözümleyici tasarlamaya yönelik bir temel sağlayabilirsiniz.
Çözümleyici, sorgu dizelerinde ve dizine alınan belgelerde metin işlemeden sorumlu tam metin arama altyapısının bir bileşenidir. Farklı çözümleyiciler, senaryoya bağlı olarak metni farklı şekillerde işliyor. Bu senaryo için telefon numaralarına göre uyarlanmış bir çözümleyici oluşturmamız gerekir.
Çözümleyiciler üç bileşenden oluşur:
- Giriş metnindeki karakterleri tek tek kaldıran veya değiştiren karakter filtreleri .
- Giriş metnini belirteçlere bölen ve bu belirteçleri arama dizininde anahtar haline getiren bir belirteçleyici.
- Belirteç oluşturucu tarafından üretilen belirteçleri işleyen belirteç filtreleri .
Aşağıdaki diyagramda, bu üç bileşenin bir tümceyi belirteç haline getirmek için birlikte nasıl çalıştığı gösterilmektedir.
Bu belirteçler daha sonra, hızlı, tam metin aramalarına olanak tanıyan ters bir dizinde depolanır. Ters çevrilmiş dizin, sözcük temelli analiz sırasında ayıklanan tüm benzersiz terimleri bulundukları belgelere eşleyerek tam metin aramasına olanak tanır. Aşağıdaki diyagramda bir örnek görebilirsiniz:
Tüm aramalar, ters dizinde depolanan terimleri aramaya kadar uzanır. Kullanıcı bir sorguyu sorunca:
- Sorgu ayrıştırılır ve sorgu terimleri analiz edilir.
- Ters çevrilmiş dizin, eşleşen terimlere sahip belgeler için taranır.
- Puanlama algoritması, alınan belgeleri sıralar.
Sorgu terimleri ters dizininizdeki terimlerle eşleşmiyorsa, sonuçlar döndürülmez. Sorguların nasıl çalıştığı hakkında daha fazla bilgi edinmek için bkz. Azure Yapay Zeka Arama'te tam metin arama.
Not
Kısmi terim sorguları bu kural için önemli bir istisnadır. Normal terim sorgularından farklı olarak, bu sorgular (ön ek sorgusu, joker karakter sorgusu ve regex sorgusu) sözcük temelli çözümleme işlemini atlar. Kısmi terimler, dizindeki terimlerle eşleşmeden önce yalnızca küçük harfle gösterilir. Çözümleyici bu tür sorguları destekleyecek şekilde yapılandırılmamışsa, dizinde eşleşen terimler olmadığından genellikle beklenmeyen sonuçlar alırsınız.
Çözümle API'sini kullanarak çözümleyicileri test etme
Azure Yapay Zeka Arama, çözümleyicilerin metinleri nasıl işlediğini anlamak için test etmenizi sağlayan bir Analiz API'si sağlar.
Aşağıdaki isteği kullanarak Çözümle API'sini çağırın:
### Test analyzer
POST {{baseUrl}}/indexes/phone-numbers-index/analyze?api-version=2026-04-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"text": "(425) 555-0100",
"analyzer": "standard.lucene"
}
API, belirttiğiniz çözümleyiciyi kullanarak metinden ayıklanan belirteçleri döndürür. Standart Lucene çözümleyicisi telefon numarasını üç ayrı belirteçe böler.
{
"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
}
]
}
Öte yandan, noktalama işareti olmadan biçimlendirilmiş telefon numarası 4255550100 tek bir belirteç haline getirilir.
{
"text": "4255550100",
"analyzer": "standard.lucene"
}
Yanıt:
{
"tokens": [
{
"token": "4255550100",
"startOffset": 0,
"endOffset": 10,
"position": 0
}
]
}
Hem sorgu terimlerinin hem de dizine alınan belgelerin analizden geçtiğini unutmayın. Önceki adımdaki arama sonuçlarını yeniden düşünerek, bu sonuçların neden döndürüldiğini görmeye başlayabilirsiniz.
İlk sorguda, belirteçlerinden 555biri , aradığınız terimlerden biriyle eşleştiklerinden beklenmeyen telefon numaraları döndürülür. İkinci sorguda, belirteç eşleştirmesi 4255550100olan tek kayıt olduğundan yalnızca bir sayı döndürülür.
Özel çözümleyici oluşturma
Gördüğünüz sonuçları anladığınıza göre, belirteç oluşturma mantığını geliştirmek için özel bir çözümleyici oluşturun.
Amaç, sorgunun veya dizine alınan dizenin biçimi ne olursa olsun telefon numaralarına karşı sezgisel arama sağlamaktır. Bu sonucu elde etmek için bir karakter filtresi, belirteç oluşturucu ve belirteç filtresi belirtin.
Karakter filtreleri
Karakter filtreleri, metin belirteç oluşturucuya beslenmeden önce metni işler. Karakter filtrelerinin yaygın kullanım alanları HTML öğelerini filtrelemek ve özel karakterleri değiştirmekten oluşur.
Tüm telefon numarası biçimleri aynı özel karakterleri ve boşlukları içermediğinden, telefon numaraları için boşluk ve özel karakterleri kaldırmak istiyorsunuz.
"charFilters": [
{
"@odata.type": "#Microsoft.Azure.Search.MappingCharFilter",
"name": "phone_char_mapping",
"mappings": [
"-=>",
"(=>",
")=>",
"+=>",
".=>",
"\\u0020=>"
]
}
]
Filtre, girişten -()+. ve boşlukları kaldırır.
| Girdi | Çıktı |
|---|---|
(321) 555-0199 |
3215550199 |
321.555.0199 |
3215550199 |
Belirteç Oluşturucular
Belirteçleyiciler, metni belirteçlere böler ve bu süreçte noktalama işaretleri gibi bazı karakterleri atar. Çoğu durumda belirteç oluşturmanın amacı, tümceyi tek tek sözcüklere bölmektir.
Bu senaryo için, telefon numarasını tek bir terim olarak yakalamak üzere keyword_v2 anahtar sözcük belirtecini kullanın.
Alternatif yaklaşımlar bölümünde açıklandığı gibi bu sorunu çözmenin tek yolu bu değildir.
Anahtar sözcük belirteçleri her zaman tek bir terim olarak kendilerine verilen metnin çıkışını yapar.
| Girdi | Çıktı |
|---|---|
The dog swims. |
[The dog swims.] |
3215550199 |
[3215550199] |
Belirteç filtreleri
Belirteç filtreleri, belirteç oluşturucu tarafından oluşturulan belirteçleri değiştirir veya filtreler. Belirteç filtresinin yaygın kullanımlarından biri, küçük harfli belirteç filtresi kullanarak tüm karakterleri küçük harfe döndürmektir. Başka bir yaygın kullanım, durdurma kelimelerini, örneğin the, and veya is gibi, filtrelemektir.
Bu senaryo için bu filtrelerden herhangi birini kullanmanız gerekmez ancak telefon numaralarının kısmi olarak aranmasına izin vermek için nGram belirteci filtresi kullanın.
"tokenFilters": [
{
"@odata.type": "#Microsoft.Azure.Search.NGramTokenFilterV2",
"name": "custom_ngram_filter",
"minGram": 3,
"maxGram": 20
}
]
NGramTokenFilterV2
nGram_v2 belirteci filtresi, minGram ve maxGram parametrelerine göre belirli bir boyutta n-gramlara belirteçleri böler.
Telefon analizcisi için minGram, kullanıcıların aramasının beklendiği en kısa alt dize olduğundan 3 olarak ayarlanır.
maxGram , tüm telefon numaralarının, uzantılar dahil, tek bir n-grama sığdığından emin olmak için 20 olarak ayarlanır.
N-gram'ın talihsiz yan etkisi, bazı yanlış pozitiflerin ortaya çıkmasıdır. N gram belirteç filtresini içermeyen aramalar için ayrı bir çözümleyici oluşturarak bunu sonraki bir adımda düzeltirsiniz.
| Girdi | Çıktı |
|---|---|
[12345] |
[123, 1234, 12345, 234, 2345, 345] |
[3215550199] |
[321, 3215, 32155, 321555, 3215550, 32155501, 321555019, 3215550199, 215, 2155, 21555, 215550, ... ] |
Çözümleyici
Karakter filtreleri, belirteç oluşturucu ve belirteç filtreleri mevcutken çözümleyiciyi tanımlamaya hazırsınız demektir.
"analyzers": [
{
"@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
"name": "phone_analyzer",
"tokenizer": "keyword_v2",
"tokenFilters": [
"custom_ngram_filter"
],
"charFilters": [
"phone_char_mapping"
]
}
]
Analiz API'sinden, aşağıdaki girişler göz önüne alındığında, özel çözümleyiciden alınan çıkışlar aşağıdaki gibidir:
| Girdi | Çıktı |
|---|---|
12345 |
[123, 1234, 12345, 234, 2345, 345] |
(321) 555-0199 |
[321, 3215, 32155, 321555, 3215550, 32155501, 321555019, 3215550199, 215, 2155, 21555, 215550, ... ] |
Çıkış sütunundaki tüm belirteçler dizinde bulunur. Sorgunuz bu terimlerden herhangi birini içeriyorsa, telefon numarası döndürülür.
Yeni çözümleyiciyi kullanarak yeniden oluşturun
Geçerli dizini silin.
### Delete the index DELETE {{baseUrl}}/indexes/phone-numbers-index?api-version=2026-04-01 HTTP/1.1 api-key: {{apiKey}}Yeni çözümleyiciyi kullanarak dizini yeniden oluşturun. Bu dizin şeması, telefon numarası alanına özel bir çözümleyici tanımı ve özel çözümleyici ataması ekler.
### Create a new index POST {{baseUrl}}/indexes?api-version=2026-04-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 } ] }
Özel çözümleyiciyi test etme
Dizini yeniden oluşturdıktan sonra aşağıdaki isteği kullanarak çözümleyiciyi test edin:
### Test custom analyzer
POST {{baseUrl}}/indexes/phone-numbers-index-2/analyze?api-version=2026-04-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"text": "+1 (321) 555-0199",
"analyzer": "phone_analyzer"
}
Artık telefon numarasından kaynaklanan belirteç koleksiyonunu görüyor olmalısınız.
{
"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
},
...
...
...
]
}
Hatalı pozitif sonuçları işlemek için özel çözümleyiciyi gözden geçirme
Dizinde örnek sorgular yapmak için özel çözümleyiciyi kullandıktan sonra, geri çekme işleminin iyileştiğini ve eşleşen tüm telefon numaralarının döndürüldüğünü görmeniz gerekir. Ancak, n-gram belirteç filtresi de bazı yanlış pozitiflerin dönmesine neden olur. Bu, n gram belirteç filtresinin ortak bir yan etkisidir.
Hatalı pozitif sonuçları önlemek için sorgulama için ayrı bir çözümleyici oluşturun. Bu çözümleyici öncekiyle aynıdır, ancak şu farkla ki custom_ngram_filter'yu çıkartır.
{
"@odata.type": "#Microsoft.Azure.Search.CustomAnalyzer",
"name": "phone_analyzer_search",
"tokenizer": "custom_tokenizer_phone",
"tokenFilters": [],
"charFilters": [
"phone_char_mapping"
]
}
Dizin tanımında hem indexAnalyzer hem de searchAnalyzer belirtin.
{
"name": "phone_number",
"type": "Edm.String",
"sortable": false,
"searchable": true,
"filterable": false,
"facetable": false,
"indexAnalyzer": "phone_analyzer",
"searchAnalyzer": "phone_analyzer_search"
}
Bu değişiklikle hazırsınız. Sonraki adımlarınız şunlardır:
Dizini silin.
Yeni özel çözümleyiciyi (
phone_analyzer-search) ekledikten ve bu çözümleyiciyi alanınphone-numberözelliğinesearchAnalyzeratadıktan sonra dizini yeniden oluşturun.Verileri yeniden yükleyin.
Aramanın beklendiği gibi çalıştığını doğrulamak için sorguları yeniden test edin. Örnek dosyayı kullanıyorsanız, bu adım adlı
phone-number-index-3üçüncü dizini oluşturur.
Alternatif yaklaşımlar
Önceki bölümde açıklanan çözümleyici, arama esnekliğini en üst düzeye çıkarmak için tasarlanmıştır. Ancak, bunu birçok önemli olmayabilecek terimi dizinde depolama maliyetiyle yapar.
Aşağıdaki örnekte belirteç oluşturmada daha verimli olan ancak dezavantajları olan alternatif bir çözümleyici gösterilmektedir.
girdisi 14255550100verüldüğünde çözümleyici telefon numarasını mantıksal olarak öbekleyemez. Örneğin, ülke kodu olan öğesini alan kodundan 1425ayıramaz. Bu tutarsızlık, bir kullanıcı aramasına ülke kodu eklemezse telefon numarasının döndürülmemesini sağlar.
"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": ""
}
]
Aşağıdaki örnekte, telefon numarası normalde bir kullanıcının aranmasını beklediğiniz öbeklere ayrılmıştır.
| Girdi | Çıktı |
|---|---|
(321) 555-0199 |
[321, 555, 0199, 321555, 5550199, 3215550199] |
Gereksinimlerinize bağlı olarak, bu sorun için daha verimli bir yaklaşım olabilir.
Çıkarımlar
Bu öğreticide özel çözümleyici oluşturma ve test etme işlemi gösterilmiştir. Bir dizin oluşturdunuz, verileri dizine yazdınız ve sonra hangi arama sonuçlarının döndürüldiğini görmek için dizine göre sorguladınız. Buradan, sözcük temelli analiz işleminin nasıl çalıştığını görmek için Çözümle API'sini kullandınız.
Bu öğreticide tanımlanan çözümleyici, telefon numaralarına karşı arama yapmak için kolay bir çözüm sunarken, benzer özellikleri paylaşan herhangi bir senaryo için özel bir çözümleyici oluşturmak için de aynı işlem kullanılabilir.
Kaynakları temizleme
Kendi aboneliğinizde çalışırken, bir projenin sonunda artık ihtiyacınız olmayan kaynakları kaldırmak iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.
Sol gezinti bölmesindeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak Kaynakları Azure portalında bulabilir ve yönetebilirsiniz.
Sonraki adımlar
Artık özel çözümleyici oluşturmayı bildiğinize göre, zengin bir arama deneyimi oluşturmak için kullanılabilecek tüm farklı filtrelere, belirteç oluşturuculara ve çözümleyicilere göz atın: