Azure OpenAI Embedding Skill

A habilidade Azure OpenAI Embedding conecta-se a um modelo de embedding implantado no seu projeto Azure OpenAI em Foundry Models ou Microsoft Foundry para gerar embeddings durante a indexação. Seus dados são processados na Geo onde seu modelo é implantado.

O assistente Importar dados no portal Azure usa a habilidade Azure OpenAI Embedding para vetorizar conteúdo. Você pode rodar o assistente e revisar o conjunto de habilidades gerado para ver como ele constrói a habilidade para incorporar modelos.

Pré-requisitos

• Um recurso Azure OpenAI em Foundry Models ou Foundry.

  • Seu recurso Azure OpenAI deve ter um subdomínio personalizado, como https://<resource-name>.openai.azure.com. Você pode encontrar esse endpoint na página Keys e Endpoint no portal Azure e usá-lo para a propriedade resourceUri nessa habilidade.

  • O recurso pai do seu projeto Foundry fornece acesso a múltiplos endpoints, incluindo https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.com, e https://<resource-name>.cognitiveservices.azure.com. Você pode encontrar esses endpoints na página Keys e Endpoint no portal Azure e usar qualquer um deles para a propriedade resourceUri nesta habilidade.

• Um modelo de embedding Azure OpenAI implantado no seu recurso ou projeto. Para modelos suportados, veja a seção Parâmetros de Habilidade .

@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 gera um erro de solicitação inválido. Para mais informações, veja o conceito tokens na documentação Azure OpenAI. Considere usar a habilidade Text Split se precisar de fragmentação de dados.

Parâmetros de habilidade

Os parâmetros são sensíveis a maiúsculas minúsculas.

Dimensões suportadas por modelName

As dimensões suportadas para uma habilidade de Azure OpenAI Embedding dependem do modelName configurado.

Entradas de competências

Resultados de competências

Definição de exemplo

Considere um registro que possui os seguintes campos:

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

Então sua definição de habilidade pode ser assim:

