支援的模型和結構定義

設定物件擴充功能時，您可以選擇要使用哪些機器學習模型分析儲存的物件。每個模型都會評估符合資格的圖片或 PDF 文件，並直接將結構化中繼資料附加至 Cloud Storage 物件。

本頁面說明各個支援的模型、資格規定和輸出結構定義，協助您在 BigQuery 中或透過 API 剖析及查詢擴充中繼資料。

模型與物件擴充之間的關係

如要啟用模型，請建立特徵設定 (FeatureConfig)，指定要掃描的 bucket 和要執行的模型。在非同步處理期間，Cloud Storage 會使用您選擇的模型評估符合資格的物件，並生成稱為物件資料充實功能的結構化 JSON 中繼資料。

每個模型都會產生專屬的 JSON 酬載，Cloud Storage 會將該酬載直接附加至物件，做為 contexts.custom 屬性下的 Google 代管物件內容。每個酬載都由開頭為 google:annotation: 的專屬情境金鑰識別。

視工作流程而定，您可以透過下列兩種方式使用這項中繼資料：

臉部偵測

使用 face-detector 模型偵測儲存圖片中的人臉。模型會偵測整個頭部和個別臉部的定界多邊形，並找出 36 個臉部特徵點，例如眼睛、鼻子和嘴巴。這項技術也會計算頭部方向角度 (例如側傾、平移和傾斜)，並評估情緒表現的可能性。

模型詳細資料

  • Model name (模型名稱)：face-detector
  • 內容鍵：google:annotation:face-detector-v1
  • 符合資格的物件：20 MiB 以下的圖片物件，且支援的 Content-Type 為 BMP、GIF、ICO、JPEG、PNG、TIFF 或 WEBP。

輸出內容的結構定義

模型會輸出 JSON 物件，其中包含 modelName、modelVersion 和 faceAnnotationGroup，以及 faceAnnotations 陣列。如果模型執行失敗，JSON 物件會包含 error 物件，而非 faceAnnotationGroup。

欄位 類型 範圍 說明
modelName string 不適用 生成這項擴充資料的機器學習模型名稱。
modelVersion string 不適用 生成這項擴充功能的機器學習模型版本。
faceAnnotationGroup object 不適用 臉部偵測擴充功能的頂層容器物件。模型執行成功時會顯示。
faceAnnotationGroup.faceAnnotations[] array 不適用 圖片中偵測到的臉部清單。
faceAnnotationGroup.faceAnnotations[].boundingPoly object 不適用 BoundingPoly 包含整個頭部和臉部，並縮放至原始圖片尺寸。
faceAnnotationGroup.faceAnnotations[].faceDetectionBoundingPoly object 不適用 臉部偵測的 BoundingPoly。比 boundingPoly 更緊密，只包含皮膚和可見的臉部特徵。
faceAnnotationGroup.faceAnnotations[].landmarks[] array 不適用 偵測到的 FaceLandmark 物件清單，代表特定臉部特徵。
faceAnnotationGroup.faceAnnotations[].rollAngle number -180 至 180 臉部順時針或逆時針旋轉的角度。
faceAnnotationGroup.faceAnnotations[].panAngle number -180 至 180 臉部指向左側或右側的水平角度 (以度為單位)。
faceAnnotationGroup.faceAnnotations[].tiltAngle number -180 至 180 臉部朝上或朝下的垂直俯仰角，以度為單位。
faceAnnotationGroup.faceAnnotations[].detectionConfidence number 0 至 1 (0% 至 100%) 整體臉部偵測的可信度分數。
faceAnnotationGroup.faceAnnotations[].landmarkingConfidence number 0 至 1 (0% 至 100%) 臉部特徵標記定位的可信度分數。
faceAnnotationGroup.faceAnnotations[].joyProbability number 0 至 1 (0% 至 100%) 臉部表情為喜悅的可能性。
faceAnnotationGroup.faceAnnotations[].sorrowProbability number 0 至 1 (0% 至 100%) 臉部表情呈現悲傷情緒的機率。
faceAnnotationGroup.faceAnnotations[].angerProbability number 0 至 1 (0% 至 100%) 臉部表情呈現憤怒的機率。
faceAnnotationGroup.faceAnnotations[].surpriseProbability number 0 至 1 (0% 至 100%) 臉部表情驚訝的可能性。
faceAnnotationGroup.faceAnnotations[].underExposedProbability number 0 至 1 (0% 至 100%) 圖片中的臉孔曝光不足的可能性。
faceAnnotationGroup.faceAnnotations[].blurredProbability number 0 至 1 (0% 至 100%) 圖片中的臉孔模糊的可能性。
faceAnnotationGroup.faceAnnotations[].headwearProbability number 0 至 1 (0% 至 100%) 人物戴著頭飾 (例如帽子) 的可能性。
error object 不適用 包含 code 和 message 的 google.rpc.Status 物件。只有在模型執行失敗時才會填入資料。

