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

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.

Como outras habilidades internas, uma habilidade de 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. Seus dados são processados na área geográfica em que o modelo é implantado. A resposta deve ter as saídas especificadas pela sua habilidade AML personalizada. Qualquer outra resposta é considerada um erro e nenhum aprimoramento é executado.

A habilidade AML pode ser chamada com a versão estável da API 2024-07-01 ou a versão da API 2024-05-01-preview para conexões com o catálogo de modelos no Azure AI Studio.

A partir da API REST de 2024-05-01-preview e no portal do Azure (que também tem como destino a versão prévia de 2024-05-01), o Azure AI Search introduziu o vetorizador de catálogo de modelos do Azure AI Studio para conexões de tempo de consulta com o catálogo de modelos no Azure AI Studio. Se você quiser usar esse vetorizador para consultas, a habilidade AML será a contrapartida de indexação para gerar inserções usando um modelo no catálogo de modelos do Azure AI Studio.

Durante a indexação, a habilidade AML pode se conectar ao catálogo de modelos para gerar vetores para o índice. No momento da consulta, as consultas podem usar um vetorizador para se conectar ao mesmo modelo para vetorizar cadeias de caracteres de texto para uma consulta vetorial. Neste fluxo de trabalho, a habilidade AML e o vetorizador de catálogo de modelos devem ser usados juntos para que você esteja usando o mesmo modelo de inserção para indexação e consultas. Consulte Como implementar a vetorização integrada usando modelos do Azure AI Studio para obter detalhes sobre esse fluxo de trabalho.

Pré-requisitos

• Um espaço de trabalho AML
• Um de pontos de extremidade Online (em tempo real) neste workspace.

@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

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

• Como definir um conjunto de qualificações
• Solução de problemas de ponto de extremidade online do AML
• Vetorização integrada com os modelos do Estúdio de IA do Azure