{
  "@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 fornecido, é produzida uma saída de embedding vetorizada.

{
  "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 busca, você deve definir um outputFieldMapping que mapeia a saída vetorizada de embedding (que é um array) para um campo vetorial. Assumindo que a saída da habilidade reside no nó de incorporação do documento, e content_vector é o campo no índice de busca, o outputFieldMapping no indexador deve ser assim:

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

Práticas recomendadas

A seguir, algumas boas práticas que você precisa considerar ao utilizar essa habilidade:

• Se você está atingindo seu limite Azure do OpenAI TPM (Tokens por minuto), considere o aviso quota limits para poder lidar adequadamente. Consulte a documentação de monitoramento Azure OpenAI para mais informações sobre o desempenho da sua instância Azure OpenAI.

• A implantação do modelo de embeddings Azure OpenAI que você usa para essa habilidade deve ser idealmente separada da implantação usada em outros casos de uso, incluindo o vetorizador consulta. Isso ajuda a que cada implantação seja adaptada ao seu caso de uso específico, levando a um desempenho otimizado e à identificação fácil do tráfego proveniente do indexador e das chamadas de embedding do índice.

• Sua instância do Azure OpenAI deve estar na mesma região ou pelo menos geograficamente próxima da região onde seu serviço de busca de IA está hospedado. Isso reduz a latência e melhora a velocidade da transferência de dados entre os serviços.

• Para evitar ter 429 códigos de erro com frequência, considere implementar o balanceamento de carga por meio do Gerenciamento de API implementando um gateway na frente de várias implantações de modelo de inserção do OpenAI Azure.

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

• Para exemplos e exemplos de código funcionais usando essa habilidade, veja os seguintes links:

  • Vetorização integrada (Python)
  • Vetorização integrada (C#)
  • Vetorização integrada (Java)

Erros e avisos

Considerações de segurança para autenticação de identidade gerenciada

Quando a habilidade Azure OpenAI Embedding usa a autenticação de identidade gerenciada, Pesquisa de IA do Azure  obtém um token de acesso Microsoft Entra para o público-alvo das Ferramentas de Pesquisa (https://cognitiveservices.azure.com) e inclui-o em solicitações enviadas ao ponto de extremidade especificado por resourceUri. A autenticação de identidade gerenciada se aplica quando authIdentity é definida ou quando ambas apiKeyauthIdentity estão vazias e o serviço usa a identidade atribuída pelo sistema.

Espera-se que o ponto de extremidade referenciado seja resourceUri seu próprio recurso Azure OpenAI ou Foundry Tools. Domínios suportados são:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

também há suporte para pontos de extremidade *.azure-api.net). Como um nome de host APIM não pode ser verificado apenas em seu nome, Pesquisa de IA do Azure  valida esses pontos de extremidade com uma verificação de conectividade dinâmica no momento da configuração e não por correspondência de domínio. Você é responsável por configurar e manter a relação entre o ponto de extremidade APIM e o recurso Azure OpenAI ou Foundry Tools por trás dele.

Um token de identidade gerenciada emitido para o público-alvo das Ferramentas de Fundação é válido em qualquer ferramenta do Foundry ou Azure recurso OpenAI no qual a identidade está autorizada. Enviá-lo para um ponto de extremidade não confiável pode expor o token.

Práticas de segurança recomendadas

Para ajudar a manter uma implantação segura, siga estas práticas:

• Defina resourceUri apenas como pontos de extremidade que você possui e confie. Prefira os domínios das Ferramentas de Fundimento listados anteriormente. Se você usar um ponto de extremidade APIM, confirme se ele está à frente do seu próprio recurso antes de habilitar a identidade gerenciada. Um nome de host de aparência confiável não é prova de propriedade.
• Aplique o princípio de privilégio mínimo à identidade gerenciada usada pelo serviço de pesquisa. A habilidade Azure OpenAI Embedding requer apenas a função de Usuário OpenAI dos Serviços Cognitivos no recurso de destino. Evite conceder funções mais amplas.
• Use o NSP (Perímetro de Segurança de Rede) e pontos de extremidade privados ou integração de VNet para restringir quais pontos de extremidade o serviço de pesquisa pode alcançar e de quais fontes o recurso de destino aceita solicitações.
• Se você usar um ponto de extremidade APIM, verifique se o gateway valida as solicitações de entrada e encaminha-as apenas para o back-end pretendido. Você também deve examinar suas políticas de acesso periodicamente.
• Prefira a identidade gerenciada em vez de apiKey. Se você usar apiKey, armazene-o e gire-o com segurança e não insira-o no controle do código-fonte. O serviço rejeita configurações que definem ambos apiKey e authIdentity.
• Examine periodicamente as definições do conjunto de habilidades, as atribuições de função de identidade gerenciada e as configurações do APIM para confirmar se resourceUri os valores, os controles de acesso e as permissões de identidade permanecem atuais e apropriados. Examine as alterações de configuração por meio dos processos estabelecidos de gerenciamento de alterações e revisão de segurança.
• Monitore Azure logs de entrada do OpenAI e do Foundry Tools, eventos de autenticação e logs de acesso para atividades inesperadas ou não autorizadas.
• Remova habilidades não utilizados, pontos de extremidade, atribuições de função e chaves de API que não são mais necessárias.

Restringir o acesso à configuração do conjunto de habilidades

Os usuários que podem criar, modificar ou executar conjuntos de habilidades controlam o ponto de extremidade de destino (resourceUri) e a configuração de autenticação usada pela habilidade. Como a habilidade envia um token de identidade gerenciada para o público-alvo das Ferramentas de Pesquisa para esse ponto de extremidade, restrinja essas permissões a administradores confiáveis e siga seus processos padrão de gerenciamento de alterações e revisão de segurança ao configurar habilidades habilitadas para identidade gerenciada.

Consulte também

• Habilidades integradas
• Como definir um conjunto de habilidades
• Como definir mapeamentos de campos de saída