文字分割技能

備註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

Important

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽詞,請參閱預覽功能。

Text Split 技能能將文字拆分成文字塊。 你可以指定要將文字拆成句子或特定長度的頁面。 位置元資料如偏移與序數位置也可作為輸出提供。 若下游技能有最大文字長度要求,例如將資料區塊傳入 Azure OpenAI 及其他模型提供者的嵌入技能,這項技能非常有用。 欲了解更多此情境資訊,請參閱 向量搜尋的區塊文件。

備註

這項技能不綁定於鑄造工具。 它不計費,也沒有 Foundry Tools 的鑰匙要求。

@odata.type

Microsoft.Skills.Text.SplitSkill

技能參數

參數依大小寫區分。

參數名稱 Description
textSplitMode 不管是 pages 不是 sentences。 頁面有可設定的最大長度,但技能會避免截斷句子,因此實際長度可能會較短。 句子是一串在句尾標點處結束的字串,例如句點、問號或驚嘆號,前提是該語言有句尾標點符號。
maximumPageLength 只有當 textSplitMode 設定為 pages時才適用。 當 unit 設為 characters時,此參數指的最大頁面長度(以字元單位)由 String.Length測量。 最低值是300,最高是50000,預設值是5000。 演算法會盡力在句子邊界處打破文字,因此每個區塊的大小可能略小於 maximumPageLength。

當 unit 設定為 azureOpenAITokens時,最大頁長即為模型的標記長度限制。 對於文字嵌入模型,頁面長度的一般建議為 512 個標記。
defaultLanguageCode (可選)以下語言代碼之一: am, bs, cs, da, de, en, es, et, fr, he, hi, hr, hu, fi, id, is, it, ja, ko, lv, no, nl, pl, pt-PT, pt-BR, ru, sk, sl, sr, sv, tr, ur, zh-Hans。 預設是英文(en)。 有幾點需要考慮:
  • 提供語言代碼有助於避免非空白語言如中文、日文和韓文將單字切半。
  • 如果你事先不熟悉該語言(例如,如果你使用 LanguageDetectionSkill 來偵測語言),我們建議使用 en 預設的語言。
pageOverlapLength 只有當 textSplitMode 設定為 pages時才適用。 每頁起始時,字元數或標記數來自前一頁末尾。 如果這個參數設為 0,後續頁面就不會有重疊的文字。 此 範例 包含參數。
maximumPagesToTake 只有當 textSplitMode 設定為 pages時才適用。 還原頁數。 預設值是 0,代表要回傳所有頁面。 如果只需要部分頁面,應該設定這個值。 此 範例 包含參數。
unit (預覽) 只有當 textSplitMode 設定為 pages時才適用。 指定是(預設)characters還是 azureOpenAITokens 。 設定單位會影響 maximumPageLength 和 pageOverlapLength。
azureOpenAITokenizerParameters (預覽) 物件,提供單位的額外參數 azureOpenAITokens 。

encoderModelName 是專用的分詞器,用於將文字轉換為詞彙,對自然語言處理(NLP)任務至關重要。 不同模型使用不同的分詞器。 有效的數值包括 GPT-4 使用的預設值 cl100k_base。 其他有效的數值包括r50k_base、p50k_base和p50k_edit。 這個技能透過 SharpToken 和 實作 tiktoken 函式庫,但並不支援所有編碼器。 例如,目前 GPT-4o 所使用的o200k_base編碼尚未支援。

allowedSpecialTokens 定義一組在分名化過程中允許使用的特殊標記集合。 特殊標記是你想要獨特處理的字串,確保它們在標記化過程中不會被分割。 例如,[“[START”]、[END]“]。 如果 tiktoken 函式庫因語言限制或其他意外行為而無法如預期執行分詞化,建議改用文字分割。

技能輸入

參數名稱 Description
text 將文字拆分成子串。
languageCode (可選)文件的語言代碼。 如果你不了解文字輸入的語言(例如你使用 LanguageDetectionSkill 來偵測語言),可以省略這個參數。 如果你設定 languageCode 為不在支援列表中 defaultLanguageCode的語言,會發出警告且文字不會被分割。

技能產出

參數名稱 Description
textItems 輸出是一個被提取的子字串陣列。 textItems 是輸出的預設名稱。

targetName 這是可選的,但如果你有多個文字分割技能,請務必設定 targetName 不會將第一個技能的資料覆蓋到第二個技能。 若 targetName 設定為 ,則用於輸出欄位映射或消耗技能輸出的下游技能,例如嵌入技能。
offsets 輸出是一個被提取的偏移量陣列。 每個索引的值是一個物件,包含該索引中文字項目的偏移量,包含三種編碼方式:UTF-8、UTF-16 和 CodePoint。 offsets 是輸出的預設名稱。

targetName 這是可選的,但如果你有多個文字分割技能,請務必設定 targetName 不會將第一個技能的資料覆蓋到第二個技能。 若 targetName 設定為 ,則用於輸出欄位映射或消耗技能輸出的下游技能,例如嵌入技能。
lengths 輸出是一個被提取的長度陣列。 每個索引的值是一個物件,包含該索引中文字項目的偏移量,包含三種編碼方式:UTF-8、UTF-16 和 CodePoint。 lengths 是輸出的預設名稱。

targetName 這是可選的,但如果你有多個文字分割技能,請務必設定 targetName 不會將第一個技能的資料覆蓋到第二個技能。 若 targetName 設定為 ,則用於輸出欄位映射或消耗技能輸出的下游技能,例如嵌入技能。
ordinalPositions 輸出是一個序數陣列,對應於文本項目在原始文本中的位置。 ordinalPositions 是輸出的預設名稱。

