Modelli e schemi supportati

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Quando configuri gli arricchimenti degli oggetti, scegli quali modelli di machine learning analizzano gli oggetti archiviati. Ogni modello valuta le immagini o i documenti PDF idonei e allega i metadati strutturati direttamente agli oggetti Cloud Storage.

Questa pagina descrive ogni modello supportato, i relativi requisiti di idoneità e lo schema di output per aiutarti ad analizzare ed eseguire query sui metadati di arricchimento in BigQuery o tramite un'API.

Relazione tra modelli e arricchimenti degli oggetti

Per attivare i modelli, devi creare una configurazione delle funzionalità (FeatureConfig) che specifica i bucket da analizzare e i modelli da eseguire. Durante l'elaborazione asincrona, Cloud Storage valuta gli oggetti idonei utilizzando i modelli scelti e genera metadati JSON strutturati chiamati arricchimenti degli oggetti.

Ogni modello produce un payload JSON dedicato che Cloud Storage collega direttamente all'oggetto come contesto dell'oggetto gestito da Google nella proprietà contexts.custom. Una chiave di contesto univoca con il prefisso google:annotation: identifica ogni payload.

A seconda del tuo flusso di lavoro, puoi utilizzare questi metadati in due modi:

• Ispeziona singoli oggetti: recupera arricchimenti per un oggetto specifico utilizzando le API degli oggetti, ad esempio il viewFullContext metodo (anteprima).
• Analisi su larga scala: esegui query sui metadati arricchiti in tutti gli oggetti di un bucket utilizzando i set di dati di Storage Insights e l'SQL standard in BigQuery.

Riconoscimento facciale

Utilizza il modello face-detector per rilevare i volti umani nelle immagini archiviate. Il modello rileva i poligoni di delimitazione per le teste intere e i singoli volti e individua 36 punti di riferimento facciali, come occhi, naso e bocca. Calcola anche gli angoli di orientamento della testa, come rollio, panoramica e inclinazione, e valuta le probabilità di espressione emotiva.

Dettagli modello

• Nome modello: face-detector
• Chiave di contesto: google:annotation:face-detector-v1
• Oggetti idonei: oggetti immagine di dimensioni pari o inferiori a 20 MiB con un Content-Type supportato di BMP, GIF, ICO, JPEG, PNG, TIFF o WEBP.

Schema di output

L'output del modello restituisce un oggetto JSON contenente modelName, modelVersion e un faceAnnotationGroup con un array di faceAnnotations. Se l'esecuzione del modello non va a buon fine, l'oggetto JSON contiene un oggetto error anziché faceAnnotationGroup.

Campo	Tipo	Intervallo	Descrizione
modelName	string	N/D	Il nome del modello di machine learning che ha generato questo arricchimento.
modelVersion	string	N/D	La versione del modello di machine learning che ha generato questa ottimizzazione.
faceAnnotationGroup	object	N/D	Oggetto contenitore di primo livello per gli arricchimenti del riconoscimento facciale. Presente quando l'esecuzione del modello ha esito positivo.
faceAnnotationGroup.faceAnnotations[]	array	N/D	Un elenco dei volti rilevati nell'immagine.
faceAnnotationGroup.faceAnnotations[].boundingPoly	object	N/D	Il BoundingPoly che racchiude l'intera testa e il viso, ridimensionato in base alle dimensioni dell'immagine originale.
faceAnnotationGroup.faceAnnotations[].faceDetectionBoundingPoly	object	N/D	BoundingPoly per il riconoscimento facciale. Più stretto di boundingPoly, che racchiude solo la pelle e i tratti del viso visibili.
faceAnnotationGroup.faceAnnotations[].landmarks[]	array	N/D	Un elenco di oggetti FaceLandmark rilevati che rappresentano caratteristiche facciali specifiche.
faceAnnotationGroup.faceAnnotations[].rollAngle	number	Da -180 a 180	Rotazione in senso orario o antiorario del volto, in gradi.
faceAnnotationGroup.faceAnnotations[].panAngle	number	Da -180 a 180	Angolo orizzontale verso cui è rivolto il volto, a sinistra o a destra, in gradi.
faceAnnotationGroup.faceAnnotations[].tiltAngle	number	Da -180 a 180	L'angolo di beccheggio verticale con cui la faccia è rivolta verso l'alto o verso il basso, in gradi.
faceAnnotationGroup.faceAnnotations[].detectionConfidence	number	Da 0 a 1 (da 0% a 100%)	Punteggio di confidenza per il riconoscimento facciale complessivo.
faceAnnotationGroup.faceAnnotations[].landmarkingConfidence	number	Da 0 a 1 (da 0% a 100%)	Punteggio di confidenza per il posizionamento dei punti di riferimento facciali.
faceAnnotationGroup.faceAnnotations[].joyProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto esprima gioia.
faceAnnotationGroup.faceAnnotations[].sorrowProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto esprima tristezza.
faceAnnotationGroup.faceAnnotations[].angerProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto esprima rabbia.
faceAnnotationGroup.faceAnnotations[].surpriseProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto esprima sorpresa.
faceAnnotationGroup.faceAnnotations[].underExposedProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto nell'immagine sia sottoesposto.
faceAnnotationGroup.faceAnnotations[].blurredProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che il volto nell'immagine sia sfocato.
faceAnnotationGroup.faceAnnotations[].headwearProbability	number	Da 0 a 1 (da 0% a 100%)	Probabilità che la persona indossi un copricapo, ad esempio un cappello o un berretto.
error	object	N/D	Un oggetto google.rpc.Status contenente code e message. Compilato solo se l'esecuzione del modello non va a buon fine.

