分析儀定義:
- 要處理哪種類型的內容(文件、圖片、音訊或影片)
- 要擷取哪些元素(文字、版面、表格、欄位、逐字稿)
- 如何結構化輸出(markdown、JSON 欄位、片段)
- 哪些 AI 模型應該用於處理
分析器是內容理解的核心建構元件。 它們將內容擷取、AI 分析與結構化資料輸出整合成單一且可重複使用的配置。 你可以使用預設分析器來處理常見情境,或是根據你的需求打造客製化分析器。
除非另有說明,本文範例皆使用 GA API 版本 2025-11-01。 標示為預覽的功能需要 2026-06-01-preview。
分析儀類型
內容理解提供多種分析器類型:
-
基礎分析器:基礎分析器,提供每種內容類型
prebuilt-document(,prebuilt-audioprebuilt-videoprebuilt-image)的核心處理能力。 將這些分析儀當作客製化分析器的基礎。 -
RAG 分析器:以語意理解萃取內容,用於搜尋與 AI 應用。 它們是針對檢索增強生成情境優化的。 範例包括
prebuilt-documentSearch和prebuilt-videoSearch。 -
領域專屬分析器:預先配置針對特定文件類型與產業,如發票、收據、身分證文件及合約。 範例包括
prebuilt-invoice、prebuilt-receipt、prebuilt-idDocument和 。 - 自訂分析儀:透過擴充基礎分析器,加入自訂欄位結構與配置,以符合特定需求而建立的分析器。
欲了解更多資訊及完整的領域專用分析器清單,請參閱 預建分析器。
註
使用 API 版本 2026-06-01-preview 建置的文件分析器,也能在需要推理證據以建立答案的情境中使用 代理模式 ,例如計算與驗證。 初步預覽支援每個分析請求一個輸入檔案。
分析儀配置結構
使用具有多個頂層屬性的 JSON 物件定義分析器配置。 您可以配置以下元件:
-
分析器屬性 -核心身份與元資料
- analyzerID - 唯一識別碼
- 名稱 - 顯示名稱
- 說明 - 目的說明
- baseAnalyzerID - 父分析器參考
-
模型配置 - AI 模型設定
- 模型 - 預設模型
-
處理配置- 內容處理選項
- config - 行為設定
-
欄位結構 - 結構化資料擷取
- fieldSchema - 欄位定義
以下是一個簡短範例,展示分析儀配置的整體結構:
{
"analyzerId": "myCustomInvoiceAnalyzer",
"description": "Extracts vendor information, line items, and totals from commercial invoices",
"baseAnalyzerId": "prebuilt-document",
"config": {
"enableOcr": true
},
"fieldSchema": {
"fields": {
"vendorName": {
"type": "string"
}
}
},
"models": {
"completion": "gpt-5.2",
"embedding": "text-embedding-3-large"
}
}
分析儀特性
利用這些特性來獨特地識別並描述你的分析儀:
analyzerId
- 說明: 分析儀的唯一識別碼。 使用此識別碼在 API 呼叫中參考分析器。
-
範例:
"prebuilt-invoice""myCustomAnalyzer" -
指引:
- 使用描述性名稱來指示分析器的用途。
- 對於自訂分析器,選擇不會與預設分析器名稱衝突的名稱。
- 使用字母、數字、點或底線。
name
- 說明: 使用者介面與文件中顯示的人類可讀顯示名稱。
-
範例:
"Invoice document understanding""Custom receipt processor"
description
- 說明: 簡要說明分析儀的功能及處理的內容。 AI 模型在現場擷取時會將這些描述作為上下文,因此清晰的描述能提升萃取準確度。
-
範例:
"Analyzes invoice documents to extract line items, totals, vendor information, and payment terms" -
指引:
- 要具體說明分析儀萃取的內容。
- 說明它支援的內容類型。
- 保持簡潔但資訊豐富。
- 撰寫清晰的描述,引導 AI 模型理解。
baseAnalyzerId
- 說明: 參考一個父分析器,該分析器繼承其配置。
-
支援的基底分析器:
-
"prebuilt-document"- 用於文件式客製化分析器 -
"prebuilt-audio"- 用於基於音訊的客製化分析儀 -
"prebuilt-video"- 用於基於影像的客製化分析儀 -
"prebuilt-image"- 用於基於影像的客製化分析儀
-
-
範例:
"baseAnalyzerId": "prebuilt-document"
註
當你指定基礎分析器時,你的自訂分析器會繼承所有預設設定,並能覆蓋特定設定。
模型配置
models
-
說明: 指定使用此分析器處理時應使用的 Foundry 模型名稱。 這些是服務使用的型號名稱(非部署名稱)。 它們必須與基礎分析儀中的某一者
supportedModels相符。 Content Understanding 支援的完整模型列表請參考 supported models。 -
屬性:
-
completion- 完成任務的模型名稱(例如田野提取、分割、圖解分析) -
embedding- 嵌入任務的模型名稱(使用知識庫)
-
- 重要: 這些型號名稱來自 Foundry 目錄,而非部署名稱。 執行時,服務會將這些模型名稱映射到你在資源層級實際配置的模型部署。
-
範例:
{ "completion": "gpt-5.2", "embedding": "text-embedding-3-large" }
請參閱「 將您的內容理解資源與 Foundry 模型連結 」以了解如何配置連接模型。
處理配置
物件包含 config 所有控制內容分析方式的處理選項。 這些選項依功能分為以下類別:
設定物件屬性
一般選項
workflow
-
請求值:
"default""agentic" -
預設:
"default" -
說明: 當你建立文件分析器時,會選擇工作流程。 使用
"default"或省略該屬性,讓服務根據分析器設定選擇工作流程。 用於"agentic"啟用 代理模式 ,以強化對複雜文件的推理。 -
回應值: 服務在建立分析器時會解析請求值。 建立或更新回應,回應
GET會回傳一個版本化的工作流程家族值。config.workflow -
成本影響: 解決的工作流程家族決定情境化速率。 以 開頭的
standard數值則使用標準的情境化率。 其他所有家族,包括advanced、agentic,以及未來的服務支援工作流程家族,則使用進階情境化速率。 代理模式也可能消耗更多模型標記,且比非代理分析花費更長時間。 -
支持單位: 具備 API 版本
2026-06-01-preview的文件分析器。 初始代理模式預覽支援每個分析請求一個輸入檔案。 -
範例:
{ "config": { "workflow": "agentic" } }
下表顯示該服務如何解析 workflow 自訂分析器:
| 分析器建立情境 | 請求值 | 回歸 config.workflow |
情境化率 |
|---|---|---|---|
API 版本或更早版本2025-11-01 |
無法提供 |
standard.2025-11-01 當使用 preview API 取得時 |
標準 |
| 無標記資料的預覽 API |
"default" 或省略 |
standard.2026-06-01-preview |
標準 |
| 帶有標記資料的預覽 API |
"default" 或省略 |
advanced.2026-06-01-preview |
進階 |
| 具備代理模式的預覽 API | "agentic" |
agentic.2026-06-01-preview |
進階 |
預建分析器會回傳服務指派、版本控制 standard 或 advanced 工作流程值。 工作流程族識別適用的情境化率。
returnDetails
- 預設值: false(依分析分析器而異)
- 說明: 控制回應中是否包含詳細資訊,如信心分數、邊界框、文字範圍及元資料。
-
使用時機:
- 在除錯擷取問題時,將其設定為
true。 - 當你需要位置資訊來提取資料時,
- 當驗證時需要信心分數。
- 用於品質保證和測試。
- 在除錯擷取問題時,將其設定為
- 對回應的影響: 隨著更多元資料大幅增加回應大小。
文件內容擷取選項
enableOcr
- 預設: 真
- 說明: 啟用光學字元辨識技術,從影像及掃描文件中擷取文字。
-
使用時機:
- 啟用掃描文件、照片及以圖片為主的 PDF 功能。
- 為了提升效能,請關閉原生數位 PDF 檔案。
- 支援來自: 文件分析器。
enableLayout
- 預設: 真
- 說明: 擷取版面資訊,包括段落、行、字、閱讀順序及結構元素。
-
使用時機:
- 理解文件結構與階層的必要條件。
- 這對於準確擷取段落與章節是必要的。
- 如果只需要原始文字擷取,請關閉。
- 支援來自: 文件式分析器。
enableFormula
- 預設: 真
- 說明: 偵測並擷取 LaTeX 格式的數學公式與方程式。
-
使用時機:
- 支援科學論文、研究文件、技術文件。
- 適用於協助工具需求 (替代文字產生)。
- 支援來自: 文件式分析器。
enableBarcode
- 預設: 真
- 說明: 偵測並擷取條碼與 QR 碼,回傳解碼後的數值。
-
使用時機:
- 啟用庫存文件、運送標籤、產品文件。
- 當條碼不存在時關閉,以提升效能。
- 支援來自: 文件式分析器。
- 支援的條碼類型: QR Code、PDF417、UPC-A、UPC-E、代碼 39、Code 128、EAN-8、EAN-13、DataBar、Code 93、Codabar、ITF、Micro QR Code、Aztec、Data Matrix、MaxiCode。
表格與圖表選項
tableFormat
-
預設:
"html" -
支持價值:
"html""markdown" - 說明: 指定擷取資料表的輸出格式。
-
使用時機:
- 請使用
"html"進行網頁渲染,或在需要保持複雜表格結構時使用。 - 在文件或基於文字的處理中使用
"markdown"來製作簡單表格。
- 請使用
- 支援來自: 文件式分析器。
chartFormat
-
預設:
"chartjs" -
支持的價值觀:
"chartjs" - 說明: 規定擷取圖表資料的格式。 與 Chart.js 函式庫相容。
-
使用時機:
- 從長條圖、折線圖和圓餅圖中提取資料時,
- 在將視覺圖表轉換成結構化資料以便重新渲染時,
- 支援來自: 文件式分析器。
圖與影像分析選項
enableFigureDescription
- 預設: false
- 說明: 生成自然語言文本描述,用於圖像、圖表、圖片和插圖。
-
使用時機:
- 適用於協助工具需求 (替代文字產生)。
- 用來理解圖表和流程圖。
- 用來從資訊圖表中提取洞見。
- 支援來自: 文件式分析器。
enableFigureAnalysis
- 預設: false
- 說明: 進行更深入的圖表分析,包括圖表資料擷取及圖表組件識別。
-
使用時機:
- 用來從文件中嵌入的圖表中提取結構化資料。
- 用來理解複雜的圖表。
- 詳細的人物分類。
- 支援來自: 文件式分析器。
註解選項
annotationFormat
-
預設:
"markdown" -
支持的價值觀:
"markdown" - 說明: 指定回傳註解的格式。
- 支援來自: 文件式分析器。
場域擷取選項
estimateFieldSourceAndConfidence
- 預設值: false(依分析分析器而異)
- 說明: 回傳每個擷取欄位值的來源位置(頁碼、邊界框)及信心分數。
-
使用時機:
- 用於驗證與品質保證工作流程。
- 為了了解提取的準確性。
- 用來偵錯資料擷取問題。
- 用於在使用者介面中標示原始文字。
-
支持單位: 文件分析器,適用於所有文件欄位類型(
extract、classify及generate方法)。
音訊與影像選項
locales
-
預設:
[](空陣列) - 說明: 針對特定語言的處理所用的語系與語言代碼列表,主要用於轉錄。
-
支援的值: BCP-47 語言代碼(例如,
["en-US", "es-ES", "fr-FR", "de-DE"]) -
使用時機:
- 用於多語言音頻轉錄。
- 為了更精確地指定預期語言。
- 用於處理特定區域變體的內容。
-
支援單位:
prebuilt-audio,prebuilt-video,prebuilt-callCenter
註
有關完整支援語言與地區的清單,請參見 語言與地區支援。
分類選項
contentCategories
- 預設: 未設定
-
說明: 定義類別或內容類型,用於自動分類並路由至專門處理程序。 搭配
enableSegment set to false使用時,目前僅支援用於文件。 它會分類整個檔案。 當與 一起使用enableSegment=true時,檔案會根據這些類別拆分成區塊,每個區段都會被分類,並可選擇性地由類別專屬的分析器處理。 總是從可用類別列表中選擇一個選項。 -
結構: 每個類別包含:
-
description- (必要)類別或文件類型的詳細描述。 此描述作為提示,引導 AI 模型決定區段邊界與分類。 包含區分特徵,幫助辨識一個類別的結束與另一個的開始。 -
analyzerId- (可選)參考其他分析器以用於此類別。 參考分析器是連結式的,而非複製式,確保行為一致。 若省略,則僅進行分類,無需額外處理(僅分割情境)。
-
-
模型使用: 父分析器
models屬性中指定的模型僅用於分割與分類。 每個子分析器使用自己的模型配置來擷取。 -
enableSegment的行為:-
enableSegment: true: 內容依類別描述分為多個區段。 每個區段都被歸類為定義的類別之一。 回傳原始內容物件中的區段元資料,並針對指定analyzerId為 的區段回傳更多內容物件。 -
enableSegment: false: 整個內容被整體分類為同一類別,並依此路由。 對於不需拆分的階層分類非常有用。
-
- 類別配對: 若未定義「其他」或「預設」類別,內容將被強制歸類至列出的其中一個類別。 加入「其他」類別,以優雅地處理未能匹配的內容。
- 支援單位: 文件分析工具與影片分析工具。 對於影片,你只能定義一個內容類別。
enableSegment
- 預設: false
-
說明: 啟用內容分割,根據 中
contentCategories指定的類別將檔案拆分成區塊。 每個區段隨後被歸類為定義的類別之一,進行選擇性處理。 -
分群行為: 該服務透過分析內容與類別描述,將內容劃分為邏輯單元。 段界的確定方式如下:
- 文件: 分類描述結合內容結構(頁面、章節、格式變更)。
- 影片: 類別描述結合視覺線索(鏡頭轉換、場景轉換、時間界限)。 目前只支援一個 contentCategory。
-
使用時機:
- 處理混合內容批次,不同零件需要不同處理(例如包含發票與收據的 PDF)。
- 將長文件拆分成分類區塊以便選擇性分析。
- 依照內容類型分析影片(例如,將廣告與主要內容分開)。
-
產出結構:
- 回傳
segments內容物件中的陣列,包含每個區段(ID、邊界、類別)的中繼資料。 - 每個段都包含其從
contentCategories獲得的分類類別。 - 對於指定類別
analyzerId的區段,會回傳更多內容物件。
- 回傳
-
階層式分割: 若類別分析器同時具備
enableSegment: true,則可遞迴拆分,實現多層次內容拆解。 - 效能影響: 對於大型檔案,尤其是多段檔案,會增加處理時間。
- 支援單位: 文件分析工具與影片分析工具。
segmentPerPage
- 預設: false
- 說明: 啟用分段時,請強制每頁一個分段,而非使用邏輯內容邊界。 取代了對單獨「每頁」分割模式的需求。
-
使用時機:
- 逐頁處理工作流程。
- 每一頁都應被視為獨立的單位。
- 對個別頁面進行平行處理。
- 多頁文件中頁面層面的欄位擷取。
- 混合文件批次,每頁是不同類型的文件。
- 支援來自: 文件式分析器。
omitContent
- 預設: false
-
說明: 當
true時,會將原始內容物件排除在回應之外。 當使用contentCategories時,回應僅包含結構化欄位資料或子分析器的內容物件。 -
使用時機:
- 當您只需要擷取的欄位值時。
- 在具有
contentCategories的組合分析器中,僅傳回已分類結果。 - 對於階層式分類鏈,僅回傳葉片分析結果。
-
範例 - 選擇性分析:
{ "config": { "enableSegment": true, "contentCategories": { "invoice": { "analyzerId": "prebuilt-invoice" }, "other": { } // Categorize but don't process }, "omitContent": true // Only return invoice analysis results } } - 支援來自: 文件分析器。
場域配置
這個 fieldSchema 屬性定義了分析器從內容中擷取的結構化資料。 它規定了欄位、類型,以及如何提取它們。
設計意圖:結構化萃取
欄位結構將非結構化內容轉換成結構化且可查詢的資料。 該結構同時具有以下兩種作用:
- 一份定義擷取哪些資料的合約
- 關於 AI 模型的 指南 ,教你該注意什麼以及如何解讀它
欄位架構結構
{
"fieldSchema": {
"name": "InvoiceAnalysis",
"fields": {
"VendorName": {
"type": "string",
"description": "Name of the vendor or supplier",
"method": "extract"
},
"InvoiceTotal": {
"type": "number",
"description": "Total amount due on the invoice",
"method": "extract"
},
"LineItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Description": { "type": "string" },
"Quantity": { "type": "number" },
"UnitPrice": { "type": "number" },
"Amount": { "type": "number" }
}
},
"description": "List of items on the invoice, typically in a table format",
"method": "generate"
}
}
}
}
欄位結構性質
name
- 說明: 結構名稱,通常描述內容類型或使用情境
-
範例:
"InvoiceAnalysis","ReceiptExtraction","ContractFields"
fields
-
說明: 物件定義每個要擷取的欄位,欄位名稱作為鍵。 空物件
{}表示未擷取結構化欄位(例如僅執行版面分析器)。 -
階層式支援: 支援巢狀欄位,使用
object和array類型來表示複雜資料結構。 - 最佳實務: 避免深度巢狀(超過兩到三層),因為這會降低效能和擷取準確度
欄位定義屬性
物件中的 fields 每個欄位具有以下性質:
type
-
支援值:
"string","number","boolean","date""object", ,"array" - 說明: 欄位值的資料型態。 選擇最適合你資料語意的類型,以達到最佳萃取效果。
- 自動正規化: 對於支援的類型欄位,Content Understanding 會自動將回傳值標準化為標準格式(例如一致日期格式)。
description
- 說明: 清楚說明該領域包含什麼內容及在哪裡可以找到。 AI 模型會將此描述視為一個迷你提示,引導田間採集,因此具體性與清晰度直接提升萃取準確度。
關於撰寫有效田野描述的資訊,請參閱 田間萃取的最佳實務。
method
-
支援值:
"generate","extract","classify" - 說明: 此領域應採用的萃取方法。 當你沒有指定方法時,系統會根據欄位類型和描述自動決定最佳方法。
-
方法類型:
-
"generate"- 數值可透過 AI 模型自由產生,基於內容(最適合需要解釋的複雜或變數領域) -
"extract"- 值依內容呈現而擷取(最適合從特定位置擷取文字)。 此欄位需estimateSourceAndConfidence將 extract 設定為true。 -
"classify"- 數值依照預先定義的類別集合分類(最佳方式是enum使用固定的可能值集合)
-
estimateSourceAndConfidence
- 預設: false
-
說明: 回傳此欄位值的來源位置(頁碼、邊界框)及信心分數。 對於
method= extract 的欄位,必須為 true。 此特性覆蓋分析儀層級estimateFieldSourceAndConfidence的特性。 -
使用時機:
- 用於驗證與品質保證工作流程。
- 為了了解提取的準確性。
- 用來偵錯資料擷取問題。
- 用於在使用者介面中標示原始文字。
-
支持單位: 文件分析器,適用於所有文件欄位類型(
extract、classify及generate方法)。
items (針對陣列類型)
- 說明: 定義陣列中項目的結構
-
屬性:
-
type- 陣列項目類型("string", ,"number""object") -
properties- 對於物件項目,定義巢狀欄位結構
-
properties (針對物件類型)
- 說明: 定義物件內巢狀欄位的結構
-
範例:
{ "Address": { "type": "object", "properties": { "Street": { "type": "string" }, "City": { "type": "string" }, "State": { "type": "string" }, "ZipCode": { "type": "string" } }, "description": "Complete mailing address" } }
完整分析儀範例
以下是一個完整的客製化發票分析器配置範例,展示了本參考文獻中討論的關鍵概念:
{
"analyzerId": "myCustomInvoiceAnalyzer",
"name": "Custom Invoice Analyzer",
"description": "Extracts vendor information, line items, and totals from commercial invoices",
"baseAnalyzerId": "prebuilt-document",
"config": {
"returnDetails": true,
"enableOcr": true,
"enableLayout": true,
"tableFormat": "html",
"estimateFieldSourceAndConfidence": true,
"omitContent": false
},
"fieldSchema": {
"name": "InvoiceFields",
"fields": {
"VendorName": {
"type": "string",
"description": "Name of the vendor or supplier, typically found in the header section",
"method": "extract"
},
"VendorAddress": {
"type": "object",
"properties": {
"Street": { "type": "string" },
"City": { "type": "string" },
"State": { "type": "string" },
"ZipCode": { "type": "string" }
},
"description": "Complete vendor mailing address"
},
"InvoiceNumber": {
"type": "string",
"description": "Unique invoice number, often labeled as 'Invoice #' or 'Invoice No.'",
"method": "extract"
},
"InvoiceDate": {
"type": "date",
"description": "Date the invoice was issued, in format MM/DD/YYYY",
"method": "extract"
},
"DueDate": {
"type": "date",
"description": "Payment due date",
"method": "extract"
},
"LineItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Description": {
"type": "string",
"description": "Item or service description"
},
"Quantity": {
"type": "number",
"description": "Quantity ordered"
},
"UnitPrice": {
"type": "number",
"description": "Price per unit"
},
"Amount": {
"type": "number",
"description": "Line total (Quantity × UnitPrice)"
}
}
},
"description": "List of items or services on the invoice, typically in a table format",
"method": "generate"
},
"Subtotal": {
"type": "number",
"description": "Sum of all line items before tax",
"method": "extract"
},
"Tax": {
"type": "number",
"description": "Tax amount"
},
"Total": {
"type": "number",
"description": "Total amount due (Subtotal + Tax)"
},
"PaymentTerms": {
"type": "string",
"description": "Payment terms and conditions (for example, 'Net 30', 'Due upon receipt')",
"method": "generate"
}
}
},
"supportedModels": {
"completion": ["gpt-5.2"],
"embedding": ["text-embedding-3-large", "text-embedding-3-small"]
},
"models": {
"completion": "gpt-5.2",
"embedding": "text-embedding-3-large"
}
}
建立自訂分析儀
若要根據本文件中描述的配置結構建立自訂分析器,請使用 Content Understanding REST API 提交您的分析器定義。
API 端點
請使用以下 curl 指令,從 JSON 檔案提交分析器設定,建立自訂分析器:
curl -X PUT "https://{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01" \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: {key}" \
-d @analyzer-definition.json
替換以下佔位符:
-
{endpoint}- 您的內容瞭解資源端點 -
{analyzerId}- 分析器的唯一識別碼 -
{key}- Your Content Understanding 訂閱金鑰 -
analyzer-definition.json- 分析儀設定檔的路徑
請求機構
分析器設定檔應該是一個包含本參考資料中屬性的 JSON 物件。 完整範例請參考 「建立自訂分析器」教學。
回應
API 會回傳一個帶有 201 Created 標頭的 Operation-Location 回應,可用來追蹤分析器創建操作的狀態。
下一步
如需完整攻略及不同內容類型(文件、圖片、音訊、影片)範例,請參閱 「建立自訂分析器」。
依內容類型配置
不同內容類型支援不同的設定選項。 這裡有個快速參考:
文件分析器
基礎分析儀:prebuilt-document
支援的配置選項:
- ✅
returnDetails - ✅
omitContent - ✅
enableOcr - ✅
enableLayout - ✅
enableFormula - ✅
enableBarcode - ✅
tableFormat - ✅
chartFormat - ✅
enableFigureDescription - ✅
enableFigureAnalysis - ✅
enableAnnotations - ✅
annotationFormat - ✅
enableSegment - ✅
segmentPerPage -
✅
estimateFieldSourceAndConfidence(結構化分析器) -
✅
contentCategories(多變體分析儀)
音訊分析儀
基礎分析儀:prebuilt-audio
支援的配置選項:
- ✅
returnDetails - ✅
locales
影像分析儀
基礎分析儀:prebuilt-video
支援的配置選項:
- ✅
returnDetails - ✅
locales - ✅
contentCategories - ✅
enableSegment - ✅
omitContent
影像分析儀
基礎分析儀:prebuilt-image
支援的配置選項:
- ✅
returnDetails
內容篩選條件會產生分析回覆
當 Foundry 模型部署處理內容時,相關的 Guardrails 實例會評估輸入提示與模型完成,以判斷是否有潛在有害內容。 如果任何類別被標記或封鎖,內容理解會在分析回應中加入 content_filters 陣列。
陣列中的 content_filters 每個物件具有以下結構:
| 財產 | 類型 | 描述 |
|---|---|---|
blocked |
布林值 |
true 如果內容被 Guardrails 實例阻擋; false 如果內容有註解但仍被允許通過。 |
source_type |
字串 | 旗標是來自模型輸入("prompt")還是模型輸出("completion")。 |
content_filter_raw |
陣列 | 來自 Guardrails 實例的原始過濾器輸出。 可能已經空了。 |
content_filter_results |
物件 | 各類別嚴重程度評分。 每個範疇包含 filtered (布林值) 和 severity ("safe", "low", "medium", 或 "high")。 |
以下類別可能出現在 content_filter_results:
| 分類 | 描述 |
|---|---|
hate |
基於受保護的特徵進行攻擊或使用貶義語言的內容。 |
sexual |
露骨或暗示性內容。 |
violence |
描繪或美化暴力行為的內容。 |
self_harm |
推廣或描述自我傷害的內容。 |
範例 content_filters 輸出
以下範例顯示一則content_filters條目,其中因高嚴重性色情內容而完全遭到封鎖:
"content_filters": [
{
"blocked": true,
"source_type": "completion",
"content_filter_raw": [],
"content_filter_results": {
"hate": {
"filtered": false,
"severity": "safe"
},
"sexual": {
"filtered": true,
"severity": "high"
},
"violence": {
"filtered": false,
"severity": "safe"
}
}
}
]
當 blocked 是 true 時,分析操作會回傳錯誤回應,且不包含欄位擷取結果。 當blocked是false且類別顯示非零嚴重性時,內容會加上註解並通過—您可以檢查content_filter_results以決定如何在自己的工作流程中處理輸出。
內容過濾器行為的變更
內容過濾閾值與區塊/註解行為會在綁定於 Foundry 模型部署的 Guardrails 實例中設定。 改變行為的方法:
- 在您的 Azure AI Foundry 專案中,請導覽到分析器所使用的模型部署。
- 選擇相關的護欄設定。
- 根據需要調整閾值或將分類從 區塊 切換到 註解 。
如果你需要以預設不允許的方式減少或停用某個篩選類別,你可以申請修改內容篩選。 欲了解更多資訊,請參閱 內容過濾與護欄。