REST 教學課程：使用技能集在 Azure AI 搜尋服務中產生可搜尋的內容

發行項
03/14/2024

在本教學課程中，瞭解如何呼叫 REST API，以在編製索引期間建立內容擷取和轉換的 AI 擴充管線。

技能集會將 AI 處理新增至原始內容，讓該內容更加統一且可搜尋。一旦您知道技能集的運作方式，您就可以支援廣泛的轉換：從影像分析到自然語言處理，到您從外部提供的自定義處理。

本教學課程可協助您瞭解如何：

在擴充管線中定義物件。
建置技能集。叫用 OCR、語言偵測、實體辨識和關鍵片語擷取。
執行管線。建立並載入搜尋索引。
使用全文搜索檢查結果。

如果您沒有 Azure 訂用帳戶，請在開始之前先開啟免費帳戶。

概觀

本教學課程使用 REST 用戶端和 Azure AI 搜尋 REST API 來建立數據源、索引器、索引器和技能集。

索引器會驅動管線中的每個步驟，從 Azure 儲存體上 Blob 容器中範例數據的內容擷取（非結構化文字和影像）開始。

擷取內容之後，技能集會從 Microsoft 執行內建技能，以尋找和擷取資訊。這些技能包括影像上的光學字元辨識（OCR）、文字的語言偵測、關鍵片語擷取和實體辨識（組織）。技能集所建立的新資訊會傳送至索引中的欄位。填入索引之後，您就可以在查詢、Facet 和篩選中使用字段。

必要條件

注意

您可以針對本教學課程使用免費的搜尋服務。免費層會將您限制為三個索引、三個索引器和三個數據源。本教學課程會各建立一個。開始之前，請確定您的服務有空間可接受新的資源。

下載檔案

下載範例數據存放庫的 ZIP 檔案，並擷取內容。瞭解做法。

將範例數據上傳至 Azure 儲存體

在 Azure 儲存體中，建立新的容器，並將其命名為cog-search-demo。
上傳範例數據檔。
取得記憶體連接字串，讓您可以在 Azure AI 搜尋服務中制定連線。
1. 在左側，選取 [ 存取金鑰]。
2. 複製金鑰一或兩個金鑰的連接字串。連接字串類似下列範例：
```
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。
在 [設定> Keys] 底下，複製管理密鑰。管理員索引鍵可用來新增、修改和刪除物件。有兩個可交換的系統管理密鑰。複製任一個。

設定 REST 檔案

啟動 Visual Studio Code 並開啟 skillset-tutorial.rest 檔案。如果您需要 REST 用戶端的協助，請參閱快速入門：使用 REST 進行文字搜尋。
提供變數的值：搜尋服務端點、搜尋服務管理員 API 金鑰、索引名稱、連接字串至 Azure 儲存體帳戶，以及 Blob 容器名稱。

建立管線

AI 擴充是由索引器驅動。本逐步解說的這個部分會建立四個物件：數據源、索引定義、技能集、索引器。

步驟 1：建立資料來源

呼叫建立數據源，將連接字串設定為包含範例數據檔的 Blob 容器。

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-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=2023-11-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=2023-11-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=2023-11-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=2023-11-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=2023-11-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=2023-11-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 擴充管線的基本步驟：數據源、技能集、索引和索引器。

引進了內建技能，以及技能集定義，可透過輸入和輸出來顯示將技能鏈結在一起的機制。您也瞭解到，outputFieldMappings在索引器定義中，需要從管線將擴充值路由傳送至 Azure AI 搜尋服務上的可搜尋索引。

最後，您已瞭解如何測試結果，並重設系統以進行進一步的反覆專案。您已瞭解針對索引發出查詢會傳回擴充索引管線所建立的輸出。

清除資源

如果您使用自己的訂用帳戶，當專案結束時，建議您移除不再需要的資源。資源若繼續執行，將需付費。您可以個別刪除資源，或刪除資源群組以刪除整組資源。

您可以使用左導覽窗格中的 [所有資源] 或 [資源群組] 連結，在入口網站中尋找和管理資源。

下一步

現在您已熟悉 AI 擴充管線中的所有物件，請進一步瞭解技能集定義和個別技能。

如何建立技能集

共用方式為

REST 教學課程：使用技能集在 Azure AI 搜尋服務中產生可搜尋的內容

概觀

必要條件

下載檔案

將範例數據上傳至 Azure 儲存體

Azure AI 服務

複製搜尋服務 URL 和 API 金鑰

設定 REST 檔案

建立管線

步驟 1：建立資料來源

步驟 2：建立技能集

步驟 3：建立索引

步驟 4：建立和執行索引器

監視索引編製

檢查結果

重設並重新執行

重要心得

清除資源

下一步

意見反應

意見反應

其他資源