BoundingPoly

BoundingPoly 物件代表封閉式多邊形，內含偵測到的圖片特徵。

欄位 類型 範圍 說明
vertices[] array 不適用 使用絕對像素 Vertex 物件的多邊形邊界座標。
normalizedVertices[] array 不適用 使用相對 NormalizedVertex 物件的邊界多邊形座標，從 0 縮放至 1。

Vertex

Vertex 物件代表縮放至原始圖片尺寸的 2D 座標點。

欄位 類型 範圍 說明
x integer 0 以上版本 水平 X 座標，以像素為單位，從左側邊緣開始計算。
y integer 0 以上 垂直 Y 座標，以頂端邊緣為準，單位為像素。

正規化 Vertex

NormalizedVertex 物件代表 2D 座標點，以相對於原始圖片尺寸的比率表示。

欄位 類型 範圍 說明
x number 0 至 1 相對於圖片寬度的水平 X 座標，其中 0.0 是左側邊緣，1.0 是右側邊緣。
y number 0 至 1 相對於圖片高度的垂直 Y 座標，其中 0.0 是頂端邊緣，1.0 是底部邊緣。

FaceLandmark

FaceLandmark 物件代表在臉部偵測到的特定臉部特徵。

欄位 類型 範圍 說明
type enum 請參閱「地標類型」 偵測到的特定臉部特徵。
position object 不適用 地標的 3D Position。

地標類型

模型可辨識 36 個特定臉部特徵：

  • TYPE_UNSPECIFIED
  • LEFT_EYE
  • RIGHT_EYE
  • LEFT_OF_LEFT_EYEBROW
  • RIGHT_OF_LEFT_EYEBROW
  • LEFT_OF_RIGHT_EYEBROW
  • RIGHT_OF_RIGHT_EYEBROW
  • MIDPOINT_BETWEEN_EYES
  • NOSE_TIP
  • UPPER_LIP
  • LOWER_LIP
  • MOUTH_LEFT
  • MOUTH_RIGHT
  • MOUTH_CENTER
  • NOSE_BOTTOM_RIGHT
  • NOSE_BOTTOM_LEFT
  • NOSE_BOTTOM_CENTER
  • LEFT_EYE_TOP_BOUNDARY
  • LEFT_EYE_RIGHT_CORNER
  • LEFT_EYE_BOTTOM_BOUNDARY
  • LEFT_EYE_LEFT_CORNER
  • RIGHT_EYE_TOP_BOUNDARY
  • RIGHT_EYE_RIGHT_CORNER
  • RIGHT_EYE_BOTTOM_BOUNDARY
  • RIGHT_EYE_LEFT_CORNER
  • LEFT_EYEBROW_UPPER_MIDPOINT
  • RIGHT_EYEBROW_UPPER_MIDPOINT
  • LEFT_EAR_TRAGION
  • RIGHT_EAR_TRAGION
  • LEFT_EYE_PUPIL
  • RIGHT_EYE_PUPIL
  • FOREHEAD_GLABELLA
  • CHIN_GNATHION
  • CHIN_LEFT_GONION
  • CHIN_RIGHT_GONION
  • LEFT_CHEEK_CENTER
  • RIGHT_CHEEK_CENTER

位置

Position 物件代表臉部特徵的 3D 座標。

