Como detetar e redigir Informações de Identificação Pessoal (PII) em conversas

O recurso PII conversacional pode avaliar conversas para extrair informações confidenciais (PII) no conteúdo em várias categorias predefinidas e editá-las. Esta API opera tanto em texto transcrito (referenciado como transcrições) como chats. Para transcrições, a API também permite a edição de segmentos de áudio, que contém as informações de PII, fornecendo as informações de temporização de áudio para esses segmentos de áudio.

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

Consulte a página PII Language Support para obter mais detalhes. Atualmente, o modelo PII GA conversacional suporta apenas a língua inglesa. O modelo de visualização e a API suportam os mesmos idiomas de 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

Nota

Consulte o artigo do Language Studio para obter informações sobre como formatar texto de conversação para enviar usando o Language Studio.

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 limites de dados abaixo.

Ao usar 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 entidade definidas para uma determinada entrada de conversa. 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 redactionSource parâmetro fornecido. Atualmente, os valores suportados para são , , , e maskedItn (que mapeia para Fala para texto APIs REST , display\displayText, e maskedItn formato, itn lexicalrespectivamente). itnlexicaltextredactionSource 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 o recurso audioRedaction, use o sinalizador opcional includeAudioRedaction com true valor. A redação de áudio é realizada com base no formato de entrada lexical.

Nota

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 dos recursos no portal do Azure

2. No menu do lado esquerdo, selecione Teclas e Ponto de extremidade. Você precisará de uma das chaves e do ponto de extremidade para autenticar suas solicitações de API.

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

   Idioma	Versão de pacote
   .NET	1.0.0
   Python	1.0.0

4. Consulte a documentação de referência a seguir para obter mais informações sobre o cliente e o objeto de retorno:

   • 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 redactionPolicy parâmetro para refletir a política de redação a ser usada ao redigir o documento na resposta. O campo de política suporta 3 tipos de políticas:

• noMask
• characterMask (padrão)
• entityMask

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

A characterMask política permite que o redactedText personagem seja mascarado, preservando o comprimento e o deslocamento do texto original. Este é o comportamento 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 entityMask política 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

Use o exemplo a seguir se você tiver 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 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.