你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

什么是内容理解分析器？

Foundry Tools 中的 Azure 内容理解 分析器 是一个可配置的处理单元，用于定义应如何分析内容以及应提取哪些信息。将分析器视为用来指导服务的食谱：

要处理的内容类型（文档、图像、音频或视频）
要提取哪些元素（文本、布局、表、字段、脚本）
如何构建输出（Markdown、JSON 字段、段）
要用于处理的 AI 模型

分析器是内容理解的核心构建基块。它们将内容提取、AI 驱动的分析和结构化数据输出合并为单个可重用的配置。可以将预生成分析器用于常见方案，也可以创建自定义分析器，以满足你的特定需求。

分析器类型

内容理解提供多种类型的分析器：

基本分析器：为每种内容类型（prebuilt-document、、、prebuilt-audioprebuilt-video、prebuilt-image）提供核心处理功能的基础分析器。这些分析器通常用于自定义分析器的构建基块。
RAG 分析器：优化用于检索增强的生成场景，从语义理解的角度抽取内容以支持搜索和 AI 应用（例如 prebuilt-documentSearch，prebuilt-videoSearch）。
特定于域的分析器：预配置特定文档类型和行业，如发票、收据、ID 文档和合同（例如prebuilt-invoice，，，prebuilt-receiptprebuilt-idDocument）。
自定义分析器：使用自定义字段架构和配置扩展基本分析器来创建的分析器以满足特定要求。

有关详细信息和可用领域专用分析器的完整列表，请参阅预构建分析器。

分析器配置结构

分析器配置是使用包含多个顶级属性的 JSON 对象定义的。可以配置以下组件：

分析器属性 - 核心标识和元数据
- analyzerId - 唯一标识符
- name - 显示名称
- description - 用途说明
- baseAnalyzerId - 父分析器参考
模型配置 - AI 模型设置
- models - 默认模型
处理配置 - 内容处理选项
- 配置 - 行为设置
字段架构 - 结构化数据提取
- fieldSchema - 字段定义

下面是一个精简示例，其中显示了分析器配置的整体结构：

{
  "analyzerId": "my-custom-invoice-analyzer",
  "description": "Extracts vendor information, line items, and totals from commercial invoices",
  "baseAnalyzerId": "prebuilt-document",
  "config": {
    ...
    "enableOcr": true
    ...
  },
  "fieldSchema": {...}
    }
  },
  "models": {
    "completion": "gpt-4.1",
    "embedding": "text-embedding-3-large"
  }
}

分析器属性

这些属性唯一标识并描述分析器：

`analyzerId`

描述： 分析器的唯一标识符。此标识符是在 API 调用中引用分析器的方式。
示例："prebuilt-invoice"， "my-custom-analyzer"
指引：
- 使用指示分析器用途的描述性名称
- 对于自定义分析器，请选择与预生成分析器名称不冲突的名称
- 将小写与连字符一起使用以保持一致性

