Como: Utilizar o Text Analytics para a saúde (pré-visualização)How to: Use Text Analytics for health (preview)

Nota

O Text Analytics para o recipiente de saúde foi recentemente atualizado.The Text Analytics for health container has recently updated. Veja as novidades para mais informações sobre as recentes alterações.See What's new for more information on recent changes. Lembre-se de puxar o recipiente mais recente para utilizar as atualizações listadas.Remember to pull the latest container to use the updates listed.

Importante

Text Analytics for health é uma capacidade de pré-visualização fornecida "AS IS" e "WITH ALL FAULTS".Text Analytics for health is a preview capability provided “AS IS” and “WITH ALL FAULTS.” Como tal, o Text Analytics for health (pré-visualização) não deve ser implementado ou implantado em qualquer utilização de produção.As such, Text Analytics for health (preview) should not be implemented or deployed in any production use. Texto Analytics para a saúde não é destinado ou disponibilizado para uso como dispositivo médico, suporte clínico, ferramenta de diagnóstico ou outra tecnologia destinada a ser usada no diagnóstico, cura, mitigação, tratamento ou prevenção de doenças ou outras condições, e nenhuma licença ou direito é concedido pela Microsoft para usar esta capacidade para tais fins.Text Analytics for health is not intended or made available for use as a medical device, clinical support, diagnostic tool, or other technology intended to be used in the diagnosis, cure, mitigation, treatment, or prevention of disease or other conditions, and no license or right is granted by Microsoft to use this capability for such purposes. Esta capacidade não é concebida ou destina-se a ser implementada ou implementada como um substituto de aconselhamento médico profissional ou de opinião de cuidados de saúde, diagnóstico, tratamento ou julgamento clínico de um profissional de saúde, e não deve ser usada como tal.This capability is not designed or intended to be implemented or deployed as a substitute for professional medical advice or healthcare opinion, diagnosis, treatment, or the clinical judgment of a healthcare professional, and should not be used as such. O cliente é o único responsável por qualquer utilização de Text Analytics para a saúde.The customer is solely responsible for any use of Text Analytics for health. A Microsoft não garante que o Text Analytics para a saúde ou quaisquer materiais fornecidos em conexão com a capacidade seja suficiente para qualquer finalidade médica ou de outra forma satisfaça os requisitos de saúde ou médico de qualquer pessoa.Microsoft does not warrant that Text Analytics for health or any materials provided in connection with the capability will be sufficient for any medical purposes or otherwise meet the health or medical requirements of any person.

Text Analytics for health é um serviço contentorizado que extrai e rotula informações médicas relevantes de textos não estruturados, tais como notas de médico, resumos de descarga, documentos clínicos e registos de saúde eletrónicos.Text Analytics for health is a containerized service that extracts and labels relevant medical information from unstructured texts such as doctor's notes, discharge summaries, clinical documents, and electronic health records.

FuncionalidadesFeatures

O Text Analytics for health container realiza atualmente Reconhecimento de Entidade Nomeada (NER), extração de relação, negação de entidade e ligação de entidade para texto em língua inglesa no seu próprio ambiente de desenvolvimento que satisfaz os seus requisitos específicos de segurança e governação de dados.The Text Analytics for health container currently performs Named Entity Recognition (NER), relation extraction, entity negation and entity linking for English-language text in your own development environment that meets your specific security and data governance requirements.

O Reconhecimento de Entidades com nome deteta palavras e frases mencionadas em texto não estruturado que podem ser associadas a um ou mais tipos semânticos, tais como diagnóstico, nome da medicação, sintoma/sinal ou idade.Named Entity Recognition detects words and phrases mentioned in unstructured text that can be associated with one or more semantic types, such as diagnosis, medication name, symptom/sign, or age.

NER de SaúdeHealth NER

Consulte as categorias de entidades devolvidas pela Text Analytics para obter uma lista completa de entidades apoiadas.See the entity categories returned by Text Analytics for health for a full list of supported entities.

Linguagens suportadasSupported languages

O Texto Analytics para a saúde só suporta documentos em inglês.Text Analytics for health only supports English language documents.