欄位 類型 範圍 說明
x number 不適用 水平 X 座標。
y number 不適用 垂直 Y 座標。
z number 不適用 相對於臉部平面的深度座標，值越小表示越靠近相機。

輸出內容範例

{
  "modelName": "face-detector",
  "modelVersion": "v1",
  "faceAnnotationGroup": {
    "faceAnnotations": [
      {
        "boundingPoly": {
          "vertices": [
            { "x": 1079, "y": 148 },
            { "x": 2152, "y": 148 },
            { "x": 2152, "y": 1396 },
            { "x": 1079, "y": 1396 }
          ],
          "normalizedVertices": [
            { "x": 0.35, "y": 0.12 },
            { "x": 0.70, "y": 0.12 },
            { "x": 0.70, "y": 0.95 },
            { "x": 0.35, "y": 0.95 }
          ]
        },
        "faceDetectionBoundingPoly": {
          "vertices": [
            { "x": 1190, "y": 427 },
            { "x": 2037, "y": 427 },
            { "x": 2037, "y": 1285 },
            { "x": 1190, "y": 1285 }
          ]
        },
        "landmarks": [
          {
            "type": "LEFT_EYE",
            "position": { "x": 1368.8, "y": 737.6, "z": 0.0016 }
          },
          {
            "type": "RIGHT_EYE",
            "position": { "x": 1659.2, "y": 755.1, "z": -116.4 }
          }
        ],
        "rollAngle": 1.959,
        "panAngle": -21.954,
        "tiltAngle": -2.267,
        "detectionConfidence": 0.98,
        "landmarkingConfidence": 0.61,
        "joyProbability": 0.18,
        "headwearProbability": 0.80
      }
    ]
  }
}

物件偵測

使用 object-detector 模型偵測及追蹤圖片中的多個不同物件。對於每個識別出的物件，模型會提供實體名稱、知識圖譜實體 ID (knowledgeGraphId)、可信度分數和定界座標。

模型詳細資料

  • Model name (模型名稱)：object-detector
  • 情境索引鍵：google:annotation:object-detector-v1
  • 符合資格的物件：大小在 20 MiB 以下的圖片物件，且具有支援的 Content-Type BMP、GIF、ICO、JPEG、PNG、TIFF 或 WEBP。

輸出內容的結構定義

模型會輸出 JSON 物件，其中包含 modelName、modelVersion 和 objectAnnotationGroup，以及 objectAnnotations 陣列。如果模型執行失敗，JSON 物件會包含 error 物件，而非 objectAnnotationGroup。

欄位 類型 範圍 說明
modelName string 不適用 生成這項擴充資料的機器學習模型名稱。
modelVersion string 不適用 生成這項擴充功能的機器學習模型版本。
objectAnnotationGroup object 不適用 物件偵測擴充功能的頂層容器物件。模型執行成功時會顯示。
objectAnnotationGroup.objectAnnotations[] array 不適用 圖片中偵測到的物件清單。
objectAnnotationGroup.objectAnnotations[].knowledgeGraphId string 不適用 偵測到物件的 Google 知識圖譜實體 ID。
objectAnnotationGroup.objectAnnotations[].name string 不適用 偵測到的物件名稱或標籤，例如 "Person" 或 "Chair"。
objectAnnotationGroup.objectAnnotations[].score number 0 至 1 (0% 至 100%) 物件偵測的信賴分數。
objectAnnotationGroup.objectAnnotations[].boundingPoly object 不適用 物件周圍的 BoundingPoly，包含像素座標 (vertices) 和標準化座標 (normalizedVertices)。
error object 不適用 包含 code 和 message 的 google.rpc.Status 物件。只有在模型執行失敗時才會填入資料。

輸出內容範例

{
  "modelName": "object-detector",
  "modelVersion": "v1",
  "objectAnnotationGroup": {
    "objectAnnotations": [
      {
        "knowledgeGraphId": "/m/01g317",
        "name": "Person",
        "score": 0.89,
        "boundingPoly": {
          "normalizedVertices": [
            { "x": 0.1, "y": 0.15 },
            { "x": 0.2, "y": 0.15 },
            { "x": 0.2, "y": 0.3 },
            { "x": 0.1, "y": 0.3 }
          ]
        }
      }
    ]
  }
}

