Utilizzare l'API Healthcare Natural Language

Questa pagina spiega come attivare l'API Healthcare Natural Language, configurare le autorizzazioni e chiamare il metodo analyzeEntities per estrarre informazioni mediche dal testo medico.

Panoramica

L'API Healthcare Natural Language fornisce soluzioni di machine learning per ricavare insight da testi medici. L'API Healthcare Natural Language dell'API Cloud Healthcare. Per una panoramica dell'API Healthcare Natural Language, consulta la documentazione concettuale dell'API Healthcare Natural Language.

L'API Healthcare Natural Language analizza dati medici non strutturati come cartelle cliniche o richieste di risarcimento assicurativi. Genera quindi una rappresentazione dei dati strutturati delle entità di conoscenza medica archiviate in queste origini dati per l'analisi e l'automazione a valle. Ad esempio, puoi:

  • Estrarre informazioni su concetti medici come malattie, farmaci, dispositivi medici, procedure e relativi attributi clinicamente pertinenti
  • Mappa i concetti medici a vocabolari medici standard come RxNorm, ICD-10, MeSH e SNOMED CT (solo utenti statunitensi)
  • Dedurre informazioni mediche dal testo e integrarle con i prodotti per l'analisi dei dati in Google Cloud

Paesi in cui è disponibile il servizio

L'API Healthcare Natural Language è disponibile nei seguenti paesi:

Nome della sede Descrizione del luogo
asia-south1 Mumbai, India
australia-southeast1 Sydney, Australia
europe-west2 Londra, Regno Unito
europe-west4 Paesi Bassi
northamerica-northeast1 Montréal, Canada
us-central1 Iowa, Stati Uniti

Abilita l'API Healthcare Natural Language

Prima di iniziare a utilizzare l'API Healthcare Natural Language, devi attivarla per il tuo progetto Google Cloud. Puoi utilizzare lo API Healthcare Natural Language senza abilitare o utilizzare le funzionalità del API Cloud Healthcare.

Per attivare l'API, completa i seguenti passaggi:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.
    5. Grant the Project > Owner role to the service account.

      To grant the role, find the Select a role list, then select Project > Owner.

    6. Click Continue.
    7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

  5. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, and then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.
  6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.
    5. Grant the Project > Owner role to the service account.

      To grant the role, find the Select a role list, then select Project > Owner.

    6. Click Continue.
    7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

  10. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, and then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.
  11. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

  12. Enable the Cloud Healthcare API.

    Enable the API

  13. Install the Google Cloud CLI.
  14. To initialize the gcloud CLI, run the following command:

    gcloud init

Configurare le autorizzazioni

Per utilizzare le funzionalità descritte in questa guida, devi disporre dell'healthcare.nlpservice.analyzeEntities autorizzazione, inclusa nel healthcare.nlpServiceViewer ruolo.

Per assegnare questo ruolo, esegui gcloud projects add-iam-policy-binding :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member serviceAccount:SERVICE_ACCOUNT_ID \
    --role roles/healthcare.nlpServiceViewer

Estrazione di entità, relazioni e attributi contestuali

L'API Healthcare Natural Language utilizza modelli sensibili al contesto per estrarre entità, relazioni e attributi contestuali. Ogni entità di testo viene estratta in una voce del dizionario di medicina. Per estrarre questo livello di informazioni mediche dal testo medico, utilizza il metodo projects.locations.services.nlp.analyzeEntities.

Per includere il vocabolario SNOMED CT concesso in licenza nelle menzioni delle entità, consulta Includere i vocabolari concessi in licenza.

Per estrarre informazioni mediche da un testo medico utilizzando l'API Healthcare Natural Language, crea una richiesta POST e specifica il testo di destinazione nel campo documentContent. La dimensione massima del testo medico è di 20.000 caratteri Unicode.

I seguenti esempi mostrano come utilizzare il metodo analyzeEntities per estrarre consigli medici dal testo medico "Il regime di insulina 5 unità IV sarà somministrati per il diabete".

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati

Corpo JSON della richiesta:

{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}
EOF

Quindi, esegui il seguente comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui il seguente comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities" | Select-Object -Expand Content

Se la richiesta ha esito positivo, la risposta include le seguenti informazioni:

  • Entità di conoscenza medica riconosciute
  • Caratteristiche funzionali
  • Relazioni tra le entità riconosciute
  • Attributi contestuali
  • Mappature delle entità di conoscenza medica in terminologie standard

Per un elenco dei tipi di entità, attributi e relazioni supportati, consulta le funzionalità dell'API Healthcare Natural Language.

La seguente risposta identifica l'insulina terapeutica, l'entità con codice C581 nel sistema terminologico NCI, come farmaco. La risposta include anche il punteggio di attendibilità assegnato alla risposta. Per ulteriori informazioni sui campi di risposta, consulta la documentazione di analyzeEntities.

Includi i vocabolari autorizzati

Per impostazione predefinita, le risposte dell'API Healthcare Natural Language includono i vocabolari medici supportati.

Puoi includere Termini clinici SNOMED, versione USA (SNOMEDCT_US) vocabolario nella risposta, se la tua richiesta soddisfa i seguenti requisiti:

  • La richiesta API ha origine negli Stati Uniti.
  • Il campo licensedVocabularies nel corpo della richiesta ha il valore SNOMEDCT_US.

Se non ti serve il vocabolario SNOMED CT, nessuno di questi sono previste limitazioni.

L'esempio seguente mostra come includere il vocabolario SNOMED CT concesso in licenza nell'oggetto LicensedVocabularies per estrarre informazioni mediche dal testo medico "Per il diabete verrà somministrato un regime insulinico di 5 unità per via endovenosa".

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati

Corpo JSON della richiesta:

{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}
EOF

Quindi, esegui il seguente comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities" | Select-Object -Expand Content
Se la richiesta va a buon fine, la risposta include i codici dei vocabolari SNOMEDCT_US e ICD10CM concessi in licenza. L'output è quanto segue e i codici del vocabolario concessi in licenza richiesti sono in grassetto:

Estrai l'output come bundle FHIR R4

Puoi estrarre le entità dal testo e mapparle alle risorse FHIR R4. elementi. Il bundle FHIR R4 risultante include tutte le entità, le menzioni delle entità, in formato JSON. Ad esempio, L'API Healthcare Natural Language mappa l'entità di base PROBLEM al FHIR Condition la risorsa R4 e l'entità PROBLEM.ANATOMICAL_STRUCTURE alla Condition.bodySite elemento FHIR. Per un elenco di altre mappature, vedi Output dell'API Healthcare Natural Language come bundle FHIR.

I seguenti esempi mostrano come estrarre consigli medici dal testo medico "Il regime di insulina 5 unità IV sarà somministrati per il diabete". in un bundle FHIR R4. Per ulteriori informazioni, consulta l'oggetto AlternativeOutputFormat.

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati

Corpo JSON della richiesta:

{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}
EOF

Quindi, esegui il seguente comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui il seguente comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/services/nlp:analyzeEntities" | Select-Object -Expand Content
Se la richiesta ha esito positivo, la risposta contiene un oggetto JSON con le seguenti voci:
  • Le menzioni di entità riconosciute con le entità e le relative relazioni in un formato simile all'output in Estrarre entità, relazioni e attributi contestuali.
  • Una chiave fhirBundle contenente una risorsa FHIR Bundle formattata come stringa. Il bundle FHIR include tutte le entità, le menzioni delle entità e le relazioni JSON.