Compartilhar via

Habilidade de inserção do Azure OpenAI

  • Artigo

A habilidade de Inserção do OpenAI do Azure conecta-se a um modelo de inserção implantado no seu recurso do OpenAI do Azure para gerar inserções durante a indexação. Seus dados são processados na área geográfica em que o modelo é implantado.

Pré-requisitos

Seu Serviço OpenAI do Azure deve ter um subdomínio personalizado associado. Se o serviço tiver sido criado por meio do portal do Azure, esse subdomínio será gerado automaticamente como parte da configuração do serviço. Certifique-se de que o serviço inclua um subdomínio personalizado antes de usá-lo com a integração da Pesquisa de IA do Azure.

Não há suporte para recursos do Serviço OpenAI do Azure (com acesso a modelos de inserção) criados no AI Studio. Somente os recursos do Serviço OpenAI do Azure criados no portal do Azure são compatíveis com a integração de habilidades de inserção do OpenAI do Azure.

O Assistente de importação e vetorização de dados do portal do Azure usa a habilidade Inserção do OpenAI do Azure para vetorizar o conteúdo. Você pode executar o assistente e examinar o conjunto de habilidades gerado para ver como o assistente cria a habilidade para inserir modelos.

Observação

Essa habilidade está associada ao Azure OpenAI e é cobrada no Preço pago conforme o uso do Azure OpenAI existente.

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Limites de dados

O tamanho máximo de uma entrada de texto deve ser de 8.000 tokens. Se a entrada exceder o máximo permitido, o modelo gerará um erro de solicitação inválido. Para obter mais informações, consulte o conceito-chave de tokens na documentação do Azure OpenAI. Considere o uso da habilidade Divisão de Texto se precisar de agrupamento de dados.

Parâmetros de habilidades

Os parâmetros diferenciam maiúsculas de minúsculas.

Entradas Descrição
resourceUri O URI do provedor de modelo, nesse caso, um recurso do OpenAI do Azure. Esse parâmetro só oferece suporte a URLs com domínio openai.azure.com, como https://<resourcename>.openai.azure.com. Se o ponto de extremidade do OpenAI do Azure tiver uma URL com o domínio cognitiveservices.azure.com, como https://<resourcename>.cognitiveservices.azure.com, um subdomínio personalizado com openai.azure.com deverá ser criado primeiro para o recurso OpenAI do Azure e usado https://<resourcename>.openai.azure.com em seu lugar.
apiKey A chave secreta usada para acessar o modelo. Se você fornecer uma chave, deixe authIdentity vazio. Se você definir apiKey e authIdentity, apiKey será usado na conexão.
deploymentId O nome do modelo de inserção do Azure OpenAI implantado. O modelo deve ser um modelo de inserção, como text-embedding-ada-002. Consulte a Lista de modelos do Azure OpenAI para modelos com suporte.
authIdentity Uma identidade gerenciada pelo usuário usada pelo serviço de pesquisa para se conectar ao Azure OpenAI. Você pode usar um sistema ou uma identidade gerenciada pelo usuário. Para usar uma identidade gerenciada pelo sistema, deixe apiKey e authIdentity em branco. A identidade gerenciada pelo sistema é usada automaticamente. Uma identidade gerenciada deve ter permissões de Usuário do OpenAI dos Serviços Cognitivos para enviar textos ao Azure OpenAI.
modelName Essa propriedade será necessária se o conjunto de habilidades for criado usando a API REST 2024-05-01-preview ou 2024-07-01. Defina essa propriedade com o nome de implantação de um modelo de inserção do OpenAI do Azure implantado no provedor especificado por meio de resourceUri e identificado por meio de deploymentId. Atualmente, os valores com suporte são text-embedding-ada-002, text-embedding-3-large e text-embedding-3-small.
dimensions (Opcional, introduzido na API REST 2024-05-01-preview). As dimensões de inserções que você deseja gerar se o modelo der suporte à redução das dimensões de inserção. Os intervalos com suporte são listados abaixo. Usa como padrão as dimensões máximas para cada modelo, se não especificado. Para os conjuntos de habilidades criados com a 2023-10-01-preview, as dimensões são fixas em 1.536.

Dimensões com suporte em modelName

As dimensões com suporte para uma habilidade de Inserção do OpenAI do Azure dependem do modelName que está configurado.

modelName Dimensões mínimas Dimensões máximas
text-embedding-ada-002 1536 1536
text-embedding-3-large 1 3072
text-embedding-3-small 1 1536

Entradas de habilidades

Entrada Descrição
text O texto de entrada a ser vetorizado. Se você estiver usando o agrupamento de dados, a origem poderá ser /document/pages/*.

Saídas de habilidades

Saída Descrição
embedding Inserção vetorizada para o texto de entrada.

Definição de exemplo

Considere um registro que tenha os seguintes campos:

{
    "content": "Microsoft released Windows 10."
}

Assim, sua definição de habilidade pode ser:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Saída de exemplo

Para o texto de entrada especificado, uma saída de inserção vetorizada é produzida.

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

A saída reside na memória. Para enviar essa saída para um campo no índice de pesquisa, você precisa definir um outputFieldMapping que mapeie a saída da inserção vetorizada (que é uma matriz) para um campo de vetor. Supondo que a saída da habilidade esteja no nó embedding do documento e content_vector seja o campo no índice de pesquisa, o outputFieldMapping no indexador terá esta aparência:

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

Práticas recomendadas

Estas são algumas das melhores práticas que você precisa considerar ao utilizar essa habilidade:

  • Se estiver atingindo o limite de TPM (tokens por minuto) do OpenAI do Azure, considere o uso da consultoria de limites de cota para resolver o problema. Veja a documentação de monitoramento do OpenAI do Azure para obter mais informações sobre o desempenho da instância do OpenAI do Azure.

  • O ideal é que a implantação do modelo de inserções do OpenAI do Azure que você usa para essa habilidade fique separada da implantação usada para outros casos de uso, incluindo o vetorizador de consulta. Isso ajuda cada implantação a ser adaptada ao seu caso de uso específico, resultando em um desempenho otimizado e identificando o tráfego do indexador e as chamadas de inserção de índice com facilidade.

  • Sua instância do OpenAI do Azure deve estar na mesma região ou, pelo menos, geograficamente perto da região em que o serviço de Pesquisa de IA está hospedado. Isso reduz a latência e aprimora a velocidade de transferência de dados entre os serviços.

  • Se você tiver um limite maior que o TPM (tokens por minuto) padrão do OpenAI do Azure, conforme publicado na documentação de cotas e limites, abra um caso de suporte com a equipe da Pesquisa de IA do Azure, para que isso possa ser ajustado de acordo. Isso ajuda o processo de indexação a não ser desnecessariamente atrasado pelo limite de TPM padrão documentado, caso você tenha limites mais altos.

  • Para ver exemplos e amostras de códigos funcionais que usam essa habilidade, confira os seguintes links:

Erros e avisos

Condição Resultado
URI nulo ou inválido Erro
Implantação nula ou inválida Erro
O texto está vazio Aviso
O texto é maior que 8.000 tokens Erro

Confira também