Detetar e redigir informações de identificação pessoal em conversas

A API PII de conversação da Linguagem de IA do Azure analisa o discurso de áudio para identificar e redigir informações confidenciais (PII) usando várias categorias predefinidas. Esta API funciona tanto em texto transcrito (referido como transcrições) como em chats. Para transcrições, ele também facilita a edição de segmentos de áudio contendo PII, fornecendo as informações de tempo para esses segmentos.

Determinar como processar os dados (opcional)

Especificar o modelo de deteção de PII

Por padrão, esse recurso usa o modelo de IA mais recente disponível em sua entrada. Você também pode configurar suas solicitações de API para usar uma versão de modelo específica.

Suporte de idiomas

Para obter mais informações, consulte a página PII Language Support. Atualmente, o modelo PII GA conversacional suporta apenas a língua inglesa. O modelo de visualização e a API suportam os mesmos idiomas da lista que os outros serviços de idiomas.

Suporte de região

A API PII conversacional dá suporte a todas as regiões do Azure suportadas pelo serviço de idiomas.

Envio de dados

Você pode enviar a entrada para a API como lista de itens de conversa. A análise é realizada aquando da receção do pedido. Como a API é assíncrona, pode haver um atraso entre o envio de uma solicitação de API e o recebimento dos resultados. Para obter informações sobre o tamanho e o número de solicitações que você pode enviar por minuto e segundo, consulte os seguintes limites de dados.

Quando você usa o recurso assíncrono, os resultados da API ficam disponíveis por 24 horas a partir do momento em que a solicitação foi ingerida e são indicados na resposta. Após esse período de tempo, os resultados são limpos e não estão mais disponíveis para recuperação.

Ao enviar dados para PII conversacional, você pode enviar uma conversa (chat ou falada) por solicitação.

A API tenta detetar todas as categorias de entidades definidas para uma entrada de conversa específica. Se desejar especificar quais entidades serão detetadas e retornadas, use o parâmetro opcional piiCategories com as categorias de entidades apropriadas.

Para transcrições faladas, as entidades detetadas são retornadas no valor do parâmetro redactionSource fornecido. Atualmente, os valores suportados para redactionSource são text, lexical, itne maskedItn (que mapeia para o formato de display\displayTextda API REST de fala para texto, lexical, itne maskedItn, respectivamente). Além disso, para a entrada de transcrição falada, essa API também fornece informações de temporização de áudio para habilitar a redação de áudio. Para usar a funcionalidade audioRedaction, use o sinalizador includeAudioRedaction opcional com o valor true. A redação de áudio é realizada com base no formato de entrada lexical.

Observação

A PII de conversação agora suporta 40.000 caracteres como tamanho do documento.

Obtendo resultados de PII

Quando você obtém resultados da deteção de PII, pode transmitir os resultados para um aplicativo ou salvar a saída em um arquivo no sistema local. A resposta da API inclui entidades reconhecidas, incluindo suas categorias e subcategorias, e pontuações de confiança. A cadeia de caracteres de texto com as entidades PII editadas também é retornada.

Exemplos

bibliotecas de cliente (SDK do Azure)

1. Vá para a página de visão geral do recurso no portal do Azure

2. No menu do lado esquerdo, selecione Chaves e Endpoint. Você precisa de uma das chaves e do endpoint para autenticar as suas solicitações de API.

3. Transfira e instale o pacote de biblioteca de cliente para o idioma da sua escolha:

   Idioma	Versão do pacote
   .NET	1.0.0
   Python	1.0.0

4. Para obter mais informações sobre o cliente e o objeto de retorno, consulte a seguinte documentação de referência:

   • C#
   • Python

API REST

Política de Redação (somente versão 2024-11-15-preview )

Na versão 2024-11-15-preview, você pode definir o parâmetro redactionPolicy para refletir a política de redação a ser usada ao redigir o documento na resposta. O domínio de intervenção abrange três tipos de políticas:

• noMask
• characterMask (padrão)
• entityMask

A política de noMask permite que o usuário retorne a resposta sem o campo redactedText.

A política de characterMask permite que o redactedText seja mascarado com um caractere, preservando o comprimento e o deslocamento do texto original. Este comportamento é a expectativa existente.

Há também um campo opcional chamado redactionCharacter onde você pode inserir o caractere a ser usado na redação se estiver usando a characterMask política

A política de entityMask permite mascarar o texto da entidade PII detetada com o tipo de entidade detetada

Use o exemplo a seguir se quiser alterar a política de redação.