targetName 這是可選的,但如果你有多個文字分割技能,請務必設定 targetName 不會將第一個技能的資料覆蓋到第二個技能。 若 targetName 設定為 ,則用於輸出欄位映射或消耗技能輸出的下游技能,例如嵌入技能。

範例定義

{
    "name": "SplitSkill", 
    "@odata.type": "#Microsoft.Skills.Text.SplitSkill", 
    "description": "A skill that splits text into chunks", 
    "context": "/document", 
    "defaultLanguageCode": "en", 
    "textSplitMode": "pages", 
    "unit": "azureOpenAITokens", 
    "azureOpenAITokenizerParameters":{ 
        "encoderModelName":"cl100k_base", 
        "allowedSpecialTokens": [ 
            "[START]", 
            "[END]" 
        ] 
    },
    "maximumPageLength": 512,
    "inputs": [
        {
            "name": "text",
            "source": "/document/text"
        },
        {
            "name": "languageCode",
            "source": "/document/language"
        }
    ],
    "outputs": [
        {
            "name": "textItems",
            "targetName": "pages"
        }
    ]
}

範例輸入

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "text": "This is the loan application for Joe Romero, a Microsoft employee who was born in Chile and who then moved to Australia...",
                "languageCode": "en"
            }
        },
        {
            "recordId": "2",
            "data": {
                "text": "This is the second document, which will be broken into several pages...",
                "languageCode": "en"
            }
        }
    ]
}

範例輸出

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "pages": [
                    "This is the loan...",
                    "In the next section, we continue..."
                ],
                "offsets": [
                    {
                        "utf8": 0,
                        "utf16": 0,
                        "codePoint": 0
                    },
                    {
                        "utf8": 146,
                        "utf16": 146,
                        "codePoint": 146
                    }
                ],
                "lengths": [
                    {
                        "utf8": 146,
                        "utf16": 146,
                        "codePoint": 146
                    },
                    {
                        "utf8": 211,
                        "utf16": 211,
                        "codePoint": 211
                    }
                ],
                "ordinalPositions" : [
                    1,
                    2
                ]
            }
        },
        {
            "recordId": "2",
            "data": {
                "pages": [
                    "This is the second document...",
                    "In the next section of the second doc..."
                ],
                "offsets": [
                    {
                        "utf8": 0,
                        "utf16": 0,
                        "codePoint": 0
                    },
                    {
                        "utf8": 115,
                        "utf16": 115,
                        "codePoint": 115
                    }
                ],
                "lengths": [
                    {
                        "utf8": 115,
                        "utf16": 115,
                        "codePoint": 115
                    },
                    {
                        "utf8": 209,
                        "utf16": 209,
                        "codePoint": 209
                    }
                ],
                 "ordinalPositions" : [
                    1,
                    2
                ]
            }
        }
    ]
}

備註

此範例設定 textItems 為 至 pagestargetName。 因為 targetName 是設定的, pages 你應該用來選擇文本分割技能輸出的數值。 在下游技能中,索引器輸出/document/pages/*欄位映射、知識庫投影與索引投影。 這個範例沒有設定 offsets、 lengths,也 ordinalPosition 沒有設定成其他名稱,所以你在下游技能中應該使用的值會保持不變。 offsets 以及 lengths 是複型別而非原始型,因為它們包含多種編碼類型的值。 你應該用來取得特定編碼的值,例如 UTF-8,會是這樣: /document/offsets/*/utf8。

分塊與向量化的範例

此範例用於整合向量化。

  • pageOverlapLength:重疊文字在 資料區塊 情境中非常有用,因為它能維持同一文件產生的區塊間的連續性。

  • maximumPagesToTake:在 向量化 情境下,頁面輸入限制非常有用,因為它能幫助你維持在提供向量化的嵌入模型所設定的最大輸入限制之下。

範例定義

此定義加入 pageOverlapLength 了 100 個字元和 maximumPagesToTake 1 個字元。

假設 maximumPageLength 是 5,000 字元(預設),接著 "maximumPagesToTake": 1 處理每個來源文件的前 5,000 字元。

此範例設定 textItems 為 至 myPagestargetName。 因為 targetName 是設定的, myPages 你應該用來選擇文本分割技能輸出的數值。 在下游技能中,索引器輸出/document/myPages/*欄位映射、知識庫投影與索引投影。

{
    "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
    "textSplitMode" : "pages", 
    "maximumPageLength": 1000,
    "pageOverlapLength": 100,
    "maximumPagesToTake": 1,
    "defaultLanguageCode": "en",
    "inputs": [
        {
            "name": "text",
            "source": "/document/content"
        },
        {
            "name": "languageCode",
            "source": "/document/language"
        }
    ],
    "outputs": [
        {
            "name": "textItems",
            "targetName": "myPages"
        }
    ]
}

取樣輸入(與前述範例相同)

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "text": "This is the loan application for Joe Romero, a Microsoft employee who was born in Chile and who then moved to Australia...",
                "languageCode": "en"
            }
        },
        {
            "recordId": "2",
            "data": {
                "text": "This is the second document, which will be broken into several sections...",
                "languageCode": "en"
            }
        }
    ]
}

取樣輸出(注意重疊)

在每個「textItems」陣列中,第一個項目的後續文字會被複製到第二個項目的開頭。

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "myPages": [
                    "This is the loan...Here is the overlap part",
                    "Here is the overlap part...In the next section, we continue..."
                ]
            }
        },
        {
            "recordId": "2",
            "data": {
                "myPages": [
                    "This is the second document...Here is the overlap part...",
                    "Here is the overlap part...In the next section of the second doc..."
                ]
            }
        }
    ]
}

錯誤案例

若某語言不支援,會產生警告。

另請參閱