Solicitar acesso ao registo de contentoresRequest access to the container registry

Preencha e envie o formulário de pedido de solicitação dos recipientes dos Serviços Cognitivos para solicitar o acesso ao contentor.Fill out and submit the Cognitive Services containers request form to request access to the container. Atualmente não será cobrado para Text Analytics para uso de saúde.Currently you will not be billed for Text Analytics for health usage.

O formulário solicita informações sobre si, sobre a sua empresa e sobre o cenário de utilizador para o qual utilizará o recipiente.The form requests information about you, your company, and the user scenario for which you'll use the container. Depois de ter apresentado o formulário, a equipa dos Serviços Cognitivos do Azure revê-o para garantir que cumpre os critérios de acesso ao registo privado de contentores.After you've submitted the form, the Azure Cognitive Services team reviews it to ensure that you meet the criteria for access to the private container registry.

Importante

Tem de utilizar um endereço de e-mail associado a uma conta microsoft account (MSA) ou Azure Ative Directory (Azure AD) no formulário.You must use an email address that's associated with either a Microsoft Account (MSA) or Azure Active Directory (Azure AD) account in the form.

Se o seu pedido for aprovado, receberá um e-mail com instruções que descrevem como obter as suas credenciais e aceder ao registo privado do contentor.If your request is approved, you'll receive an email with instructions that describe how to obtain your credentials and access the private container registry.

Utilize o CLI do Docker para autenticar o registo privado de contentoresUse the Docker CLI to authenticate the private container registry

Pode autenticar-se com o registo privado de contentores para recipientes de serviços cognitivos de qualquer forma, mas o método recomendado pela linha de comando é utilizar o Docker CLI.You can authenticate with the private container registry for Cognitive Services Containers in any of several ways, but the recommended method from the command line is to use the Docker CLI.

Utilize o docker login comando, como mostra o exemplo seguinte, para iniciar sessão containerpreview.azurecr.io no registo privado de contentores para recipientes de serviços cognitivos.Use the docker login command, as shown in the following example, to log in to containerpreview.azurecr.io, the private container registry for Cognitive Services Containers. Substitua <username> pelo nome de utilizador e pela <password> palavra-passe fornecida nas credenciais que recebeu da equipa dos Serviços Cognitivos da Azure.Replace <username> with the user name and <password> with the password that's provided in the credentials you received from the Azure Cognitive Services team.

docker login containerpreview.azurecr.io -u <username> -p <password>

Se tiver assegurado as suas credenciais num ficheiro de texto, pode concatenar o conteúdo desse ficheiro de texto, utilizando o cat comando, para o docker login comando, como mostra o exemplo seguinte.If you've secured your credentials in a text file, you can concatenate the contents of that text file, by using the cat command, to the docker login command, as shown in the following example. <passwordFile> Substitua-o pelo caminho e nome do ficheiro de texto que contém a palavra-passe e <username> pelo nome de utilizador fornecido nas suas credenciais.Replace <passwordFile> with the path and name of the text file that contains the password and <username> with the user name that's provided in your credentials.

cat <passwordFile> | docker login containerpreview.azurecr.io -u <username> --password-stdin

Instale o recipienteInstall the container

Existem várias formas de instalar e executar o recipiente.There are multiple ways you can install and run the container.

  • Utilize o portal Azure para criar um recurso Text Analytics e use o Docker para obter o seu recipiente.Use the Azure portal to create a Text Analytics resource, and use Docker to get your container.
  • Utilize os seguintes scripts PowerShell e Azure CLI para automatizar a configuração do contentor de implantação de recursos.Use the following PowerShell and Azure CLI scripts to automate resource deployment container configuration.

Instale o recipiente utilizando a Azure Web App para contentoresInstall the container using Azure Web App for Containers

A azure Web App for Containers é um recurso Azure dedicado a executar contentores na nuvem.Azure Web App for Containers is an Azure resource dedicated to running containers in the cloud. Traz capacidades fora da caixa, tais como autoscaling, suporte de contentores estivadores e composição de estiva, suporte HTTPS e muito mais.It brings out-of-the-box capabilities such as autoscaling, support of docker containers and docker compose, HTTPS support and much more.

