REST 教學課程：使用技能集在 Azure AI 搜尋服務中產生可搜尋的內容
在本教學課程中，了解如何呼叫在編製索引期間建立 AI 擴充管線的 REST API，以進行內容擷取和轉換。
技能集會將 AI 處理新增至原始內容，讓該內容更加統一且可提供搜尋。 一旦您知道技能集的運作方式，您就可以支援廣泛的轉換：從影像分析到自然語言處理，再到您從外部提供的自訂處理。
本教學課程可協助您了解如何：
- 在擴充管線中定義物件。
- 組建技能集。 叫用 OCR、語言偵測、實體辨識和關鍵片語擷取。
- 執行管線。 建立及載入搜尋索引。
- 使用完整文字搜索檢查結果。
如果您沒有 Azure 訂用帳戶，請在開始前開啟免費帳戶。
概觀
本教學課程使用 REST 用戶端和 Azure AI 搜尋 REST API 來建立資料來源、索引、索引子和技能集。
索引子驅動管線中的每一個步驟，從 Azure 儲存體上 Blob 容器中範例資料 (非結構化文字和影像) 的內容擷取開始。
擷取內容之後，技能集 會從 Microsoft 執行內建技能，以尋找和擷取資訊。 這些技能包括影像上的光學字元辨識 (OCR)、文字的語言偵測、關鍵片語擷取和實體辨識 (組織)。 技能集所建立的新資訊會傳送至索引中的欄位。 一旦填入了索引，您就可以在查詢、Facet 和篩選條件中使用這些欄位。
必要條件
注意
您可以使用免費搜尋服務來進行本教學課程。 免費層的限制為三個索引、三個索引子、以及三個資料來源。 本教學課程會各建立一個。 開始之前，請確定您的服務有空間可接受新的資源。
下載檔案
下載範例資料存放庫的 ZIP 檔案，並擷取內容。 了解作法。
將範例資料上傳至 Azure 儲存體
在 Azure 儲存體中，建立新的容器並命名為 cog-search-demo。
取得儲存體連接字串，以便在 Azure AI 搜尋服務中制訂連線。
在左側，選取 [存取金鑰]。
複製金鑰一或金鑰二的連接字串。 連接字串應類似於下列範例：
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
Azure AI 服務
內建 AI 擴充以 Azure AI 服務為後盾，包括用於自然語言和影像處理的文字分析和 Azure AI 視覺。 針對如本教學課程的小型工作負載，您可以使用每個索引子 20 筆交易的免費配置。 針對較大的工作負載，將 Azure AI Services 多區域資源附加至技能集，並使用隨用隨付價格。
複製搜尋服務 URL 與 API 金鑰
在本教學課程中，Azure AI 搜尋服務的連線需要端點和 API 金鑰。 您可以從 Azure 入口網站取得這些值。
登入 Azure 入口網站，瀏覽至搜尋服務的 [概觀] 頁面，然後複製 URL。 範例端點看起來會像是
https://mydemo.search.windows.net。在 [設定 > 金鑰] 下面，複製系統管理金鑰。 系統管理金鑰可用來新增、修改和刪除物件。 有兩個可交換的系統管理密鑰。 複製任一個。
設定 REST 檔案
啟動 Visual Studio Code，然後開啟 [skillset-tutorial.rest] 檔案。 如果您需要使用 REST 用戶端的協助，請參閱快速入門：使用 REST 進行文字搜尋。
為變數提供值：搜尋服務端點、搜尋服務系統管理 API 金鑰、索引名稱、Azure 儲存體帳戶的連接字串，以及 blob 容器名稱。
建立管線
AI 擴充是由索引子驅動。 逐步解說的這個部分會建立四個物件：資料來源、索引定義、技能集、索引子。
步驟 1：建立資料來源
呼叫建立資料來源，將連接字串設定為包含範例資料檔案的 Blob 容器。
### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ds",
"description": null,
"type": "azureblob",
"subtype": null,
"credentials": {
"connectionString": "{{storageConnectionString}}"
},
"container": {
"name": "{{blobContainer}}",
"query": null
},
"dataChangeDetectionPolicy": null,
"dataDeletionDetectionPolicy": null
}
步驟 2：建立技能集
呼叫「建立技能集」以指定哪些擴充步驟會套用於您的內容。 除非具有相依性，否則技能會以平行方式執行。
### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ss",
"description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
"cognitiveServices": null,
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"context": "/document/normalized_images/*",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name":"text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name":"offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName" : "merged_text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.SplitSkill",
"textSplitMode": "pages",
"maximumPageLength": 4000,
"defaultLanguageCode": "en",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "textItems",
"targetName": "pages"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"description": "If you have multilingual content, adding a language code is useful for filtering",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "languageName",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"context": "/document/pages/*",
"inputs": [
{
"name": "text",
"source": "/document/pages/*"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyPhrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Organization"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Location"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Person"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "persons",
"targetName": "persons"
}
]
}
]
}
重點︰
要求的主體會指定下列內建技能：
技能 描述 光學字元辨識 辨識影像檔案中的文字和數位。 文字合併 建立「合併的內容」，以重新組合先前分隔的內容，適用於內嵌影像的文件 (PDF、DOCX 等等)。 影像和文字會在文件萃取階段進行分隔。 合併技能會藉由將擴充期間建立的任何已辨識文字、影像標題或標記插入文件中擷取影像的相同位置，以重新組合這些影像和文字。 您在技能集中使用合併的內容時，此節點會包含文件中的全部文字，包括永遠不會經歷 OCR 或影像分析的純文字文件。 語言偵測 偵測語言並輸出語言名稱或代碼。 在多語系資料集中，語言欄位可用於篩選。 實體辨識 從合併的內容擷取人員、組織和位置的名稱。 文字分割 在呼叫關鍵片語擷取技能之前，將大型合併內容分成較小的區塊。 關鍵片語擷取可接受不超過 50,000 個字元的輸入。 有些範例檔案需要進行分割，以符合這項限制。 關鍵片語擷取 提取前幾個關鍵片語。 每項技術會分別對文件的內容執行。 在處理期間，Azure AI 服務會萃取每份文件，以讀取不同檔案格式的內容。 找到來自來源檔案的文字時，會將文字放入產生的
content欄位中，每份文件一個欄位。 因此，輸入會變成"/document/content"。針對關鍵片語的擷取，因為我們使用文字分隔器技能將較大的檔案分成多個頁面，所以關鍵片語擷取技能的內容會是
"document/pages/*"，而不是"/document/content"。
注意
輸出可以對應至索引、作為下游技能的輸入，或在使用語言代碼時同時作為對應和輸入。 在索引中，語言代碼可用於篩選。 如需技能集基本概念的詳細資訊，請參閱如何定義技能集。
步驟 3：建立索引
呼叫建立索引，提供用來在 Azure AI 搜尋中建立反向索引和其他建構的架構。
索引的最大元件是欄位集合，其中的資料類型和屬性會決定 Azure AI 搜尋服務中的內容和行為。 請確保您有適用於新產生輸出的欄位。
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idx",
"defaultScoringProfile": "",
"fields": [
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "text",
"type": "Collection(Edm.String)",
"facetable": false,
"filterable": true,
"searchable": true,
"sortable": false
},
{
"name": "language",
"type": "Edm.String",
"searchable": false,
"sortable": true,
"filterable": true,
"facetable": false
},
{
"name": "keyPhrases",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "organizations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "persons",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "locations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "metadata_storage_path",
"type": "Edm.String",
"key": true,
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "metadata_storage_name",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
}
]
}
步驟 4：建立和執行索引子
呼叫建立索引子以驅動管線。 到目前為止所建立的三個元件 (資料來源、技能集、索引) 都是索引子的輸入。 在 Azure AI 服務上建立索引子是用以啟動整個管線的事件。
預期此步驟需要幾分鐘的時間才能完成。 即使資料集很小，分析技能仍需要大量計算。
### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idxr",
"description": "",
"dataSourceName" : "cog-search-demo-ds",
"targetIndexName" : "cog-search-demo-idx",
"skillsetName" : "cog-search-demo-ss",
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "metadata_storage_path",
"mappingFunction" : { "name" : "base64Encode" }
},
{
"sourceFieldName": "metadata_storage_name",
"targetFieldName": "metadata_storage_name"
}
],
"outputFieldMappings" :
[
{
"sourceFieldName": "/document/merged_text",
"targetFieldName": "content"
},
{
"sourceFieldName" : "/document/normalized_images/*/text",
"targetFieldName" : "text"
},
{
"sourceFieldName" : "/document/organizations",
"targetFieldName" : "organizations"
},
{
"sourceFieldName": "/document/language",
"targetFieldName": "language"
},
{
"sourceFieldName" : "/document/persons",
"targetFieldName" : "persons"
},
{
"sourceFieldName" : "/document/locations",
"targetFieldName" : "locations"
},
{
"sourceFieldName" : "/document/pages/*/keyPhrases/*",
"targetFieldName" : "keyPhrases"
}
],
"parameters":
{
"batchSize": 1,
"maxFailedItems":-1,
"maxFailedItemsPerBatch":-1,
"configuration":
{
"dataToExtract": "contentAndMetadata",
"imageAction": "generateNormalizedImages"
}
}
}
重點︰
要求的主體包含先前物件的參考、影像處理所需的設定屬性，以及兩種類型的欄位對應。
"fieldMappings"會在技能集之前進行處理，用來將資料來源中的內容傳送到索引中的目標欄位。 您會使用欄位對應將已修改的現有內容傳送至索引。 如果兩端上的欄位名稱和類型都相同，則不需要任何對應。"outputFieldMappings"適用於技能建立的欄位，在技能集執行之後。 針對outputFieldMappings中sourceFieldName的參考項目，當您從文件萃取或擴充中建立這些項目之後，這些項目才會存在。targetFieldName是索引中的欄位，定義於索引結構描述中。"maxFailedItems"參數會設定為 -1，這會指示索引引擎在資料匯入期間忽略錯誤。 這是可接受的設定，因為示範資料來源中只有少量文件。 若要有較大的資料來源，您應將值設定為大於 0。"dataToExtract":"contentAndMetadata"陳述式會指示索引子自動從 Blob 的內容屬性和每個物件的中繼資料擷取值。imageAction參數會指示索引子從資料來源中找到的影像擷取文字。"imageAction":"generateNormalizedImages"組態可與 OCR 技術和文字合併技術結合，指示索引子從影像中擷取文字 (例如，從「停」交通號誌中擷取「停」這個字)，並將其內嵌為內容欄位的一部分。 此行為適用於內嵌影像 (例如，在 PDF 內的影像) 和獨立影像檔案，例如 JPG 檔案。
注意
建立索引子時會叫用管線。 資料的存取、輸入和輸出的對應或作業順序若有問題，都會在這個階段中出現。 若要透過程式碼或指令碼的變更重新執行管線，您可能需要先卸除物件。 如需詳細資訊，請參閱重設並重新執行。
監視編製索引
當您提交建立索引子的要求時，編制索引和擴充就會開始進行。 取決於技能集複雜度和作業，編製索引可能需要一些時間。
若要找出索引子是否仍在執行中，請呼叫 [取得索引子狀態] 檢查索引子狀態。
### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
重點︰
警告在某些案例中很常見，但不一定表示有問題。 例如，如果 Blob 容器包含影像檔案，而管線並未處理影像，您會收到指出影像未處理的警告。
在此範例中，有不含文字的 PNG 檔案。 這五種文字型技能 (語言偵測、位置的實體辨識、組織、人員和關鍵片語擷取) 都無法在此檔案上執行。 產生的通知會顯示在執行歷程記錄中。
檢查結果
您建立包含 AI 產生內容的索引後，請呼叫 [搜尋文件] 執行一些查詢以查看結果。
### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"select": "metadata_storage_name,language,organizations",
"count": true
}
篩選可協助您將結果縮小至感興趣的項目：
### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"filter": "organizations/any(organizations: organizations eq 'Microsoft')",
"select": "metadata_storage_name,organizations",
"count": true
}
這些查詢說明在 Azure AI 搜尋所建立的新欄位上，您可使用的一些查詢語法和篩選方式。 如需更多查詢範例，請參閱搜尋文件 REST API 中的範例、簡單的語法查詢範例及完整的 Lucene 查詢範例。
重設並重新執行
在開發初期階段，反覆執行設計很常見。 重設並重新執行可協助反覆運算。
重要心得
本教學課程示範使用 REST API 建立 AI 擴充管線的基本步驟：資料來源、技能集、索引和索引子。
內建技能已透過輸入和輸出連同顯示鏈結技能機制的技能集定義一起導入。 您也已了解在將管線中的擴充值路由至 Azure AI 搜尋服務上的可搜尋索引時，索引子定義中必須要有 outputFieldMappings。
最後，您了解到如何測試結果並重設系統，以進行進一步的反覆運算。 您已了解對索引發出查詢，會傳回由擴充的索引管線建立的輸出。
清除資源
如果您使用自己的訂用帳戶，當專案結束時，建議您移除不再需要的資源。 資源若繼續執行，將需付費。 您可以個別刪除資源，或刪除資源群組以刪除整組資源。
您可以使用左導覽窗格中的 [所有資源] 或 [資源群組] 連結，在入口網站中尋找和管理資源。
下一步
現在您已熟悉 AI 擴充管線中的所有物件，並可以更深入地了解技能集定義和個別技能。