Azure OpenAI Embedding skill

A competência Azure OpenAI Embedding liga-se a um modelo de embedding implementado no seu projeto Azure OpenAI em Foundry Models ou Microsoft Foundry para gerar embeddings durante a indexação. Os seus dados são processados na Geo onde o seu modelo é implementado.

O assistente Import data no portal Azure utiliza a habilidade Azure OpenAI Embedding para vetorizar conteúdo. Podes correr o assistente e rever o conjunto de competências gerado para ver como o assistente constrói a habilidade para incorporar modelos.

Pré-requisitos

• Um recurso Azure OpenAI em Foundry Models ou Foundry.

  • O seu recurso OpenAI Azure deve ter um subdomínio personalizado, como https://<resource-name>.openai.azure.com. Podes encontrar este endpoint na página Keys e Endpoint no portal Azure e usá-lo para a propriedade resourceUri nesta competência.

  • O recurso principal 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. Podes encontrar estes endpoints na página Keys e Endpoint no portal Azure e usar qualquer um deles para a propriedade resourceUri nesta competência.

• Um modelo de embedding Azure OpenAI implementado no seu recurso ou projeto. Para modelos suportados, consulte a secção Parâmetros de Competência .

@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 pedido inválido. Para mais informações, consulte o conceito chave tokens na documentação Azure OpenAI. Considera usar a habilidade Text Split se precisares de fragmentação de dados.

Parâmetros de habilidade

Os parâmetros são distinguíveis de maiúsculas minúsculas.

Dimensões suportadas por modelName

As dimensões suportadas para uma competência de Embedding Azure OpenAI dependem do modelName que está configurado.

Entradas de habilidades

Resultados em termos de competências

Definição da amostra

Considere um registo que tem os seguintes campos:

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

Então a tua definição de competência pode ser esta:

{
  "@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 da amostra

Para o texto de entrada dado, é produzida uma saída de embedding vetorizada.

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

A saída reside na memória. Para enviar esta saída para um campo no índice de pesquisa, 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 skill reside no nó de embedding do documento, e content_vector é o campo no índice de pesquisa, o outputFieldMapping no indexador deve ser assim:

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

Melhores práticas

Seguem-se algumas das melhores práticas que deve considerar ao utilizar esta competência:

• Se estiver a atingir o limite Azure do OpenAI TPM (Tokens por minuto), considere o quota limits advisory para poder abordar em conformidade. Consulte a documentação de monitorização Azure OpenAI para mais informações sobre o desempenho da sua instância Azure OpenAI.

• A implementação Azure modelo de embeddings OpenAI que usa para esta competência deve idealmente ser separada da implementação usada para outros casos de uso, incluindo o vetorizador consulta. Isto ajuda a que cada implementaçã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 do índice que incorpora chamadas.

• A sua instância Azure OpenAI deve estar na mesma região ou pelo menos geograficamente perto da região onde o seu serviço de AI Search está alojado. Isto reduz a latência e melhora a velocidade da transferência de dados entre os serviços.

• Para evitar experienciar frequentemente códigos de erro 429, considere implementar o balanceamento de carga via API Management implementando um gateway à frente de múltiplas implementações de modelos de embedding do Azure OpenAI.

• Se tiver um limite Azure TPM (Tokens por minuto) da OpenAI superior ao padrão, conforme publicado na documentação quotas e limites, abra um caso suporte com a equipa Pesquisa de IA do Azure, para que isto possa ser ajustado em conformidade. Isto ajuda a que o seu processo de indexação não seja desnecessariamente atrasado pelo limite padrão de TPM documentado, caso tenha limites mais elevados.

• Para exemplos e exemplos de código funcional usando esta competência, consulte 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 gerida

Quando a competência Azure OpenAI Embedding utiliza autenticação de identidade gerida, o Pesquisa de IA do Azure obtém um token de acesso Microsoft Entra para a audiência do Foundry Tools (https://cognitiveservices.azure.com) e inclui-o em pedidos enviados ao endpoint especificado por resourceUri. A autenticação de identidade gerida aplica-se quando authIdentity está definida, ou quando ambos apiKey e authIdentity estão vazios e o serviço utiliza a identidade atribuída pelo sistema.

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

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

Os endpoints () do *.azure-api.net) também são suportados. Como um nome de host APIM não pode ser verificado apenas pelo seu nome, o Pesquisa de IA do Azure valida estes endpoints com uma verificação de conectividade em tempo real no momento da configuração, em vez de por correspondência de domínio. És responsável por configurar e manter a relação entre o endpoint APIM e o recurso Azure OpenAI ou Foundry Tools por trás dele.

Um token de identidade gerido emitido para o público da Foundry Tools é válido contra qualquer recurso da Foundry Tools ou Azure OpenAI para o qual a identidade esteja autorizada. Enviá-lo para um endpoint 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 para endpoints que possua e em quem confia. Prefiro os domínios Foundry Tools listados anteriormente. Se usar um endpoint APIM, confirme que ele antecipa o seu próprio recurso antes de ativar a identidade gerida. Um nome de anfitrião com aparência confiável não é prova de propriedade.
• Aplicar o princípio do menor privilégio à identidade gerida usada pelo serviço de pesquisa. A competência Azure OpenAI Embedding requer apenas o papel de Utilizador OpenAI de Serviços Cognitivos no recurso alvo. Evite atribuir cargos mais amplos.
• Use o Perímetro de Segurança de Rede (NSP) e endpoints privados ou integração com VNet para restringir quais os endpoints que o serviço de pesquisa pode alcançar e de que fontes o recurso alvo aceita pedidos.
• Se usar um endpoint APIM, certifique-se de que o gateway valida os pedidos de entrada e os encaminha apenas para o backend pretendido. Também deve rever periodicamente as suas políticas de acesso.
• Prefira identidade gerida em vez de apiKey. Se usares apiKey, guarda e roda de forma segura e não o incorpores no controlo de versão. O serviço rejeita configurações que definem tanto apiKey como authIdentity.
• Revise periodicamente definições de conjuntos de competências, atribuições de papéis de identidade geridas e configurações do APIM para confirmar que resourceUri os valores, controlos de acesso e permissões de identidade permanecem atuais e apropriados. Revise as alterações de configuração através dos seus processos estabelecidos de gestão de alterações e revisão de segurança.
• Monitorize os registos de início de sessão do Azure OpenAI e Foundry Tools, eventos de autenticação e registos de acesso para atividades inesperadas ou não autorizadas.
• Remova competências não utilizadas, endpoints, atribuições de funções e chaves de API que já não são necessárias.

Restringir o acesso à configuração de competências

Os utilizadores que podem criar, modificar ou executar conjuntos de competências controlam tanto o endpoint de destino (resourceUri) como a configuração de autenticação usada pela competência. Como a competência envia um token de identidade gerida para o público das Foundry Tools para esse endpoint, restrinja essas permissões a administradores de confiança e siga os seus processos padrão de gestão de alterações e revisão de segurança ao configurar competências habilitadas para identidade gerida.

Ver também

• Competências incorporadas
• Como definir um conjunto de competências
• Como definir mapeamentos de campos de saída