Partilhar via

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

  • Artigo

Importante

O suporte para conexões de indexador com o catálogo de modelos do Azure AI Studio 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 da IA com um modelo personalizado do Azure Machine Learning (AML). Uma vez que um modelo de AML é treinado e implantado, uma habilidade de AML o integra no enriquecimento de IA.

Como outras habilidades incorporadas, uma habilidade AML tem entradas e saídas. As entradas são enviadas para seu ponto de extremidade online AML implantado como um objeto JSON, que gera uma carga JSON como 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 tenha as saídas especificadas pela sua habilidade AML . Qualquer outra resposta é considerada um erro e nenhum enriquecimento é realizado.

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 2024-05-01-preview e no portal do Azure (que também visa a pré-visualização 2024-05-01), a Pesquisa do Azure AI 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 é a contrapartida de indexação para gerar incorporaçõ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 incorporação para indexação e consultas. Consulte Como implementar vetorização integrada usando modelos do Azure AI Studio para obter detalhes sobre esse fluxo de trabalho.

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

Pré-requisitos

@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.
key (Necessário para autenticação de chave) A chave para o ponto de extremidade online AML.
resourceId (Necessário para autenticação de token). A ID de recurso do Azure Resource Manager do ponto de extremidade online da AML. 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 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.

Quais parâmetros de habilidade usar

Os parâmetros de habilidade AML necessários dependem da autenticação que seu endpoint online AML usa, se houver. 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
    • Use o uri e os parâmetros chave
  • Autenticação baseada em token. 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. 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 deve ser atribuída à função de proprietário ou colaborador.
    • Use o parâmetro resourceId .
    • Se o serviço de pesquisa estiver em uma região diferente do espaço de trabalho AML, use o parâmetro region para definir a região em que o ponto de extremidade online AML foi implantado

Contributos para as competências

Não existem entradas "predefinidas" para esta habilidade. Você pode escolher um ou mais campos que já estariam disponíveis no momento da execução dessa habilidade como entradas e a carga JSON enviada para o endpoint online AML terá campos diferentes.

Resultados em termos de competências

Não existem saídas "predefinidas" para esta habilidade. Dependendo da resposta que seu ponto de extremidade online AML retornar, adicione campos de saída para que eles possam ser coletados da resposta JSON .

Definição da amostra

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

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://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 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:

  • Se o ponto de extremidade online da AML retornar um código de status de sucesso, mas a resposta indicar que não application/jsoné , a resposta será considerada inválida e nenhum enriquecimento será executado.
  • Se o ponto de extremidade online AML retornar 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 será adicionado ao histórico de execução do indexador.

Consulte também