curl -i -X POST https://your-language-endpoint-here/language/analyze-conversations/jobs?api-version=2024-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: your-key-here" \
-d \
'
{
    "displayName": "Analyze conversations from xxx",
    "analysisInput": {
        "conversations": [
            {
                "id": "23611680-c4eb-4705-adef-4aa1c17507b5",
                "language": "en",
                "modality": "text",
                "conversationItems": [
                    {
                        "participantId": "agent_1",
                        "id": "1",
                        "text": "Good morning."
                    },
                    {
                        "participantId": "agent_1",
                        "id": "2",
                        "text": "Can I have your name?"
                    },
                    {
                        "participantId": "customer_1",
                        "id": "3",
                        "text": "Sure that is John Doe."
                    }
                ]
            }
        ]
    },
    "tasks": [
        {
            "taskName": "analyze 1",
            "kind": "ConversationalPIITask",
            "parameters": {
                "modelVersion": "2023-04-15-preview",
                "redactionCharacter"
                "redactionPolicy": {
                    "policyKind": "characterMask",
                    //characterMask|entityMask|noMask
                    "redactionCharacter": "*"
                }
            }
        }
    ]
}
`

Enviar transcrições usando fala para texto

Usa o exemplo seguinte se tiveres conversas transcritas usando o recurso de fala para texto do serviço de fala .

curl -i -X POST https://your-language-endpoint-here/language/analyze-conversations/jobs?api-version=2024-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: your-key-here" \
-d \
'
{
    "displayName": "Analyze conversations from xxx",
    "analysisInput": {
        "conversations": [
            {
                "id": "23611680-c4eb-4705-adef-4aa1c17507b5",
                "language": "en",
                "modality": "transcript",
                "conversationItems": [
                    {
                        "participantId": "agent_1",
                        "id": "8074caf7-97e8-4492-ace3-d284821adacd",
                        "text": "Good morning.",
                        "lexical": "good morning",
                        "itn": "good morning",
                        "maskedItn": "good morning",
                        "audioTimings": [
                            {
                                "word": "good",
                                "offset": 11700000,
                                "duration": 2100000
                            },
                            {
                                "word": "morning",
                                "offset": 13900000,
                                "duration": 3100000
                            }
                        ]
                    },
                    {
                        "participantId": "agent_1",
                        "id": "0d67d52b-693f-4e34-9881-754a14eec887",
                        "text": "Can I have your name?",
                        "lexical": "can i have your name",
                        "itn": "can i have your name",
                        "maskedItn": "can i have your name",
                        "audioTimings": [
                            {
                                "word": "can",
                                "offset": 44200000,
                                "duration": 2200000
                            },
                            {
                                "word": "i",
                                "offset": 46500000,
                                "duration": 800000
                            },
                            {
                                "word": "have",
                                "offset": 47400000,
                                "duration": 1500000
                            },
                            {
                                "word": "your",
                                "offset": 49000000,
                                "duration": 1500000
                            },
                            {
                                "word": "name",
                                "offset": 50600000,
                                "duration": 2100000
                            }
                        ]
                    },
                    {
                        "participantId": "customer_1",
                        "id": "08684a7a-5433-4658-a3f1-c6114fcfed51",
                        "text": "Sure that is John Doe.",
                        "lexical": "sure that is john doe",
                        "itn": "sure that is john doe",
                        "maskedItn": "sure that is john doe",
                        "audioTimings": [
                            {
                                "word": "sure",
                                "offset": 5400000,
                                "duration": 6300000
                            },
                            {
                                "word": "that",
                                "offset": 13600000,
                                "duration": 2300000
                            },
                            {
                                "word": "is",
                                "offset": 16000000,
                                "duration": 1300000
                            },
                            {
                                "word": "john",
                                "offset": 17400000,
                                "duration": 2500000
                            },
                            {
                                "word": "doe",
                                "offset": 20000000,
                                "duration": 2700000
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "tasks": [
        {
            "taskName": "analyze 1",
            "kind": "ConversationalPIITask",
            "parameters": {
                "modelVersion": "2023-04-15-preview",
                "redactionSource": "text",
                "includeAudioRedaction": true,
                "piiCategories": [
                    "all"
                ]
            }
        }
    ]
}
`

Enviar chats de texto

Use o exemplo a seguir se você tiver conversas originadas em texto. Por exemplo, conversas através de um cliente de chat baseado em texto.

curl -i -X POST https://your-language-endpoint-here/language/analyze-conversations/jobs?api-version=2024-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: your-key-here" \
-d \
'
{
    "displayName": "Analyze conversations from xxx",
    "analysisInput": {
        "conversations": [
            {
                "id": "23611680-c4eb-4705-adef-4aa1c17507b5",
                "language": "en",
                "modality": "text",
                "conversationItems": [
                    {
                        "participantId": "agent_1",
                        "id": "8074caf7-97e8-4492-ace3-d284821adacd",
                        "text": "Good morning."
                    },
                    {
                        "participantId": "agent_1",
                        "id": "0d67d52b-693f-4e34-9881-754a14eec887",
                        "text": "Can I have your name?"
                    },
                    {
                        "participantId": "customer_1",
                        "id": "08684a7a-5433-4658-a3f1-c6114fcfed51",
                        "text": "Sure that is John Doe."
                    }
                ]
            }
        ]
    },
    "tasks": [
        {
            "taskName": "analyze 1",
            "kind": "ConversationalPIITask",
            "parameters": {
                "modelVersion": "2023-04-15-preview"
            }
        }
    ]
}
`

Obter o resultado

Obtenha o operation-location a partir do cabeçalho da resposta. O valor é semelhante ao seguinte URL:

https://your-language-endpoint/language/analyze-conversations/jobs/12345678-1234-1234-1234-12345678

Para obter os resultados da solicitação, use o seguinte comando cURL. Certifique-se de substituir my-job-id pelo valor de ID numérico que você recebeu do cabeçalho de resposta anterior operation-location :

curl -X GET    https://your-language-endpoint/language/analyze-conversations/jobs/my-job-id \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: your-key-here"

Limites de serviço e dados

Para obter informações sobre o tamanho e o número de solicitações que você pode enviar por minuto e segundo, consulte o artigo Limites de serviço.