一般圖片標籤

使用 label-detector 模型，為圖片生成描述性標籤、關鍵字和廣泛的語意類別。模型會識別一般實體、風景、活動和位置，例如 Landscape、Urban 或 Night，讓您的視覺素材資源可供搜尋和編目。

模型詳細資料

  • Model name (模型名稱)：label-detector
  • 情境索引鍵：google:annotation:label-detector-v1
  • 符合資格的物件：大小不超過 20 MiB 的圖片物件，且支援的 Content-Type 為 BMP、GIF、ICO、JPEG、PNG、TIFF 或 WEBP。

輸出內容的結構定義

模型會輸出 JSON 物件，其中包含 modelName、modelVersion 和 labelAnnotationGroup，以及 labelAnnotations 陣列。如果模型執行失敗，JSON 物件會包含 error 物件，而非 labelAnnotationGroup。

欄位 類型 範圍 說明
modelName string 不適用 生成這項擴充資料的機器學習模型名稱。
modelVersion string 不適用 生成這項擴充功能的機器學習模型版本。
labelAnnotationGroup object 不適用 圖片標籤強化功能的頂層容器物件。模型執行成功時顯示。
labelAnnotationGroup.labelAnnotations[] array 不適用 偵測到的標籤和類別清單。
labelAnnotationGroup.labelAnnotations[].knowledgeGraphId string 不適用 標籤的 Google 知識圖譜實體 ID。
labelAnnotationGroup.labelAnnotations[].description string 不適用 偵測到的實體文字說明或標籤名稱。
labelAnnotationGroup.labelAnnotations[].score number 0 至 1 (0% 至 100%) 標籤的可信度分數。
labelAnnotationGroup.labelAnnotations[].topicality number 0 至 1 (0% 至 100%) 標籤與圖片主要主題的相關性，分數越高代表越顯眼。
error object 不適用 包含 code 和 message 的 google.rpc.Status 物件。只有在模型執行失敗時才會填入資料。

輸出內容範例

{
  "modelName": "label-detector",
  "modelVersion": "v1",
  "labelAnnotationGroup": {
    "labelAnnotations": [
      {
        "knowledgeGraphId": "/m/01d74z",
        "description": "Night",
        "score": 0.92,
        "topicality": 0.19
      }
    ]
  }
}

煽情露骨內容偵測

使用 content-safety 模型篩選上傳的圖片，找出敏感、露骨或不當內容。模型會根據 Google 安全政策評估圖片。這項功能會評估成人、暴力和其他敏感內容出現的可能性，協助您自動執行內容審核工作流程。

模型詳細資料

  • Model name (模型名稱)：content-safety
  • 內容鍵：google:annotation:content-safety-v1
  • 符合資格的物件：大小在 20 MiB 以下的圖片物件，且具有支援的 Content-Type BMP、GIF、ICO、JPEG、PNG、TIFF 或 WEBP。

輸出內容的結構定義

模型會輸出 JSON 物件，其中包含 modelName、modelVersion 和 contentSafetyAnnotation 物件，並附上可能性評分。如果模型執行失敗，JSON 物件會包含 error 物件，而非 contentSafetyAnnotation。

欄位 類型 值 / 範圍 說明
modelName string 不適用 生成這項擴充資料的機器學習模型名稱。
modelVersion string 不適用 生成這項擴充功能的機器學習模型版本。
contentSafetyAnnotation object 不適用 內容分析結果的頂層容器物件。模型執行成功時會顯示。
contentSafetyAnnotation.adultContentLikelihood string VERY_UNLIKELY、UNLIKELY、POSSIBLE、LIKELY、VERY_LIKELY 圖片含有成人內容的可能性。
contentSafetyAnnotation.violentContentLikelihood string VERY_UNLIKELY、UNLIKELY、POSSIBLE、LIKELY、VERY_LIKELY 圖片描繪暴力行為的可能性。
error object 不適用 包含 code 和 message 的 google.rpc.Status 物件。只有在模型執行失敗時才會填入資料。

