Partilhar via

ai_embeddings plugin (pré-visualização)

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

O ai_embeddings plugin 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 incorporaçã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 plugin 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 incorporaçã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 ( text, connectionString [,opções [,IncludeErrorMessages]])

Saiba mais sobre convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório Descrição
texto string ✔️ O texto a incorporar. O valor pode ser uma referência de coluna ou uma escalar constante.
connectionString 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 incorporação. Consulte Opções.
IncludeErrorMessages bool Indica se os erros de saída devem ser exibidos em uma nova coluna na tabela de saída. Valor predefinido: false.

Opções

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

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

Configurar política de texto explicativo

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

Para configurar a política de texto explicativo para autorizar o domínio de 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 ao 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 incorporação:

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

Dependendo do tipo de entrada, o plugin 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 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 configurado para retornar erros, _embedding_error.

Exemplos

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

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 incorpora vários textos usando o modelo de incorporação do Azure OpenAI.

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)

Melhores práticas

Os modelos de incorporação do Azure OpenAI estão sujeitos a uma forte limitação e as chamadas frequentes para este plug-in podem atingir rapidamente os limites de limitação.

Para usar o plug-in de forma eficiente, minimizando a ai_embeddings limitação e os custos, siga estas práticas recomendadas:

  • Controlar o tamanho da solicitação: ajuste o número de registros (RecordsPerRequest) e caracteres por solicitação ().CharsPerRequest
  • Controlar o tempo limite da consulta: defina GlobalTimeout um valor inferior ao tempo limite da consulta para garantir que o progresso não seja perdido em chamadas bem-sucedidas até esse ponto.
  • Manipule os limites de taxa com mais elegância: defina novas tentativas na limitação (RetriesOnThrottling).

Conteúdo relacionado

  • Last updated on