BoundingPoly

L'oggetto BoundingPoly rappresenta un poligono di delimitazione che racchiude una caratteristica dell'immagine rilevata.

Campo	Tipo	Intervallo	Descrizione
vertices[]	array	N/D	Coordinate del poligono di delimitazione utilizzando oggetti Vertex pixel assoluti.
normalizedVertices[]	array	N/D	Coordinate del poligono di delimitazione che utilizzano oggetti NormalizedVertex relativi, scalati da 0 a 1.

Vertex

L'oggetto Vertex rappresenta un punto di coordinate 2D scalato in base alle dimensioni dell'immagine originale.

Campo	Tipo	Intervallo	Descrizione
x	integer	0 o superiore	Coordinata X orizzontale, in pixel dal bordo sinistro.
y	integer	0 o superiore	Coordinata Y verticale, in pixel dal bordo superiore.

NormalizedVertex

L'oggetto NormalizedVertex rappresenta un punto di coordinate 2D espresso come rapporto rispetto alle dimensioni dell'immagine originale.

Campo	Tipo	Intervallo	Descrizione
x	number	Da 0 a 1	Coordinata X orizzontale relativa alla larghezza dell'immagine, dove 0.0 è il bordo sinistro e 1.0 è il bordo destro.
y	number	Da 0 a 1	Coordinata Y verticale relativa all'altezza dell'immagine, dove 0.0 è il bordo superiore e 1.0 è il bordo inferiore.

FaceLandmark

L'oggetto FaceLandmark rappresenta un punto di riferimento facciale specifico rilevato all'interno di un volto.

Campo	Tipo	Intervallo	Descrizione
type	enum	Vedi Tipo di punto di riferimento	Il punto di riferimento facciale specifico rilevato.
position	object	N/D	La Position 3D del punto di riferimento.

Tipo di punto di riferimento

Il modello riconosce 36 punti di riferimento facciali specifici:

• 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

Posizione

L'oggetto Position rappresenta le coordinate 3D di un punto di riferimento facciale.

Campo	Tipo	Intervallo	Descrizione
x	number	N/D	Coordinata X orizzontale.
y	number	N/D	Coordinata Y verticale.
z	number	N/D	Coordinata di profondità relativa al piano del viso, dove i valori più piccoli sono più vicini alla videocamera.

Esempio di output

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

Rilevamento di oggetti

Utilizza il modello object-detector per rilevare e monitorare più oggetti distinti in un'immagine. Per ogni oggetto identificato, il modello fornisce un nome di entità, un ID entità del Knowledge Graph (knowledgeGraphId), un punteggio di affidabilità e le coordinate di delimitazione.

Dettagli modello

• Nome modello: object-detector
• Chiave di contesto: google:annotation:object-detector-v1
• Oggetti idonei: oggetti immagine di 20 MiB o meno con un Content-Type supportato di BMP, GIF, ICO, JPEG, PNG, TIFF o WEBP.

Schema di output

L'output del modello restituisce un oggetto JSON contenente modelName, modelVersion e un objectAnnotationGroup con un array di objectAnnotations. Se l'esecuzione del modello non va a buon fine, l'oggetto JSON contiene un oggetto error anziché objectAnnotationGroup.

