Habilidade AML em um pipeline de enriquecimento da IA do Azure Search

  • Artigo

Importante

A habilidade cognitiva está em versão prévia pública sob os termos de uso complementares. A versão prévia da API REST dá suporte a essa habilidade.

A habilidade AML permite estender o enriquecimento de IA com um modelo AML (Azure Machine Learning) personalizado. Depois que um modelo AML é treinado e implantado, uma habilidade AML o integra ao enriquecimento de IA.

Assim como as habilidades criadas, uma habilidade AML tem entradas e saídas. As entradas são enviadas para o ponto de extremidade online do AML implantado como um objeto JSON, que gera uma saída JSON como uma resposta junto com um código de status de êxito. A resposta deve ter as saídas especificadas pela sua habilidade AML personalizada. Qualquer outra resposta é considerada um erro e nenhum aprimoramento é executado.

Observação

O indexador tentará novamente duas vezes determinados códigos de status HTTP padrão retornados do ponto de extremidade online do AML. Esses códigos de status HTTP são:

  • 503 Service Unavailable
  • 429 Too Many Requests

Pré-requisitos

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parâmetros de habilidades

Os parâmetros diferenciam maiúsculas de minúsculas. Quais parâmetros você optar por usar dependem de qual autenticação seu ponto de extremidade online do AML requer, se houver

Nome do parâmetro Descrição
uri (Necessário para autenticação de chave) O URI de pontuação do ponto de extremidade online do AML para o qual o payload JSON é enviado. Somente o esquema do URI https é permitido.
key (Necessário para autenticação de chave) A chave para o ponto de extremidade online do AML.
resourceId (Necessário para autenticação de token). A ID de recurso Azure Resource Manager do ponto de extremidade online do AML. Ele deve estar no formato assinaturas/{GUID}/resourceGroups/{nome-do-grupo-de-recursos}/Microsoft. MachineLearningServices/Workspaces/{Workspace-Name}/onlineendpoints/{endpoint_name}.
region (Opcional para autenticação de token). A região o ponto de extremidade online do AML é implantado.
timeout (Opcional) Quando especificado, indica o tempo limite para o cliente http que fez a chamada à API. Ele deve ser formatado como um valor XSD de "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601 ). Por exemplo, PT60S por 60 segundos. Se não for definido, um valor padrão de 30 segundos será escolhido. O tempo limite pode ser definido para um máximo de 230 segundos e um mínimo de 1 segundo.
degreeOfParallelism (Opcional) Quando especificado, indica o número de chamadas que o indexador faz em paralelo ao ponto de extremidade que você forneceu. Diminuía esse valor se o ponto de extremidade estiver falhando em uma carga de solicitação muito alta. É possível acioná-lo se o ponto de extremidade poder aceitar mais solicitações e quiser um aumento no desempenho do indexador. Se não for definido, um valor padrão de 5 segundos será usado. O degreeOfParallelism pode ser definido como um máximo de 10 e um mínimo de 1.

Quais parâmetros de habilidade usar

Os parâmetros de habilidade de AML necessários dependem de qual autenticação seu ponto de extremidade online do AML usa, se houver. Os pontos de extremidade online do AML fornecem duas opções de autenticação:

  • Autenticação baseada em chave. Uma chave estática é fornecida para autenticar solicitações de Pontuação de habilidades AML
    • Usar os parâmetros de URI e chave
  • Autenticação baseada em token. O ponto de extremidade online do AML é implantado usando a autenticação baseada em token. A identidade gerenciada do serviço de IA do Azure Search deve estar habilitado. Em seguida, a habilidade AML usa a identidade gerenciada do serviço para se autenticar no ponto de extremidade online do AML, sem a necessidade de chaves estáticas. A identidade deve ser atribuída ao proprietário ou à função de colaborador.
    • Use o parâmetro resourceId .
    • Caso o serviço de pesquisa esteja em uma região diferente do espaço de trabalho do AML, use o parâmetro região para definir a região em que o ponto de extremidade online do AML foi implantado

Entradas de habilidades

Não há nenhuma entrada "predefinida" para essa habilidade. Escolha um ou mais campos que já estariam disponíveis no momento da execução dessa habilidade, como entradas e o conteúdo JSON enviada para o ponto de extremidade online do AML terá campos diferentes.

Saídas de habilidades

Não há nenhuma saída "predefinida" para essa habilidade. Dependendo da resposta que seu ponto de extremidade online do AML retorna, adicione campos de saída para que eles possam ser retirados da resposta JSON.

Definição de exemplo

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Estrutura JSON de entrada de exemplo

Essa estrutura JSON representa o conteúdo enviado ao ponto de extremidade online do AML. Os campos da propriedade correspondem a “nomes” especificados na seção inputs da definição de habilidade. Os valores desses campos são da source desses campos (que poderia ser de um campo no documento ou potencialmente de outra habilidade)

{
  "text": "Este es un contrato en Inglés"
}

Estrutura JSON de saída de exemplo

A saída corresponde à resposta retornada de seu ponto de extremidade online do AML. O ponto de extremidade online do AML deve retornar apenas uma carga JSON (verificada observando o cabeçalho de resposta Content-Type) e deve ser um objeto em que os campos são aprimoramentos que correspondem aos “nomes” no output e cujo valor é considerado o enriquecimento.

{
    "detected_language_code": "es"
}

Definição de amostra de shaping embutida

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Estrutura JSON de entrada de shaping embutida

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Estrutura JSON de saída de exemplo de shaping embutida

{
    "detected_language_code": "es"
}

Casos de erro

Além de seu AML estar indisponível ou de enviar códigos de status mal-sucedidos, os seguintes são considerados casos errados:

  • Caso o ponto de extremidade online do AML retorne um código de status de êxito, mas a resposta indicar que não é application/json, a resposta será considerada inválida e nenhum aprimoramento será executado.
  • Se o ponto de extremidade online do AML retornar json inválido

Para casos em que o ponto de extremidade online do AML não está disponível ou retorna um erro de HTTP, um erro amigável com todos os detalhes disponíveis sobre o erro HTTP será adicionado ao histórico de execução do indexador.

Confira também