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

Artigo
12/18/2024

Importante

O suporte para conexões do indexador com o catálogo de modelos do Azure AI Foundry está em visualização pública sob termos de uso complementares. As APIs REST de visualização dão suporte a essa habilidade.

A habilidade AML permite estender o enriquecimento de IA com um modelo personalizado de AML (Azure Machine Learning) ou um modelo de inserção base implantado no Azure AI Foundry. Depois que um modelo AML é treinado e implantado, uma habilidade AML o integra a 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. Espera-se que a resposta forneça as saídas especificadas pela definição de habilidade AML . 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

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

Habilidade AML para modelos no Azure AI Foundry

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 fornece o vetorizador de 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, uma habilidade AML será a contrapartida de indexação para gerar inserções usando um modelo no catálogo de modelos do Azure AI Foundry.

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 Usar modelos de inserção do catálogo de modelos do Azure AI Foundry para obter detalhes e obter uma lista dos modelos de inserção com suporte.

É recomendável usar o assistente Importar e vetorizar dados para gerar um conjunto de habilidades que inclua uma habilidade AML para modelos de inserção implantados no Azure AI Foundry. A definição de habilidade AML para entradas, saídas e mapeamentos é gerada pelo assistente, que oferece uma maneira fácil de testar um modelo antes de escrever qualquer código.

Pré-requisitos

Um workspace AML para um modelo personalizado que você cria ou um projeto no Azure AI Foundry se um modelo de inserção for implantado do catálogo.
Um ponto de extremidade online (em tempo real) neste espaço de trabalho para um modelo personalizado ou o ponto de extremidade do modelo para inserir modelos implantados do catálogo.

@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. Para inserir modelos no catálogo de modelos do Azure AI Foundry, esse é o URI de destino.
`key`	(Necessário para autenticação de chave) A chave para o endpoint online AML ou o
`resourceId`	(Necessário para autenticação de token). A ID de recurso Azure Resource Manager do ponto de extremidade online do AML. Ela deve estar no formato `subscriptions/{guid}/resourceGroups/{resource-group-name}/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.

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 endpoint online AML é implantado usando autenticação baseada em token. A identidade gerenciada do serviço Azure AI Search deve estar habilitada e ter uma atribuição de função no workspace. 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 ser um 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 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://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 de enviar códigos de status mal-sucedidos, os seguintes são considerados casos errados:

O endpoint online AML retorna um código de status de êxito, mas a resposta indica que não application/jsoné, então a resposta é considerada inválida e nenhum enriquecimento é executado.
O endpoint online AML retorna JSON inválido.

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

Compartilhar via