Campo	Tipo	Intervallo	Descrizione
modelName	string	N/D	Il nome del modello di machine learning che ha generato questo arricchimento.
modelVersion	string	N/D	La versione del modello di machine learning che ha generato questa ottimizzazione.
objectAnnotationGroup	object	N/D	Oggetto contenitore di primo livello per gli arricchimenti del rilevamento di oggetti. Presente quando l'esecuzione del modello ha esito positivo.
objectAnnotationGroup.objectAnnotations[]	array	N/D	Un elenco di oggetti rilevati nell'immagine.
objectAnnotationGroup.objectAnnotations[].knowledgeGraphId	string	N/D	L'ID entità Google Knowledge Graph per l'oggetto rilevato.
objectAnnotationGroup.objectAnnotations[].name	string	N/D	Il nome o l'etichetta dell'oggetto rilevato, ad esempio "Person" o "Chair".
objectAnnotationGroup.objectAnnotations[].score	number	Da 0 a 1 (da 0% a 100%)	Punteggio di confidenza per il rilevamento di oggetti.
objectAnnotationGroup.objectAnnotations[].boundingPoly	object	N/D	Il BoundingPoly intorno all'oggetto, contenente le coordinate dei pixel (vertices) e le coordinate normalizzate (normalizedVertices).
error	object	N/D	Un oggetto google.rpc.Status contenente code e message. Compilato solo se l'esecuzione del modello non va a buon fine.

Esempio di output

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

Etichettatura delle immagini generiche

Utilizza il modello label-detector per generare etichette descrittive, parole chiave e ampie categorie semantiche per le immagini. Il modello identifica entità, scenari, attività e località generali, come Landscape, Urban o Night, rendendo i tuoi asset visivi ricercabili e catalogabili.

Dettagli modello

• Nome modello: label-detector
• Chiave di contesto: google:annotation:label-detector-v1
• Oggetti idonei: oggetti immagine di dimensioni pari o inferiori a 20 MiB con un Content-Type supportato di BMP, GIF, ICO, JPEG, PNG, TIFF o WEBP.

Schema di output

Il modello restituisce un output del modello JSON contenente modelName, modelVersion e un labelAnnotationGroup con un array di labelAnnotations. Se l'esecuzione del modello non va a buon fine, l'oggetto JSON contiene un oggetto error anziché labelAnnotationGroup.

Campo	Tipo	Intervallo	Descrizione
modelName	string	N/D	Il nome del modello di machine learning che ha generato questo arricchimento.
modelVersion	string	N/D	La versione del modello di machine learning che ha generato questa ottimizzazione.
labelAnnotationGroup	object	N/D	Oggetto container di primo livello per gli arricchimenti delle etichette delle immagini. Presente quando l'esecuzione del modello ha esito positivo.
labelAnnotationGroup.labelAnnotations[]	array	N/D	Un elenco di etichette e categorie rilevate.
labelAnnotationGroup.labelAnnotations[].knowledgeGraphId	string	N/D	L'ID entità Google Knowledge Graph per l'etichetta.
labelAnnotationGroup.labelAnnotations[].description	string	N/D	Descrizione testuale o nome dell'etichetta per l'entità rilevata.
labelAnnotationGroup.labelAnnotations[].score	number	Da 0 a 1 (da 0% a 100%)	Punteggio di confidenza per l'etichetta.
labelAnnotationGroup.labelAnnotations[].topicality	number	Da 0 a 1 (da 0% a 100%)	Rilevanza dell'etichetta rispetto al soggetto principale dell'immagine, dove i punteggi più alti indicano una maggiore prominenza.
error	object	N/D	Un oggetto google.rpc.Status contenente code e message. Compilato solo se l'esecuzione del modello non va a buon fine.

Esempio di output

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

Rilevamento di contenuti espliciti

Utilizza il modello content-safety per esaminare le immagini caricate e rilevare contenuti sensibili, espliciti o inappropriati. Il modello valuta le immagini in base alle norme di sicurezza di Google. Valuta la probabilità di contenuti per adulti, violenti e altri materiali sensibili per aiutarti ad automatizzare i flussi di lavoro di moderazione dei contenuti.

Dettagli modello

• Nome modello: content-safety
• Chiave di contesto: google:annotation:content-safety-v1
• Oggetti idonei: oggetti immagine di 20 MiB o meno con un Content-Type supportato di BMP, GIF, ICO, JPEG, PNG, TIFF o WEBP.

Schema di output

Il modello restituisce un oggetto JSON contenente modelName, modelVersion e un oggetto contentSafetyAnnotation con valutazioni di probabilità. Se l'esecuzione del modello non va a buon fine, l'oggetto JSON contiene un oggetto error anziché contentSafetyAnnotation.

