使用 Healthcare Natural Language API

本页面介绍了如何启用 Healthcare Natural Language API、如何配置权限以及如何调用 analyzeEntities 方法从医学信息中提取医学数据分析。

概览

Healthcare Natural Language API 提供用于从医学文本提取数据分析的机器学习解决方案。Healthcare Natural Language API 是 Cloud Healthcare API 的一部分。如需简要了解 Healthcare Natural Language API,请参阅 Healthcare Natural Language API 概念文档

Healthcare Natural Language API 会解析非机构化医学文本,例如医疗记录或保险索赔。然后,它会生成存储在这些数据源中的医学知识实体的结构化数据表示,以用于下游分析和自动化。例如,您可以:

  • 提取关于疾病、药物、医疗设备、手术及其临床相关特性等医学概念的信息
  • 将医学概念与 RxNorm、ICD-10、MeSH 和 SNOMED CT 等标准医学词汇相对应(仅限美国和英国用户)
  • 从文本中提取医学数据分析,并将其与 Google Cloud中的数据分析产品集成

可用位置

Healthcare Natural Language API 在以下位置可用:

地点名称 地点描述
asia-south1 印度孟买
australia-southeast1 澳大利亚悉尼
europe-west2 英国伦敦
europe-west4 荷兰
northamerica-northeast1 加拿大蒙特利尔
us-central1 美国爱荷华州

启用 Healthcare Natural Language API

在开始使用 Healthcare Natural Language API 之前,您必须为您的 Google Cloud 项目启用该 API。您可以在不启用或使用 Cloud Healthcare API 功能的情况下使用 Healthcare Natural Language API。

如需启用 API,请完成以下步骤:

  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

设置权限

为了使用本指南中的功能,您必须拥有 healthcare.nlpservice.analyzeEntities 权限,它包含在 healthcare.nlpServiceViewer 角色中。

如需分配此角色,请运行 gcloud projects add-iam-policy-binding 命令:

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

提取实体、关系和情境特性

Healthcare Natural Language API 使用情境感知模型来提取医疗实体、关系和情境特性。每个文本实体会提取到一个医学字典条目中。如需从医学文本中提取此级层的医学数据分析,请使用 projects.locations.services.nlp.analyzeEntities 方法。

如需在实体提及中添加 SNOMED CT 许可词汇,请参阅添加许可词汇

如需使用 Healthcare Natural Language API 从医学信息中提取医学数据分析,请发出 POST 请求并在 documentContent 字段中指定目标文本。医学文本的大小上限为 20,000 个 Unicode 字符。

以下示例展示了如何使用 analyzeEntities 方法从医学文本“Insulin regimen 5 units IV will be administered for diabetes.” 中提取医学洞见。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目的 ID
  • LOCATION:数据集位置

请求 JSON 正文:

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

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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

如果请求成功,则响应会包含以下信息:

  • 识别出的医学知识实体
  • 功能特征
  • 识别出的实体之间的关系
  • 情境特性
  • 将医学知识实体映射到标准术语

如需查看受支持的实体、属性和关系类型的列表,请参阅 Healthcare Natural Language API 功能

以下响应识别了属于药物的治疗用胰岛素,该实体在 NCI 术语系统中的代码为 C581。响应还包含为响应分配的置信度分数。如需详细了解响应字段,请参阅 analyzeEntities 文档。

添加许可词汇

默认情况下,Healthcare Natural Language API 响应包含受支持的医学词汇

如果您的请求符合以下要求,您可以在响应中添加 SNOMED 临床术语 (SNOMEDCT_US) 词汇:

  • API 请求来自美国。
  • 请求正文中的 licensedVocabularies 字段的值为 SNOMEDCT_US

如果您不需要 SNOMED CT 词汇,则不受上述任何限制。

以下示例展示了如何在 LicensedVocabularies 对象中添加 SNOMED CT 许可词汇,以便从医学文本“Insulin regimen 5 units IV will be administered for diabetes.” 中提取医学数据洞见。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目的 ID
  • LOCATION:数据集位置

请求 JSON 正文:

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

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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
如果请求成功,响应将包含 SNOMEDCT_USICD10CM 许可字典中的词汇代码。输出如下,其中请求的许可词汇代码以粗体显示:

将输出提取为 FHIR R4 软件包

您可以从文本中提取实体,并将其映射到 FHIR R4 资源和元素。生成的 FHIR R4 软件包包含 JSON 格式的所有实体、实体提及和关系。例如,Healthcare Natural Language API 会将基准实体 PROBLEM 映射到 Condition FHIR R4 资源,并将实体 PROBLEM.ANATOMICAL_STRUCTURE 映射到 Condition.bodySite FHIR 元素。如需查看其他映射的列表,请参阅将 Healthcare Natural Language API 输出作为 FHIR 软件包

以下示例展示了如何从 FHIR R4 软件包中的医学文本“Insulin regimen 5 units IV will be administered for diabetes.” 中提取医学洞见。如需了解详情,请参阅 AlternativeOutputFormat 对象。

REST

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 Google Cloud 项目的 ID
  • LOCATION:数据集位置

请求 JSON 正文:

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

如需发送请求,请选择以下方式之一:

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令,在当前目录中创建或覆盖此文件:

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

然后,执行以下命令以发送 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
如果请求成功,则响应将包含一个包含以下条目的 JSON 对象:
  • 识别的实体提及,以及实体及其关系,格式与 提取实体、关系和情境属性中的输出类似。
  • 一个 fhirBundle 键,其中包含采用字符串格式的 FHIR Bundle 资源。 FHIR 软件包包含 JSON 格式的所有实体、实体提及和关系。