Usar a API Healthcare Natural Language

Nesta página, você verá como ativar a API Healthcare Natural Language, configurar permissões e chamar o método analyzeEntities para extrair insights clínicos do texto médico.

Visão geral

A API Natural Language oferece soluções de aprendizado de máquina para gerar insights de textos médicos. A API Cloud Natural Language é parte da API Cloud Healthcare. Para uma visão geral, consulte a documentação conceitual da API Healthcare Natural Language.

A API Healthcare Natural Language analisa textos médicos não estruturados, como registros médicos ou pedidos de seguro. Em seguida, ela gera uma representação de dados estruturados das entidades de conhecimento médico armazenadas nessas fontes para análise e automação de downstream. Por exemplo, você pode:

  • extrair informações sobre conceitos médicos, como doenças, medicamentos, dispositivos médicos, procedimentos e seus atributos clinicamente relevantes;
  • mapear conceitos médicos para vocabulários médicos padrão, como RxNorm, ICD-10, MeSH e SNOMED CT (somente usuários dos EUA);
  • Extrair insights médicos de textos e integrá-los a produtos de análise de dados no Google Cloud

Locais disponíveis

A API Healthcare Natural Language está disponível nos seguintes locais:

Nome do local Descrição do local
asia-south1 Mumbai, Índia
australia-southeast1 Sydney, Austrália
europe-west2 Londres, Reino Unido
europe-west4 Países Baixos
northamerica-northeast1 Montreal, Canadá
us-central1 Iowa, EUA

Ativar a API Healthcare Natural Language

Antes de começar a usar a API Healthcare Natural Language, é necessário ativar a API no projeto do Google Cloud. É possível usar a API Healthcare Natural Language sem ativar ou usar recursos da API Cloud Healthcare.

Para ativar a API, conclua as seguintes etapas:

  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

Configurar permissões

Para usar os recursos deste guia, é necessário ter a permissão healthcare.nlpservice.analyzeEntities, que está incluída no papel healthcare.nlpServiceViewer.

Para atribuir esse papel, execute o comando gcloud projects add-iam-policy-binding:

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

Extrair entidades, relações e atributos contextuais

A API Healthcare Natural Language usa modelos com reconhecimento de contexto para extrair entidades, relações e atributos contextuais médicos. Cada entidade de texto é extraída para uma entrada de dicionário médico. Para extrair esse nível de insights médicos do texto, use o método projects.locations.services.nlp.analyzeEntities.

Para incluir o vocabulário licenciado do SNOMED CT nas menções de entidade, consulte Incluir vocabulários licenciados.

Para extrair insights médicos de textos médicos usando a API Healthcare Natural Language, faça uma solicitação POST e especifique o texto de destino em as documentContent . O tamanho máximo do texto médico é de 20 mil caracteres Unicode.

Os exemplos a seguir mostram como usar o método analyzeEntities para extrair informações médicas com base no texto médico "O regime de insulina 5 unidades IV será administrada para diabetes".

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • LOCATION: o local do conjunto de dados;

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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 a solicitação for bem-sucedida, a resposta incluirá as seguintes informações:

  • Entidades de conhecimento médico reconhecidas
  • Recursos funcionais
  • Relações entre as entidades reconhecidas
  • Atributos contextuais
  • Mapeamentos de entidades de conhecimento médico em terminologias padrão

Para uma lista de tipos de entidades, atributos e relações compatíveis, consulte a Recursos da API Healthcare Natural Language.

A resposta a seguir identifica a insulina terapêutica, a entidade com o código C581 no sistema de terminologia do NCI, como o medicamento. Ela também inclui a pontuação de confiança atribuída à resposta. Para mais informações sobre os campos de resposta, consulte a documentação analyzeEntities.

Incluir vocabulários licenciados

Por padrão, as respostas da API Healthcare Natural Language incluem o vocabulários médicos com suporte.

Você pode incluir o parâmetro Termos clínicos do SNOMED, versão nos EUA (SNOMEDCT_US) vocabulário na resposta se a solicitação atender aos seguintes requisitos:

  • A solicitação de API tem origem nos EUA.
  • O campo licensedVocabularies no corpo da solicitação tem o valor SNOMEDCT_US.

Se você não precisa do vocabulário SNOMED CT, então nenhuma dessas opções restrições são aplicáveis.

O exemplo a seguir mostra como incluir o vocabulário licenciado SNOMED CT no LicensedVocabularies objeto a ser extraído informações médicas com base no texto médico "O regime de insulina 5 unidades IV será administrada para diabetes".

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • LOCATION: o local do conjunto de dados;

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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 a solicitação for bem-sucedida, a resposta incluirá códigos de vocabulário dos vocabulários licenciados SNOMEDCT_US e ICD10CM. A saída é a seguinte, e os códigos de vocabulário licenciados solicitados estão em negrito:

Extrair a saída como um pacote FHIR R4

É possível extrair entidades do texto e mapeá-las para os recursos FHIR R4 e os elementos. O pacote FHIR R4 resultante inclui todas as entidades, menções a entidades, e relações no formato JSON. Por exemplo, o A API Healthcare Natural Language mapeia a entidade base PROBLEM para o FHIR Condition. o recurso R4 e a entidade PROBLEM.ANATOMICAL_STRUCTURE ao Elemento FHIR Condition.bodySite. Para uma lista de outros mapeamentos, consulte Saída da API Healthcare Natural Language como um pacote FHIR.

Os exemplos a seguir mostram como extrair informações médicas com base no texto médico "O regime de insulina 5 unidades IV será administrada para diabetes". em um pacote FHIR R4. Para mais informações, consulte o objeto AlternativeOutputFormat.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud;
  • LOCATION: o local do conjunto de dados;

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

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

Depois execute o comando a seguir para enviar a solicitação 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 a solicitação for bem-sucedida, a resposta conterá um objeto JSON com as seguintes entradas:
  • As menções de entidade reconhecidas com as entidades e as relações delas em um formato semelhante à saída em Extrair entidades, relações e atributos contextuais.
  • Uma chave fhirBundle contendo um recurso de pacote FHIR formatado em string. O pacote FHIR inclui todas as entidades, as entidades mencionadas e os relacionamentos em Formato JSON.