Compartilhar via

ai_embeddings plugin (versão prévia)

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

O ai_embeddings plug-in permite a incorporação de texto usando modelos de linguagem, permitindo vários cenários relacionados à IA, como aplicativos de Geração Aumentada de Recuperação (RAG) e pesquisa semântica. O plug-in usa os modelos de inserção do Serviço OpenAI do Azure e pode ser acessado usando uma identidade gerenciada ou a identidade do usuário (representação).

O ai_embeddings plug-in permite a incorporação de texto usando modelos de linguagem, permitindo vários cenários relacionados à IA, como aplicativos de Geração Aumentada de Recuperação (RAG) e pesquisa semântica. O plug-in usa os modelos de inserção do Serviço OpenAI do Azure e pode ser acessado usando a identidade do usuário (representação).

Pré-requisitos

Sintaxe

evaluate ai_embeddings ( texto, connectionString [,opções [,IncludeErrorMessages]])

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório Descrição
Texto string ✔️ O texto a ser incorporado. O valor pode ser uma referência de coluna ou um escalar constante.
cadeia de caracteres de conexão string ✔️ A cadeia de conexão para o modelo de linguagem no formato <ModelDeploymentUri>;<AuthenticationMethod>; substitua <ModelDeploymentUri> e <AuthenticationMethod> pelo URI de implantação do modelo de IA e pelo método de autenticação, respectivamente.
Opções dynamic As opções que controlam chamadas para o ponto de extremidade do modelo de inserção. Consulte Opções.
IncludeErrorMessages bool Indica se os erros devem ser gerados em uma nova coluna na tabela de saída. Valor padrão: false.

Opções

A tabela a seguir descreve as opções que controlam a maneira como as solicitações são feitas para o ponto de extremidade do modelo de inserção.

Nome Tipo Descrição
RecordsPerRequest int Especifica o número de registros a serem processados por solicitação. Valor padrão: 1.
CharsPerRequest int Especifica o número máximo de caracteres a serem processados por solicitação. Valor padrão: 0 (ilimitado). O OpenAI do Azure conta tokens, com cada token sendo convertido aproximadamente em quatro caracteres.
RetriesOnThrottling int Especifica o número de tentativas de repetição quando ocorre limitação. Valor padrão: 0.
GlobalTimeout timespan Especifica o tempo máximo de espera por uma resposta do modelo de inserção. Valor padrão: null
ModelParameters dynamic Parâmetros específicos do modelo de inserção, como dimensões de incorporação ou identificadores de usuário para fins de monitoramento. Valor padrão: null.
ReturnSuccessfulOnly bool Indica se os itens processados com êxito devem ser retornados. Valor padrão: false. Se o parâmetro IncludeErrorMessages estiver definido como true, essa opção será sempre definida como false.

Configurar a Política de Texto Explicativo

A azure_openaipolítica de texto explicativo habilita chamadas externas para os serviços de IA do Azure.

Para configurar a política de texto explicativo para autorizar o domínio do ponto de extremidade do modelo de IA:

.alter-merge cluster policy callout
```
[
  {
    "CalloutType": "azure_openai",
    "CalloutUriRegex": "https://[A-Za-z0-9-]{3,63}\\.(?:openai\\.azure\\.com|cognitiveservices\\.azure\\.com|cognitive\\.microsoft\\.com|services\\.ai\\.azure\\.com)(?:/.*)?",
    "CanCall": true
  }
]
```

Configurar Identidade Gerenciada

Ao usar a identidade gerenciada para acessar o Serviço OpenAI do Azure, você deve configurar a política de Identidade Gerenciada para permitir que a identidade gerenciada atribuída pelo sistema se autentique no Serviço OpenAI do Azure.

Para configurar a identidade gerenciada:

.alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

Devoluções

Retorna as seguintes novas colunas de inserção:

  • Uma coluna com o sufixo _embeddings que contém os valores de inserção
  • Se configurada para retornar erros, uma coluna com o sufixo _embedding_error , que contém cadeias de caracteres de erro ou é deixada em branco se a operação for bem-sucedida.

Dependendo do tipo de entrada, o plug-in retorna resultados diferentes:

  • Referência de coluna: retorna um ou mais registros com colunas adicionais prefixadas pelo nome da coluna de referência. Por exemplo, se a coluna de entrada for chamada de TextData, as colunas de saída serão nomeadas TextData_embedding e, se configuradas para retornar erros, TextData_embedding_error.
  • Escalar constante: retorna um único registro com colunas adicionais que não são prefixadas. Os nomes das colunas são _embedding e, se configurados para retornar erros, _embedding_error.

Exemplos

O exemplo a seguir insere o texto Embed this text using AI usando o modelo de inserção do OpenAI do Azure.

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embeddings(expression, connectionString)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
evaluate ai_embeddings(expression, connectionString)

O exemplo a seguir insere vários textos usando o modelo de inserção do OpenAI do Azure.

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
  "RecordsPerRequest": 10,
  "CharsPerRequest": 10000,
  "RetriesOnThrottling": 1,
  "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embeddings(TextData, connectionString, options , true)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
let options = dynamic({
  "RecordsPerRequest": 10,
  "CharsPerRequest": 10000,
  "RetriesOnThrottling": 1,
  "GlobalTimeout": 2m
});
datatable(TextData: string)
[
  "First text to embed",
  "Second text to embed",
  "Third text to embed"
]
| evaluate ai_embeddings(TextData, connectionString, options , true)

Práticas recomendadas

Os modelos de inserção do OpenAI do Azure estão sujeitos a limitações pesadas e chamadas frequentes para esse plug-in podem atingir rapidamente os limites de limitação.

Para usar o plug-in com eficiência e minimizar a ai_embeddings limitação e os custos, siga estas práticas recomendadas:

  • Tamanho da solicitação de controle: ajuste o número de registros (RecordsPerRequest) e caracteres por solicitação (CharsPerRequest).
  • Controlar o tempo limite da consulta: defina GlobalTimeout como um valor menor que o tempo limite da consulta para garantir que o progresso não seja perdido em chamadas bem-sucedidas até esse ponto.
  • Manipular limites de taxa com mais facilidade: defina novas tentativas na limitação (RetriesOnThrottling).

Conteúdo relacionado

  • Last updated on