`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中的一个匹配。内容理解支持的完整模型列表位于支持的模型中。
属性：
- completion - 完成任务的模型名称（字段提取、分段、图分析等）
- embedding - 嵌入任务的模型名称（使用知识库）
重要： 这些是 Foundry 目录中的模型名称，而不是部署名称。在运行时，服务将这些模型名称映射到在资源级别配置的实际模型部署。

Example:

{
  "completion": "gpt-4o",
  "embedding": "text-embedding-3-large"
}

请参阅将内容理解资源与 Foundry 模型连接，以获取有关如何配置连接模型的更多详细信息。

处理配置

该 config 对象包含控制如何分析内容的所有处理选项。这些选项根据功能划分为类别：

配置对象属性

常规选项

`returnDetails`

默认值： false（因分析器而异）
描述： 控制是否在响应中包含详细信息（置信度分数、边界框、文本跨度、元数据）
何时使用：
- 在调试提取问题时，将其设置为true。
- 需要提取数据的位置信息时
- 验证需要置信度分数时
- 用于质量保证和测试
对响应的影响： 使用更多元数据显著增加响应大小

文档内容提取选项

`enableOcr`

默认值： true
描述： 允许光学字符识别从图像和扫描的文档中提取文本
何时使用：
- 启用针对扫描文档、照片和图像型 PDF 的功能
- 禁用原生数字 PDF 以提高性能
支持： 文档分析器

`enableLayout`

默认值： true
描述： 提取布局信息，包括段落、行、字词、阅读顺序和结构元素
何时使用：
- 了解文档结构和层次结构所必需的
- 准确段落和章节提取需要
- 如果只需要原始文本提取，则禁用
支持： 基于文档的分析器

`enableFormula`

默认值： true
描述： 检测并提取 LaTeX 格式的数学公式和公式
何时使用：
- 启用科学文章、研究资料、技术文档
- 禁用处理常规业务文档的功能以提高性能
支持： 基于文档的分析器

`enableBarcode`

默认值： true
描述： 检测和提取条形码和 QR 码，并返回解码的值
何时使用：
- 启用用于库存文档、发货标签、产品文档
- 当条形码不存在以提高性能时禁用
支持： 基于文档的分析器
支持的条形码类型： QR Code、PDF417、QR-A、QR-E、Code 39、Code 128、EAN-8、EAN-13、DataBar、Code 93、Codabar、ITF、Micro QR Code、Aztec、Data Matrix、MaxiCode

表和图表选项

`tableFormat`

默认："html"
支持的值："html"， "markdown"
描述： 指定提取表的输出格式
何时使用：
- 使用 "html" 进行 Web 渲染或需要保留复杂表结构时使用。
- 在文档中或基于文本的处理中使用 "markdown" 来处理简单表格
支持： 基于文档的分析器

`chartFormat`

默认："chartjs"
支持的值："chartjs"
描述： 指定提取的图表和图形数据的格式（与 Chart.js 库兼容）
何时使用：
- 从条形图、折线图和饼图中提取数据时
- 将视觉图表转换为结构化数据以重新呈现
支持： 基于文档的分析器

图和图像分析选项

`enableFigureDescription`

默认值： false
描述： 为图形、图表、图像和插图生成自然语言文本说明
何时使用：
- 对于辅助功能要求（替代文本生成）
- 了解关系图和流程图
- 从信息图中提取见解
支持： 基于文档的分析器

`enableFigureAnalysis`

默认值： false
描述： 对图形执行更深入的分析，包括图表数据提取和关系图组件标识
何时使用：
- 从文档中嵌入的图表中提取结构化数据
- 了解复杂关系图
- 详细图像分类
支持： 基于文档的分析器

批注选项

`annotationFormat`

默认："markdown"
支持的值："markdown"
描述： 指定返回批注的格式
支持： 基于文档的分析器

字段提取选项

`estimateFieldSourceAndConfidence`

默认值： false（因分析器而异）
描述： 返回每个提取字段值的源位置（页码、边界框）和置信度分数。
何时使用：
- 验证和质量保证工作流
- 了解提取准确性
- 调试提取问题
- 突出显示用户界面中的源文本
支持： 文档分析器（发票、收据、ID 文档、税务表单）

音频和视频选项

`locales`

默认：[] （空数组）
描述： 针对特定语言处理的语言环境/语言代码列表（主要用于转录）
支持的值： BCP-47 语言代码（例如 ["en-US", "es-ES", "fr-FR", "de-DE"]）
何时使用：
- 多语言音频听录
- 指定预期语言以提高准确性
- 处理特定区域变体中的内容
支持者：prebuilt-audio、、 prebuilt-videoprebuilt-callCenter

注释

有关支持的语言和区域设置的完整列表，请参阅语言和区域支持。

`disableFaceBlurring`

默认值： false
描述： 控制是否应模糊图像和视频中的人脸，以保护隐私
何时使用：
- 在需要人脸可见性进行分析时，设置为 true
- 如需在共享内容中对个人信息进行去标识化，请将其设置为 false
支持：prebuilt-image， prebuilt-video

重要

内容理解中的人脸功能功能是一项受限的访问服务，需要注册才能访问。内容理解中的人脸分组和识别功能根据资格和使用条件受到限制。人脸服务仅适用于 Microsoft 托管客户和合作伙伴。使用人脸识别引入表单来申请访问。有关详细信息，请参阅负责任的 AI 投资和面部识别保护措施。

分类选项

`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
描述： 启用分段后，强制每个页面一个段，而不是使用逻辑内容边界。消除了对单独“perPage”拆分模式的需求。
何时使用：
- 逐页处理工作流
- 应将每页视为独立单元
- 单个页面的并行处理
- 多页文档中的页面级字段提取
- 混合文档批处理，其中每个页面都是不同的文档类型
支持： 基于文档的分析器