Nota

Utilizando a App Web Azure, obterá automaticamente um domínio sob a forma de <appservice_name>.azurewebsites.netUsing Azure Web App you will automatically get a domain in the form of <appservice_name>.azurewebsites.net

Execute este script PowerShell utilizando o CLI Azure para criar uma Aplicação Web para Contentores, utilizando a sua subscrição e a imagem do recipiente em HTTPS.Run this PowerShell script using the Azure CLI to create a Web App for Containers, using your subscription and the container image over HTTPS. Aguarde que o script esteja completo (aproximadamente 25-30 minutos) antes de submeter o primeiro pedido.Wait for the script to complete (approximately 25-30 minutes) before submitting the first request.

$subscription_name = ""                    # THe name of the subscription you want you resource to be created on.
$resource_group_name = ""                  # The name of the resource group you want the AppServicePlan
                                           #    and AppSerivce to be attached to.
$resources_location = ""                   # This is the location you wish the AppServicePlan to be deployed to.
                                           #    You can use the "az account list-locations -o table" command to
                                           #    get the list of available locations and location code names.
$appservice_plan_name = ""                 # This is the AppServicePlan name you wish to have.
$appservice_name = ""                      # This is the AppService resource name you wish to have.
$TEXT_ANALYTICS_RESOURCE_API_KEY = ""      # This should be taken from the Text Analytics resource.
$TEXT_ANALYTICS_RESOURCE_API_ENDPOINT = "" # This should be taken from the Text Analytics resource.
$DOCKER_REGISTRY_SERVER_PASSWORD = ""      # This will be provided separately.
$DOCKER_REGISTRY_SERVER_USERNAME = ""      # This will be provided separately.
$DOCKER_IMAGE_NAME = "containerpreview.azurecr.io/microsoft/cognitive-services-healthcare:latest"

az login
az account set -s $subscription_name
az appservice plan create -n $appservice_plan_name -g $resource_group_name --is-linux -l $resources_location --sku P3V2
az webapp create -g $resource_group_name -p $appservice_plan_name -n $appservice_name -i $DOCKER_IMAGE_NAME -s $DOCKER_REGISTRY_SERVER_USERNAME -w $DOCKER_REGISTRY_SERVER_PASSWORD
az webapp config appsettings set -g $resource_group_name -n $appservice_name --settings Eula=accept Billing=$TEXT_ANALYTICS_RESOURCE_API_ENDPOINT ApiKey=$TEXT_ANALYTICS_RESOURCE_API_KEY

# Once deployment complete, the resource should be available at: https://<appservice_name>.azurewebsites.net

Instale o recipiente utilizando a instância do contentor AzureInstall the container using Azure Container Instance

Também pode utilizar uma Instância de Contentores Azure (ACI) para facilitar a implantação.You can also use an Azure Container Instance (ACI) to make deployment easier. O ACI é um recurso que permite executar contentores Docker a pedido num ambiente Azure gerido e sem servidor.ACI is a resource that allows you to run Docker containers on-demand in a managed, serverless Azure environment.

Veja como utilizar as instâncias do contentor Azure para etapas na implantação de um recurso ACI utilizando o portal Azure.See How to use Azure Container Instances for steps on deploying an ACI resource using the Azure portal. Também pode utilizar o script abaixo do PowerShell utilizando o Azure CLI, que criará um ACI na sua subscrição utilizando a imagem do recipiente.You can also use the below PowerShell script using Azure CLI, which will create a ACI on your subscription using the container image. Aguarde que o script esteja completo (aproximadamente 25-30 minutos) antes de submeter o primeiro pedido.Wait for the script to complete (approximately 25-30 minutes) before submitting the first request. Devido ao limite do número máximo de CPUs por recurso ACI, não selecione esta opção se espera submeter mais de 5 documentos grandes (aproximadamente 5000 caracteres cada) por pedido.Due to the limit on the maximum number of CPUs per ACI resource, do not select this option if you expect to submit more than 5 large documents (approximately 5000 characters each) per request. Consulte o artigo de apoio regional da ACI para obter informações sobre a disponibilidade.See the ACI regional support article for availability information.

