支援的模型和結構定義

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

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

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

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

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

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

• 檢查個別物件：使用物件 API (例如 viewFullContext 方法 (預先發布版)) 擷取特定物件的擴充資料。
• 大規模分析：使用 儲存空間分析資料集和 BigQuery 中的標準 SQL，查詢 bucket 中所有物件的豐富中繼資料。

臉部偵測

使用 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。

BoundingPoly

BoundingPoly 物件代表包圍偵測到圖片特徵的多邊形界框。

Vertex

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

正規化 Vertex

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

FaceLandmark

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

地標類型

模型可辨識 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 座標。

輸出內容範例

{
  "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": "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": "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": "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。

支援的類別

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
      }
    ]
  }
}

後續步驟

• 瞭解 object enrichments。
• 設定 object enrichments。
• 管理物件擴充功能。
• 在 BigQuery 中分析物件擴充功能。
• 查看 featureConfigs JSON API 資源。
• 排解物件擴充功能問題。