`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": "generative"
      }
    }
  }
}

字段架构属性

`name`

描述： 架构的名称，通常描述内容类型或用例
示例："InvoiceAnalysis"、、 "ReceiptExtraction""ContractFields"

`fields`

描述： 定义要提取的每个字段的对象，字段名称为键。空对象 {} 表示未提取结构化字段（例如，仅进行布局分析的分析器）。
分层支持： 支持通过 object 嵌套字段和 array 类型表示复杂数据结构
最佳做法： 避免深度嵌套（超过 2-3 级别），因为它可以减少性能和提取准确性

字段定义属性

对象中的每个 fields 字段具有以下属性：

`type`

支持的值："string"、、、"number""boolean"、"date"、 "object""array"
描述： 字段值的数据类型。选择与数据语义最匹配的类型，以便进行最佳提取。

`description`

描述： 明确说明字段包含的内容和查找位置。 AI 模型将此说明作为引导字段提取的迷你提示进行处理，因此具体性和清晰度直接提高提取准确性。

有关编写有效字段说明的信息，请参阅字段提取的最佳做法。

`method`

支持的值："generate"、 "extract""classify"
描述： 要用于此字段的提取方法。如果未指定，系统会根据字段类型和说明自动确定最佳方法。
方法类型：
- "generate" - 基于内容使用 AI 模型自由生成值（最适合需要解释的复杂或可变字段）
- "extract" - 按照内容中呈现的方式提取值（最适合从特定位置直接提取文本）。提取要求将 enableSourceGroundingAndConfidence 设置为 true 以用于此字段。
- "classify" - 值根据预定义的类别集进行分类（最好在一组固定的可能值中使用 enum 时）

`estimateSourceAndConfidence`

默认值： false
描述： 返回此字段值的源位置（页码、边界框）和置信度分数。对于 method = extract 的字段，必须为 true。此属性将替代分析器级别 estimateFieldSourceAndConfidence 属性。
何时使用：
- 验证和质量保证工作流
- 了解提取准确性
- 调试提取问题
- 突出显示用户界面中的源文本
支持： 文档分析器（发票、收据、ID 文档、税务表单）

`items` （对于数组类型）

描述： 定义数组中项的结构
属性：
- type - 数组项的类型（"string"、 "number"、 "object"）
- properties - 对于对象项，定义嵌套字段结构

`properties` （对于对象类型）

描述： 定义对象中嵌套字段的结构

Example:

{
  "Address": {
    "type": "object",
    "properties": {
      "Street": { "type": "string" },
      "City": { "type": "string" },
      "State": { "type": "string" },
      "ZipCode": { "type": "string" }
    },
    "description": "Complete mailing address"
  }
}

完整分析器示例

下面是自定义发票分析器配置的综合示例，该配置演示了本参考中讨论的关键概念：

{
  "analyzerId": "my-custom-invoice-analyzer",
  "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": "generative"
      },
      "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 (e.g., 'Net 30', 'Due upon receipt')",
        "method": "generative"
      }
    }
  },
  "supportedModels": {
    "completion": ["gpt-4o", "gpt-4o-mini", "gpt-4.1"],
    "embedding": ["text-embedding-3-large", "text-embedding-3-small"]
  },
  "models": {
    "completion": "gpt-4.1",
    "embedding": "text-embedding-3-large"
  }
}

创建自定义分析器

若要根据本文档中所述的配置结构创建自定义分析器，请使用内容理解 REST API 提交分析器定义。

API 终结点

使用以下 curl 命令，从 JSON 文件提交分析器配置以创建自定义分析器：

curl -X PUT "https://{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01-preview" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -d @analyzer-definition.json

替换以下占位符：

{endpoint} - 你的内容理解资源终结点
{analyzerId} - 分析器的唯一标识符
{key} - 内容理解订阅密钥
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
✅ disableFaceBlurring

图像分析器

基本分析器：prebuilt-image

支持的配置选项：

✅ returnDetails
✅ disableFaceBlurring

了解内容理解中提供的预生成分析器
浏览分析器模板以快速入门
按照自定义分析器教程创建自己的分析器
了解最佳做法，以实现最佳提取效果
查看文档元素和视频元素，了解有关提取内容的详细信息
在 Foundry 中创建和测试分析器入门

反馈

此页面是否有帮助？

Last updated on 2025-11-18

通过

什么是内容理解分析器？

分析器类型

分析器配置结构

分析器属性

analyzerId

name

description

baseAnalyzerId

模型配置

models

处理配置

配置对象属性

常规选项

returnDetails

文档内容提取选项

enableOcr

enableLayout

enableFormula

enableBarcode

表和图表选项

tableFormat

chartFormat

图和图像分析选项

enableFigureDescription

enableFigureAnalysis

批注选项

annotationFormat

字段提取选项

estimateFieldSourceAndConfidence

音频和视频选项

locales

disableFaceBlurring

分类选项

contentCategories

enableSegment

segmentPerPage

omitContent

字段配置

设计意向：结构化提取

字段模式结构

字段架构属性

name

fields

字段定义属性

type

description

method

estimateSourceAndConfidence

items （对于数组类型）

properties （对于对象类型）

完整分析器示例

创建自定义分析器

API 终结点

请求主体

响应

后续步骤

按内容类型配置

文档分析器

音频分析器

视频分析器

图像分析器

相关内容

反馈

其他资源

`analyzerId`

`name`

`description`

`baseAnalyzerId`

`models`

`returnDetails`

`enableOcr`

`enableLayout`

`enableFormula`

`enableBarcode`

`tableFormat`

`chartFormat`

`enableFigureDescription`

`enableFigureAnalysis`

`annotationFormat`

`estimateFieldSourceAndConfidence`

`locales`

`disableFaceBlurring`

`contentCategories`

`enableSegment`

`segmentPerPage`

`omitContent`

`name`

`fields`

`type`

`description`

`method`

`estimateSourceAndConfidence`

`items` （对于数组类型）

`properties` （对于对象类型）