Nota

As instâncias do recipiente Azure não incluem suporte HTTPS para os domínios construídos.Azure Container Instances don't include HTTPS support for the builtin domains. Se precisar de HTTPS, terá de o configurar manualmente, incluindo a criação de um certificado e o registo de um domínio.If you need HTTPS, you will need to manually configure it, including creating a certificate and registering a domain. Pode encontrar instruções para o fazer com o NGINX abaixo.You can find instructions to do this with NGINX below.

$subscription_name = ""                    # The name of the subscription you want you resource to be created on.
$resource_group_name = ""                  # The name of the resource group you want the AppServicePlan
                                           # and AppService to be attached to.
$resources_location = ""                   # This is the location you wish the web app to be deployed to.
                                           # You can use the "az account list-locations -o table" command to
                                           # Get the list of available locations and location code names.
$azure_container_instance_name = ""        # This is the AzureContainerInstance name you wish to have.
$TEXT_ANALYTICS_RESOURCE_API_KEY = ""      # This should be taken from the Text Analytics resource.
$TEXT_ANALYTICS_RESOURCE_API_ENDPOINT = "" # This should be taken from the Text Analytics resource.
$DOCKER_REGISTRY_SERVER_PASSWORD = ""      # This will be provided separately.
$DOCKER_REGISTRY_SERVER_USERNAME = ""      # This will be provided separately.
$DNS_LABEL = ""                            # This is the DNS label name you wish your ACI will have
$DOCKER_REGISTRY_LOGIN_SERVER = "containerpreview.azurecr.io"
$DOCKER_IMAGE_NAME = "containerpreview.azurecr.io/microsoft/cognitive-services-healthcare:latest"

az login
az account set -s $subscription_name
az container create --resource-group $resource_group_name --name $azure_container_instance_name --image $DOCKER_IMAGE_NAME --cpu 4 --memory 12 --registry-login-server $DOCKER_REGISTRY_LOGIN_SERVER --registry-username $DOCKER_REGISTRY_SERVER_USERNAME --registry-password $DOCKER_REGISTRY_SERVER_PASSWORD --port 5000 --dns-name-label $DNS_LABEL --environment-variables Eula=accept Billing=$TEXT_ANALYTICS_RESOURCE_API_ENDPOINT ApiKey=$TEXT_ANALYTICS_RESOURCE_API_KEY

# Once deployment complete, the resource should be available at: http://<unique_dns_label>.<resource_group_region>.azurecontainer.io:5000

Conectividade ACI seguraSecure ACI connectivity

Por predefinição, não existe qualquer garantia quando se utiliza a ACI com API de contentores.By default there is no security provided when using ACI with container API. Isto porque normalmente os contentores funcionam como parte de uma cápsula que é protegida do exterior por uma ponte de rede.This is because typically containers will run as part of a pod which is protected from the outside by a network bridge. No entanto, pode modificar um recipiente com um componente frontal, mantendo o ponto final do recipiente em privado.You can however modify a container with a front-facing component, keeping the container endpoint private. Os exemplos a seguir usam o NGINX como porta de entrada para suportar a autenticação HTTPS/SSL e o certificado de cliente.The following examples use NGINX as an ingress gateway to support HTTPS/SSL and client-certificate authentication.

Nota

NGINX é um servidor HTTP de código aberto e de alto desempenho e procuração.NGINX is an open-source, high-performance HTTP server and proxy. Um recipiente NGINX pode ser utilizado para pôr termo a uma ligação TLS para um único recipiente.An NGINX container can be used to terminate a TLS connection for a single container. São também possíveis soluções de rescisão TLS baseadas em ingresss em NGINX mais complexas.More complex NGINX ingress-based TLS termination solutions are also possible.

Configurar o NGINX como um portal de entradaSet up NGINX as an ingress gateway

