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

Artigo
12/18/2024

Importante

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

A habilidade AML permite estender o enriquecimento de IA com um modelo personalizado de Aprendizado de Máquina do Azure (AML) ou um modelo de incorporação de base implantado no Azure AI Foundry. Uma vez que um modelo de AML é treinado e implantado, uma habilidade de AML o integra 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 ponto de extremidade 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 sucesso. Seus dados são processados na área geográfica onde seu modelo é implantado. Espera-se que a resposta forneça os resultados especificados pela sua definição de habilidade AML . Qualquer outra resposta é considerada um erro e nenhum enriquecimento é realizado.

Nota

O indexador tentará novamente duas vezes para certos códigos de status HTTP padrão retornados do ponto de extremidade online 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 2024-05-01-preview e no portal do Azure (que também tem como alvo a pré-visualização 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 é a contrapartida de indexação para gerar incorporaçõ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 incorporação para indexação e consultas. Consulte Usar modelos de incorporação do catálogo de modelos do Azure AI Foundry para obter detalhes e obter uma lista dos modelos de incorporação suportados.

Recomendamos usar o assistente Importar e vetorizar dados para gerar um conjunto de habilidades que inclua uma habilidade AML para modelos de incorporação implantados no Azure AI Foundry. A definição de habilidades 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 espaço de trabalho AML para um modelo personalizado que você cria ou um projeto no Azure AI Foundry se um modelo de incorporação for implantado a partir 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 incorporar modelos implantados a partir do catálogo.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parâmetros de habilidade

Os parâmetros diferenciam maiúsculas de minúsculas. Os parâmetros que você escolhe usar dependem da autenticação que seu ponto de extremidade online AML exige, se houver

Nome do parâmetro	Description
`uri`	(Necessário para autenticação de chave) O URI de pontuação do ponto de extremidade online AML para o qual a carga JSON é enviada. Somente o esquema de URI https é permitido. Para incorporar modelos no catálogo de modelos do Azure AI Foundry, este é o URI de destino.
`key`	(Necessário para autenticação de chave) A chave para o ponto de extremidade online AML ou o
`resourceId`	(Necessário para autenticação de token). A ID de recurso do Azure Resource Manager do ponto de extremidade online da AML. Deverá 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 em que o ponto de extremidade online AML é implantado.
`timeout`	(Opcional) Quando especificado, indica o tempo limite para o cliente http que faz a chamada de API. Ele deve ser formatado como um valor XSD "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601). Por exemplo, `PT60S` durante 60 segundos. Se não estiver definido, será escolhido um valor padrão de 30 segundos. 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 fornecido. Você pode diminuir esse valor se o ponto de extremidade estiver falhando sob uma carga de solicitação muito alta. Você pode aumentá-lo se o seu endpoint for capaz de aceitar mais solicitações e você quiser um aumento no desempenho do indexador. Se não estiver definido, um valor padrão de 5 será usado. O grau de paralelismo pode ser definido para um máximo de 10 e um mínimo de 1.

Autenticação

Os pontos de extremidade online AML oferecem 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 de AML. Defina os uri parâmetros e key para esta conexão.
Autenticação baseada em token, onde o ponto de extremidade online AML é implantado usando autenticação baseada em token. A identidade gerenciada do serviço Azure AI Search deve ser habilitada e ter uma atribuição de função no espaço de trabalho. Em seguida, a habilidade AML usa a identidade gerenciada do serviço para autenticar no ponto de extremidade online AML, sem 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.

Contributos para as competências

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

Resultados em termos de competências

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

Definição da amostra

  {
    "@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"
      }
    ]
  }

Exemplo de estrutura JSON de entrada

Essa estrutura JSON representa a carga útil que é enviada para seu ponto de extremidade online AML. Os campos de nível superior da estrutura correspondem aos "nomes" especificados na inputs seção da definição de habilidade. Os valores desses campos são dos source campos (que podem ser de um campo no documento ou, potencialmente, de outra habilidade)

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

Exemplo de estrutura JSON de saída

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

{
    "detected_language_code": "es"
}

Definição de exemplo de modelagem em linha

  {
    "@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 modelagem em linha

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

Estrutura JSON de saída de amostra de modelagem embutida

{
    "detected_language_code": "es"
}

Casos de erro

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

O ponto de extremidade online AML retorna um código de status de sucesso, mas a resposta indica que não application/jsoné, então a resposta é considerada inválida e nenhum enriquecimento é executado.
O ponto de extremidade 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.

Partilhar via