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

Use a habilidade de AML para estender o enriquecimento de IA com um modelo de inserção base implantado do catálogo de modelos do Azure AI Foundry ou um modelo AML ( Azure Machine Learning ) personalizado. Depois que um modelo AML é treinado e implantado, a habilidade AML integra o modelo em um conjunto de habilidades.

Uso de habilidades AML

Como outras habilidades integradas, uma habilidade AML personalizada tem entradas e saídas. As entradas são enviadas para um endpoint online AML implantado como um objeto JSON. A saída do ponto de extremidade deve ser uma carga JSON na resposta, juntamente 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 fornecer as saídas especificadas pela definição de habilidade de AML . Qualquer outra resposta é considerada um erro e nenhum enriquecimento é executado.

Você pode chamar a habilidade de AML com a versão estável da API REST ou um SDK do Azure equivalente. Para conexões com o catálogo de modelos no portal do Azure AI Foundry, use uma versão prévia da API.

Habilidade AML para modelos no Azure AI Foundry

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

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, você deve usar a habilidade AML e o vetorizador de catálogo de modelos juntos para que o mesmo modelo de inserção seja usado para indexação e consultas. Para obter mais informações, incluindo uma lista de modelos de inserção com suporte, consulte Usar modelos de inserção do catálogo de modelos do Azure AI Foundry.

É recomendável usar o assistente Importar dados (novos) para gerar um conjunto de habilidades que inclui uma habilidade de AML para modelos de inserção implantados no Azure AI Foundry. O assistente gera a definição de habilidade AML para entradas, saídas e mapeamentos, fornecendo uma maneira fácil de testar um modelo antes de escrever qualquer código.

Pré-requisitos

• Um projeto do Azure AI Foundry para um modelo de inserção implantado no catálogo ou um workspace AML para um modelo personalizado criado.
• O ponto de extremidade de modelo para um modelo de inserção implantado no catálogo ou um ponto de extremidade online (em tempo real) do seu workspace AML para um modelo personalizado.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parâmetros de habilidades

Os parâmetros diferenciam maiúsculas de minúsculas. Os parâmetros usados dependem de qual autenticação o ponto de extremidade online do AML requer, se houver.

Autenticação

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. Defina os uri parâmetros e key para esta conexão.

• Autenticação baseada em token, em que o ponto de extremidade online AML é implantado usando a autenticação baseada em token. O serviço Azure AI Search deve ter uma identidade gerenciada e uma atribuição de função no workspace AML. 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 do serviço de pesquisa deve ter a função Proprietário ou Colaborador . Defina o resourceId parâmetro e, se o serviço de pesquisa estiver em uma região diferente do espaço de trabalho AML, defina o region parâmetro.

Entradas de habilidades

As entradas de habilidade são um nó do documento enriquecido criado durante a quebra de documento. Por exemplo, pode ser o documento raiz, uma imagem normalizada ou o conteúdo de um blob. Não há nenhuma entrada predefinida para essa habilidade. Para entradas, você deve especificar um ou mais nós que são preenchidos no momento da execução da habilidade AML.

Saídas de habilidades

As saídas de habilidade são novos nós de um documento enriquecido criado pela habilidade. Não há nenhuma saída predefinida para essa habilidade. Para saídas, você deve fornecer nós que possam ser preenchidos a partir da resposta JSON de sua habilidade AML.

Definição de exemplo

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.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 para o 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 das "fontes" desses campos, que podem ser de um campo no documento ou de outra habilidade.

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

Estrutura JSON de saída de exemplo

A saída corresponde à resposta do 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://language-model.models.contoso.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 enviar códigos de status sem sucesso, os seguintes casos são considerados erros:

• O ponto de extremidade online AML retorna um código de status de êxito, mas a resposta indica que não application/jsoné . Portanto, a resposta é inválida e nenhum enriquecimento é executado.

• O endpoint online AML retorna JSON inválido.

Se o ponto de extremidade online AML não estiver disponível ou retornar um erro HTTP, um erro amigável com quaisquer detalhes disponíveis sobre o erro HTTP será adicionado ao histórico de execução do indexador.

Confira também

• Criar um conjunto de habilidades na IA do Azure Search
• Usar modelos de inserção do catálogo de modelos do Azure AI Foundry
• Solucionar problemas de implantação e pontuação de ponto de extremidade online do Azure Machine Learning