O NGINX utiliza ficheiros de configuração para ativar funcionalidades em tempo de execução.NGINX uses configuration files to enable features at runtime. Para permitir a rescisão de TLS para outro serviço, deve especificar um certificado SSL para encerrar a ligação TLS e proxy_pass especificar um endereço para o serviço.In order to enable TLS termination for another service, you must specify an SSL certificate to terminate the TLS connection and proxy_pass to specify an address for the service. Uma amostra é fornecida abaixo.A sample is provided below.

Nota

ssl_certificate espera que um caminho seja especificado dentro do sistema de ficheiros local do contentor NGINX.ssl_certificate expects a path to be specified within the NGINX container's local filesystem. O endereço especificado proxy_pass deve estar disponível na rede do contentor NGINX.The address specified for proxy_pass must be available from within the NGINX container's network.

O recipiente NGINX carregará todos os ficheiros no _.conf_ que são montados /etc/nginx/conf.d/ no caminho de configuração HTTP.The NGINX container will load all of the files in the _.conf_ that are mounted under /etc/nginx/conf.d/ into the HTTP configuration path.

server {
  listen              80;
  return 301 https://$host$request_uri;
}
server {
  listen              443 ssl;
  # replace with .crt and .key paths
  ssl_certificate     /cert/Local.crt;
  ssl_certificate_key /cert/Local.key;

  location / {
    proxy_pass http://cognitive-service:5000;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP  $remote_addr;
  }
}

Exemplo Docker compor arquivoExample Docker compose file

O exemplo abaixo mostra como um ficheiro de composição de estiva pode ser criado para implantar o NGINX e o Text Analytics para recipientes de saúde:The below example shows how a docker compose file can be created to deploy the NGINX and Text Analytics for health containers:

version: "3.7"
services:
  cognitive-service:
    image: {IMAGE_ID}
    ports:
      - 5000:5000
    environment:
      - eula=accept
      - billing={ENDPOINT_URI}
      - apikey={API_KEY}
      - Logging:Disk:Format=json
    volumes:
        # replace with path to logs folder
      - <path-to-logs-folder>:/output
  nginx:
    image: nginx
    ports:
      - 443:443
    volumes:
        # replace with paths for certs and conf folders
      - <path-to-certs-folder>:/cert
      - <path-to-conf-folder>:/etc/nginx/conf.d/

Para iniciar este ficheiro de composição do Docker, execute o seguinte comando a partir de uma consola ao nível da raiz do ficheiro:To initiate this Docker compose file, execute the following command from a console at the root level of the file:

docker-compose up

Para mais informações, consulte a documentação da NGINX sobre a rescisão do NGINX SSL.For more information, see NGINX's documentation on NGINX SSL Termination.

Exemplo pedido de APIExample API request

O contentor fornece APIs de ponto final de predição de consulta com base em REST.The container provides REST-based query prediction endpoint APIs. Também fornecemos uma ferramenta de visualização no recipiente que é acessível por anexar a demonstração ao ponto final do recipiente, por exemplo:We have also provided a visualization tool in the container that is accessible by appending the demo to the endpoint of the container for example:

http://<serverURL>:5000/demo

Utilize o pedido de cURL de exemplo abaixo para submeter uma consulta ao recipiente que implementou substituindo a serverURL variável pelo valor adequado.Use the example cURL request below to submit a query to the container you have deployed replacing the serverURL variable with the appropriate value.

curl -X POST 'http://<serverURL>:5000/text/analytics/v3.2-preview.1/entities/health' --header 'Content-Type: application/json' --header 'accept: application/json' --data-binary @example.json

O seguinte JSON é um exemplo de um ficheiro JSON anexado ao Text Analytics para o corpo POSTAL do pedido de API de saúde:The following JSON is an example of a JSON file attached to the Text Analytics for health API request's POST body:

example.json

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Patient reported itchy sores after swimming in the lake."
    },
    {
      "language": "en",
      "id": "2",
      "text": "Prescribed 50mg benadryl, taken twice daily."
    }
  ]
}

Corpo de resposta da APIAPI response body

O seguinte JSON é um exemplo do Text Analytics para o organismo de resposta da API em saúde:The following JSON is an example of the Text Analytics for health API response body:

