在搜尋情境中，使用者使用不同詞語表達同一概念（例如“手機”與“智能手機”），可能導致搜尋結果不全。同義字功能將這些詞語視為等同，以擴充搜尋範圍，提升搜尋召回率和使用者體驗。
操作前檢查清單
在執行同義字檔案變更前，務必確認以下事項：
確認關鍵索引至少擁有一個副本分區，以保障服務在單節點重啟期間的可用性。（刪除詞典時將引起叢集重啟）
監控並確認叢集負載處於健康水平（建議：CPU使用率 < 60%，堆記憶體使用量率 < 50%）。
串連叢集，通過
GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem.heap_*查看所有節點的CPU和堆記憶體使用量率。
工作原理與決策指南
理解同義字的兩種配置方式及其利弊，有助於做出正確的技術選型。
同義字文法規則
同義字檔案必須為 UTF-8 編碼的 .txt 檔案。檔案中的每一行定義一組同義字規則，支援以下兩種格式：
等價同義字（Solr格式）
用英文逗號分隔的詞語將被視為完全等價。搜尋其中任意一個詞，都會匹配包含這組詞中任何一個的文檔。# 樣本：搜尋“手機”、“智能手機”或“行動電話”時，效果相同。 手機,智能手機,行動電話 ipod,i-pod,i pod定向映射（WordNet格式）
使用=>將一組詞語映射到一個標準詞，通常用于歸一化，即將不規範的用詞指向規範用詞。# 樣本：將"usa"和"us"都映射到“美國”。 usa,us => 美國
兩種配置方式對比與決策
支援通過上傳檔案或在索引配置中內聯定義同義字兩種方式，兩種方式的對比如下表所示。
對比項 | 方式一：上傳檔案 | 方式二：內聯定義 |
操作方式 | 上傳TXT檔案到ES叢集，然後在索引 | 直接在索引 |
優點 |
|
|
缺點 | 已有索引無法動態載入新詞典。 |
|
適用情境 | 詞典內容穩定、不常變更，且需要在多個索引間共用的情境。 | 對可用性要求極高，或需要頻繁、快速更新同義字的情境。 |
操作步驟
方式一：通過上傳檔案配置（可複用）
此方式適合詞典相對固定的情境。
步驟一：上傳同義字檔案
以下樣本通過filter過濾器配置同義字，使用測試檔案aliyun_synonyms.txt，其內容為：begin, start。
登入Elasticsearch控制台，選擇目標地區和資源群組，然後單擊目標執行個體ID。
在左側導覽列，選擇 配置與管理 > 進階設定，在基礎配置地區找到同義字配置，單擊上傳。
在彈出的面板中，單擊配置，然後選擇上傳方式：
檔案尾碼必須是.txt，檔案名稱包含大小寫字母、數字和底線，且長度不超過30個字元
上傳檔案：從本地選擇同義字TXT檔案。
添加OSS檔案：輸入Bucket名稱和同義字檔案名稱後，單擊添加。
限制：OSS Bucket必須與ES執行個體在同一地區。
單擊保存，確認後執行。
步驟二：建立索引並引用同義字檔案
等待執行個體狀態恢複為正常，串連叢集後建立索引，並配置其使用已上傳的同義字檔案。
PUT /aliyun-index-test
{
"settings": {
"index":{
"analysis": {
"analyzer": {
"by_smart": {
"type": "custom",
"tokenizer": "ik_smart",
"filter": ["by_tfr","by_sfr"],
"char_filter": ["by_cfr"]
},
"by_max_word": {
"type": "custom",
"tokenizer": "ik_max_word",
"filter": ["by_tfr","by_sfr"],
"char_filter": ["by_cfr"]
}
},
"filter": {
"by_tfr": {
"type": "stop",
"stopwords": [" "]
},
"by_sfr": {
"type": "synonym",
"synonyms_path": "analysis/aliyun_synonyms.txt"
}
},
"char_filter": {
"by_cfr": {
"type": "mapping",
"mappings": ["| => |"]
}
}
}
}
}
}不同版本的叢集，其索引建立文法存在一定差異，請參見ES常見版本操作索引樣本。
步驟三：配置同義字欄位title
ES 7.0以下版本
PUT /aliyun-index-test/_mapping/doc { "properties": { "title": { "type": "text", "analyzer": "by_max_word", "search_analyzer": "by_smart" } } }ES 7.0及以上版本
PUT /aliyun-index-test/_mapping/ { "properties": { "title": { "type": "text", "analyzer": "by_max_word", "search_analyzer": "by_smart" } } }
步驟四：驗證同義字效果
使用_analyze API驗證分詞器是否已正確載入同義字，假設同義字檔案包含 begin,start。
GET /aliyun-index-test/_analyze
{
"analyzer": "by_smart",
"text":"begin"
}成功的返回結果應同時包含 begin 和 start 兩個詞元（token）。
{
"tokens" : [
{
"token" : "begin",
"start_offset" : 0,
"end_offset" : 5,
"type" : "ENGLISH",
"position" : 0
},
{
"token" : "start",
"start_offset" : 0,
"end_offset" : 5,
"type" : "SYNONYM",
"position" : 0
}
]
}步驟五：測試搜尋效果
寫入兩份包含同義字的文檔
PUT /aliyun-index-test/doc/1 { "title": "Shall I begin?" }PUT /aliyun-index-test/doc/2 { "title": "I start work at nine." }搜尋其中一個詞（例如
begin），可同時召回包含begin和start的文檔。GET /aliyun-index-test/_search { "query" : { "match" : { "title" : "begin" }}, "highlight" : { "pre_tags" : ["<red>", "<bule>"], "post_tags" : ["</red>", "</bule>"], "fields" : { "title" : {} } } }返回結果：
{ "took" : 70, "timed_out" : false, "_shards" : { "total" : 1, "successful" : 1, "skipped" : 0, "failed" : 0 }, "hits" : { "total" : { "value" : 2, "relation" : "eq" }, "max_score" : 0.28247005, "hits" : [ { "_index" : "aliyun-index-test", "_type" : "_doc", "_id" : "1", "_score" : 0.28247005, "_source" : { "title" : "Shall I begin?" }, "highlight" : { "title" : [ "Shall I <red>begin</red>?" ] } }, { "_index" : "aliyun-index-test", "_type" : "_doc", "_id" : "2", "_score" : 0.25069216, "_source" : { "title" : "I start work at nine." }, "highlight" : { "title" : [ "I <red>start</red> work at nine." ] } } ] } }
方式二：在索引設定中內聯配置（不便複用）
此方式將同義字規則直接寫入索引配置，適合詞典小且需要快速迭代的情境。
步驟一：建立索引並定義同義字
串連叢集，在建立索引時直接將同義字規則定義在synonyms數組中。
PUT /my_index
{
"settings": {
"analysis": {
"analyzer": {
"my_synonyms": {
"filter": [
"lowercase",
"my_synonym_filter"
],
"tokenizer": "ik_smart"
}
},
"filter": {
"my_synonym_filter": {
"synonyms": [
"begin,start"
],
"type": "synonym"
}
}
}
}
}上述命令建立了一個名為 my_index 的索引，並配置了自訂文本分析，處理流程為：
當文字欄位使用 my_synonyms 分析器時，ik_smart 分詞器將輸入文本切分成詞元；lowercase 過濾器將所有詞元轉換為小寫；my_synonym_filter 過濾器將小寫後的詞元（如 begin 或 start）映射到其同義字組（即兩者都被視為同一個規範詞）。
步驟二：配置同義字欄位title
ES 7.0以下版本
PUT /my_index/_mapping/doc { "properties": { "title": { "type": "text", "analyzer": "my_synonyms" } } }ES 7.0及以上版本
PUT /my_index/_mapping/ { "properties": { "title": { "type": "text", "analyzer": "my_synonyms" } } }
步驟三：驗證同義字效果
GET /my_index/_analyze
{
"analyzer":"my_synonyms",
"text":"Shall I begin?"
}返回結果：
{
"tokens" : [
{
"token" : "shall",
"start_offset" : 0,
"end_offset" : 5,
"type" : "ENGLISH",
"position" : 0
},
{
"token" : "i",
"start_offset" : 6,
"end_offset" : 7,
"type" : "ENGLISH",
"position" : 1
},
{
"token" : "begin",
"start_offset" : 8,
"end_offset" : 13,
"type" : "ENGLISH",
"position" : 2
},
{
"token" : "start",
"start_offset" : 8,
"end_offset" : 13,
"type" : "SYNONYM",
"position" : 2
}
]
}同義字操作對叢集的影響
不同的同義字操作對叢集的影響不同。瞭解以下區別，有助於根據業務需求選擇合適的更新方式。
操作方式 | 是否觸發叢集重啟 | 說明 |
累加式更新（上傳同名檔案） | 否 | 上傳與已有檔案同名的同義字檔案時，屬於累加式更新（熱更新），不觸發叢集重啟 |
控制台更新同義字詞庫（新檔案名稱或刪除檔案） | 是 | 上傳新檔案名稱的同義字檔案或刪除已有檔案後儲存，會觸發叢集滾動重啟 |
累加式更新同義字檔案（熱更新）
當上傳的同義字檔案與已有檔案同名時，系統執行累加式更新（熱更新），不會觸發叢集重啟。新上傳的檔案直接覆蓋原檔案，新建立的索引將自動使用更新後的詞庫。
累加式更新後，已有索引不會自動載入新詞庫。如需在已有索引中生效，需關閉後重新開啟索引（Close/Open），或重建索引。
控制台更新詞庫觸發叢集重啟
以下操作會觸發叢集滾動重啟：
上傳新檔案名稱的同義字檔案後儲存。
刪除已有同義字檔案後儲存。
若業務需要避免叢集重啟，建議使用 elasticsearch-analysis-dynamic-synonym 外掛程式實現動態更新機制。
滾動重啟期間可能出現以下影響：
服務抖動：節點逐個重啟期間，即使有副本分區，也可能出現查詢延遲短暫升高或服務抖動。
服務中斷風險：叢集負載過高或索引沒有副本等極端條件下，重啟可能導致部分請求失敗或短暫服務中斷。
重啟時間長度：重啟和詞庫分發的總耗時取決於叢集規模、資料量和負載，可能需要幾分鐘甚至更長時間。
配置生效期間的讀寫可用性
同義字配置提交後，執行個體進入生效中狀態。在此期間：
執行個體的讀寫功能正常可用，不影響現有業務的資料讀寫操作。
僅同義字擴充功能暫時不生效，使用新同義字規則的搜尋查詢可能返回不完整的結果。
生效完成後，執行個體恢複正常狀態，新建立的索引將自動使用更新後的同義字詞庫。
常見問題
配置或更新同義字後叢集狀態異常（Yellow）或變更卡住怎麼辦？
配置或更新同義字後，如果叢集狀態變為 Yellow 或後續變更卡住，通常由以下原因引起：
同義字檔案格式不規範：檔案中包含大寫字母但未轉換為小寫，導致分析器（Analyzer）解析失敗。
OpenStorePlugin 報錯：同義字檔案內容異常觸發 OpenStorePlugin 錯誤，導致分區無法正常分配，叢集狀態異常並阻塞後續變更。
可以按照以下方法排查和解決：
檢查並修正同義字檔案：確認檔案中所有單詞均已統一轉換為小寫字母，修正後重新上傳。
增加 lowercase 過濾器：在索引 Settings 的 analyzer filter 配置中增加
lowercase過濾器，確保分詞時自動將詞條轉換為小寫。樣本配置："filter": { "my_synonym_filter": { "type": "synonym", "synonyms_path": "analysis/your-dict-name.txt" } }, "analyzer": { "my_synonyms": { "filter": ["lowercase", "my_synonym_filter"], "tokenizer": "ik_smart" } }索引無法操作時的恢複：若因修改 Analyzer Filter 導致需要關閉或重建索引且影響生產環境，或在控制台無法執行操作時，可嘗試通過強制重新分區等方式恢複叢集狀態：
POST /_cluster/reroute?retry_failed=true
使用 analysis-dynamic-synonym 外掛程式進行同義字熱更新有哪些風險？
開源外掛程式 analysis-dynamic-synonym 支援從遠程或本地檔案動態載入同義字，無需重啟叢集即可使新的同義字規則生效。但該外掛程式存在以下已知風險：
並發缺陷：在高並發查詢和寫入情境下，該外掛程式可能導致 Elasticsearch 進程死結，進而引起 CPU 使用率打滿和服務不可用。
適用情境限制：在 Serverless 執行個體或對穩定性要求極高的生產環境中，謹慎使用該外掛程式。啟用前，建議先在測試環境中充分評估實際查詢和寫入負載下的穩定性表現，確認後再部署到生產環境。如果同義字更新頻率不高，建議優先使用累加式更新方式（上傳同名檔案），避免引入第三方外掛程式的潛在風險。