Campo	Tipo	Valori / Intervallo	Descrizione
modelName	string	N/D	Il nome del modello di machine learning che ha generato questo arricchimento.
modelVersion	string	N/D	La versione del modello di machine learning che ha generato questa ottimizzazione.
contentSafetyAnnotation	object	N/D	Oggetto contenitore di primo livello per i risultati dell'analisi dei contenuti. Presente quando l'esecuzione del modello ha esito positivo.
contentSafetyAnnotation.adultContentLikelihood	string	VERY_UNLIKELY, UNLIKELY, POSSIBLE, LIKELY, VERY_LIKELY	Probabilità che l'immagine includa contenuti per adulti.
contentSafetyAnnotation.violentContentLikelihood	string	VERY_UNLIKELY, UNLIKELY, POSSIBLE, LIKELY, VERY_LIKELY	Probabilità che l'immagine raffiguri violenza.
error	object	N/D	Un oggetto google.rpc.Status contenente code e message. Compilato solo se l'esecuzione del modello non va a buon fine.

Esempio di output

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

Classificazione PDF

Utilizza il modello pdf-classification per classificare automaticamente i documenti PDF in base alla loro struttura testuale e visiva. Il modello assegna categorie gerarchiche standardizzate per attività, settore e argomenti. Queste categorie ti aiutano a organizzare grandi raccolte di documenti, a basare il recupero dell'AI generativa e a indirizzare i documenti ai flussi di lavoro downstream.

Dettagli modello

• Nome modello: pdf-classification
• Chiave di contesto: google:annotation:pdf-classification-v1
• Oggetti idonei: oggetti di documenti PDF di dimensioni pari o inferiori a 20 MiB con un Content-Type di application/pdf.

Schema di output

Il modello restituisce un oggetto JSON contenente modelName, modelVersion e un pdfClassificationCategoryList con un array di categories classificati. Se l'esecuzione del modello non va a buon fine, l'oggetto JSON contiene un oggetto error anziché pdfClassificationCategoryList.

Campo	Tipo	Intervallo	Descrizione
modelName	string	N/D	Il nome del modello di machine learning che ha generato questo arricchimento.
modelVersion	string	N/D	La versione del modello di machine learning che ha generato questa ottimizzazione.
pdfClassificationCategoryList	object	N/D	Oggetto contenitore di primo livello per i risultati della classificazione dei PDF. Presente quando l'esecuzione del modello va a buon fine.
pdfClassificationCategoryList.categories[]	array	N/D	Un elenco delle categorie di classificazione rilevate.
pdfClassificationCategoryList.categories[].label	string	Consulta le categorie di classificazione dei PDF	Il percorso della categoria gerarchica, ad esempio "/Finance/Accounting & Auditing/Tax Preparation & Planning".
pdfClassificationCategoryList.categories[].score	number	Da 0 a 1 (da 0% a 100%)	Punteggio di confidenza per la categoria assegnata.
error	object	N/D	Un oggetto google.rpc.Status contenente code e message. Compilato solo se l'esecuzione del modello non va a buon fine.

Categorie supportate

Il modello pdf-classification assegna categorie di contenuti gerarchici standardizzate ai documenti PDF.

Le categorie sono strutturate in modo gerarchico con barre (/) che separano la profondità delle categorie. Iniziano con un verticale di primo livello ampio e si restringono a sottocategorie specifiche:

• Verticali di primo livello: domini di argomenti generali, ad esempio /Finance, /Law & Government o /Computers & Electronics.
• Sottocategorie: argomenti specifici all'interno di un verticale, ad esempio /Finance/Accounting & Auditing/Tax Preparation & Planning.
• /OtherSottocategorie: categorie per i contenuti in linea con la categoria principale, ma che non rientrano in nessuna sottocategoria secondaria specifica.

Se un documento tratta più argomenti distinti, il modello può assegnare più categorie ad alta affidabilità a un singolo oggetto PDF.

Categorie di primo livello

Il modello classifica i documenti PDF in 27 categorie di primo livello:

• /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

Le sottocategorie seguono il percorso gerarchico /Top-Level-Vertical/Subcategory, con livelli più profondi facoltativi, in queste categorie di primo livello. Per l'elenco completo di tutti i percorsi delle categorie supportati, consulta Categorie di classificazione PDF.

Esempio di output

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

Passaggi successivi

• Scopri di più sugli arricchimenti degli oggetti.
• Configura gli enrichment degli oggetti.
• Gestisci gli arricchimenti degli oggetti.
• Analizza gli arricchimenti degli oggetti in BigQuery.
• Esamina la risorsa API JSON featureConfigs.
• Risolvi i problemi relativi agli arricchimenti degli oggetti.