{
    "documents": [
        {
            "id": "1",
            "entities": [
                {
                    "id": "0",
                    "offset": 17,
                    "length": 11,
                    "text": "itchy sores",
                    "category": "SymptomOrSign",
                    "confidenceScore": 1.0,
                    "isNegated": false
                }
            ]
        },
        {
            "id": "2",
            "entities": [
                {
                    "id": "0",
                    "offset": 11,
                    "length": 4,
                    "text": "50mg",
                    "category": "Dosage",
                    "confidenceScore": 1.0,
                    "isNegated": false
                },
                {
                    "id": "1",
                    "offset": 16,
                    "length": 8,
                    "text": "benadryl",
                    "category": "MedicationName",
                    "confidenceScore": 1.0,
                    "isNegated": false,
                    "links": [
                        {
                            "dataSource": "UMLS",
                            "id": "C0700899"
                        },
                        {
                            "dataSource": "CHV",
                            "id": "0000044903"
                        },
                        {
                            "dataSource": "MMSL",
                            "id": "899"
                        },
                        {
                            "dataSource": "MSH",
                            "id": "D004155"
                        },
                        {
                            "dataSource": "NCI",
                            "id": "C300"
                        },
                        {
                            "dataSource": "NCI_DTP",
                            "id": "NSC0033299"
                        },
                        {
                            "dataSource": "PDQ",
                            "id": "CDR0000039163"
                        },
                        {
                            "dataSource": "PSY",
                            "id": "05760"
                        },
                        {
                            "dataSource": "RXNORM",
                            "id": "203457"
                        }
                    ]
                },
                {
                    "id": "2",
                    "offset": 32,
                    "length": 11,
                    "text": "twice daily",
                    "category": "Frequency",
                    "confidenceScore": 1.0,
                    "isNegated": false
                }
            ],
            "relations": [
                {
                    "relationType": "DosageOfMedication",
                    "bidirectional": false,
                    "source": "#/documents/1/entities/0",
                    "target": "#/documents/1/entities/1"
                },
                {
                    "relationType": "FrequencyOfMedication",
                    "bidirectional": false,
                    "source": "#/documents/1/entities/2",
                    "target": "#/documents/1/entities/1"
                }
            ]
        }
    ],
    "errors": [],
    "modelVersion": "2020-07-24"
}

Saída de deteção de negaçãoNegation detection output

Ao utilizar a deteção de negação, em alguns casos, um único termo de negação pode abordar vários termos ao mesmo tempo.When using negation detection, in some cases a single negation term may address several terms at once. A negação de uma entidade reconhecida está representada na produção JSON pelo valor booleano da isNegated bandeira:The negation of a recognized entity is represented in the JSON output by the boolean value of the isNegated flag:

{
  "id": "2",
  "offset": 90,
  "length": 10,
  "text": "chest pain",
  "category": "SymptomOrSign",
  "score": 0.9972,
  "isNegated": true,
  "links": [
    {
      "dataSource": "UMLS",
      "id": "C0008031"
    },
    {
      "dataSource": "CHV",
      "id": "0000023593"
    },
    ...

Saída de extração de relaçãoRelation extraction output

A saída de extração de relação contém referências URI à origem da relação, e o seu alvo.Relation extraction output contains URI references to the source of the relation, and its target. As entidades com o papel de relação ENTITY são atribuídas ao target campo.Entities with relation role of ENTITY are assigned to the target field. As entidades com o papel de relação ATTRIBUTE são atribuídas ao source campo.Entities with relation role of ATTRIBUTE are assigned to the source field. As relações de abreviatura contêm campos e campos bidirecionais, source target e bidirectional serão definidas para true .Abbreviation relations contain bidirectional source and target fields, and bidirectional will be set to true.

"relations": [
                {
                    "relationType": "DosageOfMedication",
                    "bidirectional": false,
                    "source": "#/documents/1/entities/0",
                    "target": "#/documents/1/entities/1"
                },
                {
                    "relationType": "FrequencyOfMedication",
                    "bidirectional": false,
                    "source": "#/documents/1/entities/2",
                    "target": "#/documents/1/entities/1"
                }
            ]
  },
...
]

Ver tambémSee also