輸出內容範例

{
  "modelName": "content-safety",
  "modelVersion": "v1",
  "contentSafetyAnnotation": {
    "adultContentLikelihood": "VERY_UNLIKELY",
    "violentContentLikelihood": "UNLIKELY"
  }
}

PDF 分類

使用 pdf-classification 模型，根據 PDF 文件的文字和視覺結構自動分類。模型會為業務、產業和主題指派標準化的階層式類別。這些類別可協助您整理大量文件、建立生成式 AI 檢索基準，以及將文件轉送至下游工作流程。

模型詳細資料

  • Model name (模型名稱)：pdf-classification
  • 情境索引鍵：google:annotation:pdf-classification-v1
  • 符合條件的物件：Content-Type 為 application/pdf 且大小不超過 20 MiB 的 PDF 文件物件。

輸出內容的結構定義

模型會輸出 JSON 物件，其中包含 modelName、modelVersion 和 pdfClassificationCategoryList，以及分類 categories 的陣列。如果模型執行失敗，JSON 物件會包含 error 物件，而非 pdfClassificationCategoryList。

欄位 類型 範圍 說明
modelName string 不適用 生成這項擴充資料的機器學習模型名稱。
modelVersion string 不適用 生成這項擴充功能的機器學習模型版本。
pdfClassificationCategoryList object 不適用 PDF 分類結果的頂層容器物件。模型執行成功時會顯示。
pdfClassificationCategoryList.categories[] array 不適用 偵測到的分類類別清單。
pdfClassificationCategoryList.categories[].label string 請參閱 PDF 分類類別 階層類別路徑，例如 "/Finance/Accounting & Auditing/Tax Preparation & Planning"。
pdfClassificationCategoryList.categories[].score number 0 至 1 (0% 至 100%) 指派類別的可信度分數。
error object 不適用 包含 code 和 message 的 google.rpc.Status 物件。只有在模型執行失敗時才會填入資料。

支援的類別

pdf-classification 模型會為 PDF 文件指派標準化的階層式內容類別。

類別是以階層結構呈現，並以正斜線 (/) 分隔類別深度。開頭是廣泛的頂層產業，然後縮小至特定子類別：

  • 頂層類別：廣泛的主題領域，例如 /Finance、/Law & Government 或 /Computers & Electronics。
  • 子類別：產業中的特定主題，例如 /Finance/Accounting & Auditing/Tax Preparation & Planning。
  • /Other 子類別：內容與上層類別一致，但不屬於任何特定子類別。

如果文件涵蓋多個不同主題，模型可以為單一 PDF 物件指派多個高信賴度類別。

頂層類別

模型會將 PDF 文件分為 27 個頂層類別：

  • /Adult
  • /Arts & Entertainment
  • /Autos & Vehicles
  • /Beauty & Fitness
  • /Books & Literature
  • /Business & Industrial
  • /Computers & Electronics
  • /Finance
  • /Food & Drink
  • /Games
  • /Health
  • /Hobbies & Leisure
  • /Home & Garden
  • /Internet & Telecom
  • /Jobs & Education
  • /Law & Government
  • /News
  • /Online Communities
  • /People & Society
  • /Pets & Animals
  • /Real Estate
  • /Reference
  • /Science
  • /Sensitive Subjects
  • /Shopping
  • /Sports
  • /Travel & Transportation

子類別會遵循階層路徑 /Top-Level-Vertical/Subcategory，並可選擇在這些頂層類別下加入更深層級。如需所有支援類別路徑的完整清單，請參閱「PDF 分類類別」。

輸出內容範例

{
  "modelName": "pdf-classification",
  "modelVersion": "v1",
  "pdfClassificationCategoryList": {
    "categories": [
      {
        "label": "/Finance/Accounting & Auditing/Tax Preparation & Planning",
        "score": 0.85
      },
      {
        "label": "/Business & Industrial/Printing & Publishing/Document & Printing Services",
        "score": 0.25
      }
    ]
  }
}

後續步驟