在本文中,了解定義搜尋索引結構描述的步驟,並將其推送至搜尋服務。 建立索引時,系統會在搜尋服務上建立實體資料結構。 索引一旦存在,載入索引作為個別工作。
必要條件
以搜尋服務參與者身分撰寫權限,或撰寫系統管理 API 金鑰進行金鑰型驗證。
了解您想要編製索引的資料。 搜尋索引是以您想要進行搜尋的外部內容為基礎。 可搜尋的內容會儲存為索引中的欄位。 您應該清楚瞭解您想要在 Azure AI 搜尋服務上進行可搜尋、可擷取、可篩選、可多面向和可排序的來源字段。 如需指引, 請參閱架構檢查清單 。
您也必須在來源資料中具有唯一欄位,其可用於索引中的文件索引鍵 (或識別碼)。
穩定的索引位置。 目前不支援將現有索引移至不同的搜尋服務。 重新瀏覽應用程式需求,並確定您現有的搜尋服務(容量和區域)已足以滿足您的需求。 如果您相依於 Azure AI 服務或 Azure OpenAI, 請選擇提供所有必要資源的區域 。
最後,針對您所能建立的物件數目,所有服務層級都具有索引限制。 例如,如果在免費層上進行實驗,則您在任何指定時間都只能使用三個索引。 在索引本身,簡單和複雜欄位的數目具有向量限制和索引限制。
文件索引鍵
搜尋索引建立有兩個需求:索引在搜尋服務上必須有唯一的名稱,而且必須有檔索引鍵。 欄位上的布爾 key
屬性可以設定為 true,以指出哪個欄位提供檔索引鍵。
文件索引鍵是搜尋文件的唯一識別碼,而搜尋文件則是可完整描述某些內容的欄位集合。 例如,如果您要編製電影資料集的索引,則搜尋文件包含單一電影的標題、類型和持續時間。 影片名稱在此數據集中是唯一的,因此您可以使用電影名稱作為檔索引鍵。
在 Azure AI 搜尋服務中,檔索引鍵是字串,而且必須源自數據源中提供要編製索引內容的唯一值。 一般規則是,搜尋服務不會產生索引鍵值,但在某些案例中(例如 Azure 數據表索引器)會合成現有的值,為編製索引的檔建立唯一索引鍵。 另一個案例是區塊化或數據分割數據的一對多索引編製,在此情況下,會針對每個區塊產生檔索引鍵。
在累加式索引編製期間,當新和更新的內容完成索引編製,系統就會新增具有新索引鍵的內送文件,或者合併或覆寫具有現有索引鍵的內送文件,上述情形是取決於索引欄位是否已填入資料或為 Null。
檔案索引鍵的要點包括:
- 索引鍵欄位中值的最大長度為 1,024 個字元。
- 每個索引中只有一個最上層字段必須選擇為索引鍵欄位,而且必須是類型
Edm.String
。 - 簡單欄位的
key
預設值為 false,複雜欄位為 null。
索引鍵欄位可用來直接查閱檔,並更新或刪除特定檔。 查閱或編製檔索引時,索引鍵欄位的值會以區分大小寫的方式處理。 如需詳細資訊,請參閱 GET 檔 (REST) 和索引檔 (REST)。
結構描述檢查清單
使用此檢查清單來協助制定搜尋索引的設計決策。
請檢閱命名慣例,讓索引和欄位名稱符合命名規則。
請檢閱支援的資料類型。 資料類型會影響欄位的使用方式。 例如,您可以篩選數值內容,但無法搜尋全文。 最常見的資料類型為
Edm.String
,該類型用於可搜尋的文字,並使用全文搜尋引擎進行權杖化和查詢。 向量欄位最常見的資料類型是Edm.Single
,但您也可以使用其他類型。提供索引的描述(預覽),最多 4,000 個字元。 當系統必須存取數個索引,並根據描述做出決策時,這個人類可讀取的文字是寶貴的。 請考慮必須在運行時間挑選正確索引的模型內容通訊協定 (MCP) 伺服器。 決策可以根據描述,而不是單獨根據索引名稱。 2025-05-01-preview REST API、Azure 入口網站或提供此功能之 Azure SDK 的發行前版本套件中提供索引描述欄位。 如需詳細資訊,請參閱 新增索引描述。
識別文件索引鍵。 文件索引鍵是索引需求。 這是從源數據欄位填入的單一字串字位,其中包含唯一值。 例如,如果您要從 Blob 儲存體編製索引,則中繼資料儲存體路徑通常會用來作為文件索引鍵,因為該路徑會唯一識別容器中的每個 Blob。
在資料來源中識別特定欄位,這些欄位會提供索引中的可搜尋內容。
可搜尋的非向量內容包括使用全文搜尋引擎所查詢的短或長字串。 如果內容較詳細 (簡短片語或較長的句構),請使用不同的分析器進行實驗,以查看文字的權杖化方式。
可搜尋的向量內容可以是以數學表示形式存在的影像或文字 (任何語言)。 您可以使用狹窄資料類型或向量壓縮,讓向量欄位變小。
上設定的屬性會決定搜尋行為和搜尋服務上索引的實體表示法。 判斷欄位應如何屬性化,是許多開發人員的反覆程式。 若要加速流程,請使用範例資料來執行作業,以便輕鬆進行卸除和重建。
識別哪些來源欄位可作為篩選。 數值內容和簡短文字欄位,特別是具有重複值的欄位都是不錯的選擇。 使用篩選時,請記得:
篩選可用於向量和非vector 查詢,但篩選本身會套用至索引中的人類可讀取(非vector)字段。
您可以選擇將可篩選的欄位用於多面向導覽。
可篩選的欄位會依任意順序傳回,而且不會進行相關性評分,因此也請考慮將它們排序。
針對向量欄位,指定向量搜尋組態,以及用來建立瀏覽路徑並填入內嵌空間的演算法。 如需詳細資訊,請參閱新增向量欄位。
向量欄位具有非向量欄位所沒有的額外屬性,例如要使用的演算法和向量壓縮。
向量欄位會省略向量資料上沒有用處的屬性,例如排序、篩選和 Facet。
對於非向量欄位,決定是否要使用預設分析器 (
"analyzer": null
) 或不同的分析器。 分析器可用來在索引編製和查詢執行期間將文字欄位權杖化。若為多語言字串,請考慮語言分析器。
若為連字號連接的字串或特殊字元,請考慮特製化分析器。 其中一個範例是關鍵字,其會將欄位的整個內容視為單一語彙基元。 此行為適合用於郵遞區號、識別碼和產品名稱等資料。 如需詳細資訊,請參閱部分字詞搜尋和具有特殊字元的模式。
注意
針對在索引編製期間權杖化的字詞,全文搜尋功能會在這些字詞間運行。 如果您的查詢無法傳回您預期的結果, 請測試令牌化 ,以確認您要搜尋的字串確實存在。 您可以在字串上嘗試使用不同的分析器,查看各種分析器產生權杖的方式。
設定欄位定義
fields 集合會定義搜尋文件的結構。 所有欄位都有名稱、數據類型和屬性。
將欄位設定為可搜尋、可篩選、可排序或可 Facet,對索引大小和查詢效能有影響。 請勿在查詢表達式中未參考的欄位上設定這些屬性。
如果欄位未設定為可搜尋、可篩選、可排序或可多面向,則無法在任何查詢表達式中參考字段。 對於查詢中未使用的欄位而言,這是理想的做法,但在搜尋結果中是必要的。
REST API 具有以數據類型為基礎的預設屬性,匯入精靈也會使用 Azure 入口網站。 Azure SDK 沒有預設值,但它們有包含屬性和行為的字段子類別,例如 字串的 SearchableField 和 基本類型的 SimpleField 。
下表摘要說明 REST API 的預設欄位屬性。
資料類型 | 可搜尋 | 可擷取 | 可篩選 | 可面向化 | 可排序 | 已儲存 |
---|---|---|---|---|---|---|
Edm.String |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Collection(Edm.String) |
✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
Edm.Boolean |
❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
Edm.Int32 、 、 Edm.Int64 Edm.Double |
❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
Edm.DateTimeOffset |
❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
Edm.GeographyPoint |
✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
Edm.ComplexType |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Collection(Edm.Single) 和所有其他向量欄位類型 |
✅ | ✅ 或 ❌ | ❌ | ❌ | ❌ | ✅ |
字串欄位也可以選擇性地與分析器和同義字對應相關聯。 可篩選、可排序或可多面向類型的 Edm.String
欄位最多可以有 32 KB 的長度。 這是因為這類欄位的值會被視為單一搜尋字詞,而 Azure AI 搜尋中字詞的最大長度為 32 KB。 如果您需要將比這更多的文字儲存在單一字串字位中,您應該在索引定義中明確地將可篩選、可排序和可 Facet 設定為 false
。
向量欄位必須與維度和向量配置文件相關聯。 如果您使用 Azure 入口網站中的匯入和向量化數據精靈來新增向量欄位,則可擷取的預設值為 true。 如果您使用 REST API,這個設定值將是不成立(false)。
下表說明欄位屬性。
屬性 | 描述 |
---|---|
NAME | 必要。 設定欄位名稱,該欄位在索引或父欄位的 fields 集合中必須是唯一的。 |
類型 | 必要。 設定欄位的數據類型。 欄位可以是簡單或複雜的。 簡單欄位是基本類型,例如 Edm.String 文字或 Edm.Int32 整數。
複雜欄位 可以有屬於簡單或複雜的子欄位。 這可讓您建立對象和對象的數位模型,進而讓您將大部分的 JSON 對象結構上傳至索引。 如需支援類型的完整清單,請參閱 支援的數據類型 。 |
鑰匙 | 必要。 將此屬性設定為 true,以指定欄位的值可唯一識別索引中的檔。 如需詳細資訊,請參閱 本文中的檔索引鍵 。 |
可擷取 | 指出是否可以在搜尋結果中傳回欄位。 如果您要使用欄位做為篩選、排序或評分機制,但不想讓使用者看到欄位,請將此屬性 false 設定為 。 此屬性必須是 true 索引鍵字段,而且它必須是 null 複雜欄位。 這個屬性可以在現有的欄位上變更。 將可擷取的 true 設定不會造成索引記憶體需求增加。 預設值為 true 簡單欄位和 null 複雜欄位。 |
可搜尋 | 指出欄位是否可全文搜索,而且可以在搜尋查詢中參考。 這表示它會進行 語彙分析 ,例如在編製索引期間斷詞。 如果您將可搜尋的字段設定為類似 「Sunny day」 的值,則會在內部將它正規化為個別標記“sunny” 和 “day”。 這可啟用全文搜索這些字詞。 或 Edm.String 類型的Collection(Edm.String) 欄位預設為可搜尋。 此屬性必須為 false 其他非字串數據類型的簡單欄位,而且它必須是 null 複雜欄位。
可搜尋欄位會耗用您索引中的額外空間,因為 Azure AI 搜尋會處理這些欄位的內容,並將其組織在輔助數據結構中,以便進行高效能搜尋。 如果您要在索引中節省空間,而且不需要在搜尋中包含欄位,請將 [可搜尋] 設定為 false 。 如需詳細資訊,請參閱 全文搜索在 Azure AI 搜尋 中的運作方式。 |
可篩選 | 指出是否要在查詢中 $filter 參考欄位。 可篩選與可搜尋的字串處理方式不同。 類型 Edm.String 或 Collection(Edm.String) 可篩選的欄位不會進行語彙分析,因此比較僅適用於完全相符專案。 例如,如果您將這類字段設定為 「Sunny day」,f 則找不到相符專案$filter=f eq 'sunny' ,但$filter=f eq 'Sunny day' 會。 此屬性必須為 null 複雜欄位。 預設值為 true 簡單欄位和 null 複雜欄位。 若要減少索引大小,請在您不會篩選的欄位上,將此屬性設定為 false 。 |
可排序 | 指出是否要在表達式中 $orderby 參考欄位。 根據預設,Azure AI 搜尋會依分數排序結果,但在許多體驗中,使用者想要依檔中的字段排序。 只有在單一值時,才能排序簡單字段(在父檔的範圍內有單一值)。
簡單集合欄位無法排序,因為它們是多重值。 複雜集合的簡單子欄位也是多重值,因此無法排序。 不論其為即時父欄位或上階字段,都是複雜的集合,都是如此。 複雜欄位無法排序,而且可排序的屬性必須 null 適用於這類欄位。 可排序的預設值是 true 單一值簡單欄位、 false 多重值簡單欄位,以及 null 複雜欄位。 |
可面向化 | 指出是否要在Facet查詢中參考欄位。 通常用於搜尋結果的呈現中,包括依類別的點擊計數(例如,搜尋數字相機,並查看依品牌點擊、依百萬像素、價格等等)。 此屬性必須為 null 複雜欄位。 型 Edm.GeographyPoint 別或 Collection(Edm.GeographyPoint) 不可多面向的欄位。 預設值為 true 所有其他簡單欄位。 若要減少索引大小,請將此屬性設定為 false 您不會進行多面向的欄位。 |
分析器 | 設定在編製索引和查詢作業期間標記字串的語彙分析器。 此屬性的有效值包括語言分析器、內建分析器和自定義分析器。 預設值為 standard.lucene 。 此屬性只能與可搜尋的字串字段搭配使用,而且不能與 searchAnalyzer 或 indexAnalyzer 一起設定。 選擇分析器並在索引中建立字段之後,就無法變更欄位。 必須為null 複雜欄位。 |
搜尋分析器 | 將此屬性與 indexAnalyzer 一起設定為索引和查詢指定不同的語彙分析器。 如果您使用這個屬性,請將分析器設定為 null ,並確定 indexAnalyzer 已設定為允許的值。 此屬性的有效值包括內建分析器和自定義分析器。 此屬性只能與可搜尋的欄位搭配使用。 搜尋分析器可以在現有的欄位上更新,因為它只在查詢時間使用。 必須為 null 複雜欄位。 |
索引分析器 | 將此屬性與 searchAnalyzer 一起設定為索引和查詢指定不同的語彙分析器。 如果您使用這個屬性,請將分析器設定為 null ,並確定 searchAnalyzer 設定為允許的值。 此屬性的有效值包括內建分析器和自定義分析器。 此屬性只能與可搜尋的欄位搭配使用。 選擇索引分析器之後,就無法變更欄位。 必須為 null 複雜欄位。 |
synonymMaps | 要與此欄位關聯的同義字名稱清單。 此屬性只能與可搜尋的欄位搭配使用。 目前每個欄位只支援一個同義字對應。 將同義字對應指派給字段可確保以該欄位為目標的查詢字詞會使用同義字對應中的規則在查詢時間展開。 這個屬性可以在現有的欄位上變更。 必須是 null 或複雜欄位的空白集合。 |
欄位 | 如果這是 類型 Edm.ComplexType 為 或 Collection(Edm.ComplexType) 的欄位,則為子欄位的清單。 簡單欄位必須或 null 空白。 如需如何使用子欄位的詳細資訊,請參閱 如何在 Azure AI 搜尋 中建立複雜數據類型模型。 |
建立索引
當您準備好建立索引時,請使用可傳送要求的搜尋用戶端。 您可使用 Azure 入口網站或 REST API 進行早期開發和概念證明測試,否則通常會使用 Azure SDK。
進行開發時,請考量頻繁進行的重建作業。 由於實體結構是在服務中建立,因此許多修改作業都需要卸除和重新建立索引。 您可以考慮處理部份的資料,讓重建更快速。
透過 Azure 入口網站 索引設計會針對特定資料類型強制執行需求和架構規則,例如不允許數值欄位上的全文搜尋功能。
登入 Azure 入口網站。
檢查空間。 搜尋服務受限於索引數目上限,依服務層級而不同。 請確認您有足夠空間容納第二個索引。
在搜尋服務 [概觀 ] 頁面中,選擇其中一個選項來建立搜尋索引:
- 新增索引:用於指定索引結構描述的內嵌編輯器
- 匯入精靈
精靈是一種端對端工作流程,可建立索引子、資料來源和已完成的索引。 同時也可以載入資料。 如果這不是您想要的功能,請改用 [新增索引]。
下列螢幕快照會醒目提示指令列上出現 新增索引、匯入數據 和 匯入及向量化數據精靈 的位置。
建立索引之後,您可以在左窗格的 [ 索引 ] 頁面上再次找到它。
提示
在 Azure 入口網站 中建立索引之後,您可以複製 JSON 表示法,並將其新增至應用程式程式代碼。
針對跨來源查詢來設定 corsOptions
索引結構描述包含設定 corsOptions
的區段。 根據預設,用戶端 JavaScript 無法呼叫任何 API,因為瀏覽器會阻止所有跨原始來源的要求。 若要允許對索引進行跨原始來源查詢,請設定 corsOptions 屬性來啟用 CORS (跨原始來源資源共用)。 基於安全緣故,僅查詢 API 才能支援 CORS。
"corsOptions": {
"allowedOrigins": [
"*"
],
"maxAgeInSeconds": 300
您可以為 CORS 設定下列屬性:
allowedOrigins (必要):這是被允許存取索引的原始來源清單。 允許從這些原始來源提供的 JavaScript 程式碼查詢您的索引 (假設呼叫者提供有效的金鑰或具有權限)。 每個原始來源的形式通常是
protocol://<fully-qualified-domain-name>:<port>
(儘管經常會忽略<port>
)。 如需詳細資訊,請參閱 跨原始來源資源共用 (Wikipedia)。如果您想要允許所有原始來源進行存取,請在
*
陣列中包含 作為單一項目。 「此做法並不建議用於實際執行環境搜尋服務」,但對於開發和偵錯作業通常很有幫助。maxAgeInSeconds (選用):瀏覽器會使用這個值,來判斷快取 CORS 預檢回應的持續期間 (以秒為單位)。 這必須是非負數的整數。 快取期間越長可提供越好的效能,但其會延長 CORS 原則需要生效的時間量。 如果未設定此值,則會使用預設持續時間 (5 分鐘)。
現有索引上允許的更新
建立索引會在搜尋服務上建立實體資料結構 (檔案和反轉的索引)。 一旦建立索引,您就能夠使用建立或更新索引來影響變更,這是取決於修改內容是否會讓這些實體結構無效。 在索引中建立欄位之後,就無法變更大部分的欄位屬性。
若要將應用程式程式代碼中的變換降到最低,您可以 建立索引別名 ,做為搜尋索引的穩定參考。 您可以更新索引別名以指向較新的索引版本,而不是使用索引名稱更新程序代碼。
為了將設計程序中的流失情形最小化,下表說明結構描述中固定和彈性的元素。 變更固定元素需要重建索引,而彈性元素則可以隨時變更,不會影響實體實作。 如需詳細資訊,請參閱 更新或重建索引。
元素 | 可以更新嗎? |
---|---|
名稱 | 否 |
機碼 | 否 |
欄位名稱和類型 | 否 |
欄位屬性 (可搜尋、可篩選、可面向化、可排序) | 否 |
欄位屬性 (可擷取) | 是的 |
預存 (適用於向量) | 否 |
分析器 | 您可以在索引中新增和修改自訂分析器。 針對字串欄位的分析器指派,您只能修改 searchAnalyzer 。 所有其他指派和修改都需要重建。 |
評分設定檔 | 是的 |
建議工具 | 否 |
跨原點資源共用 (CORS) | 是的 |
加密 | 是的 |
同義字對應 | 是的 |
語意設定 | 是的 |
下一步
使用下列連結來瞭解可新增至索引的特殊功能:
使用這些連結來載入或更新索引: